Plan ändern
Ändern Sie den Plan eines bestehenden Abonnements und ermöglichen Sie sowohl Upgrades als auch Downgrades auf andere Preisstufen.
Hinweis: Standardmäßig werden dafür die vorhandenen Zahlungsinformationen des Kunden verwendet. Setzen Sie collect_via_payment_link, um stattdessen über eine gehostete Checkout-Seite abzurechnen.
Geplante Tarifänderungen
Verwenden Sie deneffective_at-Parameter, um zu steuern, wann die Tarifänderung wirksam wird:
Zahlungsfehlerbehandlung
Verwenden Sie denon_payment_failure-Parameter, um zu steuern, was passiert, wenn die Zahlung für die Tarifänderung fehlschlägt:
on_payment_failure nicht angegeben ist, erfolgt die Standardverhalten gemäß Ihrer Geschäftseinstellung im Dashboard.Über Payment Link abrechnen
Setzen Siecollect_via_payment_link auf true, um den Kunden stattdessen zu einer gehosteten Checkout-Seite weiterzuleiten, anstatt die gespeicherte Zahlungsmethode zu belasten. Die Antwort enthält dann payment_id, payment_link, client_secret und expires_on — leiten Sie den Kunden zu payment_link weiter, um die Zahlung abzuschließen.
Dies erfordert:
422 zurück. Solange der Link unbezahlt ist, bleibt das Abonnement auf seinem aktuellen Plan, und eine weitere Anfrage mit change-plan gibt 409 zurück.
Rabattcodes
Sie können beim Ändern von Plänen einen oder mehrere kombinierte Rabattcodes anwenden, indem Sie das Arraydiscount_codes übergeben (maximal 20 Einträge, die in Array-Reihenfolge angewendet werden). Das einzelne Feld discount_code ist veraltet, funktioniert aber weiterhin für bestehende Integrationen; es kann in derselben Anfrage nicht mit discount_codes kombiniert werden.
Autorisierungen
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Pfadparameter
Subscription Id
Body
Unique identifier of the product to subscribe to
Proration Billing Mode
prorated_immediately, full_immediately, difference_immediately, do_not_bill Number of units to subscribe for. Must be at least 1.
x >= 0Whether adaptive currency fees should be included in the price (true) or added on top (false). If not specified, uses the subscription's stored setting.
Addons for the new plan. Note : Leaving this empty would remove any existing addons
Replace a scheduled plan change with this one.
The scheduled change is cancelled by the transaction that applies this change. A change that never applies leaves the schedule in place.
effective_at: next_billing_date is allowed. The new schedule then
replaces the old one in the request transaction.
A pending plan change still gets a 409. This field does not affect it.
The preview route shares this request body, so a preview that sets this
field also passes the scheduled-change 409.
Collect the plan-change amount with a payment link. The customer then pays on a checkout page.
The business needs the allow_plan_change_via_payment_link capability.
The request needs effective_at: immediately. The request also needs
on_payment_failure: prevent_change.
The preview route shares this request body and ignores this field.
DEPRECATED: Use discount_codes instead. Cannot be used together with discount_codes.
Stacked discount codes to apply to the new plan. Max 20. Cannot be used together with discount_code. If provided, replaces any existing discount codes. Empty array removes all discounts. If not provided (None), existing discounts with preserve_on_plan_change=true are preserved.
When to apply the plan change.
immediately(default): Apply the plan change right awaynext_billing_date: Schedule the change for the next billing date
immediately, next_billing_date Metadata for the payment. If not passed, the metadata of the subscription will be taken
Controls behavior when the plan change payment fails.
prevent_change: Keep subscription on current plan until payment succeedsapply_change(default): Apply plan change immediately regardless of payment outcome
If not specified, uses the business-level default setting.
prevent_change, apply_change Antwort
Subscription plan changed. A link request can return checkout details. A pending plan change applies after payment succeeds.
Handles for a hosted checkout page that settles a plan change.
The four fields repeat UpdatePaymentMethodResponse and a subset of
CreateSubscriptionResponse. A shared type would rename the generated SDK
types for all three routes, so each route keeps its own.