> ## Documentation Index > Fetch the complete documentation index at: https://docs.purincash.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Subaccount > Cria uma subconta: um ledger de saldo próprio para um cliente seu, dentro da sua conta. Cobranças criadas com `subaccountId` creditam o saldo da subconta quando o pagamento confirma, e você consulta quanto pertence a cada cliente sem manter essa contabilidade do seu lado. A subconta não é uma conta PurinCash: ela não tem login, não tem chave de API e o dinheiro real permanece na carteira da sua conta. O saldo dela é uma camada de atribuição sobre o seu, e por isso criar subconta não exige documento nem aprovação. Se `externalId` for informado e já existir outra subconta com o mesmo valor neste ambiente, a resposta é `409` com o `subaccountId` da existente, o que permite tratar a criação como idempotente. Limite de 1000 subcontas por conta e por ambiente. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/subaccounts openapi: 3.1.0 info: title: PurinCash API version: 1.0.0 servers: - url: https://api.purincash.com description: Produção security: - bearerAuth: [] tags: - name: Cartao description: Pagamentos no cartao de credito. - name: Cobrancas description: Cobrancas PIX avulsas com valor livre. - name: Entregas description: Conteudo entregue automaticamente apos o pagamento. - name: Disputas description: Contestacoes (MED) e envio de evidencias. - name: Pagamentos description: Pagamentos PIX e LTC vinculados ou nao a um produto. - name: Saques description: Saques em PIX, LTC e USDT. - name: Produtos description: Produtos de cobranca criados pela API. - name: Sandbox description: Simulacao de pagamentos e saldo de teste. - name: Splits description: Cobrancas divididas entre varias contas. - name: Loja description: Produtos da loja do Discord (somente leitura). - name: Subcontas description: Ledger de saldo por cliente do integrador. - name: Assinaturas description: PIX recorrente. - name: Carteira description: Saldo, retencoes e valores a liberar. paths: /v1/subaccounts: post: tags: - Subcontas summary: Create Subaccount description: >- Cria uma subconta: um ledger de saldo próprio para um cliente seu, dentro da sua conta. Cobranças criadas com `subaccountId` creditam o saldo da subconta quando o pagamento confirma, e você consulta quanto pertence a cada cliente sem manter essa contabilidade do seu lado. A subconta não é uma conta PurinCash: ela não tem login, não tem chave de API e o dinheiro real permanece na carteira da sua conta. O saldo dela é uma camada de atribuição sobre o seu, e por isso criar subconta não exige documento nem aprovação. Se `externalId` for informado e já existir outra subconta com o mesmo valor neste ambiente, a resposta é `409` com o `subaccountId` da existente, o que permite tratar a criação como idempotente. Limite de 1000 subcontas por conta e por ambiente. operationId: createSubaccount requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string maxLength: 100 description: Nome do cliente dono da subconta. email: type: string maxLength: 255 description: >- E-mail de contato do cliente (informativo, não autentica nada). externalId: type: string maxLength: 200 description: >- ID do cliente no seu sistema. Único por conta e ambiente quando presente. Repetir devolve 409 com a subconta existente. metadata: type: string maxLength: 2048 default: '{}' description: String JSON livre, devolvida sem alteração. example: name: Loja do João email: joao@exemplo.com externalId: cliente_42 metadata: '{"plano":"pro"}' responses: '201': description: Subconta criada. content: application/json: schema: $ref: '#/components/schemas/Subaccount' example: subaccountId: sacc_a1b2c3d4e5f60718293a4b5c6d7e8f90 name: Loja do João email: joao@exemplo.com externalId: cliente_42 active: true balanceCents: 0 totalReceivedCents: 0 metadata: '{"plano":"pro"}' createdAt: '2026-08-04T12:00:00.000Z' updatedAt: '2026-08-04T12:00:00.000Z' '400': description: Nome ausente ou limite de subcontas atingido. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: name is required '409': description: Já existe subconta com este externalId neste ambiente. content: application/json: schema: type: object properties: error: type: string subaccountId: type: string description: ID da subconta existente com este externalId. example: error: A subaccount with this externalId already exists subaccountId: sacc_a1b2c3d4e5f60718293a4b5c6d7e8f90 '500': description: Erro interno. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Internal error components: schemas: Subaccount: type: object properties: subaccountId: type: string description: ID da subconta, prefixo sacc_. Use em cobranças e consultas. name: type: string email: type: string externalId: type: string description: Seu ID para este cliente. Vazio quando não informado. active: type: boolean description: Subconta desativada não recebe novas cobranças nem entradas. balanceCents: type: integer description: Saldo atual do ledger, em centavos. totalReceivedCents: type: integer description: Total já creditado por vendas, sem descontar transferências. metadata: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time Error: type: object properties: error: type: string description: >- Mensagem de erro legivel. Trate pelo codigo HTTP; o texto pode mudar. securitySchemes: bearerAuth: type: http scheme: bearer description: Chave de API gerada no dashboard da PurinCash (ps_live_ ou ps_test_). ````