Charge Schedules API

The Charge Schedules API allows you to create and manage recurring charge schedules in bulk. This API is designed for high-volume operations, enabling you to upload CSV files to create multiple schedules at once, and manage existing schedules through batch pause, resume, and delete operations.

Available Endpoints

• Bulk Create Schedules - POST /schedules/upload
• Monitor Bulk Creation - GET /recurring_exports/:recurring_id
• Download Bulk Status - GET /recurring_exports/:recurring_id/download
• Bulk Pause Schedules - PATCH /schedules/bulk_pause
• Bulk Resume Schedules - PATCH /schedules/bulk_resume
• Bulk Delete Schedules - DELETE /schedules/bulk_delete

Related Endpoints

• Schedules API - Individual schedule management
• List Schedules - GET /schedules
• Create Schedule - POST /schedules
• Customers API - Customer management

Overview

The Charge Schedules API provides bulk operations for managing recurring charges:

• CSV Upload - Create hundreds or thousands of charge schedules from a single CSV file
• Progress Monitoring - Track the status of bulk creation jobs in real-time
• Status Reports - Download detailed reports with success/failure status for each schedule
• Bulk Pause - Pause multiple active schedules simultaneously
• Bulk Resume - Resume multiple paused schedules at once
• Bulk Delete - Permanently delete multiple schedules in a single operation

Common Use Cases

• Migrating subscription customers from another platform
• Setting up recurring payments for a large customer base
• Seasonal schedule management (pause/resume for holidays)
• Batch cancellation of schedules for churned customers
• Initial setup of recurring billing for enterprise clients

How Bulk Creation Works

1. Prepare a CSV file with customer and schedule details
2. Upload the CSV file to create a bulk creation job
3. Monitor the job progress using the recurring_id
4. Download the status report to review results and handle errors
5. Successful schedules begin executing automatically

CSV File Format

When creating schedules in bulk, your CSV file must include the following columns:

Column	Required	Description
customer_key	Yes	Unique identifier for the customer row (for tracking)
customer	Yes	Customer ID (cust_*) with an attached card
card	No	Specific card ID to charge (uses default if not specified)
amount	Yes	Charge amount in smallest currency unit
description	No	Description for each charge
every	Yes	Frequency multiplier (e.g., 1 for every month)
period	Yes	Time unit: day, week, or month
days_of_month	Conditional	Days to charge (required for monthly period)
start_date	No	Schedule start date (YYYY-MM-DD)
end_date	No	Schedule end date (YYYY-MM-DD)

Example CSV

customer_key,customer,card,amount,description,every,period,days_of_month,start_date,end_date
sub_001,cust_test_abc123,,100000,Monthly premium plan,1,month,1,2025-02-01,2026-01-31
sub_002,cust_test_def456,card_test_xyz789,50000,Basic subscription,1,month,15,2025-02-01,
sub_003,cust_test_ghi012,,200000,Enterprise plan,1,month,1;15,2025-02-01,2025-12-31

Authentication

All Charge Schedules API endpoints require authentication using your secret key.

Bulk Operation Limits

Operation	Limit
CSV file size	10MB maximum
Schedules per CSV	10,000 rows maximum
Schedule IDs per bulk pause/resume/delete	100 IDs maximum
Concurrent bulk creation jobs	5 per account

Job Status Lifecycle

Bulk creation jobs progress through these statuses:

1. pending - Job is queued and waiting to start
2. processing - Job is actively creating schedules
3. completed - Job finished (check report for individual results)
4. failed - Job encountered a fatal error

Error Handling

Bulk Creation Errors

Bulk creation jobs are designed to be resilient. If individual rows fail:

• The job continues processing remaining rows
• Failed rows are logged in the status report
• Download the report to see specific error messages per row

Common CSV Errors

Error	Description	Resolution
invalid_customer	Customer ID not found	Verify customer exists and has a card attached
invalid_card	Card not found or expired	Use a valid card ID or remove to use default
invalid_amount	Amount is zero or negative	Provide a positive integer amount
invalid_period	Invalid period value	Use day, week, or month
missing_days_of_month	Required for monthly period	Specify days (e.g., 1 or 1;15)

Bulk Pause/Resume/Delete Errors

Error	Description	Resolution
schedule_not_found	One or more schedule IDs invalid	Verify all schedule IDs exist
invalid_status	Schedule in wrong state for operation	Check current schedule status
too_many_ids	Exceeded maximum IDs per request	Split into multiple requests (max 100)

Best Practices

1. Validate CSV Before Upload

Check your CSV file for:

• Correct column headers
• Valid customer IDs
• Proper date formats (YYYY-MM-DD)
• Amount values as integers (not decimals)

2. Monitor Job Progress

Poll the monitor endpoint periodically:

// Check every 5 seconds until complete
const checkStatus = async (recurringId) => {
  const status = await getJobStatus(recurringId);
  if (status.state === 'completed') {
    return await downloadReport(recurringId);
  }
  setTimeout(() => checkStatus(recurringId), 5000);
};

3. Handle Partial Failures

Always download and review the status report:

• Retry failed rows individually or in a new CSV
• Log errors for investigation
• Notify affected customers if needed

4. Use Unique Customer Keys

Include meaningful customer_key values to easily identify rows in status reports and match results back to your system.

Related Resources

• Recurring Payments Guide - Complete subscription implementation
• Schedules API - Individual schedule management
• Webhooks - Handle schedule events