Aperçu du Changement de Plan

Aperçu des effets d’un changement de plan d’abonnement avant de s’y engager. Renvoie le montant de la charge immédiate et les détails du nouvel abonnement sans effectuer de changements réels.

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>"
  }
}

Utilisez ce point de terminaison pour montrer exactement aux clients ce qu’ils seront facturés lors de la mise à niveau ou de la rétrogradation de leur abonnement, améliorant ainsi la transparence et réduisant les demandes de support.

​

Cas d’Utilisation

• Confirmation de commande : Affichez le coût au prorata avant que les clients ne confirment un changement de plan
• Calculatrices de tarification : Créez des calculatrices de mise à niveau/déclassement dans votre application
• Libre-service client : Permettez aux clients d’explorer les options de plan avec des prix précis
• Validation des réductions : Prévisualisez comment un code de réduction affecte le prix du changement de plan

Vous pouvez inclure un discount_code dans la demande de prévisualisation pour voir comment la réduction affecte la charge immédiate et la nouvelle tarification du plan avant de valider le changement.

​

Champs de réponse

La réponse de prévisualisation inclut :

Champ	Description
immediate_charge	La charge qui serait créée immédiatement, y compris les articles et le résumé
new_plan	L’objet d’abonnement complet montrant comment il apparaîtrait après le changement de plan

Le immediate_charge.summary contient le montant total qui serait facturé. Utilisez ceci pour afficher la tarification à vos clients avant qu’ils ne confirment le changement de plan.

Autorisations

Authorization · string · header · requis

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

Paramètres de chemin

subscription_id · string · requis

Subscription Id

Corps

application/json

product_id · string · requis

Unique identifier of the product to subscribe to

proration_billing_mode · enum<string> · requis

Proration Billing Mode

Options disponibles: prorated_immediately, full_immediately, difference_immediately, do_not_bill

quantity · integer<int32> · requis

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

Plage requise: 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

Options disponibles: 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.

Options disponibles: prevent_change, apply_change

Réponse

200

application/json

Preview of subscription plan change

immediate_charge · object · requis

Show child attributes

new_plan · object · requis

Response struct representing subscription details

Show child attributes