Create a Subscription

​

Prerequisites

• Subscriptions must be enabled for your account.
• The customer must already exist in /v2/customers.
• The card must be collected with Payment Element and returned as a pgct_ token.

​

Backend request

curl --request POST \
  --url https://api.pagou.ai/v2/subscriptions \
  --header "Authorization: Bearer YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "customer_id": "9f9a8df6-0b3d-40d5-9f6b-a9e96c0a9101",
    "token": "pgct_example_token",
    "amount": 4900,
    "currency": "BRL",
    "interval": "month",
    "interval_count": 1,
    "failure_policy": "retry_then_cancel",
    "metadata": {
      "plan": "pro"
    }
  }'

​

Behavior

• amount is in cents and is used for each billing cycle.
• Without trial_end, the first charge runs immediately and the subscription starts as active after success.
• With trial_end, Pagou may validate the card first and keep the subscription as trialing until the trial ends.
• An unknown customer_id returns 404.
• A disabled subscription permission returns 403.

​

What to store

• subscription id
• customer id
• current status
• current_period_start and current_period_end
• latest transaction id, when present

​

Read next

• Subscription Lifecycle
• Subscription Webhooks
• API: Create a Subscription