Skip to main content
POST
/
subscriptions
/
{id}
/
change
/
preview
Preview subscription plan change
curl --request POST \
  --url https://api.cloud.flexprice.io/v1/subscriptions/{id}/change/preview \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "billing_cadence": "RECURRING",
  "billing_cycle": "anniversary",
  "billing_period": "MONTHLY",
  "proration_behavior": "create_prorations",
  "target_plan_id": "<string>",
  "billing_period_count": 123,
  "metadata": {}
}
'
{
  "change_type": "upgrade",
  "current_plan": {
    "description": "<string>",
    "id": "<string>",
    "lookup_key": "<string>",
    "name": "<string>"
  },
  "effective_date": "<string>",
  "metadata": {},
  "new_billing_cycle": {
    "billing_anchor": "<string>",
    "billing_cadence": "RECURRING",
    "billing_period": "MONTHLY",
    "billing_period_count": 123,
    "period_end": "<string>",
    "period_start": "<string>"
  },
  "next_invoice_preview": {
    "currency": "<string>",
    "due_date": "<string>",
    "line_items": [
      {
        "amount": "<string>",
        "description": "<string>",
        "is_proration": true,
        "period_end": "<string>",
        "period_start": "<string>",
        "quantity": "<string>",
        "unit_price": "<string>"
      }
    ],
    "subtotal": "<string>",
    "tax_amount": "<string>",
    "total": "<string>"
  },
  "proration_details": {
    "charge_amount": "<string>",
    "charge_description": "<string>",
    "credit_amount": "<string>",
    "credit_description": "<string>",
    "currency": "<string>",
    "current_period_end": "<string>",
    "current_period_start": "<string>",
    "days_remaining": 123,
    "days_used": 123,
    "net_amount": "<string>",
    "proration_date": "<string>"
  },
  "subscription_id": "<string>",
  "target_plan": {
    "description": "<string>",
    "id": "<string>",
    "lookup_key": "<string>",
    "name": "<string>"
  },
  "warnings": [
    "<string>"
  ]
}

Authorizations

​
x-api-key
string
header
required

Enter your API key in the format x-api-key <api-key>*

Path Parameters

​
id
string
required

Subscription ID

Body

application/json

Subscription change preview request

Request object for changing a subscription plan (upgrade/downgrade)

​
billing_cadence
enum<string>
required
Available options:
RECURRING,
ONETIME
​
billing_cycle
enum<string>
required
Available options:
anniversary,
calendar
​
billing_period
enum<string>
required
Available options:
MONTHLY,
ANNUAL,
WEEKLY,
DAILY,
QUARTERLY,
HALF_YEARLY
​
proration_behavior
enum<string>
required
Available options:
create_prorations,
none
​
target_plan_id
string
required

target_plan_id is the ID of the new plan to change to (required)

​
billing_period_count
integer

billing_period_count is the billing period count for the new subscription

​
metadata
object

metadata contains additional key-value pairs for storing extra information

Response

OK

Response showing the financial impact of a subscription plan change

​
change_type
enum<string>
Available options:
upgrade,
downgrade,
lateral
​
current_plan
object
​
effective_date
string

effective_date is when the change would take effect

​
metadata
object

metadata from the request

​
new_billing_cycle
object
​
next_invoice_preview
object
​
proration_details
object
​
subscription_id
string

subscription_id is the ID of the subscription being changed

​
target_plan
object
​
warnings
string[]

warnings contains any warnings about the change