Create a subscription upgrade

Creates a subscription upgrade that can be used to add or remove add-ons from an existing contract term.

• Use /subscriptions/{subscription_id}/upgrade/{order_id}/estimate to preview pricing before confirming
• Use /subscriptions/{subscription_id}/upgrade/{order_id}/start to begin the upgrade

How plan_id affects pricing:

• plan_id omitted — the upgrade keeps the subscription’s current plan version and contracted pricing (customers stay grandfathered). If bricks includes a brick that doesn’t exist on the current plan version, it is pulled in from that plan’s latest published version, producing a merged plan version.
• plan_id provided — the upgrade switches to the latest published version of the referenced plan. If bricks references a brick that only exists on the subscription’s prior plan version, it is carried over into a merged plan version.
• plan_id may reference a different plan than the subscription’s current plan; that is how cross-plan upgrades are expressed.
• plan_id is only honoured when bricks is also provided. Sending plan_id without bricks returns 400.

How bricks affects existing discounts:

Per-brick discounts are replaced, not merged. The discount sent on a brick becomes that brick’s complete set of discounts for this order, and a brick sent without a discount ends up with none — any discount it previously carried is dropped.

This applies to every brick in the payload, not only the ones being changed. A brick included solely to keep it on the order still needs its discount resent, or it loses it.

Read the current values from the subscription’s line items — discount is returned there in the same shape this endpoint accepts — and send them back for every brick whose discount should carry over.

POST /subscriptions/{subscription_id}/upgrade

Create a subscription upgrade

cURL

curl --request POST \
  --url https://api.salesbricks.com/api/v2/subscriptions/{subscription_id}/upgrade \
  --header 'Content-Type: application/json' \
  --header 'X-SALESBRICKS-KEY: <api-key>' \
  --data '
{
  "starts_at": "2023-12-25",
  "bricks": [
    {
      "brick_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "quantity": 123,
      "discount": [
        {
          "rate": "<string>",
          "amount": 123,
          "renews": false
        }
      ]
    }
  ],
  "plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "discount_coupons": [
    "<string>"
  ],
  "phases": [
    {
      "phase_position": 1,
      "bricks": [
        {
          "brick_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "quantity": 123,
          "discount": [
            {
              "rate": "<string>",
              "amount": 123,
              "renews": false
            }
          ]
        }
      ],
      "starts_at": "2023-12-25",
      "contract_length": 2,
      "plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "payment_terms": 499,
      "discount_coupons": [
        "<string>"
      ]
    }
  ],
  "custom_order_form_html": "<string>",
  "metadata": "<unknown>"
}
'

200

{
  "order_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "contract_value": "<string>",
  "pdf_url": "<string>",
  "starts_at": "2023-12-25",
  "ends_at": "2023-12-25",
  "order_type": "TRIAL"
}

Authorizations

X-SALESBRICKS-KEY · string · header · required

API key for authentication

Path Parameters

subscription_id · string · required

Pattern: ^([a-zA-Z\d\-]+)$

Body

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

SubscriptionInputUpgradeSinglePhase

SubscriptionInputUpgradeMultiPhase

Subscription upgrade input serializer for upgrading a subscription order.

This payload has two forms — see anyOf:

• Single-phase — omit phases; the order-level starts_at, contract_length, billing_frequency and bricks define the one phase and are required.
• Multi-phase — send phases; the phases own the timeline, billing frequency and bricks, and the order-level equivalents become optional (omitted, they are derived from the phases).

The fields are declared optional because OpenAPI 3.0 cannot make one field's required depend on another. Sending neither form is a 400.

starts_at · string<date> · required

The effective date of the subscription upgrade. Required only when phases is omitted: when phases is provided the phases own the timeline, so the effective date is taken from the first phase's starts_at and this order-level value is ignored.

bricks · object[] · required

The bricks included in subscription upgrade. Quantity is used to upgrade the add-on quantity (ie. adding 2 more units should be quantity 2 -> quantity 4). For usage, quantity is used to set the pre-commitment (ie. previously having 5 pre-commitment quantity and updating it to 10 would update the pre-commitment quantity to 10.)

Show child attributes

plan_id · string<uuid>

Optional plan ID for the upgrade. When provided, the upgrade switches to the latest published version of that plan; when omitted, it keeps the subscription's existing plan version and contracted pricing. Must be sent together with bricks — plan_id alone is rejected with 400. See the endpoint description for full semantics including cross-plan upgrades and merged plan versions.

discount_coupons · string[]

Discount coupon codes to apply to the subscription upgrade. Currently only supports one discount coupon - only the first one in the list will be applied.

phases · object[] | null

Optional list of phases for a multi-phase upgrade. Each phase's phase_position must match a phase on the base order; only the phases being changed need to be sent, and omitted positions are inherited from the base order unchanged. Order-level bricks and starts_at are ignored when phases are provided — the phases own the timeline and the first phase's starts_at is the upgrade's effective date.

Show child attributes

custom_order_form_html · string

The custom order form html to use with <html><body>...</body></html> formatting

metadata · any | null

Optional metadata to add to the subscription. Sending an empty map will delete all keys. Keys prefixed with _ are private and will be ignored.

Response

200

application/json

Serializer for individual subscription order

order_id · string<uuid> · required

Unique identifier for the order

contract_value · string · required · read-only

Total contract value with currency

pdf_url · string · required · read-only

URL to download signed order form PDF

starts_at · string<date>

ends_at · string<date>

order_type · enum<string>

• TRIAL - Trial
• STANDARD - New Business
• RENEWAL - Renewal
• UPGRADE - Upgrade
• RECAST - Recast

Available options: TRIAL, STANDARD, RENEWAL, UPGRADE, RECAST