> ## 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. # Update a subscription upgrade > Updates a subscription upgrade order. This endpoint allows you to modify bricks, AP contacts, and other properties for an existing upgrade order. **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. ## OpenAPI ````yaml https://api.salesbricks.com/api/v2/openapi.yaml patch /subscriptions/{subscription_id}/upgrade/{order_id} 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/{order_id}: patch: tags: - Subscription Upgrades summary: Update a subscription upgrade description: >- Updates a subscription upgrade order. This endpoint allows you to modify bricks, AP contacts, and other properties for an existing upgrade order. **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. operationId: updateSubscriptionUpgrade parameters: - in: path name: order_id schema: type: string pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ required: true - in: path name: subscription_id schema: type: string pattern: ^([a-zA-Z\d\-]+)$ required: true requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchedSubscriptionUpgradePatch' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PatchedSubscriptionUpgradePatch' multipart/form-data: schema: $ref: '#/components/schemas/PatchedSubscriptionUpgradePatch' responses: '200': content: application/json: schema: type: object properties: subscription_id: type: string 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: PatchedSubscriptionUpgradePatch: type: object description: >- Subscription input serializer for upgrade PATCH operations. Excludes immutable fields: contract_length, billing_frequency, currency. These fields are inherited from the base order and cannot be changed during an upgrade. starts_at IS allowed to be changed (e.g., for Kognitos integration). properties: starts_at: type: string format: date description: >- The start date of the subscription. Required unless `phases` is provided, in which case phase 0's start date is used. plan_id: type: string format: uuid description: >- The ID of the plan. Required unless every phase declares its own `plan_id` — it is the plan for any phase that does not. bricks: type: array items: $ref: '#/components/schemas/LineItemInput' description: >- The bricks included in the subscription. Required unless `phases` is provided, in which case every brick comes from the phases. discount_coupons: type: array items: type: string description: >- Discount coupon codes to apply to the subscription. Currently only supports one discount coupon - only the first one in the list will be applied. phases: type: array items: $ref: '#/components/schemas/OrderPhaseInput' nullable: true description: >- Optional list of phases for multi-phase orders. When provided, ALL phases come from this array (first element = phase 0, second = phase 1, etc.) and `starts_at`, `contract_length`, `billing_frequency` and `bricks` become optional — omit them and they are derived from the phases. `plan_id` is still required, and every brick in every phase must belong to it. When absent, the order-level fields define a single phase. point_of_contact_id: type: string format: uuid description: The ID of the point of contact (Person) object signatory_user_id: type: string format: uuid description: The ID of the signatory user (Person) object auto_renews: type: boolean description: Whether the subscription auto-renews. Defaults to true. accounts_payable_emails: type: array items: type: string format: email description: List of email addresses for accounts payable contacts customer_id: type: string format: uuid description: The ID of the customer payment_terms: type: integer maximum: 999 minimum: 0 description: >- The number of days from an invoice being generated that the buyer is expected to pay in renewal_contract_period: type: integer minimum: 1 nullable: true description: >- The contract period for renewals in months. If null, inherits from initial contract period. renewal_uplifted_rate: type: string format: decimal pattern: ^-?\d{0,3}(?:\.\d{0,2})?$ nullable: true description: >- The percentage rate to uplift renewal pricing. If null, no uplift is applied. transaction_method: enum: - ORDER_FORM - STRIPE type: string x-spec-enum-id: c68094511bb51423 description: |- The medium by which the order is agreed. * `ORDER_FORM` - Order form * `STRIPE` - Stripe 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. custom_order_form_html: type: string description: >- The custom order form html to use with `...` formatting accepted_payment_methods_config: allOf: - $ref: '#/components/schemas/AcceptedPaymentMethodsConfig' nullable: true description: >- Configuration for accepted payment methods during checkout and paywall first_charge_date: enum: - CONTRACT_START_DATE - CHECKOUT_DATE type: string x-spec-enum-id: 453208d46b2cb502 description: >- When the first invoice should be charged. If not provided, defaults to seller's first_charge_date setting, or CHECKOUT_DATE if seller has no setting. * `CONTRACT_START_DATE` - Contract Start Date * `CHECKOUT_DATE` - Checkout Date legal_entity_id: type: string format: uuid nullable: true description: >- Optional ID of the legal entity that issues this subscription. Falls back to the seller's default legal entity when omitted. 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. Discounts are replaced, not merged: what is sent here becomes the line item's complete set of discounts. Omitting this field for a brick that currently has a discount drops that discount. Read the current values from the subscription's line items, which return `discount` in this same shape, and send them back for every brick whose discount should carry over. required: - brick_id OrderPhaseInput: type: object description: >- Input serializer for a single order phase in multi-phase operations. ``phase_position`` is required on every phase. For creation, recast and estimate the array is the complete phase set, so positions must be the full 0-based sequence (position N at index N). For upgrades only the phases being changed are sent, so positions are a subset of the base order's phase positions. ``starts_at`` is optional — phase 0 defaults to the order-level starts_at, and subsequent phases are derived from the previous phase's end date. ``contract_length`` replaces the old ``ends_at`` field. Required for create/estimate/recast; not needed for upgrades (end date inherited from the base order). The phase *output* reports ``ends_at`` rather than ``contract_length``, so a read-modify-write of a phase has to convert: ``contract_length`` is the number of whole months from ``starts_at`` to the day after ``ends_at``. Phases are contiguous and whole-month, so the conversion is exact. ``billing_frequency`` follows the same rule: required for create/estimate/recast, where phases own the billing frequency outright, and inherited from the base order's phase on upgrades. ``plan_id`` is optional and lets a phase sell a different plan from the order's, matching what the order builder already supports (SAL-6327). Omitted, the phase uses the order-level ``plan_id``. properties: phase_position: type: integer minimum: 0 description: Phase position (0-based). Must be unique across phases. starts_at: type: string format: date nullable: true description: >- Start date of this phase. Optional — phase 0 defaults to order-level starts_at; subsequent phases are derived from the previous phase's end date + 1 day. contract_length: type: integer minimum: 1 nullable: true description: >- Duration of this phase in months. Required for create, estimate, and recast. Not required for upgrades (end date inherited from the base order). billing_frequency: enum: - MONTHLY - QUARTERLY - SEMI_ANNUALLY - ANNUALLY - ALL_UPFRONT - CUSTOM type: string x-spec-enum-id: 5f29351b16a5547f description: >- Billing frequency for this phase. Required for create, estimate and recast — when phases are provided they own the billing frequency outright, so the order-level billing_frequency is not consulted. Not required for upgrades (inherited from the base order's phase). The legacy name `billing_schedule` is still accepted. * `MONTHLY` - Monthly * `QUARTERLY` - Quarterly * `SEMI_ANNUALLY` - Semi-annually * `ANNUALLY` - Annually * `ALL_UPFRONT` - All upfront * `CUSTOM` - Custom plan_id: type: string format: uuid nullable: true description: >- Optional plan for this phase. Each phase may sell a different plan; the phase's bricks are then validated and priced against it. Defaults to the order-level `plan_id`. payment_terms: type: integer maximum: 999 minimum: 0 description: >- Payment terms in days for this phase. Named to match the order-level `payment_terms` input and the phase output — the model field it lands on is `payment_due_upon_receipt`, which is still accepted as a legacy name. Omitted, the phase inherits the order-level value. bricks: type: array items: $ref: '#/components/schemas/LineItemInput' description: The bricks included in this phase. discount_coupons: type: array items: type: string description: >- Discount coupon codes to apply to this phase. Currently only supports one discount coupon - only the first one in the list will be applied. required: - bricks - phase_position AcceptedPaymentMethodsConfig: type: object description: |- Serializer for accepted payment methods configuration. Modelled after spearhead/seller/models.py:AcceptedPaymentMethodsConfig. properties: paywall_credit_card: type: boolean default: true description: >- If card is allowed at paywall. Dependent on seller's Stripe capabilities. paywall_check: type: boolean default: true description: If pay by check is allowed at paywall. paywall_ach: type: boolean default: true description: >- If ACH is allowed at paywall. Dependent on seller's Stripe capabilities. paywall_wire: type: boolean default: true description: If pay by wire is allowed at paywall. checkout_credit_card: type: boolean default: true description: >- If card is allowed during checkout. Dependent on seller's Stripe capabilities. checkout_ach: type: boolean default: true description: >- If ACH is allowed during checkout. Dependent on Seller's Stripe capabilities. checkout_order_form: type: boolean default: true description: If Order Form is allowed during checkout. minimum_order_form_tcv: type: integer default: 0 description: >- The minimum total value which an order must have in order to qualify for an order form checkout. paywall_force_autopay: type: boolean default: false description: If true a buyer cannot opt out of autopay when paying invoices 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 - [Update a subscription](/api-reference/subscriptions/update-a-subscription.md) - [Update a subscription recast](/api-reference/subscription-recasts/update-a-subscription-recast.md) - [Update details for a closed subscription](/api-reference/subscription-state/update-details-for-a-closed-subscription.md)