Create and manage recurring subscriptions with plans, trials, cancellations, and billing schedules.
Overview
Subscriptions connect customers to plans for recurring access and billing. Each subscription tracks its billing cycle, trial period, cancellation status, and renewal schedule.
Subscriptions can be standard recurring, gift (donor or recipient), or membership-based with IP authorization.
How It Works
- Create a subscription - Assign a customer to a plan with optional trial period and coupon
- Manage the lifecycle - Handle renewals, plan changes, pauses, and cancellations
- Track status - Monitor active, trialing, past_due, canceled, and expired states
Example: A customer subscribes to your Premium Monthly plan with a 14-day trial. After the trial, they're automatically billed. Later, they upgrade to the Annual plan mid-cycle with prorated billing.
API Endpoints
| Method | Endpoint | Description |
|---|---|---|
GET | /api/v1/core/subscriptions | List all subscriptions |
POST | /api/v1/core/subscriptions | Create a new subscription |
GET | /api/v1/core/subscriptions/{id} | Get a subscription's details |
PUT | /api/v1/core/subscriptions/{id} | Update a subscription |
DELETE | /api/v1/core/subscriptions/{id} | Cancel a subscription |
PUT | /api/v1/core/subscriptions/{id}/change_plan | Change subscription plan |
POST | /api/v1/core/subscriptions/{id}/skip_trial | End trial immediately |
POST | /api/v1/core/subscriptions/renew | Renew a subscription |
POST | /api/v1/core/subscriptions/redeem | Redeem a gift subscription |
DELETE | /api/v1/core/subscriptions/{id}/phases | Delete a subscription phase |
POST | /api/v1/core/subscriptions/{id}/shipments/{shipment_id}/returns | Create a shipment return |
Subscription Statuses
| Status | What It Means |
|---|---|
active | Subscription is active and paid |
canceled | Subscription was canceled |
past_due | Payment failed, awaiting retry |
trialing | Customer is in trial period |
unpaid | Payment failed after all retries |
incomplete | Initial payment failed, awaiting completion |
incomplete_expired | Initial payment window expired |
extended | Subscription extended beyond normal period |
Related Endpoints
- List Subscriptions - Retrieve subscriptions with filtering