Zum Hauptinhalt springen
POST
/
api
/
customer
/
subscriptions
/
{id}
/
plan-tier-preview
Preview a tier switch
curl --request POST \
  --url https://coreapi.io/api/customer/subscriptions/{id}/plan-tier-preview \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "planTierId": "f5ece259-08ea-77a4-8bd9-9f3a9ed9e246",
  "items": []
}
'
{
  "creditAmount": "14.50",
  "chargeAmount": "24.50",
  "currency": "EUR",
  "effectiveAt": "2023-11-07T05:31:56Z",
  "recurringTotal": {
    "netAmount": "49.00",
    "taxAmount": "9.31",
    "grossAmount": "58.31",
    "currency": "EUR"
  },
  "warnings": [
    "active_discount_will_be_lost"
  ]
}

Autorisierungen

​
Authorization
string
header
erforderlich

Customer access token. Send it as Authorization: Bearer . Obtain it server side via POST /customers/{id}/authenticate (use the response accessToken), or from a customer portal session. The token must carry the customer:plan:switch permission.

Pfadparameter

​
id
string<uuid>
erforderlich

The subscription UUID.

Beispiel:

"1280792f-4e23-793d-8e9c-3a1bf36630bd"

Body

application/json
​
planTierId
string
erforderlich

UUID of the target tier to preview.

​
items
object[]

Optional quantity overrides for editable items of the target tier.

Antwort

The switch preview. May be null when no schedule exists yet.

Financial preview of a tier switch. creditAmount and chargeAmount are absolute decimal strings, the direction is implied by the field name.

​
creditAmount
string

Credit for unused time on the current items. 0.00 when the target tier does not credit.

Beispiel:

"14.50"

​
chargeAmount
string

Charge for the partial period on the new items.

Beispiel:

"24.50"

​
currency
string
Beispiel:

"EUR"

​
effectiveAt
string<date-time>

Date the switch is calculated for. For end_of_period tiers the preview uses the current moment, so the amounts are an approximation.

​
recurringTotal
object

Recurring amount for one billing period. Amounts are decimal strings.

​
warnings
string[]

Hints about side effects, for example that an active discount will not carry over.

Beispiel:
["active_discount_will_be_lost"]