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