Automatic Pix offer on API subscriptions

Subscriptions created via API now offer Pix Automático to the payer, without you needing to change the integration of subscriptions you already have.

📘

By completing this guide, you will have created a subscription eligible for the automatic offer, identified the authorization linked to it, and set up webhook tracking.

The goal is to increase the recurrence and predictability of your Pix subscription revenue, without creating a second integration.

🚧

Attention

The automatic offer is available for accounts eligible for Pix Automático. Subscriptions created before the feature became available do not receive the offer. Production release: 10/29/2026.

When to use

Use this offer when:

  • your integration creates subscriptions via API with payment by Pix, bank slip, or "Ask the Customer";
  • you want the payer to be able to authorize automatic debit of the next charges, without a new integration;
  • you want to track the authorization and the debits of the subscriptions through webhooks.

Before you start

Before implementing:

  • confirm that the account is eligible for Pix Automático: approved account, approved documents, registered Pix key, and active Pix receipts;
  • define whether the offer should be made on all subscriptions or only on some of them, using the field pixAutomaticAuthorizationMode;
  • configure the Pix Automático event webhooks that will track the authorization and the charges.

To understand the difference between this journey and Pix Automático with mandatory authorization, see Difference between Pix Automático and Subscriptions.

Conditions for the subscription to receive the offer

The offer is generated when all the conditions below are met.

ConditionRule
AccountThe account must be eligible for Pix Automático. Eligibility changes are notified by the event PIX_AUTOMATIC_RECURRING_ELIGIBILITY_UPDATED.
Payment method (billingType)PIX, BOLETO, or UNDEFINED (shown as "Ask the Customer"). Subscriptions with CREDIT_CARD do not receive the offer.
Frequency (cycle)WEEKLY, MONTHLY, QUARTERLY, SEMIANNUALLY, or YEARLY. The cycles BIWEEKLY and BIMONTHLY do not receive the offer.
DiscountThe subscription cannot have a discount (discount) configured, percentage or fixed amount.
Authorization modeThe field pixAutomaticAuthorizationMode cannot be set to DISABLED.
Creation dateOnly subscriptions created from the date the feature became available.

The offer is presented on the subscription's current charge. Only the current charge is generated with a composed QR Code: if other charges were already created, they keep the standalone QR Code. While the authorization is pending (CREATED), the offer continues on the next charges, until the authorization is activated or ended by the EXPIRED event.

The offer behaves the same way for subscriptions created through the Asaas interface.

A subscription that does not meet the conditions is created normally, without Pix Automático authorization, and its charges follow as regular charges.

How it works

When you create an eligible subscription via API, Asaas:

  1. creates a Pix Automático authorization linked to the subscription;
  2. generates the subscription's current charge with a composed QR Code, which combines the charge data and the recurrence's location data;
  3. after the payer authorizes, automatically sends the payment instructions of the following charges to the payer's bank.
📘

The open charge of the subscription is the one that carries the offer. At creation, it is the first charge. If it is paid without activating Pix Automático or expires, the next charge becomes the current one and receives the composed QR Code.

📘

Journey 4 is the term in the Pix Regulation for the flow in which the payer pays or schedules a charge with a due date and, only afterwards, receives the offer to authorize Pix Automático. The Pix arrangement's recurrence corresponds, in the Asaas API, to the Pix Automático authorization. The states CRIADA, APROVADA, CANCELADA and EXPIRADA correspond to the authorization statuses CREATED, ACTIVE, CANCELLED, and EXPIRED.

Offer and authorization Following charges with active authorization
ItemBehavior in your integration
Subscription creation requestNo new field is required. The optional field pixAutomaticAuthorizationMode allows you to disable the offer on a specific subscription.
Current charge QR CodeStill obtained through the invoice or the Pix QR Code endpoint. On the current charge, the payload contains the recurrence location.
AuthorizationLinked to the subscription and can be queried with the subscriptionId filter in the authorization listing.
Following chargesIf the authorization is active, they are debited automatically on the due date. If it is still pending (CREATED), the payer pays them as regular charges.

Difference from Pix Automático with mandatory authorization

Automatic offer on subscriptions (Journey 4)Mandatory authorization (Journey 3)
Charge that carries the offerCurrent charge, with a due date, which can be paid or scheduledImmediate payment
AuthorizationOptional, offered after payment or schedulingMandatory, granted together with the payment
How to enableAutomatic on eligible subscriptionsSee the Pix Automático implementation guide

1. Create the subscription

Use the same endpoint as Create new subscription: POST /v3/subscriptions. To receive the offer, you do not need to send any new field.

{
  "customer": "cus_000005219613",
  "billingType": "PIX",
  "value": 89.90,
  "nextDueDate": "2026-12-10",
  "cycle": "MONTHLY",
  "description": "Monthly plan",
  "externalReference": "subscription-123"
}

To disable the offer on this subscription, send the field with the value DISABLED:

{
  "customer": "cus_000005219613",
  "billingType": "PIX",
  "value": 89.90,
  "nextDueDate": "2026-12-10",
  "cycle": "MONTHLY",
  "pixAutomaticAuthorizationMode": "DISABLED"
}
FieldTypeRequiredDescription
pixAutomaticAuthorizationModestringNoPix Automático offer mode on the subscription. Accepted values: OPTIONAL (default) and DISABLED.

The other parameters follow the reference for Create new subscription.

The creation response includes the field pixAutomaticAuthorizationMode with the subscription's effective mode. OPTIONAL indicates that the offer was generated; DISABLED indicates that it was not, either because it was explicitly sent or because the subscription is ineligible.

Response with the field omitted and an eligible subscription:

{
  "object": "subscription",
  "id": "sub_vsqwcqmdykq5tm2l",
  "dateCreated": "2026-11-06",
  "customer": "cus_000009547456",
  "paymentLink": null,
  "value": 10.00,
  "nextDueDate": "2026-12-11",
  "cycle": "WEEKLY",
  "description": null,
  "billingType": "UNDEFINED",
  "deleted": false,
  "status": "ACTIVE",
  "externalReference": null,
  "checkoutSession": null,
  "sendPaymentByPostalService": false,
  "fine": { "value": 0.00, "type": "FIXED" },
  "interest": { "value": 0.00, "type": "PERCENTAGE" },
  "split": null,
  "pixAutomaticAuthorizationMode": "OPTIONAL"
}

The field takes effect from the subscription creation: if it is sent when updating the subscription, it is ignored.

🚧

Attention

Send OPTIONAL explicitly only when the Pix Automático offer is essential to your flow. If your integration creates subscriptions with varied settings, leave the field out: ineligible subscriptions are created without error.

Validations

SituationHTTP statuscodedescription
OPTIONAL and frequency not allowed400invalid_objectThe subscription frequency is not allowed for Pix Automático recurrences.
OPTIONAL and subscription with discount400invalid_objectPix Automático cannot be used on subscriptions with a configured discount.
OPTIONAL and payment method not allowed400invalid_objectPix Automático is only available for subscriptions with Pix or "Ask the Customer" charges.
OPTIONAL and account not eligible for Pix Automático400invalid_objectYou do not have permission to use this feature. Contact your account manager.
Value other than OPTIONAL or DISABLED400parse_errorThe field 'pixAutomaticAuthorizationMode' provided is invalid.

In all cases the subscription is not created. Error response format:

{
  "errors": [
    {
      "code": "invalid_object",
      "description": "Pix Automático cannot be used on subscriptions with a configured discount."
    }
  ]
}

2. Make the current charge available to the payer

The subscription's charges are obtained as for any subscription, through List charges of a subscription (GET /v3/subscriptions/{id}/payments), where {id} is the subscription identifier returned in Step 1. At creation, the current charge is the first one.

To present the payment to the payer, use one of the options you already use:

  • the charge's invoice link (invoiceUrl); or
  • the Get Pix QR Code for payments endpoint (GET /v3/payments/{id}/pixQrCode), where {id} is the charge identifier.

On subscriptions with the offer, the current charge's QR Code payload is a composed QR Code. The other charges created keep the standalone QR Code. You do not need to choose the format: Asaas returns the composed QR Code on the current charge and the standalone one on the others. No new field is returned. The payer's bank reads the QR Code, processes the payment or scheduling, and at the end presents the Pix Automático offer.

🚧

Attention

Do not build the QR Code manually and do not validate the size or internal structure of the payload. Pass to the payer exactly the content returned by Asaas.

3. Identify the authorization linked to the subscription

Use List authorizations with the subscriptionId filter to find the Pix Automático authorization generated for the subscription: GET /v3/pix/automatic/authorizations?subscriptionId={subscriptionId}.

Query parameterTypeRequiredDescription
subscriptionIdstringNoSubscription identifier in Asaas, returned when the subscription is created (Step 1).

The status and customerId filters, and offset and limit pagination, remain available and can be combined with subscriptionId.

Example listing response:

{
  "object": "list",
  "hasMore": false,
  "totalCount": 1,
  "limit": 10,
  "offset": 0,
  "data": [
    {
      "id": "f491dd86-c552-4468-9d9b-ad0eda4c0aa0",
      "contractId": "1619468",
      "customerId": "cus_000009547456",
      "frequency": "WEEKLY",
      "startDate": "2026-11-06",
      "status": "CREATED",
      "value": 10.00,
      "originType": "PAYMENT_AND_RECURRING_OFFER_QR_CODE",
      "subscriptionId": "sub_vsqwcqmdykq5tm2l",
      "paymentCreationMode": "SUBSCRIPTION",
      "retryPolicy": "NOT_ALLOWED"
    }
  ]
}
FieldDescription
idAuthorization identifier. Use it to relate webhook events and payment instructions to the subscription.
statusCurrent authorization status. Right after the subscription is created, the status is CREATED.
subscriptionIdSubscription that originated the authorization.
originTypeAuthorization origin. The value PAYMENT_AND_RECURRING_OFFER_QR_CODE identifies authorizations generated by the automatic offer on subscriptions.
paymentCreationModeHow the authorization's charges are created. On subscription authorizations, the value is SUBSCRIPTION.
retryPolicyDebit retry policy. On subscription authorizations, the value is NOT_ALLOWED.
📘

Recommended

Store the subscriptionId ↔ authorization.id pair in your system. Payment instruction events carry paymentInstruction.authorization.id and paymentInstruction.paymentId, and these identifiers are how you reconcile each automatic debit with the subscription and the charge.

4. Track the authorization and the debits through webhooks

Enable the Pix Automático events in addition to the charge events your integration already consumes. It is not necessary to query the authorization listing periodically.

📘

Important

Webhook delivery is asynchronous and the order between events is not guaranteed. Do not rely on order and use authorization.id, subscriptionId, and paymentId to correlate the events.

Authorization events

EventWhen it occurs in this journey
PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CREATEDThe authorization is created for the eligible subscription.
PIX_AUTOMATIC_RECURRING_AUTHORIZATION_ACTIVATEDAsaas received the Pix Automático confirmation message from the payer's institution. It is independent of the charge settlement.
PIX_AUTOMATIC_RECURRING_AUTHORIZATION_REFUSEDNot issued in Journey 4. It only occurs in Journey 3.
PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CANCELLEDThe authorization was cancelled by the payer, by you, or as a result of a subscription change. The reason is provided in authorization.cancellationReason.
PIX_AUTOMATIC_RECURRING_AUTHORIZATION_EXPIREDThe authorization reached its end date, including when the payer never activated it.

Payment instruction events

EventWhen it occurs
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CREATEDThe debit instruction for a subscription charge is created.
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_SCHEDULEDThe payer's institution scheduled the debit for the due date.
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_REFUSEDThe instruction was refused at scheduling or processing.
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CANCELLEDThe instruction was cancelled.

Each charge's financial confirmation is still reported by the charge events (PAYMENT_CONFIRMED and PAYMENT_RECEIVED).

Expected sequences

Payer pays the current charge and authorizes Pix Automático

PAYMENT_CREATED (current charge)
↓
PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CREATED
↓
PAYMENT_RECEIVED and PIX_AUTOMATIC_RECURRING_AUTHORIZATION_ACTIVATED
(no fixed order between the two)

Following charges with active authorization

PAYMENT_CREATED
↓
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CREATED
↓
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_SCHEDULED
↓
PAYMENT_CONFIRMED

Debit refused due to insufficient balance or the payer's limit

PAYMENT_CREATED
↓
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CREATED
↓
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_SCHEDULED
↓
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_REFUSED

In Journey 4 there is no automatic debit retry. Retries are disabled by default (retryPolicy = NOT_ALLOWED). After INSTRUCTION_REFUSED, the charge stays pending and can be paid separately.

Payer pays the current charge without authorizing

PAYMENT_CREATED (current charge)
↓
PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CREATED
↓
PAYMENT_RECEIVED (current charge)

The authorization stays CREATED and the offer continues on the next charges.

Authorization that is never activated

PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CREATED
↓
(authorization stays CREATED while the offer is renewed on the current charges)
↓
PIX_AUTOMATIC_RECURRING_AUTHORIZATION_EXPIRED (on the end date)

Payer cancels the authorization after it was activated

PIX_AUTOMATIC_RECURRING_AUTHORIZATION_ACTIVATED
↓
PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CANCELLED

Charge changed while the authorization is active

(charge changed)
↓
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CANCELLED

Only that charge's instruction is cancelled. The authorization remains active.

See the cancellationReason values in Pix Automático authorization cancellation reasons.

🚧

Attention

Changes to essential subscription fields may cancel the authorization. With the authorization CREATED or ACTIVE, changing value, cycle, nextDueDate, billingType (except from UNDEFINED to PIX), or deactivating the subscription cancels the authorization. Changing interest, fine, or discount cancels only if the authorization is CREATED. Before changing a subscription with an active authorization, check the impact: if the authorization is cancelled, the payer will need to pay the charges manually.

Confirm the result

After creating an eligible subscription, check:

  • the creation response shows pixAutomaticAuthorizationMode = OPTIONAL;
  • the current charge returns the composed QR Code and the payer can see the offer when paying or scheduling;
  • the authorization listing, filtered by subscriptionId, returns the authorization with status CREATED;
  • the PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CREATED event is received by your webhook.

Final state of each scenario:

ScenarioSubscriptionFirst chargeAuthorizationFollowing charges
Payer pays or schedules the current charge and authorizesActivePaidACTIVEDebited automatically on the due date
Payer pays the first charge without authorizingActivePaidCREATEDRegular charges, paid by the payer. The offer continues until the authorization is activated or ended (EXPIRED)
Payer does not pay the first chargeActiveOverdueCREATEDThe next charge becomes the current one and receives the composed QR Code
Payer cancels the authorizationActivePaidCANCELLEDRegular charges, paid by the payer
You cancel the authorizationActivePaidCANCELLEDRegular charges, paid by the payer
You change an essential subscription fieldActiveDepends on paymentCANCELLEDRegular charges, paid by the payer
You remove the subscriptionRemovedDepends on paymentCANCELLEDNot generated

Best practices

  • Do not condition service delivery on the authorization. Payment of the charge must not depend on joining Pix Automático. A payer who pays without authorizing is in good standing.
  • Do not assume every subscription has an authorization. Ineligible subscriptions, those set to DISABLED, or those from ineligible accounts do not generate an authorization. Confirm via the pixAutomaticAuthorizationMode field in the response, the listing with subscriptionId, or the PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CREATED event.
  • Use the QR Code returned by Asaas. Only the current charge comes with the composed QR Code. On the other charges, the QR Code is standalone.
  • Track through webhooks, without depending on order. Use authorization events to know when automatic debit becomes effective and charge events for financial confirmation.
  • Implement idempotency. Webhooks follow an at-least-once delivery model. Persist the event id before processing. See How to implement idempotency in Webhooks.
  • Pass the QR Code through unchanged. The composed QR Code is larger than a common dynamic QR Code. Do not validate its size or payload structure.
  • Guide your payers. The offer appears in the payer's bank app at the end of paying or scheduling the current charge. While the authorization is not activated, it reappears on the next current charges.
  • Test in the Sandbox. You can test the offer in the Sandbox by paying the composed QR Code from one Asaas account to another, which is the simplest way.

API reference

📘

API reference

See the endpoints Create new subscription, List authorizations, and Cancel an authorization in the Reference.

Next steps


Did this page help you?