> ## Documentation Index > Fetch the complete documentation index at: https://docs.salesbricks.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml https://api.salesbricks.com/api/v2/openapi.yaml post /subscriptions/{subscription_id}/upgrade openapi: 3.0.3 info: title: Salesbricks REST API version: 2.0.0 description: API reference for external integrations servers: - url: https://api.salesbricks.com/api/v2 description: Production - url: https://api.staging.salesbricks.com/api/v2 description: Staging security: - ApiKeyAuth: [] tags: - name: Subscriptions description: >- Operations related to subscription management, including creation, updates, and retrieving subscription details. Subscriptions can be upgraded to add / remove add-ons by using the POST /subscriptions/{subscription_id}/upgrade endpoint and can be recasted for replacing the current agreement using the POST /subscriptions/{subscription_id}/recast endpoint - name: Customers description: >- Operations related to customer management, including creation, updates, and managing customer person objects. - name: Invoices description: Operations related to subscription's invoicing details. - name: Plans description: >- Operations related to listing and getting plan details including bricks in the plan. - name: Payment Methods description: Operations related to subscription's payment method. paths: /subscriptions/{subscription_id}/upgrade: post: tags: - Subscription Upgrades summary: Create a subscription upgrade description: >- 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. operationId: createSubscriptionUpgrade parameters: - in: path name: subscription_id schema: type: string pattern: ^([a-zA-Z\d\-]+)$ required: true requestBody: content: application/json: schema: $ref: '#/components/schemas/SubscriptionInputUpgrade' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/SubscriptionInputUpgrade' multipart/form-data: schema: $ref: '#/components/schemas/SubscriptionInputUpgrade' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SubscriptionOrder' description: '' '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: BadRequestResponse: value: error: code: ERR_BAD_REQUEST message: >- Bad request — the input payload is malformed, missing required fields, or contains invalid data. summary: Bad Request Response description: '' '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: NotFoundResponse: value: error: code: ERR_NOT_FOUND message: >- Not found — the resource you are looking for does not exist. summary: Not Found Response description: '' components: schemas: SubscriptionInputUpgrade: type: object description: >- Subscription upgrade input serializer for upgrading a subscription order. properties: plan_id: type: string format: uuid description: >- 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. starts_at: type: string format: date description: The start date of the subscription upgrade bricks: type: array items: $ref: '#/components/schemas/LineItemInput' description: >- 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.) discount_coupons: type: array items: type: string description: >- 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: type: string description: >- The custom order form html to use with `...` formatting metadata: nullable: true description: >- Optional metadata to add to the subscription. Sending an empty map will delete all keys. Keys prefixed with _ are private and will be ignored. required: - bricks - starts_at SubscriptionOrder: type: object description: Serializer for individual subscription order properties: order_id: type: string format: uuid description: Unique identifier for the order starts_at: type: string format: date ends_at: type: string format: date order_type: enum: - TRIAL - STANDARD - RENEWAL - UPGRADE - RECAST type: string description: |- * `TRIAL` - Trial * `STANDARD` - New Business * `RENEWAL` - Renewal * `UPGRADE` - Upgrade * `RECAST` - Recast x-spec-enum-id: f190c93bb8b6757b contract_value: type: string readOnly: true description: Total contract value with currency pdf_url: type: string readOnly: true description: URL to download signed order form PDF required: - contract_value - order_id - pdf_url ErrorResponse: type: object description: >- Standardizes API error responses with a consistent structure containing error code and message. properties: error: $ref: '#/components/schemas/Error' required: - error LineItemInput: type: object description: Line item input serializer for creating a new estimate properties: brick_id: type: string format: uuid quantity: type: integer discount: type: array items: $ref: '#/components/schemas/LineItemDiscount' nullable: true description: >- A list of discounts to apply to the line item — at most one renewing rate, one one-time rate, and one fixed amount. required: - brick_id Error: type: object description: >- Represents individual error details with a standardized code and descriptive message. properties: code: enum: - ERR_NOT_FOUND - ERR_BAD_REQUEST - ERR_SERVER_ERROR type: string x-spec-enum-id: dc5a5d6feae1b697 description: >- Error code indicating the type of error: NOT_FOUND for missing resources, BAD_REQUEST for invalid input, SERVER_ERROR for internal server issues * `ERR_NOT_FOUND` - ERR_NOT_FOUND * `ERR_BAD_REQUEST` - ERR_BAD_REQUEST * `ERR_SERVER_ERROR` - ERR_SERVER_ERROR message: type: string error_id: type: string format: uuid description: >- Correlation handle for SERVER_ERROR responses — quote this when contacting support; it joins to the structured server log line for the failure. Not present on 4xx responses. required: - code - message LineItemDiscount: type: object description: Discount serializer for a subscription estimate line item properties: rate: type: string format: decimal pattern: ^-?\d{0,14}(?:\.\d{0,6})?$ description: >- The discount rate as a percentage with up to six decimal places (e.g. 10 = 10%, 62.6758 = 62.6758%). Mutually exclusive with `amount`. amount: type: integer description: >- A fixed discount amount in cents (e.g. 1000 = $10.00). One-time only — `renews` must be false when `amount` is set. Mutually exclusive with `rate`. The amount is applied as-is and is not clamped to the line item total, so it should not exceed the brick's price. renews: type: boolean default: false description: >- If the discount is carried over at renewal. Must be false when `amount` is set, as fixed discounts are one-time only. securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-SALESBRICKS-KEY description: API key for authentication ```` ## Related topics - [Order Types](/documentation/order-types.md) - [Building an Order](/quickstart-guide/building-an-order.md) - [subscription.inactive](/api-reference/webhooks/subscription/inactive.md)