> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Preview Plan Change
> Preview the effects of a subscription plan change before committing to it. Returns the immediate charge amount and the new subscription details without making any actual changes.
Use this endpoint to show customers exactly what they'll be charged when upgrading or downgrading their subscription, improving transparency and reducing support requests.
## Use Cases
* **Checkout confirmation**: Display the prorated charge before customers confirm a plan change
* **Pricing calculators**: Build upgrade/downgrade calculators in your application
* **Customer self-service**: Let customers explore plan options with accurate pricing
* **Discount validation**: Preview how stacked discount codes affect the plan change pricing
You can include `discount_codes` (an array of up to 20 codes, applied in order) in the preview request to see how the stacked discounts affect the immediate charge and new plan pricing before committing to the change. The singular `discount_code` field is deprecated but still supported for backward compatibility; we recommend `discount_codes` going forward.
## Response Fields
The preview response includes:
| Field | Description |
| ------------------ | ------------------------------------------------------------------------------ |
| `immediate_charge` | The charge that would be created immediately, including line items and summary |
| `new_plan` | The full subscription object showing how it would look after the plan change |
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.
## OpenAPI
````yaml post /subscriptions/{subscription_id}/change-plan/preview
openapi: 3.1.0
info:
title: public
description: ''
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
version: 1.102.0
servers:
- url: https://test.dodopayments.com/
description: Test Mode Server Host
- url: https://live.dodopayments.com/
description: Live Mode Server Host
security: []
tags:
- name: Products
- name: Payments
- name: Subscriptions
- name: Addons
- name: Customers
- name: Refunds
- name: Disputes
- name: Events
- name: License Keys
- name: Entitlements
- name: Licenses
- name: Discounts
- name: Meters
- name: Credit Entitlements
- name: Credit Entitlement Balances
- name: Outgoing Webhooks
- name: Checkout
- name: Webhook Events
paths:
/subscriptions/{subscription_id}/change-plan/preview:
post:
tags:
- Subscriptions
operationId: change_plan_preview_handler
parameters:
- name: subscription_id
in: path
description: Subscription Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateSubscriptionPlanReq'
required: true
responses:
'200':
description: Preview of subscription plan change
content:
application/json:
schema:
$ref: '#/components/schemas/ChangePlanPreviewResponse'
'500':
description: Something went wrong :(
security:
- API_KEY: []
x-codeSamples:
- lang: JavaScript
source: >-
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);
- lang: Python
source: |-
import os
from dodopayments import DodoPayments
client = DodoPayments(
bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"), # This is the default and can be omitted
)
response = client.subscriptions.preview_change_plan(
subscription_id="subscription_id",
product_id="product_id",
proration_billing_mode="prorated_immediately",
quantity=0,
)
print(response.immediate_charge)
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/dodopayments/dodopayments-go\"\n\t\"github.com/dodopayments/dodopayments-go/option\"\n)\n\nfunc main() {\n\tclient := dodopayments.NewClient(\n\t\toption.WithBearerToken(\"My Bearer Token\"),\n\t)\n\tresponse, err := client.Subscriptions.PreviewChangePlan(\n\t\tcontext.TODO(),\n\t\t\"subscription_id\",\n\t\tdodopayments.SubscriptionPreviewChangePlanParams{\n\t\t\tUpdateSubscriptionPlanReq: dodopayments.UpdateSubscriptionPlanReqParam{\n\t\t\t\tProductID: dodopayments.F(\"product_id\"),\n\t\t\t\tProrationBillingMode: dodopayments.F(dodopayments.UpdateSubscriptionPlanReqProrationBillingModeProratedImmediately),\n\t\t\t\tQuantity: dodopayments.F(int64(0)),\n\t\t\t},\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.ImmediateCharge)\n}\n"
- lang: Java
source: >-
package com.dodopayments.api.example;
import com.dodopayments.api.client.DodoPaymentsClient;
import com.dodopayments.api.client.okhttp.DodoPaymentsOkHttpClient;
import
com.dodopayments.api.models.subscriptions.SubscriptionPreviewChangePlanParams;
import
com.dodopayments.api.models.subscriptions.SubscriptionPreviewChangePlanResponse;
import
com.dodopayments.api.models.subscriptions.UpdateSubscriptionPlanReq;
public final class Main {
private Main() {}
public static void main(String[] args) {
DodoPaymentsClient client = DodoPaymentsOkHttpClient.fromEnv();
SubscriptionPreviewChangePlanParams params = SubscriptionPreviewChangePlanParams.builder()
.subscriptionId("subscription_id")
.updateSubscriptionPlanReq(UpdateSubscriptionPlanReq.builder()
.productId("product_id")
.prorationBillingMode(UpdateSubscriptionPlanReq.ProrationBillingMode.PRORATED_IMMEDIATELY)
.quantity(0)
.build())
.build();
SubscriptionPreviewChangePlanResponse response = client.subscriptions().previewChangePlan(params);
}
}
- lang: Kotlin
source: >-
package com.dodopayments.api.example
import com.dodopayments.api.client.DodoPaymentsClient
import com.dodopayments.api.client.okhttp.DodoPaymentsOkHttpClient
import
com.dodopayments.api.models.subscriptions.SubscriptionPreviewChangePlanParams
import
com.dodopayments.api.models.subscriptions.SubscriptionPreviewChangePlanResponse
import
com.dodopayments.api.models.subscriptions.UpdateSubscriptionPlanReq
fun main() {
val client: DodoPaymentsClient = DodoPaymentsOkHttpClient.fromEnv()
val params: SubscriptionPreviewChangePlanParams = SubscriptionPreviewChangePlanParams.builder()
.subscriptionId("subscription_id")
.updateSubscriptionPlanReq(UpdateSubscriptionPlanReq.builder()
.productId("product_id")
.prorationBillingMode(UpdateSubscriptionPlanReq.ProrationBillingMode.PRORATED_IMMEDIATELY)
.quantity(0)
.build())
.build()
val response: SubscriptionPreviewChangePlanResponse = client.subscriptions().previewChangePlan(params)
}
- lang: Ruby
source: |-
require "dodopayments"
dodo_payments = Dodopayments::Client.new(
bearer_token: "My Bearer Token",
environment: "test_mode" # defaults to "live_mode"
)
response = dodo_payments.subscriptions.preview_change_plan(
"subscription_id",
product_id: "product_id",
proration_billing_mode: :prorated_immediately,
quantity: 0
)
puts(response)
- lang: PHP
source: |-
subscriptions->previewChangePlan(
'subscription_id',
productID: 'product_id',
prorationBillingMode: 'prorated_immediately',
quantity: 0,
adaptiveCurrencyFeesInclusive: true,
addons: [['addonID' => 'addon_id', 'quantity' => 0]],
discountCode: 'discount_code',
discountCodes: ['string'],
effectiveAt: 'immediately',
metadata: ['foo' => 'string'],
onPaymentFailure: 'prevent_change',
);
var_dump($response);
} catch (APIException $e) {
echo $e->getMessage();
}
- lang: C#
source: >-
using System;
using DodoPayments.Client;
using DodoPayments.Client.Models.Subscriptions;
DodoPaymentsClient client = new();
SubscriptionPreviewChangePlanParams parameters = new()
{
SubscriptionID = "subscription_id",
ProductID = "product_id",
ProrationBillingMode = SubscriptionPreviewChangePlanParamsProrationBillingMode.ProratedImmediately,
Quantity = 0,
};
var response = await
client.Subscriptions.PreviewChangePlan(parameters);
Console.WriteLine(response);
components:
schemas:
UpdateSubscriptionPlanReq:
type: object
required:
- product_id
- quantity
- proration_billing_mode
properties:
adaptive_currency_fees_inclusive:
type:
- boolean
- 'null'
description: >-
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:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/AttachAddonReq'
description: |-
Addons for the new plan.
Note : Leaving this empty would remove any existing addons
discount_code:
type:
- string
- 'null'
description: >-
DEPRECATED: Use discount_codes instead. Cannot be used together with
discount_codes.
deprecated: true
x-stainless-deprecation-message: Use `discount_id` instead.
discount_codes:
type:
- array
- 'null'
items:
type: string
description: >-
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:
$ref: '#/components/schemas/EffectiveAt'
description: |-
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
metadata:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/Metadata'
description: >-
Metadata for the payment. If not passed, the metadata of the
subscription will be taken
on_payment_failure:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/OnPaymentFailure'
description: >-
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.
product_id:
type: string
description: Unique identifier of the product to subscribe to
proration_billing_mode:
$ref: '#/components/schemas/ProrationBillingMode'
description: Proration Billing Mode
quantity:
type: integer
format: int32
description: Number of units to subscribe for. Must be at least 1.
minimum: 0
ChangePlanPreviewResponse:
type: object
required:
- new_plan
- immediate_charge
properties:
immediate_charge:
$ref: '#/components/schemas/ImmediateCharge'
new_plan:
$ref: '#/components/schemas/SubscriptionResponse'
AttachAddonReq:
type: object
title: Attach Addon Request
required:
- addon_id
- quantity
properties:
addon_id:
type: string
quantity:
type: integer
format: int32
minimum: 0
EffectiveAt:
type: string
description: When to apply a subscription plan change.
enum:
- immediately
- next_billing_date
Metadata:
type: object
additionalProperties:
type: string
propertyNames:
type: string
OnPaymentFailure:
type: string
description: >-
Specifies how to handle subscription plan changes when payment fails.
This enum controls whether the subscription should be updated
immediately
or only after payment succeeds.
enum:
- prevent_change
- apply_change
ProrationBillingMode:
type: string
title: Proration Billing Mode
enum:
- prorated_immediately
- full_immediately
- difference_immediately
- do_not_bill
ImmediateCharge:
type: object
required:
- summary
- line_items
- effective_at
properties:
effective_at:
type: string
format: date-time
description: When the plan change will be effective
line_items:
type: array
items:
$ref: '#/components/schemas/LineItem'
summary:
$ref: '#/components/schemas/LineItemSummary'
SubscriptionResponse:
type: object
description: Response struct representing subscription details
required:
- subscription_id
- recurring_pre_tax_amount
- tax_inclusive
- currency
- status
- created_at
- product_id
- quantity
- trial_period_days
- subscription_period_interval
- payment_frequency_interval
- subscription_period_count
- payment_frequency_count
- next_billing_date
- previous_billing_date
- customer
- metadata
- cancel_at_next_billing_date
- billing
- on_demand
- addons
- meters
- credit_entitlement_cart
- meter_credit_entitlement_cart
properties:
addons:
type: array
items:
$ref: '#/components/schemas/AddonCartResponseItem'
description: Addons associated with this subscription
billing:
$ref: '#/components/schemas/BillingAddress'
description: Billing address details for payments
cancel_at_next_billing_date:
type: boolean
description: Indicates if the subscription will cancel at the next billing date
cancellation_comment:
type:
- string
- 'null'
description: Free-text cancellation comment, if any
cancellation_feedback:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/CancellationFeedback'
description: Customer-supplied churn reason, if any
cancelled_at:
type:
- string
- 'null'
format: date-time
description: Cancelled timestamp if the subscription is cancelled
created_at:
type: string
format: date-time
description: Timestamp when the subscription was created
credit_entitlement_cart:
type: array
items:
$ref: '#/components/schemas/CreditEntitlementCartResponse'
description: Credit entitlement cart settings for this subscription
currency:
$ref: '#/components/schemas/Currency'
description: Currency used for the subscription payments
custom_field_responses:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/CustomFieldResponse'
description: Customer's responses to custom fields collected during checkout
customer:
$ref: '#/components/schemas/CustomerLimitedDetailsResponse'
description: Customer details associated with the subscription
customer_business_name:
type:
- string
- 'null'
description: >-
Business / legal name associated with the tax id (B2B). When set
this is
used on the invoice in place of the customer's personal name.
discount_cycles_remaining:
type:
- integer
- 'null'
format: int32
description: 'DEPRECATED: Use discounts[].cycles_remaining instead.'
discount_id:
type:
- string
- 'null'
description: >-
DEPRECATED: Use discounts instead. Returns the first discount's ID
if present.
discounts:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/DiscountDetailResponse'
description: All stacked discounts applied, ordered by position
expires_at:
type:
- string
- 'null'
format: date-time
description: Timestamp when the subscription will expire
metadata:
$ref: '#/components/schemas/Metadata'
description: Additional custom data associated with the subscription
meter_credit_entitlement_cart:
type: array
items:
$ref: '#/components/schemas/MeterCreditEntitlementCartResponse'
description: Meter credit entitlement cart settings for this subscription
meters:
type: array
items:
$ref: '#/components/schemas/MeterCartResponseItem'
description: Meters associated with this subscription (for usage-based billing)
next_billing_date:
type: string
format: date-time
description: >-
Timestamp of the next scheduled billing. Indicates the end of
current billing period
on_demand:
type: boolean
description: Wether the subscription is on-demand or not
payment_frequency_count:
type: integer
format: int32
description: Number of payment frequency intervals
payment_frequency_interval:
$ref: '#/components/schemas/TimeInterval'
description: Time interval for payment frequency (e.g. month, year)
payment_method_id:
type:
- string
- 'null'
description: Saved payment method id used for recurring charges
previous_billing_date:
type: string
format: date-time
description: >-
Timestamp of the last payment. Indicates the start of current
billing period
product_id:
type: string
description: Identifier of the product associated with this subscription
quantity:
type: integer
format: int32
description: Number of units/items included in the subscription
recurring_pre_tax_amount:
type: integer
format: int32
description: >-
Amount charged before tax for each recurring payment in smallest
currency unit (e.g. cents)
scheduled_change:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/ScheduledPlanChangeResponse'
description: Scheduled plan change details, if any
status:
$ref: '#/components/schemas/SubscriptionStatus'
description: Current status of the subscription
subscription_id:
type: string
description: Unique identifier for the subscription
subscription_period_count:
type: integer
format: int32
description: Number of subscription period intervals
subscription_period_interval:
$ref: '#/components/schemas/TimeInterval'
description: Time interval for the subscription period (e.g. month, year)
tax_id:
type:
- string
- 'null'
description: Tax identifier provided for this subscription (if applicable)
tax_inclusive:
type: boolean
description: Indicates if the recurring_pre_tax_amount is tax inclusive
trial_period_days:
type: integer
format: int32
description: Number of days in the trial period (0 if no trial)
LineItem:
oneOf:
- type: object
title: Subscription
required:
- id
- product_id
- unit_price
- quantity
- tax_inclusive
- currency
- proration_factor
- type
properties:
currency:
$ref: '#/components/schemas/Currency'
description:
type:
- string
- 'null'
id:
type: string
name:
type:
- string
- 'null'
product_id:
type: string
proration_factor:
type: number
format: double
quantity:
type: integer
format: int32
tax:
type:
- integer
- 'null'
format: int32
tax_inclusive:
type: boolean
tax_rate:
type:
- number
- 'null'
format: float
type:
type: string
enum:
- subscription
x-stainless-const: true
unit_price:
type: integer
format: int32
- type: object
title: Addon
required:
- id
- name
- tax_category
- unit_price
- quantity
- tax_rate
- tax_inclusive
- currency
- proration_factor
- type
properties:
currency:
$ref: '#/components/schemas/Currency'
description:
type:
- string
- 'null'
id:
type: string
name:
type: string
proration_factor:
type: number
format: double
quantity:
type: integer
format: int32
tax:
type:
- integer
- 'null'
format: int32
tax_category:
$ref: '#/components/schemas/TaxCategory'
tax_inclusive:
type: boolean
tax_rate:
type: number
format: float
type:
type: string
enum:
- addon
x-stainless-const: true
unit_price:
type: integer
format: int32
- type: object
title: Meter
required:
- id
- name
- units_consumed
- chargeable_units
- free_threshold
- price_per_unit
- subtotal
- tax_rate
- tax_inclusive
- currency
- type
properties:
chargeable_units:
type: string
currency:
$ref: '#/components/schemas/Currency'
description:
type:
- string
- 'null'
free_threshold:
type: integer
format: int64
id:
type: string
name:
type: string
price_per_unit:
type: string
subtotal:
type: integer
format: int32
tax:
type:
- integer
- 'null'
format: int32
tax_inclusive:
type: boolean
tax_rate:
type: number
format: float
type:
type: string
enum:
- meter
x-stainless-const: true
units_consumed:
type: string
discriminator:
propertyName: type
LineItemSummary:
type: object
required:
- total_amount
- currency
- settlement_amount
- settlement_currency
- customer_credits
properties:
currency:
$ref: '#/components/schemas/Currency'
customer_credits:
type: integer
format: int64
settlement_amount:
type: integer
format: int32
settlement_currency:
$ref: '#/components/schemas/Currency'
settlement_tax:
type:
- integer
- 'null'
format: int32
tax:
type:
- integer
- 'null'
format: int32
total_amount:
type: integer
format: int32
AddonCartResponseItem:
type: object
title: Addon Cart Response Item
description: Response struct representing subscription details
required:
- addon_id
- quantity
properties:
addon_id:
type: string
quantity:
type: integer
format: int32
BillingAddress:
type: object
required:
- country
properties:
city:
type:
- string
- 'null'
description: City name
country:
$ref: '#/components/schemas/CountryCodeAlpha2'
description: Two-letter ISO country code (ISO 3166-1 alpha-2)
state:
type:
- string
- 'null'
description: State or province name
street:
type:
- string
- 'null'
description: >-
Street address including house number and unit/apartment if
applicable
zipcode:
type:
- string
- 'null'
description: Postal code or ZIP code
CancellationFeedback:
type: string
enum:
- too_expensive
- missing_features
- switched_service
- unused
- customer_service
- low_quality
- too_complex
- other
CreditEntitlementCartResponse:
type: object
description: >-
Response struct representing credit entitlement cart details for a
subscription
required:
- credit_entitlement_id
- credit_entitlement_name
- unit
- product_id
- credits_amount
- rollover_enabled
- overage_enabled
- overage_behavior
- remaining_balance
- overage_balance
properties:
credit_entitlement_id:
type: string
credit_entitlement_name:
type: string
credits_amount:
type: string
expires_after_days:
type:
- integer
- 'null'
format: int32
low_balance_threshold_percent:
type:
- integer
- 'null'
format: int32
max_rollover_count:
type:
- integer
- 'null'
format: int32
overage_balance:
type: string
description: Customer's current overage balance for this entitlement
overage_behavior:
$ref: '#/components/schemas/CbbOverageBehavior'
overage_enabled:
type: boolean
overage_limit:
type:
- string
- 'null'
product_id:
type: string
remaining_balance:
type: string
description: Customer's current remaining credit balance for this entitlement
rollover_enabled:
type: boolean
rollover_percentage:
type:
- integer
- 'null'
format: int32
rollover_timeframe_count:
type:
- integer
- 'null'
format: int32
rollover_timeframe_interval:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/TimeInterval'
unit:
type: string
description: Unit label for the credit entitlement (e.g., "API Calls", "Tokens")
Currency:
type: string
enum:
- AED
- ALL
- AMD
- ANG
- AOA
- ARS
- AUD
- AWG
- AZN
- BAM
- BBD
- BDT
- BGN
- BHD
- BIF
- BMD
- BND
- BOB
- BRL
- BSD
- BWP
- BYN
- BZD
- CAD
- CHF
- CLP
- CNY
- COP
- CRC
- CUP
- CVE
- CZK
- DJF
- DKK
- DOP
- DZD
- EGP
- ETB
- EUR
- FJD
- FKP
- GBP
- GEL
- GHS
- GIP
- GMD
- GNF
- GTQ
- GYD
- HKD
- HNL
- HRK
- HTG
- HUF
- IDR
- ILS
- INR
- IQD
- JMD
- JOD
- JPY
- KES
- KGS
- KHR
- KMF
- KRW
- KWD
- KYD
- KZT
- LAK
- LBP
- LKR
- LRD
- LSL
- LYD
- MAD
- MDL
- MGA
- MKD
- MMK
- MNT
- MOP
- MRU
- MUR
- MVR
- MWK
- MXN
- MYR
- MZN
- NAD
- NGN
- NIO
- NOK
- NPR
- NZD
- OMR
- PAB
- PEN
- PGK
- PHP
- PKR
- PLN
- PYG
- QAR
- RON
- RSD
- RUB
- RWF
- SAR
- SBD
- SCR
- SEK
- SGD
- SHP
- SLE
- SLL
- SOS
- SRD
- SSP
- STN
- SVC
- SZL
- THB
- TND
- TOP
- TRY
- TTD
- TWD
- TZS
- UAH
- UGX
- USD
- UYU
- UZS
- VES
- VND
- VUV
- WST
- XAF
- XCD
- XOF
- XPF
- YER
- ZAR
- ZMW
CustomFieldResponse:
type: object
description: Customer's response to a custom field
required:
- key
- value
properties:
key:
type: string
description: Key matching the custom field definition
value:
type: string
description: Value provided by customer
CustomerLimitedDetailsResponse:
type: object
required:
- customer_id
- name
- email
properties:
customer_id:
type: string
description: Unique identifier for the customer
email:
type: string
description: Email address of the customer
metadata:
$ref: '#/components/schemas/Metadata'
description: Additional metadata associated with the customer
name:
type: string
description: Full name of the customer
phone_number:
type:
- string
- 'null'
description: Phone number of the customer
DiscountDetailResponse:
type: object
description: |-
Response struct for a discount with its position in a stack and optional
cycle-tracking information (for subscriptions).
required:
- position
- discount_id
- business_id
- type
- code
- amount
- times_used
- restricted_to
- created_at
- preserve_on_plan_change
- metadata
properties:
amount:
type: integer
format: int32
description: The discount amount in **basis points** (e.g., 540 => 5.4%).
business_id:
type: string
description: The business this discount belongs to
code:
type: string
description: The discount code
created_at:
type: string
format: date-time
description: Timestamp when the discount was created
cycles_remaining:
type:
- integer
- 'null'
format: int32
description: >-
Remaining billing cycles for this discount on this subscription
(None for one-time payments)
discount_id:
type: string
description: The unique discount ID
expires_at:
type:
- string
- 'null'
format: date-time
description: Optional date/time after which discount is expired
metadata:
$ref: '#/components/schemas/Metadata'
description: Additional metadata
name:
type:
- string
- 'null'
description: Name for the Discount
position:
type: integer
format: int32
description: Position of this discount in the stack (0-based)
preserve_on_plan_change:
type: boolean
description: >-
Whether this discount should be preserved when a subscription
changes plans
restricted_to:
type: array
items:
type: string
description: List of product IDs to which this discount is restricted
subscription_cycles:
type:
- integer
- 'null'
format: int32
description: Number of subscription billing cycles this discount is valid for
times_used:
type: integer
format: int32
description: How many times this discount has been used
type:
$ref: '#/components/schemas/DiscountType'
description: The type of discount
usage_limit:
type:
- integer
- 'null'
format: int32
description: Usage limit for this discount, if any
MeterCreditEntitlementCartResponse:
type: object
description: >-
Response struct representing meter-credit entitlement mapping cart
details for a subscription
required:
- meter_id
- meter_name
- credit_entitlement_id
- product_id
- meter_units_per_credit
properties:
credit_entitlement_id:
type: string
meter_id:
type: string
meter_name:
type: string
meter_units_per_credit:
type: string
product_id:
type: string
MeterCartResponseItem:
type: object
description: >-
Response struct representing usage-based meter cart details for a
subscription
required:
- meter_id
- free_threshold
- currency
- name
- measurement_unit
properties:
currency:
$ref: '#/components/schemas/Currency'
description:
type:
- string
- 'null'
free_threshold:
type: integer
format: int64
measurement_unit:
type: string
meter_id:
type: string
name:
type: string
price_per_unit:
type:
- string
- 'null'
example: '10.50'
TimeInterval:
type: string
enum:
- Day
- Week
- Month
- Year
ScheduledPlanChangeResponse:
type: object
required:
- id
- product_id
- quantity
- effective_at
- created_at
- addons
properties:
addons:
type: array
items:
$ref: '#/components/schemas/ScheduledAddonResponse'
description: Addons included in the scheduled change
created_at:
type: string
format: date-time
description: When this scheduled change was created
effective_at:
type: string
format: date-time
description: When the change will be applied
id:
type: string
description: The scheduled plan change ID
product_description:
type:
- string
- 'null'
description: Description of the product being changed to
product_id:
type: string
description: The product ID the subscription will change to
product_name:
type:
- string
- 'null'
description: Name of the product being changed to
quantity:
type: integer
format: int32
description: Quantity for the new plan
SubscriptionStatus:
type: string
enum:
- pending
- active
- on_hold
- cancelled
- failed
- expired
TaxCategory:
type: string
description: >-
Represents the different categories of taxation applicable to various
products and services.
enum:
- digital_products
- saas
- e_book
- edtech
CountryCodeAlpha2:
type: string
description: ISO country code alpha2 variant
enum:
- AF
- AX
- AL
- DZ
- AS
- AD
- AO
- AI
- AQ
- AG
- AR
- AM
- AW
- AU
- AT
- AZ
- BS
- BH
- BD
- BB
- BY
- BE
- BZ
- BJ
- BM
- BT
- BO
- BQ
- BA
- BW
- BV
- BR
- IO
- BN
- BG
- BF
- BI
- KH
- CM
- CA
- CV
- KY
- CF
- TD
- CL
- CN
- CX
- CC
- CO
- KM
- CG
- CD
- CK
- CR
- CI
- HR
- CU
- CW
- CY
- CZ
- DK
- DJ
- DM
- DO
- EC
- EG
- SV
- GQ
- ER
- EE
- ET
- FK
- FO
- FJ
- FI
- FR
- GF
- PF
- TF
- GA
- GM
- GE
- DE
- GH
- GI
- GR
- GL
- GD
- GP
- GU
- GT
- GG
- GN
- GW
- GY
- HT
- HM
- VA
- HN
- HK
- HU
- IS
- IN
- ID
- IR
- IQ
- IE
- IM
- IL
- IT
- JM
- JP
- JE
- JO
- KZ
- KE
- KI
- KP
- KR
- KW
- KG
- LA
- LV
- LB
- LS
- LR
- LY
- LI
- LT
- LU
- MO
- MK
- MG
- MW
- MY
- MV
- ML
- MT
- MH
- MQ
- MR
- MU
- YT
- MX
- FM
- MD
- MC
- MN
- ME
- MS
- MA
- MZ
- MM
- NA
- NR
- NP
- NL
- NC
- NZ
- NI
- NE
- NG
- NU
- NF
- MP
- 'NO'
- OM
- PK
- PW
- PS
- PA
- PG
- PY
- PE
- PH
- PN
- PL
- PT
- PR
- QA
- RE
- RO
- RU
- RW
- BL
- SH
- KN
- LC
- MF
- PM
- VC
- WS
- SM
- ST
- SA
- SN
- RS
- SC
- SL
- SG
- SX
- SK
- SI
- SB
- SO
- ZA
- GS
- SS
- ES
- LK
- SD
- SR
- SJ
- SZ
- SE
- CH
- SY
- TW
- TJ
- TZ
- TH
- TL
- TG
- TK
- TO
- TT
- TN
- TR
- TM
- TC
- TV
- UG
- UA
- AE
- GB
- UM
- US
- UY
- UZ
- VU
- VE
- VN
- VG
- VI
- WF
- EH
- YE
- ZM
- ZW
CbbOverageBehavior:
type: string
description: >-
Controls how overage is handled at the end of a billing cycle.
| Preset | Charge at billing | Credits reduce overage |
Preserve overage at reset |
|-------------------------|:-----------------:|:---------------------:|:-------------------------:|
| `forgive_at_reset` | No | No |
No |
| `invoice_at_billing` | Yes | No |
No |
| `carry_deficit` | No | No |
Yes |
| `carry_deficit_auto_repay` | No | Yes |
Yes |
enum:
- forgive_at_reset
- invoice_at_billing
- carry_deficit
- carry_deficit_auto_repay
DiscountType:
type: string
enum:
- percentage
x-stainless-const: true
ScheduledAddonResponse:
type: object
required:
- addon_id
- name
- quantity
properties:
addon_id:
type: string
description: The addon ID
name:
type: string
description: Name of the addon
quantity:
type: integer
format: int32
description: Quantity of the addon
securitySchemes:
API_KEY:
type: http
scheme: bearer
````