Skip to main content
Uma assinatura representa uma cobrança recorrente de um cliente por um produto ou serviço. Faturas são geradas automaticamente a cada período de renovação.

​
Estrutura

Uma assinatura é representada em nossa API pela seguinte estrutura: 
{
  "id": "sub_abc123xyz",
  "livemode": false,
  "customerId": "cus_ahwDXrgYvur89iPs",
  "paymentMethodId": "pm_abc123xyz",
  "status": "active",
  "currency": "BRL",
  "interval": "month",
  "intervalCount": 1,
  "cancelAtPeriodEnd": false,
  "startDate": "2024-11-15T10:00:00.000Z",
  "endDate": null,
  "trialStartDate": null,
  "trialEndDate": null,
  "currentPeriodStart": "2024-11-15T10:00:00.000Z",
  "currentPeriodEnd": "2024-12-15T10:00:00.000Z",
  "canceledAt": null,
  "cancellationReason": null,
  "items": [
    {
      "id": "si_abc123xyz",
      "subscriptionId": "sub_abc123xyz",
      "productId": "prod_xyz789abc",
      "priceId": "price_def456ghi",
      "name": "Plano Pro",
      "amount": 9900,
      "quantity": 1,
      "createdAt": "2024-11-15T10:00:00.000Z",
      "updatedAt": "2024-11-15T10:00:00.000Z"
    }
  ],
  "createdAt": "2024-11-15T10:00:00.000Z",
  "updatedAt": "2024-11-15T10:00:00.000Z"
}

​
Atributos:

{
  "id": "sub_abc123xyz",
}
id : string.
Identificador único da assinatura, começando com sub_
{
  "livemode": false,
}
livemode : boolean.
Indica se a assinatura está em modo de produção (true) ou teste (false)
{
  "customerId": "cus_ahwDXrgYvur89iPs",
}
customerId : string.
ID do cliente associado à assinatura. Veja a referência completa aqui
{
  "paymentMethodId": "pm_abc123xyz",
}
paymentMethodId : string | null.
ID do método de pagamento utilizado para as cobranças recorrentes. Veja a referência completa aqui
{
  "status": "active",
}
status : string.
Status atual da assinatura
StatusDescrição
activeA assinatura está ativa e sendo cobrada
trialingA assinatura está em período de teste
past_dueO pagamento está atrasado
canceledA assinatura foi cancelada
unpaidA assinatura está inadimplente
incompleteA assinatura está pendente de confirmação
{
  "interval": "month",
}
interval : string.
Intervalo de cobrança: day, week, month, year
{
  "intervalCount": 1,
}
intervalCount : number.
Quantidade de intervalos entre cada cobrança. Ex.: intervalCount: 3 com interval: month = cobrança a cada 3 meses
{
  "cancelAtPeriodEnd": false,
}
cancelAtPeriodEnd : boolean.
Se true, a assinatura será cancelada ao final do período atual em vez de renovar
{
  "currentPeriodStart": "2024-11-15T10:00:00.000Z",
  "currentPeriodEnd": "2024-12-15T10:00:00.000Z",
}
currentPeriodStart / currentPeriodEnd : string | null.
Datas de início e fim do período de cobrança atual em formato ISO 8601
{
  "trialStartDate": null,
  "trialEndDate": null,
}
trialStartDate / trialEndDate : string | null.
Datas do período de teste em formato ISO 8601. null se não há período de teste
{
  "cancellationReason": null,
}
cancellationReason : string | null.
Motivo do cancelamento. Valores: low_quality, missing_features, other, switched_service, too_complex, too_expensive, unused
{
  "items": [
    {
      "id": "si_abc123xyz",
      "subscriptionId": "sub_abc123xyz",
      "productId": "prod_xyz789abc",
      "priceId": "price_def456ghi",
      "name": "Plano Pro",
      "amount": 9900,
      "quantity": 1,
      "createdAt": "2024-11-15T10:00:00.000Z",
      "updatedAt": "2024-11-15T10:00:00.000Z"
    }
  ]
}
items : array.
Lista de itens da assinatura. Cada item contém id, subscriptionId, productId, priceId, name, amount (em centavos), quantity, createdAt e updatedAt
{
  "canceledAt": null,
}
canceledAt : string | null.
Data em que a assinatura foi cancelada em formato ISO 8601. null se ativa
{
  "createdAt": "2024-11-15T10:00:00.000Z",
}
createdAt : string.
Data de criação da assinatura em formato ISO 8601
{
  "updatedAt": "2024-11-15T10:00:00.000Z",
}
updatedAt : string.
Data da última atualização da assinatura em formato ISO 8601