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.

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)
`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)
`status`	string	Subscription status (see statuses below)
`billing`	string	Billing type
`quantity`	integer	Number of subscription quantities
`auto_renew`	boolean	Whether subscription will auto-renew
`cancel_at_period_end`	boolean	Whether subscription cancels at period end
`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
`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
`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
`ip_addresses`	array	Authorized IP addresses
`domains`	array	Authorized domains
`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
`source`	string	Source of subscription creation
`schedule`	object	Subscription schedule object
`recommended_plan_id`	integer	ID of recommended plan for upgrade
`old_provider_id`	string	External system reference ID
`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 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