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,
      "is_unlimited": true,
      "discount": [
        {
          "rate": "<string>",
          "amount": 123,
          "renews": false
        }
      ]
    }
  ],
  "crm_opportunity_id": "<string>",
  "plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "discount_coupons": [
    "<string>"
  ],
  "phases": [
    {
      "phase_position": 1,
      "bricks": [
        {
          "brick_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "quantity": 123,
          "is_unlimited": true,
          "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>"
}
'

import requests

url = "https://api.salesbricks.com/api/v2/subscriptions/{subscription_id}/upgrade"

payload = {
    "starts_at": "2023-12-25",
    "bricks": [
        {
            "brick_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "quantity": 123,
            "is_unlimited": True,
            "discount": [
                {
                    "rate": "<string>",
                    "amount": 123,
                    "renews": False
                }
            ]
        }
    ],
    "crm_opportunity_id": "<string>",
    "plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "discount_coupons": ["<string>"],
    "phases": [
        {
            "phase_position": 1,
            "bricks": [
                {
                    "brick_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
                    "quantity": 123,
                    "is_unlimited": True,
                    "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>"
}
headers = {
    "X-SALESBRICKS-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-SALESBRICKS-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    starts_at: '2023-12-25',
    bricks: [
      {
        brick_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
        quantity: 123,
        is_unlimited: true,
        discount: [{rate: '<string>', amount: 123, renews: false}]
      }
    ],
    crm_opportunity_id: '<string>',
    plan_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    discount_coupons: ['<string>'],
    phases: [
      {
        phase_position: 1,
        bricks: [
          {
            brick_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
            quantity: 123,
            is_unlimited: true,
            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>'
  })
};

fetch('https://api.salesbricks.com/api/v2/subscriptions/{subscription_id}/upgrade', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.salesbricks.com/api/v2/subscriptions/{subscription_id}/upgrade",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'starts_at' => '2023-12-25',
    'bricks' => [
        [
                'brick_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
                'quantity' => 123,
                'is_unlimited' => true,
                'discount' => [
                                [
                                                                'rate' => '<string>',
                                                                'amount' => 123,
                                                                'renews' => false
                                ]
                ]
        ]
    ],
    'crm_opportunity_id' => '<string>',
    'plan_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'discount_coupons' => [
        '<string>'
    ],
    'phases' => [
        [
                'phase_position' => 1,
                'bricks' => [
                                [
                                                                'brick_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
                                                                'quantity' => 123,
                                                                'is_unlimited' => true,
                                                                '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>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-SALESBRICKS-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.salesbricks.com/api/v2/subscriptions/{subscription_id}/upgrade"

	payload := strings.NewReader("{\n  \"starts_at\": \"2023-12-25\",\n  \"bricks\": [\n    {\n      \"brick_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"quantity\": 123,\n      \"is_unlimited\": true,\n      \"discount\": [\n        {\n          \"rate\": \"<string>\",\n          \"amount\": 123,\n          \"renews\": false\n        }\n      ]\n    }\n  ],\n  \"crm_opportunity_id\": \"<string>\",\n  \"plan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"discount_coupons\": [\n    \"<string>\"\n  ],\n  \"phases\": [\n    {\n      \"phase_position\": 1,\n      \"bricks\": [\n        {\n          \"brick_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n          \"quantity\": 123,\n          \"is_unlimited\": true,\n          \"discount\": [\n            {\n              \"rate\": \"<string>\",\n              \"amount\": 123,\n              \"renews\": false\n            }\n          ]\n        }\n      ],\n      \"starts_at\": \"2023-12-25\",\n      \"contract_length\": 2,\n      \"plan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"payment_terms\": 499,\n      \"discount_coupons\": [\n        \"<string>\"\n      ]\n    }\n  ],\n  \"custom_order_form_html\": \"<string>\",\n  \"metadata\": \"<unknown>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-SALESBRICKS-KEY", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.salesbricks.com/api/v2/subscriptions/{subscription_id}/upgrade")
  .header("X-SALESBRICKS-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"starts_at\": \"2023-12-25\",\n  \"bricks\": [\n    {\n      \"brick_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"quantity\": 123,\n      \"is_unlimited\": true,\n      \"discount\": [\n        {\n          \"rate\": \"<string>\",\n          \"amount\": 123,\n          \"renews\": false\n        }\n      ]\n    }\n  ],\n  \"crm_opportunity_id\": \"<string>\",\n  \"plan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"discount_coupons\": [\n    \"<string>\"\n  ],\n  \"phases\": [\n    {\n      \"phase_position\": 1,\n      \"bricks\": [\n        {\n          \"brick_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n          \"quantity\": 123,\n          \"is_unlimited\": true,\n          \"discount\": [\n            {\n              \"rate\": \"<string>\",\n              \"amount\": 123,\n              \"renews\": false\n            }\n          ]\n        }\n      ],\n      \"starts_at\": \"2023-12-25\",\n      \"contract_length\": 2,\n      \"plan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"payment_terms\": 499,\n      \"discount_coupons\": [\n        \"<string>\"\n      ]\n    }\n  ],\n  \"custom_order_form_html\": \"<string>\",\n  \"metadata\": \"<unknown>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.salesbricks.com/api/v2/subscriptions/{subscription_id}/upgrade")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-SALESBRICKS-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"starts_at\": \"2023-12-25\",\n  \"bricks\": [\n    {\n      \"brick_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"quantity\": 123,\n      \"is_unlimited\": true,\n      \"discount\": [\n        {\n          \"rate\": \"<string>\",\n          \"amount\": 123,\n          \"renews\": false\n        }\n      ]\n    }\n  ],\n  \"crm_opportunity_id\": \"<string>\",\n  \"plan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"discount_coupons\": [\n    \"<string>\"\n  ],\n  \"phases\": [\n    {\n      \"phase_position\": 1,\n      \"bricks\": [\n        {\n          \"brick_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n          \"quantity\": 123,\n          \"is_unlimited\": true,\n          \"discount\": [\n            {\n              \"rate\": \"<string>\",\n              \"amount\": 123,\n              \"renews\": false\n            }\n          ]\n        }\n      ],\n      \"starts_at\": \"2023-12-25\",\n      \"contract_length\": 2,\n      \"plan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"payment_terms\": 499,\n      \"discount_coupons\": [\n        \"<string>\"\n      ]\n    }\n  ],\n  \"custom_order_form_html\": \"<string>\",\n  \"metadata\": \"<unknown>\"\n}"

response = http.request(request)
puts response.read_body

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

{
  "error": {
    "code": "ERR_BAD_REQUEST",
    "message": "Bad request — the input payload is malformed, missing required fields, or contains invalid data."
  }
}

{
  "error": {
    "code": "ERR_NOT_FOUND",
    "message": "Not found — the resource you are looking for does not exist."
  }
}

Subscription Upgrades

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

The upgrade keeps the subscription’s CRM account. Pass crm_opportunity_id to link it to its own opportunity in your connected CRM; without one, no opportunity is linked or created.

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 --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,
      "is_unlimited": true,
      "discount": [
        {
          "rate": "<string>",
          "amount": 123,
          "renews": false
        }
      ]
    }
  ],
  "crm_opportunity_id": "<string>",
  "plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "discount_coupons": [
    "<string>"
  ],
  "phases": [
    {
      "phase_position": 1,
      "bricks": [
        {
          "brick_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "quantity": 123,
          "is_unlimited": true,
          "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>"
}
'

import requests

url = "https://api.salesbricks.com/api/v2/subscriptions/{subscription_id}/upgrade"

payload = {
    "starts_at": "2023-12-25",
    "bricks": [
        {
            "brick_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "quantity": 123,
            "is_unlimited": True,
            "discount": [
                {
                    "rate": "<string>",
                    "amount": 123,
                    "renews": False
                }
            ]
        }
    ],
    "crm_opportunity_id": "<string>",
    "plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "discount_coupons": ["<string>"],
    "phases": [
        {
            "phase_position": 1,
            "bricks": [
                {
                    "brick_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
                    "quantity": 123,
                    "is_unlimited": True,
                    "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>"
}
headers = {
    "X-SALESBRICKS-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-SALESBRICKS-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    starts_at: '2023-12-25',
    bricks: [
      {
        brick_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
        quantity: 123,
        is_unlimited: true,
        discount: [{rate: '<string>', amount: 123, renews: false}]
      }
    ],
    crm_opportunity_id: '<string>',
    plan_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    discount_coupons: ['<string>'],
    phases: [
      {
        phase_position: 1,
        bricks: [
          {
            brick_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
            quantity: 123,
            is_unlimited: true,
            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>'
  })
};

fetch('https://api.salesbricks.com/api/v2/subscriptions/{subscription_id}/upgrade', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.salesbricks.com/api/v2/subscriptions/{subscription_id}/upgrade",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'starts_at' => '2023-12-25',
    'bricks' => [
        [
                'brick_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
                'quantity' => 123,
                'is_unlimited' => true,
                'discount' => [
                                [
                                                                'rate' => '<string>',
                                                                'amount' => 123,
                                                                'renews' => false
                                ]
                ]
        ]
    ],
    'crm_opportunity_id' => '<string>',
    'plan_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'discount_coupons' => [
        '<string>'
    ],
    'phases' => [
        [
                'phase_position' => 1,
                'bricks' => [
                                [
                                                                'brick_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
                                                                'quantity' => 123,
                                                                'is_unlimited' => true,
                                                                '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>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-SALESBRICKS-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.salesbricks.com/api/v2/subscriptions/{subscription_id}/upgrade"

	payload := strings.NewReader("{\n  \"starts_at\": \"2023-12-25\",\n  \"bricks\": [\n    {\n      \"brick_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"quantity\": 123,\n      \"is_unlimited\": true,\n      \"discount\": [\n        {\n          \"rate\": \"<string>\",\n          \"amount\": 123,\n          \"renews\": false\n        }\n      ]\n    }\n  ],\n  \"crm_opportunity_id\": \"<string>\",\n  \"plan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"discount_coupons\": [\n    \"<string>\"\n  ],\n  \"phases\": [\n    {\n      \"phase_position\": 1,\n      \"bricks\": [\n        {\n          \"brick_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n          \"quantity\": 123,\n          \"is_unlimited\": true,\n          \"discount\": [\n            {\n              \"rate\": \"<string>\",\n              \"amount\": 123,\n              \"renews\": false\n            }\n          ]\n        }\n      ],\n      \"starts_at\": \"2023-12-25\",\n      \"contract_length\": 2,\n      \"plan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"payment_terms\": 499,\n      \"discount_coupons\": [\n        \"<string>\"\n      ]\n    }\n  ],\n  \"custom_order_form_html\": \"<string>\",\n  \"metadata\": \"<unknown>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-SALESBRICKS-KEY", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.salesbricks.com/api/v2/subscriptions/{subscription_id}/upgrade")
  .header("X-SALESBRICKS-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"starts_at\": \"2023-12-25\",\n  \"bricks\": [\n    {\n      \"brick_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"quantity\": 123,\n      \"is_unlimited\": true,\n      \"discount\": [\n        {\n          \"rate\": \"<string>\",\n          \"amount\": 123,\n          \"renews\": false\n        }\n      ]\n    }\n  ],\n  \"crm_opportunity_id\": \"<string>\",\n  \"plan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"discount_coupons\": [\n    \"<string>\"\n  ],\n  \"phases\": [\n    {\n      \"phase_position\": 1,\n      \"bricks\": [\n        {\n          \"brick_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n          \"quantity\": 123,\n          \"is_unlimited\": true,\n          \"discount\": [\n            {\n              \"rate\": \"<string>\",\n              \"amount\": 123,\n              \"renews\": false\n            }\n          ]\n        }\n      ],\n      \"starts_at\": \"2023-12-25\",\n      \"contract_length\": 2,\n      \"plan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"payment_terms\": 499,\n      \"discount_coupons\": [\n        \"<string>\"\n      ]\n    }\n  ],\n  \"custom_order_form_html\": \"<string>\",\n  \"metadata\": \"<unknown>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.salesbricks.com/api/v2/subscriptions/{subscription_id}/upgrade")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-SALESBRICKS-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"starts_at\": \"2023-12-25\",\n  \"bricks\": [\n    {\n      \"brick_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"quantity\": 123,\n      \"is_unlimited\": true,\n      \"discount\": [\n        {\n          \"rate\": \"<string>\",\n          \"amount\": 123,\n          \"renews\": false\n        }\n      ]\n    }\n  ],\n  \"crm_opportunity_id\": \"<string>\",\n  \"plan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"discount_coupons\": [\n    \"<string>\"\n  ],\n  \"phases\": [\n    {\n      \"phase_position\": 1,\n      \"bricks\": [\n        {\n          \"brick_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n          \"quantity\": 123,\n          \"is_unlimited\": true,\n          \"discount\": [\n            {\n              \"rate\": \"<string>\",\n              \"amount\": 123,\n              \"renews\": false\n            }\n          ]\n        }\n      ],\n      \"starts_at\": \"2023-12-25\",\n      \"contract_length\": 2,\n      \"plan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"payment_terms\": 499,\n      \"discount_coupons\": [\n        \"<string>\"\n      ]\n    }\n  ],\n  \"custom_order_form_html\": \"<string>\",\n  \"metadata\": \"<unknown>\"\n}"

response = http.request(request)
puts response.read_body

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

{
  "error": {
    "code": "ERR_BAD_REQUEST",
    "message": "Bad request — the input payload is malformed, missing required fields, or contains invalid data."
  }
}

{
  "error": {
    "code": "ERR_NOT_FOUND",
    "message": "Not found — the resource you are looking for does not exist."
  }
}

Authorizations

X-SALESBRICKS-KEY

string

header

required

API key for authentication

Path Parameters

subscription_id

string

required

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

Body

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

crm_opportunity_id

string

Optional ID of the opportunity (deal in HubSpot) in your connected CRM to link the subscription to. Requires a linked CRM account, and must not be linked to another subscription. Omit for no change; pass an empty string to unlink it.

Maximum string length: 255

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.

downgrade_method

enum<string> | null

Method to apply for the downgrade. CREDIT - apply as credit, REFUND - refund the money back. Omitted is treated as CREDIT.

CREDIT - Credit
REFUND - Refund

Available options:

CREDIT,

REFUND

Response

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

crm_account_id

string | null

required

read-only

ID of the account linked in your connected CRM, if any.

crm_opportunity_id

string | null

required

read-only

ID of the opportunity linked in your connected CRM, if any.

starts_at

string<date>

Start date of the order

ends_at

string<date>

End date of the order

order_type

enum<string>

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

Available options:

TRIAL,

STANDARD,

RENEWAL,

UPGRADE,

RECAST

APIs

REST API Endpoints

Usage

Webhooks

Create a subscription upgrade

Authorizations

Path Parameters

Body

Response