Schedules API

The Schedules API allows you to create and manage recurring payments and automated transfers on a schedule.

Available Endpoints

• List Schedules - GET /schedules
• Retrieve Schedule - GET /schedules/:id

Overview

Schedules enable automated recurring operations:

• Recurring charges - Automatically charge customers on a schedule
• Recurring transfers - Automatically transfer funds to recipients
• Flexible frequencies - Daily, weekly, monthly schedules
• Occurrence tracking - Track each execution of a schedule

Common Use Cases

• Subscription billing (monthly/annual charges)
• Scheduled payouts to marketplace vendors
• Recurring donations
• Membership fees
• Automated commission payments

How Schedules Work

1. Create a schedule with frequency (daily, weekly, monthly)
2. Schedule executes automatically at specified intervals
3. Each execution creates an "occurrence"
4. Occurrences link to the actual charge or transfer created
5. Monitor schedule status and occurrence results

Authentication

All Schedule API endpoints require authentication using your secret key.

Schedule Frequencies

Schedules support the following frequencies:

Frequency	Description	Example Use Case
daily	Runs every day at specified time	Daily payouts
weekly	Runs once per week on specified day	Weekly subscriptions
monthly	Runs once per month on specified day	Monthly billing

Schedule Status Lifecycle

A schedule progresses through these statuses:

1. active - Schedule is running and will execute on schedule
2. suspended - Schedule is paused (can be resumed)
3. deleted - Schedule is permanently disabled
4. completed - Schedule reached its end date

Occurrences

Each time a schedule executes, it creates an occurrence. Occurrences have their own statuses:

• scheduled - Occurrence is queued to run
• running - Occurrence is currently executing
• successful - Occurrence completed successfully
• failed - Occurrence failed (payment declined, insufficient balance, etc.)
• skipped - Occurrence was skipped (e.g., schedule was suspended)

Best Practices

1. Handle Failed Occurrences

Not all scheduled operations will succeed. Implement webhook handlers for:

• schedule.occurrence.failed - Handle failed payments/transfers
• schedule.occurrence.successful - Track successful operations

2. Monitor Schedule Health

Regularly check schedule status and recent occurrences:

• High failure rates may indicate customer payment issues
• Suspended schedules won't execute until reactivated

3. Set End Dates

For fixed-term subscriptions, set an end_date:

{
  "period": "month",
  "end_date": "2027-12-31"
}

4. Use Metadata

Store subscription details in metadata for easy lookup:

{
  "metadata": {
    "plan": "premium",
    "customer_id": "cust_123",
    "subscription_id": "sub_456"
  }
}

Limitations

• Minimum schedule interval: 1 day
• Maximum active schedules per account: Contact support for limits
• Schedules cannot be edited after creation (must delete and recreate)
• Failed occurrences are not automatically retried

Error Handling

Common errors when working with schedules:

Error Code	Description	Solution
invalid_frequency	Invalid period value	Use daily, weekly, or monthly
invalid_start_date	Start date in the past	Use future date
insufficient_balance	Not enough balance for transfer	Add funds before schedule runs
invalid_recipient	Recipient not found or inactive	Verify recipient exists

Related Resources

• Occurrences API - View schedule execution history
• Recurring Payments Guide - Complete subscription implementation
• Webhooks - Handle schedule events