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
| Field | Type | What it is |
|---|---|---|
name | string | orgs/{org}/projects/{project}/envs/{env}/customer_subscriptions/{customer_subscription}. |
uid | string | csb_<cell><ulid>; never reused. Output only. |
meta | ResourceMeta | Resource metadata. |
subject | Subject | Who holds it. Output only. |
source | string | stripe, app_store, or google_play. Output only. |
processor_subscription_id | string | The processor's subscription id. Output only. |
status | string | trialing, active, past_due, paused, canceled, unpaid, incomplete, or incomplete_expired, as the processor reports it. Output only. |
items | LineItem[] | The prices, by lookup key, and their quantities. Output only. |
current_period_end_time | timestamp | The end of the paid period. Output only. |
cancel_at_period_end | bool | Whether it ends at current_period_end_time instead of renewing. Output only. |
trial_end_time | timestamp | The end of the trial, when there is one. Output only. |
metadata | struct | The checkout's metadata. Output only. |
billing_country_code | string | The 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_code | string | Upper-case ISO 4217 currency of the latest settled payment, empty when unknown. Output only. |
latest_paid_amount_minor | int64 | Minor-unit amount collected on the latest paid invoice, when reported. Output only. |
latest_invoice_id | string | Processor invoice id of the latest paid subscription charge, empty when none. Output only. |
latest_payment_id | string | Processor payment id (for example Stripe pi_…) of the latest paid charge, or store transaction id when reported; empty when none. Output only. |
last_paid_time | timestamp | Timestamp of the latest settled subscription payment, when reported. Output only. |
available_portal_switch_price | string | On 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.
| Method | Call | What it does |
|---|---|---|
GET | get | Gets a customer subscription. |
GET | list | Lists customer subscriptions, newest first. |
POST | cancel | Cancels a web subscription, now or at the period end, and optionally refunds its last payment (for example a statutory cancellation window). |
POST | resume | Resumes a web subscription set to cancel at its period end. |
POST | 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 | change_plan | Move 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