Xem trước thay đổi gói

Xem trước tác động của việc thay đổi gói đăng ký trước khi cam kết thực hiện. Trả về số tiền phí ngay lập tức và chi tiết đăng ký mới mà không thực hiện bất kỳ thay đổi nào.

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('sub_Iuaq622bbmmfOGrVTqdXv', {
  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,
      "customer_credits_currency": "AED",
      "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>"
    },
    "brand_id": "<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>"
    },
    "has_payment_method": true,
    "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,
    "cancellation_comment": "<string>",
    "cancellation_feedback": "too_expensive",
    "cancelled_at": "2023-11-07T05:31:56Z",
    "cancelled_by": {
      "actor_type": "customer",
      "email": "<string>",
      "name": "<string>"
    },
    "custom_field_responses": [
      {
        "key": "<string>",
        "value": "<string>"
      }
    ],
    "customer_business_name": "<string>",
    "discount_cycles_remaining": 123,
    "discount_id": "<string>",
    "discounts": [
      {
        "amount": 123,
        "business_id": "<string>",
        "code": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "discount_id": "<string>",
        "metadata": {},
        "position": 123,
        "preserve_on_plan_change": true,
        "restricted_to": [
          "<string>"
        ],
        "times_used": 123,
        "type": "flat",
        "cycles_remaining": 123,
        "expires_at": "2023-11-07T05:31:56Z",
        "name": "<string>",
        "subscription_cycles": 123,
        "usage_limit": 123
      }
    ],
    "expires_at": "2023-11-07T05:31:56Z",
    "paused_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>",
    "trial_amount": 123
  }
}

Sử dụng endpoint này để hiển thị cho khách hàng chính xác những gì họ sẽ bị tính phí khi nâng cấp hoặc hạ cấp gói đăng ký, cải thiện tính minh bạch và giảm yêu cầu hỗ trợ.

​

Trường hợp sử dụng

• Xác nhận thanh toán: Hiển thị phí tính theo tỷ lệ trước khi khách hàng xác nhận thay đổi gói
• Máy tính giá cả: Xây dựng các máy tính nâng cấp/hạ cấp trong ứng dụng của bạn
• Dịch vụ tự phục vụ khách hàng: Cho phép khách hàng khám phá các tùy chọn gói với giá chính xác
• Xác nhận chiết khấu: Xem trước cách mã chiết khấu xếp chồng ảnh hưởng đến giá thay đổi gói

Bạn có thể bao gồm discount_codes (một mảng tối đa 20 mã, được áp dụng theo thứ tự) trong yêu cầu xem trước để xem cách các chiết khấu xếp chồng ảnh hưởng đến phí ngay lập tức và giá của gói mới trước khi cam kết thay đổi. Trường discount_code đơn lẻ đã lỗi thời nhưng vẫn được hỗ trợ để tương thích ngược; chúng tôi khuyến nghị sử dụng discount_codes về sau.

​

Các trường phản hồi

Phản hồi xem trước bao gồm:

Trường	Mô tả
immediate_charge	Chi phí sẽ được tạo ngay lập tức, bao gồm mục dòng và tóm tắt
new_plan	Đối tượng đăng ký đầy đủ hiển thị trông như thế nào sau khi thay đổi gói

The immediate_charge.summary contains the total amount that would be charged. Use this to display pricing to your customers before they confirm the plan change.

Ủy quyền

Authorization · string · header · bắt buộc

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

Tham số đường dẫn

subscription_id · string · bắt buộc

Subscription Id

Nội dung

application/json

product_id · string · bắt buộc

Unique identifier of the product to subscribe to

proration_billing_mode · enum<string> · bắt buộc

Proration Billing Mode

Tùy chọn có sẵn: prorated_immediately, full_immediately, difference_immediately, do_not_bill, prorated_immediately_keep_cycle

quantity · integer<int32> · bắt buộc

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

Phạm vi bắt buộc: x >= 0

adaptive_currency_fees_inclusive · boolean | null

Whether adaptive currency fees should be included in the price (true) or added on top (false). If not specified, uses the subscription's stored setting.

addons · Attach Addon Request · object[] | null

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

Show child attributes

cancel_older_payment_link · boolean

Cancel the payment link of a pending plan change, so that this change can replace it.

The link is cancelled only if the customer has not started to pay. A paid or in-progress payment gives a 409. A failed cancel gives a 503, and a retry is safe.

The request is validated before the cancel. A later failure, for example an amount below the minimum, leaves the subscription on its current plan with no open link. A retry is safe.

The preview route shares this request body and ignores this field.

cancel_scheduled_change_plan · boolean

Replace a scheduled plan change with this one.

The scheduled change is cancelled by the transaction that applies this change. A change that never applies leaves the schedule in place.

effective_at: next_billing_date is allowed. The new schedule then replaces the old one in the request transaction.

A pending plan change still gets a 409. This field does not affect it.

The preview route shares this request body, so a preview that sets this field also passes the scheduled-change 409.

collect_via_payment_link · boolean

Collect the plan-change amount with a payment link. The customer then pays on a checkout page.

The business needs the allow_plan_change_via_payment_link capability. The request needs effective_at: immediately. The request also needs on_payment_failure: prevent_change.

The preview route shares this request body and ignores this field.

discount_code · string | null · không còn sử dụng

DEPRECATED: Use discount_codes instead. Cannot be used together with discount_codes.

discount_codes · string[] | null

Stacked discount codes to apply to the new plan. Max 20. Cannot be used together with discount_code. If provided, replaces any existing discount codes. Empty array removes all discounts. If not provided (None), existing discounts with preserve_on_plan_change=true are preserved.

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

Tùy chọn có sẵn: immediately, next_billing_date

metadata · null | 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.

Tùy chọn có sẵn: prevent_change, apply_change

return_url · string | null

The URL that receives the customer after they pay the payment link. Needs collect_via_payment_link: true. Without it, the request gets a 422. A change that collects no money issues no link and does not use the URL. The preview route validates this field but does not use it.

The redirect adds subscription_id, payment_id and status. The status value is the status of the plan-change payment. It is not the status of the subscription. When that payment fails, the subscription stays active on its current plan. To try again, call this endpoint again to get a new link. The new plan can apply after the redirect, when the payment webhook arrives.

Phản hồi

200

application/json

Preview of subscription plan change

immediate_charge · object · bắt buộc

Show child attributes

new_plan · object · bắt buộc

Response struct representing subscription details

Show child attributes