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

# Create a Subscription

> Cria uma subscription.

Cria uma subscription para um customer. Sem trial, a subscription nasce
`incomplete` e a primeira invoice fica aberta com um `payment_intent`.
Quando a primeira cobrança é paga, a subscription vira `active`; se não for
paga em até 23 horas, vira `incomplete_expired`.

<ParamField body="customer" type="string" required>
  Customer da subscription (`cus_*`).
</ParamField>

<ParamField body="items" type="array" required>
  Itens recorrentes. Cada item usa `price` recorrente ou `price_data.recurring`.
</ParamField>

<ParamField body="default_payment_method" type="string">
  Payment method salvo (`pm_*`). Quando enviado, a primeira cobrança é
  enfileirada automaticamente.
</ParamField>

<ParamField body="collection_method" type="string">
  `charge_automatically` ou `send_invoice`. Padrão:
  `charge_automatically`.
</ParamField>

<ParamField body="days_until_due" type="integer">
  Dias até vencimento quando `collection_method` é `send_invoice`.
</ParamField>

<ParamField body="discount" type="string">
  Desconto aplicado às invoices da subscription.
</ParamField>

<Note>
  Em uma subscription com trial, se `default_payment_method` não for enviado, a
  resposta inclui `pending_setup_intent`. Busque esse setup intent para obter o
  `client_secret` e confirmar um cartão antes do fim do trial.
</Note>

<ParamField body="trial_period_days" type="integer">
  Dias de trial. Durante o trial a subscription fica `trialing`. Use apenas um
  entre `trial_period_days` e `trial_end`.
</ParamField>

<ParamField body="trial_end" type="string">
  Timestamp ISO 8601 exato para o fim do trial. Use apenas um entre
  `trial_end` e `trial_period_days`.
</ParamField>

<ParamField body="trial_settings" type="object">
  Política de fim de trial.

  <Expandable title="Campos de trial_settings">
    <ParamField body="end_behavior.missing_payment_method" type="string">
      Um de `create_invoice`, `pause` ou `cancel`. Use `pause` para deixar a
      subscription em `paused` quando o trial terminar sem payment method, sem
      criar a invoice do fim do trial.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="metadata" type="object">
  Metadata livre.
</ParamField>

<RequestExample>
  ```bash Com price de catálogo theme={}
  curl -X POST "https://api.chargefy.io/v1/subscriptions" \
    -H "Authorization: Bearer {{API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "customer": "cus_123",
      "items": [
        {
          "price": "price_123"
        }
      ]
    }'
  ```

  ```bash Com price_data inline theme={}
  curl -X POST "https://api.chargefy.io/v1/subscriptions" \
    -H "Authorization: Bearer {{API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "customer": "cus_123",
      "items": [
        {
          "price_data": {
            "recurring": {
              "interval": "month"
            },
            "unit_amount": 10000
          }
        }
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Trial com setup intent pendente theme={}
  {
    "id": "sub_123",
    "object": "subscription",
    "billing_cycle_anchor": "2026-05-19T18:00:00Z",
    "billing_mode": {
      "type": "classic"
    },
    "cancel_at": null,
    "cancel_at_period_end": false,
    "canceled_at": null,
    "cancellation_details": {
      "comment": null,
      "feedback": null,
      "reason": null
    },
    "collection_method": "charge_automatically",
    "created_at": "2026-05-19T18:00:00Z",
    "currency": "brl",
    "current_period_end": "2026-06-02T18:00:00Z",
    "current_period_start": "2026-05-19T18:00:00Z",
    "customer": "cus_123",
    "days_until_due": null,
    "default_payment_method": null,
    "ended_at": null,
    "items": {
      "object": "list",
      "data": [],
      "has_more": false,
      "url": "/v1/subscription-items?subscription=sub_123"
    },
    "latest_invoice": "in_123",
    "livemode": true,
    "metadata": {},
    "next_billing_at": "2026-06-02T18:00:00Z",
    "pause_collection": null,
    "payment_settings": {},
    "pending_setup_intent": "seti_123",
    "pending_update": null,
    "start_date": "2026-05-19T18:00:00Z",
    "status": "trialing",
    "trial_end": "2026-06-02T18:00:00Z",
    "trial_settings": {
      "end_behavior": {
        "missing_payment_method": "pause"
      }
    },
    "trial_start": "2026-05-19T18:00:00Z",
    "updated_at": "2026-05-19T18:00:00Z"
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json Response 200 theme={}
  {
    "id": "sub_123",
    "object": "subscription",
    "billing_cycle_anchor": "2026-05-19T18:00:00Z",
    "billing_mode": {
      "type": "classic"
    },
    "cancel_at": null,
    "cancel_at_period_end": false,
    "canceled_at": null,
    "cancellation_details": {
      "comment": null,
      "feedback": null,
      "reason": null
    },
    "collection_method": "charge_automatically",
    "created_at": "2026-05-19T18:00:00Z",
    "currency": "brl",
    "current_period_end": "2026-06-19T18:00:00Z",
    "current_period_start": "2026-05-19T18:00:00Z",
    "customer": "cus_123",
    "days_until_due": null,
    "default_payment_method": "pm_123",
    "ended_at": null,
    "items": {
      "object": "list",
      "data": [],
      "has_more": false,
      "url": "/v1/subscription-items?subscription=sub_123"
    },
    "latest_invoice": "in_123",
    "livemode": true,
    "metadata": {},
    "next_billing_at": "2026-06-19T18:00:00Z",
    "pause_collection": null,
    "payment_settings": {},
    "pending_setup_intent": null,
    "pending_update": null,
    "start_date": "2026-05-19T18:00:00Z",
    "status": "incomplete",
    "trial_end": null,
    "trial_settings": {
      "end_behavior": {
        "missing_payment_method": "create_invoice"
      }
    },
    "trial_start": null,
    "updated_at": null
  }
  ```
</ResponseExample>