# Automatic Scheduling

# 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**:

```bash
POST /v1/subscription-payments
```

```json
{
  "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](retry-policies.md)**: Learn how failed payments are automatically retried
* **[Webhooks and Notifications](webhooks-and-notifications.md)**: Set up notifications for scheduled payments
* **[Subscription Concepts](subscription-concepts.md)**: Review subscription entities and statuses