Skip to main content
Use the subscription status to decide customer access and operational follow-up.

​
Statuses

​
Renewals

When the billing period ends, active and trialing subscriptions renew: Pagou charges the card, or, for Pix Automático, the payer’s bank debits the authorized amount. Successful renewals emit subscription.started after a trial or subscription.renewed for later cycles.

​
Failed payments

failure_policy controls what happens after a failed card renewal:
  • retry_then_cancel: move through retry handling before cancellation.
  • immediate_cancel: cancel when the renewal cannot be collected.
Use retry_offsets_days only when you need explicit retry spacing. For Pix Automático, retry timing cannot be configured and retry_offsets_days has no effect. See how failed debits work in Pix Automático Subscriptions.

​
Plan changes

Plan changes are available for card subscriptions. On a Pix Automático subscription, PATCH 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). PATCH /v2/subscriptions/{id} with a product_id moves a card subscription to another plan of the same product family. Moving up a tier is charged immediately, for the remaining part of the period, and keeps the renewal date. Moving down a tier on an active subscription is scheduled: nothing is charged, nothing is refunded, and the new plan takes effect at current_period_end. A change between plans on different billing cycles is always immediate, at the full price, and restarts the renewal date. While a change is scheduled, pendingChange holds the target plan, the amount the renewal will bill — the plan plus anything billed alongside it — and the date it applies. The renewal that follows bills the new plan and clears pendingChange. Send the current plan’s product_id to cancel a scheduled change. The status does not change because of a plan change, with one exception: a past_due subscription that settles the open cycle at the new plan’s full price returns to active.

​
Cancellation

Card: POST /v2/subscriptions/{id}/cancel schedules cancellation at the end of the current period. The subscription becomes cancel_scheduled immediately, emits subscription.updated, and later moves to canceled. Pix Automático: the cancellation is immediate and emits subscription.canceled. The response is either already canceled, or keeps the current status with recurringAuthorization.status: "cancel_pending" until the cancellation is confirmed. See Pix Automático Subscriptions.