Vorschau auf Planänderung

Vorschau auf die Auswirkungen einer Änderung des Abonnementplans, bevor Sie sich dafür entscheiden. Gibt den sofort fälligen Betrag und die neuen Abonnementdetails zurück, ohne tatsächliche Änderungen vorzunehmen.

POST /subscriptions/{subscription_id}/change-plan/preview

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
});

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

console.log(response.immediate_charge);

200

{
  "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:

Feld	Beschreibung
immediate_charge	Die Gebühr, die sofort erstellt würde, einschließlich Posten und Zusammenfassung
new_plan	Das 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

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

application/json

Preview of subscription plan change

immediate_charge · object · erforderlich

Show child attributes

new_plan · object · erforderlich

Response struct representing subscription details

Show child attributes