How to generate new charges from a subscription

In the Sandbox, you can use booklet generation to bring forward the creation of a subscription's future charges.

This feature lets you validate queries, reconciliations, and other processes that depend on these charges existing, without waiting for each cycle to be generated naturally.

When to use it

Use this feature to test:

• a subscription's future charges;
• recurrence flows;
• charge queries and synchronizations;
• reports and reconciliations;
• business rules related to upcoming cycles;
• events applicable to the generated charges.

Before you start

You need to:

1. Have a Sandbox account and API key.
2. Create a subscription.
3. Store the subscription ID.
4. Define the date up to which charges should be generated.
5. Use the booklet generation endpoint.

See Generate subscription booklet.

How it works

Normally, a subscription's charges are created gradually, according to the configured cycle.

When you generate the booklet, Asaas brings forward the creation of charges up to the end date provided.

Create subscription
        ↓
Generate booklet
        ↓
Provide the end date
        ↓
Create future charges
        ↓
Query and validate the results

1. Create a subscription

Create the subscription with the desired cycle, amount, and due date.

Store the returned ID, as it will be used to generate the booklet.

2. Generate the booklet

Use the booklet generation endpoint and provide the deadline for creating the charges.

The date determines up to which period charges will be brought forward.

For example:

• an end date in December generates charges up to that period;
• an end date in June of next year generates charges up to June;
• longer periods may generate more charges in a single operation.

3. Validate the generated charges

After running the operation:

1. query the charges linked to the subscription;
2. check the number created;
3. validate due dates and amounts;
4. confirm there were no duplicates;
5. process the applicable events;
6. validate reports, synchronizations, and reconciliations.

Generate charges
        ↓
Query through the API
        ↓
Validate count and due dates
        ↓
Process applicable events
        ↓
Update the application

Expected behavior

When generating the booklet:

• future charges are created up to the date provided;
• the charges become available for querying;
• the subscription keeps following its recurrence;
• no payment is made;
• the status of the charges is not changed to paid.

Impact on the integration

The operation may create several charges at once.

Your application must be prepared to:

• process multiple records;
• avoid duplicates during synchronizations;
• paginate queries when necessary;
• link each charge to the subscription;
• handle events received in sequence;
• update reports and reconciliations.

If the charges are not generated

Check that:

• the subscription belongs to the Sandbox;
• the subscription ID is correct;
• the subscription is active;
• the end date is later than the existing charges;
• the URL and the API key belong to the Sandbox;
• the required parameters were sent correctly.

Validation checklist

Before considering the flow validated, confirm that your application:

• identifies the charges by subscription;
• processes multiple charges without duplicates;
• validates amounts and due dates;
• handles pagination in queries;
• processes events idempotently;
• keeps logs of imported charges;
• distinguishes created charges from paid charges.

Next steps

• Generate subscription booklet
• Test credit card payments
• Configure payment Webhooks
• Query a subscription's charges
• Test other features in the Sandbox