> ## Documentation Index > Fetch the complete documentation index at: https://developer.pagou.ai/llms.txt > Use this file to discover all available pages before exploring further. # Pix Automático Subscriptions > Bill a customer on a recurring schedule with Pix Automático: the payer authorizes once with a QR code and their bank debits each cycle. With Pix Automático, the payer authorizes the recurring debit once, in their bank app, by scanning a QR code. From then on, the payer's bank debits each cycle and Pagou tells you the outcome through subscription webhooks. ## How it works 1. Create the customer with `POST /v2/customers`, including a CPF or CNPJ. 2. Create the subscription with `payment_method: "pix_automatic"`. No card token is involved. 3. Show `authorization.qr_code` to the payer. 4. The payer authorizes the recurring debit in their bank app. 5. The payer's bank debits each cycle. Listen to subscription webhooks to follow authorizations, payments, failures, and cancellation. What changes compared to card subscriptions: | | Card | Pix Automático | | --------------------------- | --------------------------------------------------------------------------- | ---------------------------------------- | | Status right after creation | `active` or `trialing` | `incomplete`, until the payer authorizes | | Who starts each charge | Pagou | the payer's bank | | Cancellation | at the end of the period (`cancel_scheduled`), emits `subscription.updated` | immediate, emits `subscription.canceled` | | Plan change | available | not available | ## Prerequisites * Subscriptions must be enabled for your account (`403` otherwise), and so must Pix Automático (`422` otherwise). See **Errors**. * The customer must exist in `/v2/customers` with a CPF or CNPJ in `document`. Address and phone are optional. * `currency` must be `BRL`. ## Create a subscription without a trial Without `trial_end`, the same QR code authorizes the recurring debit **and** pays the first cycle. ```bash theme={null} 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", "payment_method": "pix_automatic", "amount": 4900, "currency": "BRL", "interval": "month", "interval_count": 1, "billing_day_of_month": 10, "comment": "Pro plan", "failure_policy": "retry_then_cancel", "metadata": { "plan": "pro" } }' ``` Response `201`: ```json theme={null} { "success": true, "requestId": "0190a2b4-18a7-7de0-9a43-69b7cf261201", "data": { "id": "019e5d23-6ec8-73de-9c95-06093c62ba00", "customerId": "9f9a8df6-0b3d-40d5-9f6b-a9e96c0a9101", "status": "incomplete", "paymentMethod": "pix_automatic", "billingModel": "provider_initiated", "billingDayOfMonth": 10, "interval": "month", "intervalCount": 1, "amount": 4900, "currency": "BRL", "trialEnd": null, "currentPeriodStart": "2026-09-23T14:00:00.000Z", "currentPeriodEnd": "2026-10-23T14:00:00.000Z", "cancelAtPeriodEnd": false, "canceledAt": null, "failurePolicy": "retry_then_cancel", "retryOffsetsDays": [1, 2, 3, 4, 5], "cancellationReason": null, "customerEmail": "buyer@example.com", "cardLast4": null, "metadata": { "plan": "pro" }, "informations": null, "products": [], "authorization": { "type": "pix_qr", "qr_code": "00020101021226870014br.gov.bcb.pix2565qr.example.com/rec/019e5d236ec85204000053039865802BR6304A1B2", "expires_at": "2026-09-24T14:00:00.000Z", "status": "awaiting_customer" }, "recurringAuthorization": { "status": "pending" }, "createdAt": "2026-09-23T14:00:00.000Z", "updatedAt": "2026-09-23T14:00:00.000Z" } } ``` The subscription stays `incomplete` until the payer authorizes **and** the first debit is paid. At that point it becomes `active` and you receive `subscription.started` with `previous_status: "incomplete"`. This flow does **not** send `subscription.created`. ## Create a subscription with a trial Send `trial_end` (ISO 8601, in the future) and the QR code only authorizes the recurring debit. Nothing is charged until the trial ends. Trials depend on your account configuration. When they are not available, the request returns `422` with `PIX_AUTOMATIC_TRIAL_NOT_SUPPORTED` and nothing is created. Where trials are available, also send `billing_day_of_month`. The first debit is scheduled for the first occurrence of that day on or after the signup date, and that date must fall on or after `trial_end` and at least 3 full days (72 hours) after the moment of signup. Without `billing_day_of_month`, the billing day is the signup day, so the first debit would fall before the trial ends and the request is rejected. When the dates do not fit, the request returns `422` with `PIX_AUTHORIZATION_FAILED` and a `detail` that explains why. In this example the subscription is created on September 23, with `trial_end` on October 7 and `billing_day_of_month: 10`, so the first debit is scheduled for October 10: ```bash theme={null} 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", "payment_method": "pix_automatic", "amount": 4900, "currency": "BRL", "interval": "month", "interval_count": 1, "billing_day_of_month": 10, "trial_end": "2026-10-07T00:00:00.000Z" }' ``` Response `201`: ```json theme={null} { "success": true, "requestId": "0190a2b4-18a7-7de0-9a43-69b7cf261202", "data": { "id": "019e5d23-7a10-7c4e-8f21-3b5d8e0a1c02", "customerId": "9f9a8df6-0b3d-40d5-9f6b-a9e96c0a9101", "status": "incomplete", "paymentMethod": "pix_automatic", "billingModel": "provider_initiated", "billingDayOfMonth": 10, "interval": "month", "intervalCount": 1, "amount": 4900, "currency": "BRL", "trialEnd": "2026-10-07T00:00:00.000Z", "currentPeriodStart": "2026-09-23T14:00:00.000Z", "currentPeriodEnd": "2026-10-07T00:00:00.000Z", "cancelAtPeriodEnd": false, "canceledAt": null, "failurePolicy": "retry_then_cancel", "retryOffsetsDays": [1, 2, 3, 4, 5], "cancellationReason": null, "customerEmail": "buyer@example.com", "cardLast4": null, "metadata": null, "informations": null, "products": [], "authorization": { "type": "pix_qr", "qr_code": "00020101021226870014br.gov.bcb.pix2565qr.example.com/rec/019e5d237a107c4e5204000053039865802BR6304C3D4", "expires_at": null, "status": "awaiting_customer" }, "recurringAuthorization": { "status": "pending" }, "createdAt": "2026-09-23T14:00:00.000Z", "updatedAt": "2026-09-23T14:00:00.000Z" } } ``` When the payer approves the authorization, the subscription becomes `trialing` and you receive `subscription.created` (with `latest_transaction: null`). Three days before `trial_end` you receive `subscription.trial_will_end`, if the subscription is already `trialing` by then. The first debit after the trial makes it `active` and sends `subscription.started`. ## Request fields | Field | Required | Notes | | --------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `customer_id` | yes | public customer id. The customer needs a CPF or CNPJ. | | `payment_method` | yes | `"pix_automatic"`. Do not send `token`: the request is rejected. | | `amount` | yes | cents, billed every cycle. Some accounts require at least `100` (R\$ 1,00). | | `interval` / `interval_count` | yes / no | see **Billing intervals**. `interval_count` defaults to `1`. | | `billing_day_of_month` | no | `1` to `31`. Values above `27` are treated as `27`. Without a trial it is a preference, not a guaranteed debit date. With a trial, send it: it schedules the first debit (see **Create a subscription with a trial**). | | `comment` | no | up to 140 characters. It may be shown to the payer, depending on your account configuration. | | `trial_end` | no | see **Create a subscription with a trial**. | | `failure_policy` | no | `retry_then_cancel` (default) or `immediate_cancel`. See **Failed debits**. | | `metadata`, `informations`, `idempotency_key` | no | same behavior as card subscriptions. | ### Billing intervals | `interval` | `interval_count` | Availability | | ---------- | ---------------- | ------------------------------------- | | `week` | `1` | available | | `month` | `1`, `6`, `12` | available | | `month` | `3` | depends on your account configuration | | `day` | any | never available | Any other combination, or one your account does not support, returns `422` with `PIX_AUTHORIZATION_FAILED` and a `detail` that says the interval is not supported. ## Show the QR code The `authorization` block is what the payer needs: | Field | Meaning | | ------------------ | ---------------------------------------------------------------------------- | | `type` | always `pix_qr` | | `qr_code` | Pix copy-and-paste code. Render it as a QR code or offer it for copying. | | `payment_link_url` | hosted page where the payer can authorize, when available. It may be absent. | | `expires_at` | when the code expires, when known. It may be `null`. | | `status` | `awaiting_customer` | `GET /v2/subscriptions/{id}` returns `authorization` only while the authorization is pending. After the payer approves or rejects it, the block disappears. If the payer never authorizes, what happens depends on your account configuration: the subscription either stays `incomplete`, or is canceled when the code expires and you receive `subscription.canceled`. To stop waiting, cancel it yourself (see **Cancel**). `recurringAuthorization.status` tells you where the authorization stands: `pending`, `approved`, `rejected`, `cancel_pending`, or `canceled`. On `GET` by id, `recurringAuthorization.lastDebit` shows the most recent debit attempt. ## What to store * subscription `id` * customer `id` * current `status` * `authorization.qr_code`, while the authorization is pending * `recurringAuthorization.status` * `latest_transaction.id` from the webhooks, when present ## Status and webhooks | Moment | Status | Webhook (`data.event_type`) | | -------------------------------------------------------------------------------------------- | --------------------- | ---------------------------------------------- | | subscription created, without a trial | `incomplete` | none | | payer authorized and first debit paid, without a trial | `active` | `subscription.started` | | subscription created, with a trial | `incomplete` | none | | payer authorized, with a trial | `trialing` | `subscription.created` | | 3 days before `trial_end`, if already `trialing` | `trialing` | `subscription.trial_will_end` | | first debit paid after the trial | `active` | `subscription.started` | | payer rejected the authorization, or let it expire (depending on your account configuration) | `canceled` | `subscription.canceled`, with `failure_reason` | | a later cycle was paid | `active` | `subscription.renewed` | | a debit failed | see **Failed debits** | `subscription.payment_failed` | | subscription canceled | `canceled` | `subscription.canceled` | Things to know when you handle these events: * Pix Automático charges are reported **only** through `subscription.*` events. You do not receive `transaction.*` webhooks for them. * `latest_transaction.method` is `"pix"`. The payload does not say which payment method the subscription uses, so identify Pix Automático subscriptions by the `id` you stored, or read `paymentMethod` with `GET /v2/subscriptions/{id}`. * `failure_reason` is informative. Do not build logic on specific values. ## Failed debits The payer's bank may try a debit more than once. Those intermediate attempts do not generate events. When no attempts are left, you receive `subscription.payment_failed` with `attempt_number` and `failure_reason`. * If it was the first debit of a subscription **without** a trial, the subscription stays `incomplete`. * Otherwise (the first debit after a trial, or a later cycle), with `failure_policy: retry_then_cancel` the subscription becomes `past_due` and you receive `subscription.past_due`. For a later cycle, a debit paid afterwards makes it `active` again and sends `subscription.renewed`. * A failed debit does not create a new transaction. On `subscription.payment_failed` and `subscription.past_due`, `latest_transaction` is the most recent transaction of the subscription, which is usually the previous paid cycle. * `retry_offsets_days` is accepted but has no effect: retry timing follows the Pix Automático rules and cannot be configured. * Anything else `failure_policy` does for Pix Automático depends on your account configuration. `subscription.canceled` is the only confirmation that a subscription ended. ## Cancel `POST /v2/subscriptions/{id}/cancel` works while the subscription is `incomplete`, `trialing`, `active`, or `past_due`. For Pix Automático the cancellation is **immediate**: it is never scheduled for the end of the period, the status never becomes `cancel_scheduled`, and the webhook is `subscription.canceled`, not `subscription.updated`. The response comes in one of two forms, depending on your account configuration: * **Already canceled:** `status` is `canceled` and `recurringAuthorization.status` is `canceled`. * **Waiting for confirmation:** `status` keeps its current value and `recurringAuthorization.status` is `cancel_pending`. The subscription becomes `canceled` once the cancellation is confirmed, and you receive `subscription.canceled` then. In both cases, treat `subscription.canceled` as the source of truth. Repeating the call on a subscription that is `canceled`, or whose cancellation is waiting for confirmation, returns `200` with no change. Two concurrent calls on the same subscription may return `409` with `SUBSCRIPTION_CANCEL_IN_PROGRESS`; retry after a short wait. ## Limitations * **Plan changes are not available.** `PATCH /v2/subscriptions/{id}` with `product_id` returns `422` and the plan stays the same: `PLAN_CHANGE_UNAVAILABLE_FOR_PAYMENT_METHOD` when the subscription is tied to a catalog plan, or `SUBSCRIPTION_HAS_NO_CATALOG_PLAN` / `PRODUCT_NOT_FOUND` when it is not. To move the payer to another plan, cancel the subscription and create a new one, which needs a new authorization. * **Billing intervals** are limited to the table in **Request fields**. * **Trials** depend on your account configuration. * **Retry spacing** cannot be configured: `retry_offsets_days` is ignored. * **The debit date is not guaranteed.** Follow the webhooks instead of expecting a charge on a fixed day. ## Errors | Situation | HTTP | `code` | | ---------------------------------------------------------------------------------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Subscriptions are not enabled for your account | `403` | `FORBIDDEN` | | Pix Automático is not enabled for your account | `422` | `UNSUPPORTED_PAYMENT_METHOD`, `PIX_AUTOMATIC_ACCOUNT_NOT_ELIGIBLE`, or `PIX_AUTOMATIC_SUBACCOUNT_REQUIRED` | | Pix Automático is not configured for your account | `400` | `BAD_REQUEST` | | The customer has no CPF or CNPJ | `400` | `BAD_REQUEST` | | Unknown `customer_id` | `404` | `NOT_FOUND` | | `trial_end` is not available for your account | `422` | `PIX_AUTOMATIC_TRIAL_NOT_SUPPORTED` | | Unsupported interval, amount below your account's minimum, or trial dates that do not fit `billing_day_of_month` | `422` | `PIX_AUTHORIZATION_FAILED` | | The authorization could not be set up. The subscription is created as `canceled`. | `422` | `PIX_AUTHORIZATION_FAILED` | | Plan change requested | `422` | `PLAN_CHANGE_UNAVAILABLE_FOR_PAYMENT_METHOD`, or `SUBSCRIPTION_HAS_NO_CATALOG_PLAN` / `PRODUCT_NOT_FOUND` when the subscription is not tied to a catalog plan | | Cancellation already running for the same subscription | `409` | `SUBSCRIPTION_CANCEL_IN_PROGRESS` | When Pix Automático is not enabled or not configured, contact support to enable it for your account. ## Sandbox In the sandbox (`https://api.sandbox.pagou.ai`) there is no payer's bank on the other side: nobody scans the QR code and nothing is debited on its own. You play the payer's bank with `POST /v2/subscriptions/{id}/simulate`. The subscription moves exactly as it would in production and you receive the same webhooks. Create the customer and the subscription as described above, with your sandbox token. Then send one event per call: ```bash theme={null} curl --request POST \ --url https://api.sandbox.pagou.ai/v2/subscriptions/019e5d23-6ec8-73de-9c95-06093c62ba00/simulate \ --header "Authorization: Bearer YOUR_SANDBOX_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "event": "authorize" }' ``` The response is `200` with the updated subscription, in the same shape as `GET /v2/subscriptions/{id}`. | `event` | Accepted while `recurringAuthorization.status` is | Without a trial | With a trial | | ----------- | ------------------------------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | `authorize` | `pending` | the payer authorizes and the first cycle is paid: `active`, `subscription.started` | the payer authorizes: `trialing`, `subscription.created` | | `reject` | `pending` | the payer refuses: `canceled`, `subscription.canceled` with `failure_reason` | same | | `pay` | `approved` | the next cycle is paid: `subscription.renewed` | the first debit is paid: `active`, `subscription.started`; after that, `subscription.renewed` | | `fail` | `approved` | the debit fails: `subscription.payment_failed`, then see below | same | After `fail`, with `failure_policy: retry_then_cancel` the subscription becomes `past_due` and you receive `subscription.past_due`; for a later cycle, a `pay` makes it `active` again with `subscription.renewed`. With `immediate_cancel` it becomes `canceled` and you receive `subscription.canceled`. With a trial, a `fail` before the first debit is paid leaves the subscription `past_due` and no `pay` recovers it: cancel it and create a new one to keep testing. What to know about the sandbox: * One call is one event. Each `pay` pays one cycle right away, whatever the billing interval. * The subscription moves only when you call the endpoint. Do not rely on time-based events such as `subscription.trial_will_end` in the sandbox. * An event that does not fit the current authorization or status returns `409` with `SUBSCRIPTION_SIMULATION_NOT_APPLICABLE` and changes nothing: for example, `pay` before `authorize`, or `authorize` twice. * `authorization.qr_code` has the Pix format, but it does not set up a real recurring authorization: do not scan it with a bank app, use `authorize` instead. `expires_at` is `null` and the authorization never expires on its own: use `reject` to test a refused authorization. * The sandbox accepts `trial_end` without checking it against `billing_day_of_month`, and the first debit happens when you send `pay`. In production, trials depend on your account configuration and the dates must fit (see **Create a subscription with a trial**). * Billing intervals are `week` × `1` and `month` × `1`, `6`, or `12`. `month` × `3` is refused, and so is an amount below `100`. * A cancellation responds already `canceled`. * Do not use `PUT /v2/transactions/{id}` on a Pix Automático charge: it changes the transaction but not the subscription. * The Pix values in [Test Data](/start-here/test-data) (documents and the `7300` amount) do not apply to Pix Automático. * The route exists only in the sandbox. In production it returns `404`. ## Read next * [Subscriptions Overview](/subscriptions/overview) * [Subscription Lifecycle](/subscriptions/lifecycle) * [Subscription Webhooks](/subscriptions/webhooks) * [API: Create a Subscription](/api-reference/subscriptions/create) * [API: Cancel a Subscription](/api-reference/subscriptions/cancel) * [API: Simulate a Pix Automático Event](/api-reference/subscriptions/simulate)