Skip to main content
Create a subscription upgrade
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>",
        "renews": true
      }
    }
  ],
  "plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "discount_coupons": [
    "<string>"
  ],
  "custom_order_form_html": "<string>",
  "metadata": "<unknown>"
}
'
{
  "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

Subscription upgrade input serializer for upgrading a subscription order.

​
starts_at
string<date>
required

The start date of the subscription upgrade

​
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.)

​
plan_id
string<uuid>

Optional plan ID for the upgrade. When provided, the upgrade uses the latest published pricing for that plan. When omitted, the upgrade keeps your existing pricing. Any new bricks will use the same plan's pricing, or if not available, the latest plan's pricing. This is to grandfather customers in at their existing pricing.

​
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.

​
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

Serializer for individual subscription order

​
order_id
string<uuid>
required

Unique identifier for the order

​
contract_value
string
required

Total contract value with currency

​
pdf_url
string
required

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