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": {
    "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_charge_at_billing": true,
        "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>",
        "price_per_unit": "10.50",
        "description": "<string>"
      }
    ],
    "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>",
    "tax_id": "<string>"
  }
}
Verwenden Sie diesen Endpunkt, um den Kunden genau zu zeigen, was ihnen bei einem Upgrade oder Downgrade ihres Abonnements in Rechnung gestellt wird, um die Transparenz zu verbessern und Supportanfragen zu reduzieren.

​
Anwendungsfälle

  • Bestätigungsbildschirm: Zeigen Sie die anteilige Gebühr an, bevor die Kunden eine Planänderung bestätigen
  • Preiskalkulatoren: Erstellen Sie Upgrade-/Downgrade-Kalkulatoren in Ihrer Anwendung
  • Kunden-Selbstbedienung: Lassen Sie Kunden die Planoptionen mit genauen Preisen erkunden

​
Antwortfelder

Die Vorschauantwort enthält:
FeldBeschreibung
immediate_chargeDie Gebühr, die sofort erstellt werden würde, einschließlich der Einzelposten und der 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
​
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

​
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