Skip to content
Console
On this page

Change plan on a customer subscription

Move a web subscription onto another recurring catalog plan.

Move a web subscription onto another recurring catalog plan.

  • Path POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/customer_subscriptions/customer-subscription:changePlan
  • Scope billing:write
  • Effect write — a successful call changes state.
  • Collection customer_subscriptions

Request

FieldTypeWhat it is
namestringThe subscription to change. Required.
productstringThe key of the catalog product to move to. Required.
pricestringThe key of the product's recurring price (for example monthly or yearly). Optional when the product has one recurring price.
proration_behaviorProrationBehaviorHow the change is billed; unspecified is create_prorations. One of create_prorations, none, always_invoice.
validate_onlyboolRun every check and answer the subscription as it would read, without changing anything.

Response

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.

ResourceMeta

FieldTypeWhat it is
generationint64Increases by one on every change to spec. Output only.
etagstringStrong ETag (AIP-154): changes on any change to spec, status, or metadata. Send it back as If-Match or etag to make Update and Delete conditional; a mismatch fails with ABORTED / 409 ETAG_MISMATCH. Output only.
create_timetimestampWhen the Resource was created. Output only.
update_timetimestampWhen the Resource last changed. Output only.
delete_timetimestampSet while the Resource is being deleted. Output only.
labelsmap<string, string>Caller-writable, indexed labels (AIP-122 label rules).
annotationsmap<string, string>Caller-writable, unindexed annotations.
display_namestringCaller-writable human-readable name.
creatorstringThe principal that created the Resource. Output only.

Subject

FieldTypeWhat it is
end_userstringAn end user's id (Sylphx Auth, or the app's own OIDC issuer). One of the kind group.
customer_organizationstringA customer organization's id. One of the kind group.

LineItem

FieldTypeWhat it is
pricestringThe price's lookup key. Required.
quantityint32How many; default 1. Seats for a per-seat or family price.

Errors

Every error arrives in the body Errors describes.

Examples

curl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/customer_subscriptions/customer-subscription:changePlan" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product":"…"}'