Estimate a subscription upgrade

Gets a pricing estimate for an open subscription upgrade including the billing schedule and grand total.

POST /subscriptions/{subscription_id}/upgrade/estimate

Estimate a subscription upgrade

cURL

curl --request POST \
  --url https://api.salesbricks.com/api/v2/subscriptions/{subscription_id}/upgrade/estimate \
  --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>"
      ]
    }
  ]
}
'

200

{
  "ends_at": "2023-12-25",
  "sub_total": 123,
  "grand_total": 123,
  "line_items": [
    {
      "quantity": 123,
      "brick_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "brick_name": "<string>",
      "sub_total": 123,
      "plan_id": "<string>",
      "plan_name": "<string>",
      "grand_total": "<string>",
      "grand_total_details": "<string>",
      "tiers_breakdown": [
        {
          "quantity": 0,
          "unit_price": "<string>",
          "sub_total": "<string>",
          "duration_text": "<string>"
        }
      ],
      "pre_commitment_schedule": "<string>",
      "discount": [
        {
          "rate": "<string>",
          "amount": 123,
          "renews": false
        }
      ]
    }
  ],
  "billing_schedule": [
    {
      "starts_at": "<string>",
      "ends_at": "<string>",
      "sub_total": 123,
      "grand_total": "<string>",
      "grand_total_details": "<string>"
    }
  ],
  "grand_total_details": "<unknown>",
  "phases": [
    {
      "phase_position": 123,
      "starts_at": "2023-12-25",
      "ends_at": "2023-12-25",
      "billing_frequency": "MONTHLY",
      "payment_terms": 123,
      "sub_total": 123,
      "grand_total": 123,
      "line_items": [
        {
          "quantity": 123,
          "brick_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "brick_name": "<string>",
          "sub_total": 123,
          "plan_id": "<string>",
          "plan_name": "<string>",
          "grand_total": "<string>",
          "grand_total_details": "<string>",
          "tiers_breakdown": [
            {
              "quantity": 0,
              "unit_price": "<string>",
              "sub_total": "<string>",
              "duration_text": "<string>"
            }
          ],
          "pre_commitment_schedule": "<string>",
          "discount": [
            {
              "rate": "<string>",
              "amount": 123,
              "renews": false
            }
          ]
        }
      ],
      "billing_schedule": [
        {
          "starts_at": "<string>",
          "ends_at": "<string>",
          "sub_total": 123,
          "grand_total": "<string>",
          "grand_total_details": "<string>"
        }
      ]
    }
  ]
}

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

SubscriptionInputUpgradeEstimateSinglePhase

SubscriptionInputUpgradeEstimateMultiPhase

Subscription upgrade estimate input serializer for generating pricing estimate for subscription order upgrade.

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 use 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

Response

200

application/json

Subscription /estimate output serializer from OrderPricing

SAL-6964: the commercial payload lives at exactly one altitude. A multi-phase order carries it per phase and omits the order-level copies — the same brick appears once per phase and may differ in each, so a single flattened set can only misrepresent it. A single-phase order keeps the order-level fields and omits phases entirely, since a lone phase restates the order. See PHASE_OWNED_FIELDS.

ends_at · string<date> · required

The end date of the subscription

sub_total · integer · required

Subtotal before taxes and discounts

grand_total · integer · required

Final total after taxes and discounts

line_items · object[] · required

The line items of the subscription

Show child attributes

billing_schedule · object[] · required

The billing schedule of the subscription

Show child attributes

grand_total_details · any · required

Breakdown containing total discount and tax amounts

phases · object[]

Per-phase breakdown. Only present for multi-phase estimates.

Show child attributes