---
title: "Criar subconta"
method: POST
path: "/sub-accounts/create"
---

# Criar subconta

`POST /sub-accounts/create`

## Request

- Base URL: `https://api.abacatepay.com/v2`
- URL: `https://api.abacatepay.com/v2/sub-accounts/create`
- Auth: HTTP bearer

Cadastra um vendedor como subconta da sua loja, identificado pelo CPF ou CNPJ. Idempotente pelo `taxId`: se a subconta já existe, a API devolve a existente, com o saldo atual.

## Request body

- object
  - `name` string, required: Nome do titular.
  - `taxId` string, required: CPF ou CNPJ do titular, com ou sem máscara.
  - `externalId` string: Identificador da subconta no seu sistema. Não pode se repetir entre as subcontas da loja.
  - `metadata` object: Campos livres; todos os valores precisam ser texto.

## Response `200`

Subconta criada, ou a existente com o mesmo `taxId`.

- object
  - `data` SubAccount: Subconta de um vendedor, com o saldo atual.
    - `id` string: ID único da subconta.
    - `name` string: Nome do titular.
    - `taxId` string: CPF ou CNPJ do titular, só dígitos.
    - `externalId` string, nullable: Identificador no seu sistema.
    - `balance` object: Saldo da subconta em centavos.
      - `available` integer: Disponível para saque.
      - `blocked` integer: Retido.
    - `devMode` boolean: Indica se a subconta foi criada em ambiente de testes.
    - `metadata` object
    - `createdAt` string, date-time
    - `updatedAt` string, date-time
  - `error` string, nullable
  - `success` boolean: Se a requisição obteve sucesso ou não.

## Other responses

- `401`: Não autorizado. Falha na autenticação.

## Changes

- **2026-11-02** `8be803988b57`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/abacatepay/apis/api-abacatepay/changes/sub-accounts/create/post.md)

---

[API](https://skmtc.dev/abacatepay/apis/api-abacatepay.md) - [All operations](https://skmtc.dev/abacatepay/apis/api-abacatepay/llms.txt) - [OpenAPI document](https://skmtc.dev/abacatepay/apis/api-abacatepay/revisions/8be803988b57?raw)