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/domain 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.
Subscription Object
| Attribute | Type | Description |
|---|---|---|
id | integer | Unique identifier for the subscription |
user_id | integer | ID of the customer who owns the subscription |
plan | integer | ID of the plan (expandable to full plan object) |
address | integer | ID of the shipping address (expandable) |
coupon | integer | ID of the applied coupon (expandable) |
default_source | integer | ID of the default payment source (expandable) |
latest_invoice | integer | ID of the most recent invoice (expandable) |
latest_churn_prediction | object | Latest churn prediction data, or null |
status | string | Subscription status (see statuses below) |
type | string | Subscription type: regular, membership, gift_donor, gift_recipient, donation |
is_membership | boolean | Whether this is a membership subscription |
billing | string | Payment collection method: charge_automatically or send_invoice |
quantity | integer | Number of subscription quantities |
auto_renew | integer | 1 if subscription will auto-renew, 0 otherwise |
cancel_at_period_end | integer | 1 if subscription cancels at period end, 0 otherwise |
cancel_at | timestamp | Unix timestamp when subscription will cancel |
canceled_at | timestamp | Unix timestamp when subscription was canceled |
cancel_reason | string | Reason for cancellation |
current_period_start | timestamp | Unix timestamp of current period start |
current_period_end | timestamp | Unix timestamp of current period end |
start_date | timestamp | Unix timestamp when subscription started |
end_date | timestamp | Unix timestamp of fixed end date |
ended_at | timestamp | Unix timestamp when subscription ended |
trial_start | timestamp | Unix timestamp when trial started |
trial_end | timestamp | Unix timestamp when trial ends |
expires_at | timestamp | Unix timestamp when subscription expires |
renews_at | timestamp | Unix timestamp of next renewal |
days_until_due | integer | Days until payment is due |
source | string | Acquisition source label (e.g. api, web, phone) |
is_gift_donor | boolean | Whether this is a gift from a donor |
is_gift_recipient | boolean | Whether this is a received gift |
gift_code | string | Gift redemption code (auto-generated for donors) |
is_redeemed | boolean | Whether gift has been redeemed |
gift_donor_subscription_id | integer | ID of the donor’s subscription |
is_imported | boolean | Whether subscription was imported |
old_provider_id | string | External system reference ID |
ip_addresses | array | Authorized IP addresses (membership only) |
domains | array | Authorized email domains (membership only) |
shipments_remaining | integer | Remaining shipments in the period |
shipments_undeliverable | boolean | Whether shipments are undeliverable |
shipments_suspended_until | timestamp | Unix timestamp until shipments are suspended |
address_required | boolean | Whether shipping address is required by the plan’s product |
recommended_plan_id | integer | ID of recommended plan for upgrade |
vendor_tip_amount | integer | Vendor tip amount |
schedule | object | Subscription schedule object (phases, end behavior) |
metadata | object | Key-value pairs for storing additional data |
created | timestamp | Unix timestamp of creation |
API Endpoints
| Method | Endpoint | Description |
|---|---|---|
GET | /api/v1/core/subscriptions | List subscriptions |
POST | /api/v1/core/subscriptions | Create subscription |
GET | /api/v1/core/subscriptions/{id} | Get subscription |
PUT | /api/v1/core/subscriptions/{id} | Update subscription |
DELETE | /api/v1/core/subscriptions/{id} | Cancel subscription |
POST | /api/v1/core/subscriptions/renew | Renew subscription |
POST | /api/v1/core/subscriptions/redeem | Redeem gift subscription |
DELETE | /api/v1/core/subscriptions/{id}/phases | Delete phase |
Subscription Statuses
| Status | Description |
|---|---|
active | Subscription is active and paid |
trialing | Customer is in trial period |
scheduled | Subscription is scheduled to start in the future |
pending_payment | Awaiting initial payment confirmation |
past_due | Payment failed, awaiting retry |
canceled | Subscription was canceled |
unpaid | Payment failed after all retries |
incomplete | Initial payment failed, awaiting completion |
incomplete_expired | Initial payment window expired |
extended | Subscription extended beyond normal period |