> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.solvimon.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.solvimon.com/_mcp/server. # Upgrade quotes An upgrade quote changes a running subscription to a new plan, new terms or new pricing. The change has an owner, approvals and customer acceptance before Solvimon bills anything. When the upgrade starts part-way through a billing period, Solvimon automatically credits the unused part of the old subscription. --- ## Why this matters A sales-led upgrade is a commercial change that needs the same controls as a new deal. The customer accepts a quote, and an approver approves terms that fall outside policy. An edit of the live subscription skips both controls. An upgrade quote does not change the running subscription until the customer accepts. Then, on the agreed date, a new subscription replaces it, and one invoice settles the overlap. > **Note** > > Upgrade quotes are one of three ways to change a plan. Use [plan changes in a pricing plan group](/platform-guides/customers-and-billing/subscriptions/plan-changes) to move between plans of the same family in one call. Use [self-serve plan changes](/platform-guides/customers-and-billing/self-serve-plan-changes) to let customers change their own pricing in the portal. Both add a schedule to the same subscription. An upgrade quote creates a new subscription instead. ## How it works ```mermaid sequenceDiagram participant R as Sales rep participant S as Solvimon participant C as Customer R->>S: POST /v1/quotes/upgrade S-->>R: Quote, quote version (DRAFT), quote subscription R->>S: Edit the quote subscription, then finalize S-->>R: FINAL, or WAITING_APPROVAL if a policy is triggered C->>S: Accepts or signs the quote S->>S: Creates the new subscription S->>S: On the start date, cancels the original subscription and credits its unused period ``` The request copies the subscription you upgrade into a new quote subscription with `type` `QUOTE` and `status` `DRAFT`. The copy keeps the original's billing terms and custom fields, links back through `upgraded_from_pricing_plan_subscription_id`, and gets one schedule. Solvimon copies that schedule from the schedule that runs on your `start_at` date. The copy has the new start date and, if you pass one, the new pricing plan version. The original subscription does not change until the customer accepts the quote. After the customer accepts and the new subscription exists: | Subscription | What happens | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | New subscription | A regular billing subscription that is active. It starts on the upgrade's `start_at`. | | Original subscription | Gets an inactive period of type `UPGRADE` from the upgrade start and an `upgraded_to_pricing_plan_subscription_id` link. Solvimon cancels it on the upgrade start date, and its initial term no longer applies. | ## Create an upgrade quote ### Via API Call [Create an upgrade quote](https://docs.solvimon.com/api-docs/configuration-api/quotes/post-quotes-upgrade) with the subscription you want to change and the date the change takes effect. **`Create an upgrade quote`** ```bash Create an upgrade quote curl -X POST https://test.api.solvimon.com/v1/quotes/upgrade \ -H "X-API-KEY: " \ -H "Content-Type: application/json" \ -d '{ "quote": { "owner_user_id": "user_EwDegI0tt0diFEBEed12", "name": "Upgrade to Pro", "expires_at": "2026-10-31T00:00:00Z" }, "pricing_plan_subscription": { "id": "ppsu_gwDeeN0tBe7h5NAw9d1q", "reference": "acme-upgrade-pro-2026-10" }, "pricing_plan_schedule": { "pricing_plan_version_id": "ppve_gwDeep0tDRcSvkAfeN1Z", "start_at": "2026-10-20T00:00:00Z" } }' ``` The response returns `201` with the three resources that the call created: **`Response (shortened)`** ```json Response (shortened) { "quote": { "object_type": "QUOTE", "id": "quot_awDwHo0tYd4VZdBhe010", "customer_id": "cust_awDeAl0tsKup9BBJNU1m", "owner_user_id": "user_EwDegI0tt0diFEBEed12", "name": "Upgrade to Pro" }, "quote_version": { "object_type": "QUOTE_VERSION", "id": "quve_zwDsvH0vxuCEuSCv6j18", "quote_id": "quot_awDwHo0tYd4VZdBhe010", "version": 1, "status": "DRAFT", "expires_at": "2026-10-31T00:00:00Z" }, "pricing_plan_subscription": { "object_type": "PRICING_PLAN_SUBSCRIPTION", "id": "ppsu_HwDeeN0ueZElY7AltP1z", "reference": "acme-upgrade-pro-2026-10", "type": "QUOTE", "status": "DRAFT", "upgraded_from_pricing_plan_subscription_id": "ppsu_gwDeeN0tBe7h5NAw9d1q" } } ``` | Field | Required | Description | | ------------------------------------------------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `quote.owner_user_id` | Yes | The user who owns the quote, usually the sales rep. | | `quote.name` | No | Name of the quote. | | `quote.expires_at` | No | When the quote version expires. Cannot be in the past. | | `quote.custom_fields` | No | Custom field values for the quote. | | `pricing_plan_subscription.id` | Yes | The running subscription to upgrade. | | `pricing_plan_subscription.reference` | Yes | Reference for the quote subscription. Must be unique for the customer among quote subscriptions. | | `pricing_plan_subscription.custom_fields` | No | Replace the custom field values copied from the original. Solvimon never copies custom fields that are marked unique. | | `pricing_plan_subscription.initial_term`, `renewal_term`, `auto_renewal` | No | Replace the values copied from the original. | | `pricing_plan_schedule.start_at` | Yes | The date the upgrade takes effect. | | `pricing_plan_schedule.pricing_plan_version_id` | No | The pricing plan version to move to. Leave it out to keep the current version and change only terms or pricing. | | `pricing_plan_schedule.end_at` | No | End of the new schedule. Leave it out for an open-ended schedule. If it falls before the end of the copied initial term, Solvimon drops the initial term so that `end_at` applies. | After the call, adjust the schedule of the quote subscription (discounts, commitments, enabled pricing) as you do for any other quote. Then finalize the quote version. The API creates the quote subscription as `DRAFT`. Through the API, set its `status` to `ACTIVE` before you finalize. See [Share, accept and convert a quote](/platform-guides/customers-and-billing/quoting/share-accept-and-convert-a-quote#finalize-a-quote-version). Desk does this for you. When you finalize, Solvimon evaluates your [approval policies](/platform-guides/customers-and-billing/quoting/approval-policy). You can [check them first](/platform-guides/customers-and-billing/quoting/approval-policy#check-approvals-before-finalizing). ### Via Desk 1. On the subscription, open the context menu and select **Create upgrade quote**. 2. On **New upgrade quote**, set the **Subscription start date**. The date is in the customer's timezone. It defaults to the end of the subscription's last schedule. 3. Optionally, set an **End date**. 4. Select **Create upgrade quote**. Desk opens the new quote subscription. 5. Select the plan and adjust the pricing. The quote view links to the subscription that it upgrades from. After acceptance, it also links to the new subscription. ## Mid-period credit When the upgrade starts part-way through a period that Solvimon already invoiced for the original subscription, Solvimon credits the unused part. This always occurs. There is no setting for it. On the upgrade start date, Solvimon shortens the original subscription's schedule to end on that date. Solvimon then adds a negative line for each fee that meets both conditions: * A `FINAL` invoice billed the fee in advance. * The billed period continues after the upgrade start. **`Credit formula`** ```text Credit formula credit = fee billed for the period x days from the upgrade start to the end of the billed period / days in one billing period, counted from the upgrade start ``` Solvimon counts days on calendar dates in the customer's timezone. For a monthly fee, the denominator is the number of days from the upgrade start to the same day one month later. Solvimon puts the credit on a new invoice for the original subscription. It then combines that invoice with the first invoice of the new subscription. This occurs even if invoice combination is off for both subscriptions. The customer receives one invoice for the switch. | Charge on the original subscription | On upgrade | | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | Recurring or per-seat fee billed in advance, on a `FINAL` invoice | Solvimon credits the unused days. | | Fee billed in advance on an invoice that is still `DRAFT` or `OPEN` | No credit. Solvimon voids the invoice and creates it again for the shorter period. | | One-off fee billed in advance | No credit. | | Fee that grants wallet credits | No credit. The granted credits stay valid. | ### Example A customer pays a Platform fee of \$3,000 per month in advance, with anniversary billing on the 5th. The invoice for 5 October – 5 November 2026 is `FINAL`. The customer accepts an upgrade quote to a \$5,000 plan that starts on 20 October. | Line | Calculation | Amount | | ------------------------------------------ | -------------------------------------------------------------- | ----------- | | Credit for the original Platform fee | \$3,000 x 16 days (20 Oct – 5 Nov) / 31 days (20 Oct – 20 Nov) | −\$1,548.39 | | New Platform fee, 20 October – 20 November | Full period | \$5,000.00 | | Combined invoice | | \$3,451.61 | With calendar billing, Solvimon prorates the first invoice of the new subscription. See [Billing cycles & Pro-ration](/platform-guides/customers-and-billing/subscriptions/billing-cycles-proration). ## Validation errors | Status | Field | Cause | | ------ | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `400` | `quote`, `pricing_plan_subscription`, `pricing_plan_subscription.id`, `pricing_plan_schedule`, `pricing_plan_schedule.start_at` | A mandatory field is missing. | | `400` | `pricing_plan_subscription.reference` | Another quote subscription of this customer already uses the reference. | | `400` | `pricing_plan_schedule` | No schedule of the original subscription covers `start_at`, for example a date after its last schedule ends. | | `400` | `pricing_plan_schedule.start_at` | `start_at` is on or before the start of the schedule it upgrades from. | | `404` | | The owner user, subscription or customer does not exist. | ## Edge cases * An upgrade can start before the original's initial term ends. Solvimon clears the initial term when it cancels the original subscription for the upgrade. * Discounts, commitments and overrides copied from the running schedule count towards [approval policies](/platform-guides/customers-and-billing/quoting/approval-policy) on the upgrade quote, even if the rep did not add them. ---