Skip to content
Console
On this page

Customer subscriptions

A Customer Subscription is a subject's recurring purchase, mirrored from the processor after Money read it back.

A Customer Subscription is a subject's recurring purchase, mirrored from the processor after Money read it back. Money writes it; a caller changes it only through :cancel and :resume.

Service Sylphx Money · Resource type money.sylphx.com/CustomerSubscription · Name pattern orgs/{org}/projects/{project}/envs/{env}/customer_subscriptions/{customer_subscription} · Shape record

Fields

FieldTypeWhat it is
namestringorgs/{org}/projects/{project}/envs/{env}/customer_subscriptions/{customer_subscription}.
uidstringcsb_<cell><ulid>; never reused. Output only.
metaResourceMetaResource metadata.
subjectSubjectWho holds it. Output only.
sourcestringstripe, app_store, or google_play. Output only.
processor_subscription_idstringThe processor's subscription id. Output only.
statusstringtrialing, active, past_due, paused, canceled, unpaid, incomplete, or incomplete_expired, as the processor reports it. Output only.
itemsLineItem[]The prices, by lookup key, and their quantities. Output only.
current_period_end_timetimestampThe end of the paid period. Output only.
cancel_at_period_endboolWhether it ends at current_period_end_time instead of renewing. Output only.
trial_end_timetimestampThe end of the trial, when there is one. Output only.
metadatastructThe checkout's metadata. Output only.
billing_country_codestringThe buyer's billing country, upper-case ISO 3166-1 alpha-2 (for example HK), for a web subscription: the processor customer's billing address (which checkout requires and saves), else the default payment method's billing address. Kept current when the processor reports a subscription or customer change. Empty when unknown, and for store subscriptions. Output only.
currency_codestringUpper-case ISO 4217 currency of the latest settled payment, empty when unknown. Output only.
latest_paid_amount_minorint64Minor-unit amount collected on the latest paid invoice, when reported. Output only.
latest_invoice_idstringProcessor invoice id of the latest paid subscription charge, empty when none. Output only.
latest_payment_idstringProcessor payment id (for example Stripe pi_…) of the latest paid charge, or store transaction id when reported; empty when none. Output only.
last_paid_timetimestampTimestamp of the latest settled subscription payment, when reported. Output only.
available_portal_switch_pricestringOn GetCustomerSubscription, the eligible annual catalog price key, or empty when Money cannot offer the switch. An offer is not a quote: Money checks eligibility again when creating the hosted confirmation session. Output only.

Methods

Every method of the collection, in the registry's order, with the scope it needs. The full request, response and examples are one link away.

MethodCallWhat it does
GETgetGets a customer subscription.
GETlistLists customer subscriptions, newest first.
POSTcancelCancels a web subscription, now or at the period end, and optionally refunds its last payment (for example a statutory cancellation window).
POSTresumeResumes a web subscription set to cancel at its period end.
POSTupdate_quantityChanges the seat quantity of a web subscription, now, and syncs the processor's subscription item to it. A retry with the same Idempotency-Key (required) and the same request changes nothing twice.
POSTchange_planMove a web subscription onto another recurring catalog plan.

get

Gets a customer subscription.

GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/customer_subscriptions/customer-subscription · scope billing:read · effect read · Request, response and examples

list

Lists customer subscriptions, newest first.

GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/customer_subscriptions · scope billing:read · effect read · paginated · Request, response and examples

cancel

Cancels a web subscription, now or at the period end, and optionally refunds its last payment (for example a statutory cancellation window).

POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/customer_subscriptions/customer-subscription:cancel · scope billing:write · effect destructive · Request, response and examples

resume

Resumes a web subscription set to cancel at its period end.

POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/customer_subscriptions/customer-subscription:resume · scope billing:write · effect write · Request, response and examples

update_quantity

Changes the seat quantity of a web subscription, now, and syncs the processor's subscription item to it. A retry with the same Idempotency-Key (required) and the same request changes nothing twice.

POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/customer_subscriptions/customer-subscription:updateQuantity · scope billing:write · effect write · Request, response and examples

change_plan

Move a web subscription onto another recurring catalog plan.

POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/customer_subscriptions/customer-subscription:changePlan · scope billing:write · effect write · Request, response and examples