Automatic Scheduling

What is Automatic Scheduling?

Automatic scheduling creates recurring payments automatically without merchant intervention. When enabled, the system automatically creates payments 48 hours before the due date, ensuring timely processing while giving customers advance notice.

This feature eliminates the need to manually create each recurring payment, reducing operational overhead and ensuring consistent payment timing.

How It Works

Requirements

Automatic scheduling is available when:

1. automaticScheduleAllowed: true - The subscription has automatic scheduling enabled
2. amountType: "FIXED" - Only fixed amounts can be automatically scheduled (variable amounts require manual creation)
3. Subscription is ACTIVE - The subscription must be in active status

Payment Creation Timeline

When a payment is successfully processed (PAID), the system automatically:

1. Calculates the next payment date based on the subscription frequency:

   • MONTHLY: Next payment is one month after the last payment
   • WEEKLY: Next payment is 7 days after the last payment
   • QUARTERLY: Next payment is 3 months after the last payment
   • And so on for other frequencies

2. Creates the next payment 48 hours before the calculated due date

3. Processes the payment on the scheduled date

Example Timeline:

January 15, 2025: Payment #1 is processed and marked as PAID
                  System calculates next payment: February 15, 2025
                  System creates Payment #2 (scheduled for February 15)

February 15, 2025: Payment #2 is processed
                   System calculates next payment: March 15, 2025
                   System creates Payment #3 (scheduled for March 15)

... and the cycle continues automatically

Lead Time

Payments are created 48 hours before the due date. This lead time:

• Ensures sufficient time for payment processing
• Gives customers advance notice
• Complies with regulatory requirements (for PIX Automatic)
• Provides a window for payment cancellation if needed

Complete Example

Here's a complete example for a monthly subscription:

January 15, 2025: 
  - Payment #1 is processed and marked as PAID
  - System automatically calculates: Next payment = February 15, 2025
  - System automatically creates Payment #2 (scheduled for February 15)

February 13, 2025 (48 hours before):
  - Payment #2 is created with status PENDING

February 15, 2025:
  - Payment #2 is processed
  - System automatically calculates: Next payment = March 15, 2025
  - System automatically creates Payment #3 (scheduled for March 15)

March 13, 2025 (48 hours before):
  - Payment #3 is created with status PENDING

March 15, 2025:
  - Payment #3 is processed
  - ... and the cycle continues automatically

First Payment

When a subscription becomes ACTIVE, the first payment is automatically scheduled if:

• automaticScheduleAllowed: true
• amountType: "FIXED"
• startDate is provided

The first payment is created 48 hours before the startDate and processed on the startDate.

Example:

Subscription Created: January 1, 2025
Start Date: February 1, 2025
First Payment Created: January 30, 2025 (48 hours before)
First Payment Processed: February 1, 2025

Manual Payment Creation

If automatic scheduling is disabled (automaticScheduleAllowed: false) or the subscription uses variable amounts (amountType: "VARIABLE"), merchants must manually create each payment.

When to use manual creation:

• Variable amounts that change each billing cycle
• Special payment dates that don't follow the standard frequency
• One-time adjustments or corrections
• Testing or development scenarios

How to create manually:

POST /v1/subscription-payments

{
  "subscriptionId": "subscription-guid",
  "amount": 10000,
  "scheduledDate": "2025-02-15T10:00:00Z",
  "description": "Monthly payment",
  "internalReferenceId": "MERCHANT-REF-123"
}

Automatic Cancellation

Subscriptions are automatically cancelled on their expirationDate. When a subscription expires:

• The subscription status changes to EXPIRED
• No further payments are created or processed
• The last scheduled payment (if any) is processed before expiration

Best Practices

Enable Automatic Scheduling When Possible

• Use automaticScheduleAllowed: true for fixed-amount subscriptions
• Reduces operational overhead
• Ensures consistent payment timing
• Improves customer experience

Monitor Subscriptions

• Track subscription status changes
• Monitor payment processing
• Handle failed payments appropriately

Handle Edge Cases

• Ensure startDate is in the future for first payment
• Set appropriate expirationDate for automatic cancellation
• Monitor subscriptions approaching expiration

Use Manual Creation When Needed

• For variable amounts
• For special payment dates
• For testing scenarios

Next Steps

• Retry Policies: Learn how failed payments are automatically retried
• Webhooks and Notifications: Set up notifications for scheduled payments
• Subscription Concepts: Review subscription entities and statuses