---
title: "Criar uma nova assinatura (Checkout de assinatura)"
method: POST
path: "/subscriptions/create"
---

# Criar uma nova assinatura (Checkout de assinatura)

`POST /subscriptions/create`

Cria um Checkout de assinatura — uma página de pagamento igual ao Checkout comum, mas para cobrança recorrente.

Aceita os mesmos parâmetros do Checkout (`returnUrl`, `completionUrl`, `customerId`, `externalId`, `metadata`, `coupons`, `methods`). O Checkout de assinatura aceita **apenas um produto**; o ciclo (frequência) já deve estar definido no produto ao criá-lo na loja — não é enviado no checkout.

## Request body

- object — Mesmos parâmetros do Checkout, com `items` contendo exatamente um item (`id` e `quantity`). O produto referenciado deve ter sido criado com ciclo de assinatura (frequency) na loja.
  - `items` object[], required — Lista com **exatamente um** item. O produto deve ter sido criado com ciclo de assinatura (frequency). O valor total é calculado a partir do produto.
    - `id` string, required — ID público do produto na sua loja (produto criado com ciclo de assinatura).
    - `quantity` integer, required — Quantidade (geralmente 1 para assinatura).
  - `methods` string[] — Métodos de pagamento disponíveis. Assinaturas suportam apenas CARD. Padrão ["CARD"].
  - `returnUrl` string, uri — URL para onde o cliente será redirecionado ao clicar em "Voltar" no checkout.
  - `completionUrl` string, uri — URL para onde o cliente será redirecionado após o pagamento ser concluído.
  - `customerId` string — ID de um cliente já cadastrado na sua loja. Se informado, o checkout será pré-preenchido com os dados deste cliente.
  - `coupons` string[] — Lista de cupons que podem ser utilizados nesta cobrança.
  - `externalId` string — ID da assinatura no seu sistema, caso queira manter uma referência própria.
  - `metadata` object — Metadados adicionais. Campo livre para a sua aplicação.

## Response `200`

Checkout de assinatura criado com sucesso. Use a `url` retornada para redirecionar o cliente.

- object
  - `data` Billing
    - `id` string — Identificador único do Checkout.
    - `externalId` string, nullable — ID do Checkout no seu sistema.
    - `url` string, uri — URL onde o usuário pode concluir o pagamento.
    - `amount` number — Valor total a ser pago em centavos.
    - `paidAmount` number, nullable — Valor já pago em centavos. Null se ainda não foi pago.
    - `items` object[] — Lista de itens no Checkout.
      - `id` string — ID do produto.
      - `quantity` integer — Quantidade do item.
    - `status` 'PENDING' | 'EXPIRED' | 'CANCELLED' | 'PAID' | 'REFUNDED' — Status atual do Checkout.
    - `coupons` string[] — Lista de cupons aplicados no Checkout.
    - `devMode` boolean — Indica se a cobrança foi criada em ambiente de testes.
    - `customerId` string, nullable — ID do cliente associado ao Checkout.
    - `returnUrl` string, uri, nullable — URL para onde o cliente será redirecionado ao clicar em "Voltar".
    - `completionUrl` string, uri, nullable — URL para onde o cliente será redirecionado após o pagamento.
    - `receiptUrl` string, uri, nullable — URL do comprovante de pagamento.
    - `upSellProductId` string, nullable — ID do produto de upsell vinculado ao Checkout. Null se nenhum produto de upsell foi informado na criação.
    - `installmentsCount` integer, nullable — Número de parcelas do pagamento quando realizado via Cartão de crédito com mais de uma parcela. `null` para pagamentos à vista ou realizados por outros métodos (PIX, Boleto).
    - `dueDate` string, date, nullable — Data de vencimento do boleto (`YYYY-MM-DD`). `null` quando não foi configurada ou quando o método de pagamento não é BOLETO.
    - `interest` BoletoInterest — Juros por atraso aplicados ao boleto após o vencimento. Late interest applied to the boleto after the due date. Aplica-se apenas a `method: "BOLETO"`; ignorado nos demais métodos.
      - `value` integer, required — Percentual de juros ao mês em centésimos de percentual (`100` = 1% ao mês, `250` = 2,5% ao mês). Quando `0` ou omitido, sem juros. Calculado pro rata die após o vencimento. EN: Monthly late-interest rate in hundredths of a percent (`100` = 1%/month). Accrues pro rata die after the due date; `0` or omitted disables interest.
    - `fine` BoletoFine — Multa por atraso aplicada uma única vez após o vencimento do boleto. One-time late fine applied after the due date. Aplica-se apenas a `method: "BOLETO"`; ignorado nos demais métodos.
      - `value` integer, required — Quando `type = "PERCENTAGE"`: centésimos de percentual sobre o valor do boleto (`200` = 2%). Quando `type = "FIXED"`: valor fixo em centavos (`1000` = R$ 10,00). Quando `0` ou omitido, sem multa. EN: With `type: "PERCENTAGE"`, value is in hundredths of a percent (`200` = 2%). With `type: "FIXED"`, value is in cents (`1000` = R$ 10.00). `0` or omitted disables the fine.
      - `type` 'PERCENTAGE' | 'FIXED', required — Tipo da multa. `PERCENTAGE` aplica percentual sobre o valor do boleto; `FIXED` aplica um valor fixo em centavos. EN: Fine type. `PERCENTAGE` applies a percent of the boleto amount; `FIXED` applies a fixed amount in cents.
    - `metadata` object — Metadados adicionais do Checkout.
    - `createdAt` string, date-time — Data e hora de criação do Checkout.
    - `updatedAt` string, date-time — Data e hora da última atualização do Checkout.
  - `error` string, nullable
  - `success` boolean — Se a requisição obteve sucesso ou não.

## Other responses

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

---

[API](https://skmtc.net/abacatepay/apis/api-abacatepay.md) · [All operations](https://skmtc.net/abacatepay/apis/api-abacatepay/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/abacatepay/api-abacatepay/revisions/6b89a7fa70f5/schema)