Plan ändern

Ändern Sie den Plan eines bestehenden Abonnements, um sowohl Upgrades als auch Downgrades zu verschiedenen Preiskategorien zu ermöglichen.

Hinweis: Dies verwendet die vorhandenen Zahlungsinformationen des Kunden, um den Plan zu upgraden/downgraden.

POST /subscriptions/{subscription_id}/change-plan

JavaScript

JavaScript

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env['DODO_PAYMENTS_API_KEY'], // This is the default and can be omitted
});

await client.subscriptions.changePlan('subscription_id', {
  product_id: 'product_id',
  proration_billing_mode: 'prorated_immediately',
  quantity: 0,
});

​

Umgang mit Zahlungsfehlern

Verwenden Sie den on_payment_failure-Parameter, um zu steuern, was passiert, wenn die Zahlung für die Planänderung fehlschlägt:

Value	Verhalten
prevent_change	Behalten Sie das Abonnement im aktuellen Plan, bis die Zahlung erfolgreich ist. Die Planänderung bleibt ausstehend.
apply_change	Wenden Sie die Planänderung sofort an, unabhängig vom Zahlungsergebnis. Dies ist die Standardeinstellung.

Wenn on_payment_failure nicht angegeben ist, gilt das auf Unternehmensebene konfigurierte Verhalten im Dashboard.

​

Rabattcodes

Sie können einen Rabattcode anwenden, wenn Sie den Plan ändern, indem Sie den Parameter discount_code übergeben.

Szenario	Verhalten
discount_code bereitgestellt	Validiert und wendet den Rabatt auf den neuen Plan an.
discount_code nicht bereitgestellt, bestehender Rabatt mit preserve_on_plan_change=true	Bestehender Rabatt wird beibehalten, wenn er auf das neue Produkt anwendbar ist.
discount_code nicht bereitgestellt, kein beibehaltbarer Rabatt	Kein Rabatt angewendet.

Verwenden Sie Rabattcodes während Planänderungen, um bei Upgrades Aktionspreise anzubieten, oder übergeben Sie einen Code, wenn Sie Kunden auf eine neue Tarifstufe migrieren.

Verwenden Sie prevent_change für kritische Upgrades, bei denen Sie die Zahlung sicherstellen wollen, bevor Sie Zugang zu Premiumfunktionen gewähren.

Autorisierungen

Authorization · string · header · erforderlich

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Pfadparameter

subscription_id · string · erforderlich

Subscription Id

Body

application/json

product_id · string · erforderlich

Unique identifier of the product to subscribe to

proration_billing_mode · enum<string> · erforderlich

Proration Billing Mode

Verfügbare Optionen: prorated_immediately, full_immediately, difference_immediately, do_not_bill

quantity · integer<int32> · erforderlich

Number of units to subscribe for. Must be at least 1.

Erforderlicher Bereich: x >= 0

addons · Attach Addon Request · object[] | null

Addons for the new plan. Note : Leaving this empty would remove any existing addons

Show child attributes

discount_code · string | null

Optional discount code to apply to the new plan. If provided, validates and applies the discount to the plan change. If not provided and the subscription has an existing discount with preserve_on_plan_change=true, the existing discount will be preserved (if applicable to the new product).

effective_at · enum<string>

When to apply the plan change.

• immediately (default): Apply the plan change right away
• next_billing_date: Schedule the change for the next billing date

Verfügbare Optionen: immediately, next_billing_date

metadata · object

Metadata for the payment. If not passed, the metadata of the subscription will be taken

Show child attributes

on_payment_failure · null | enum<string>

Controls behavior when the plan change payment fails.

• prevent_change: Keep subscription on current plan until payment succeeds
• apply_change (default): Apply plan change immediately regardless of payment outcome

If not specified, uses the business-level default setting.

Verfügbare Optionen: prevent_change, apply_change

Antwort

200

Subscription plan changed. If on_payment_failure=prevent_change, the plan change is pending until payment succeeds.