Zum Hauptinhalt springen
POST
/
subscriptions
/
{subscription_id}
/
change-plan
/
preview
JavaScript
import DodoPayments from 'dodopayments';

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

const response = await client.subscriptions.previewChangePlan('subscription_id', {
  product_id: 'product_id',
  proration_billing_mode: 'prorated_immediately',
  quantity: 0,
});

console.log(response.immediate_charge);
{
  "immediate_charge": {
    "effective_at": "2023-11-07T05:31:56Z",
    "line_items": [
      {
        "currency": "AED",
        "id": "<string>",
        "product_id": "<string>",
        "proration_factor": 123,
        "quantity": 123,
        "tax_inclusive": true,
        "type": "subscription",
        "unit_price": 123,
        "description": "<string>",
        "name": "<string>",
        "tax": 123,
        "tax_rate": 123
      }
    ],
    "summary": {
      "currency": "AED",
      "customer_credits": 123,
      "settlement_amount": 123,
      "settlement_currency": "AED",
      "total_amount": 123,
      "settlement_tax": 123,
      "tax": 123
    }
  },
  "new_plan": {
    "addons": [
      {
        "addon_id": "<string>",
        "quantity": 123
      }
    ],
    "billing": {
      "country": "AF",
      "city": "<string>",
      "state": "<string>",
      "street": "<string>",
      "zipcode": "<string>"
    },
    "cancel_at_next_billing_date": true,
    "created_at": "2023-11-07T05:31:56Z",
    "credit_entitlement_cart": [
      {
        "credit_entitlement_id": "<string>",
        "credit_entitlement_name": "<string>",
        "credits_amount": "<string>",
        "overage_balance": "<string>",
        "overage_behavior": "forgive_at_reset",
        "overage_enabled": true,
        "product_id": "<string>",
        "remaining_balance": "<string>",
        "rollover_enabled": true,
        "unit": "<string>",
        "expires_after_days": 123,
        "low_balance_threshold_percent": 123,
        "max_rollover_count": 123,
        "overage_limit": "<string>",
        "rollover_percentage": 123,
        "rollover_timeframe_count": 123,
        "rollover_timeframe_interval": "Day"
      }
    ],
    "currency": "AED",
    "customer": {
      "customer_id": "<string>",
      "email": "<string>",
      "name": "<string>",
      "metadata": {},
      "phone_number": "<string>"
    },
    "metadata": {},
    "meter_credit_entitlement_cart": [
      {
        "credit_entitlement_id": "<string>",
        "meter_id": "<string>",
        "meter_name": "<string>",
        "meter_units_per_credit": "<string>",
        "product_id": "<string>"
      }
    ],
    "meters": [
      {
        "currency": "AED",
        "free_threshold": 123,
        "measurement_unit": "<string>",
        "meter_id": "<string>",
        "name": "<string>",
        "description": "<string>",
        "price_per_unit": "10.50"
      }
    ],
    "next_billing_date": "2023-11-07T05:31:56Z",
    "on_demand": true,
    "payment_frequency_count": 123,
    "payment_frequency_interval": "Day",
    "previous_billing_date": "2023-11-07T05:31:56Z",
    "product_id": "<string>",
    "quantity": 123,
    "recurring_pre_tax_amount": 123,
    "status": "pending",
    "subscription_id": "<string>",
    "subscription_period_count": 123,
    "subscription_period_interval": "Day",
    "tax_inclusive": true,
    "trial_period_days": 123,
    "cancelled_at": "2023-11-07T05:31:56Z",
    "custom_field_responses": [
      {
        "key": "<string>",
        "value": "<string>"
      }
    ],
    "discount_cycles_remaining": 123,
    "discount_id": "<string>",
    "expires_at": "2023-11-07T05:31:56Z",
    "payment_method_id": "<string>",
    "scheduled_change": {
      "addons": [
        {
          "addon_id": "<string>",
          "name": "<string>",
          "quantity": 123
        }
      ],
      "created_at": "2023-11-07T05:31:56Z",
      "effective_at": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "product_id": "<string>",
      "quantity": 123,
      "product_description": "<string>",
      "product_name": "<string>"
    },
    "tax_id": "<string>"
  }
}
Verwenden Sie diesen Endpunkt, um den Kunden genau zu zeigen, was ihnen bei einem Upgrade oder Downgrade ihres Abonnements berechnet wird, wodurch die Transparenz verbessert und Supportanfragen reduziert werden.

Anwendungsfälle

  • Checkout-Bestätigung: Zeigen Sie die anteilige Gebühr an, bevor Kunden eine Planänderung bestätigen
  • Preisrechner: Erstellen Sie Upgrade/Downgrade-Rechner in Ihrer Anwendung
  • Kunden-Self-Service: Lassen Sie Kunden mit genauen Preisen Planoptionen erkunden
  • Rabattvalidierung: Zeigen Sie, wie sich ein Rabattcode auf die Planänderungspreise auswirkt
Sie können ein discount_code in die Vorschau-Anfrage einfügen, um zu sehen, wie sich der Rabatt auf die sofortige Gebühr und die neuen Planpreise auswirkt, bevor Sie die Änderung vornehmen.

Antwortfelder

Die Vorschau-Antwort enthält:
FeldBeschreibung
immediate_chargeDie Gebühr, die sofort erstellt würde, einschließlich Posten und Zusammenfassung
new_planDas vollständige Abonnementobjekt, das zeigt, wie es nach der Planänderung aussehen würde
Der immediate_charge.summary enthält den Gesamtbetrag, der berechnet werden würde. Verwenden Sie dies, um Ihren Kunden die Preise anzuzeigen, bevor sie die Planänderung bestätigen.

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

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

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

Preview of subscription plan change

immediate_charge
object
erforderlich
new_plan
object
erforderlich

Response struct representing subscription details

Last modified on April 1, 2026