> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upag.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Referência

> Crie e gerencie assinaturas recorrentes dos seus clientes

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.

## <Icon icon="folder-tree" type="solid" /> Estrutura

Uma assinatura é representada em nossa API pela seguinte estrutura:

```json theme={null}
{
  "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:

<AccordionGroup>
  <Accordion title="id:">
    ```json {2} theme={null}
    {
      "id": "sub_abc123xyz",
    }
    ```

    `id` : <u> string. </u> <br />
    Identificador único da assinatura, começando com `sub_`
  </Accordion>

  <Accordion title="livemode:">
    ```json {2} theme={null}
    {
      "livemode": false,
    }
    ```

    `livemode` : <u> boolean. </u> <br />
    Indica se a assinatura está em modo de produção (`true`) ou teste (`false`)
  </Accordion>

  <Accordion title="customerId:">
    ```json {2} theme={null}
    {
      "customerId": "cus_ahwDXrgYvur89iPs",
    }
    ```

    `customerId` : <u> string. </u> <br />
    ID do cliente associado à assinatura. Veja a referência completa <a href="../customers/reference">aqui</a>
  </Accordion>

  <Accordion title="paymentMethodId:">
    ```json {2} theme={null}
    {
      "paymentMethodId": "pm_abc123xyz",
    }
    ```

    `paymentMethodId` : <u> string | null. </u> <br />
    ID do método de pagamento utilizado para as cobranças recorrentes. Veja a referência completa <a href="../payment-methods/reference">aqui</a>
  </Accordion>

  <Accordion title="status:">
    ```json {2} theme={null}
    {
      "status": "active",
    }
    ```

    `status` : <u> string. </u> <br />
    Status atual da assinatura

    <Info>
      | Status       | Descrição                                     |
      | ------------ | --------------------------------------------- |
      | `active`     | **A assinatura está ativa e sendo cobrada**   |
      | `trialing`   | **A assinatura está em período de teste**     |
      | `past_due`   | **O pagamento está atrasado**                 |
      | `canceled`   | **A assinatura foi cancelada**                |
      | `unpaid`     | **A assinatura está inadimplente**            |
      | `incomplete` | **A assinatura está pendente de confirmação** |
    </Info>
  </Accordion>

  <Accordion title="interval:">
    ```json {2} theme={null}
    {
      "interval": "month",
    }
    ```

    `interval` : <u> string. </u> <br />
    Intervalo de cobrança: `day`, `week`, `month`, `year`
  </Accordion>

  <Accordion title="intervalCount:">
    ```json {2} theme={null}
    {
      "intervalCount": 1,
    }
    ```

    `intervalCount` : <u> number. </u> <br />
    Quantidade de intervalos entre cada cobrança. Ex.: `intervalCount: 3` com `interval: month` = cobrança a cada 3 meses
  </Accordion>

  <Accordion title="cancelAtPeriodEnd:">
    ```json {2} theme={null}
    {
      "cancelAtPeriodEnd": false,
    }
    ```

    `cancelAtPeriodEnd` : <u> boolean. </u> <br />
    Se `true`, a assinatura será cancelada ao final do período atual em vez de renovar
  </Accordion>

  <Accordion title="currentPeriodStart / currentPeriodEnd:">
    ```json {2-3} theme={null}
    {
      "currentPeriodStart": "2024-11-15T10:00:00.000Z",
      "currentPeriodEnd": "2024-12-15T10:00:00.000Z",
    }
    ```

    `currentPeriodStart` / `currentPeriodEnd` : <u> string | null. </u> <br />
    Datas de início e fim do período de cobrança atual em formato ISO 8601
  </Accordion>

  <Accordion title="trialStartDate / trialEndDate:">
    ```json {2-3} theme={null}
    {
      "trialStartDate": null,
      "trialEndDate": null,
    }
    ```

    `trialStartDate` / `trialEndDate` : <u> string | null. </u> <br />
    Datas do período de teste em formato ISO 8601. `null` se não há período de teste
  </Accordion>

  <Accordion title="cancellationReason:">
    ```json {2} theme={null}
    {
      "cancellationReason": null,
    }
    ```

    `cancellationReason` : <u> string | null. </u> <br />
    Motivo do cancelamento. Valores: `low_quality`, `missing_features`, `other`, `switched_service`, `too_complex`, `too_expensive`, `unused`
  </Accordion>

  <Accordion title="items:">
    ```json {2-12} theme={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"
        }
      ]
    }
    ```

    `items` : <u> array. </u> <br />
    Lista de itens da assinatura. Cada item contém `id`, `subscriptionId`, `productId`, `priceId`, `name`, `amount` (em centavos), `quantity`, `createdAt` e `updatedAt`
  </Accordion>

  <Accordion title="canceledAt:">
    ```json {2} theme={null}
    {
      "canceledAt": null,
    }
    ```

    `canceledAt` : <u> string | null. </u> <br />
    Data em que a assinatura foi cancelada em formato ISO 8601. `null` se ativa
  </Accordion>

  <Accordion title="createdAt:">
    ```json {2} theme={null}
    {
      "createdAt": "2024-11-15T10:00:00.000Z",
    }
    ```

    `createdAt` : <u> string. </u> <br />
    Data de criação da assinatura em formato ISO 8601
  </Accordion>

  <Accordion title="updatedAt:">
    ```json {2} theme={null}
    {
      "updatedAt": "2024-11-15T10:00:00.000Z",
    }
    ```

    `updatedAt` : <u> string. </u> <br />
    Data da última atualização da assinatura em formato ISO 8601
  </Accordion>
</AccordionGroup>