> ## 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. # Order Phases > Split one contract into sequential phases, each with its own plan, pricing, billing frequency, and payment terms ## Overview A **phase** is a slice of a contract with its own dates and its own commercial terms. Phases run back to back, so a customer can move from one plan, price, or billing cadence to the next without a second order, a second signature, or a second checkout. Use phases when a deal has distinct stages, for example: * A free or discounted trial period that converts to a paid subscription. * An implementation or services period followed by a recurring subscription. * A ramp-up on a smaller plan before moving to the full plan. * A multi-year contract where each year is billed on a different cadence or at a different price. Every order has at least one phase. A standard order is simply a one-phase order, and it looks and behaves exactly as it always has. Phases only appear in Salesbricks once an order has two or more. If you don't see a **Phases** section in the order builder, multi-phase orders aren't enabled for your account yet. Reach out to us in your dedicated Slack channel. ### Phases compared to ramping and upgrades | Use | When to reach for it | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | [Ramping](/orders/ramping-structures) | The plan and terms stay the same, but line item quantities or rates step up over the contract. | | **Phases** | The plan, bricks, billing frequency, payment terms, or discounts change at a set date, and you want everything captured in one order form. | | [Upgrade](/orders/order-types#upgrade) | The customer's needs change after the order has closed. An upgrade is a separate order layered on top of the current one. | ## How phases work Each phase owns its own schedule and selection. A few settings stay at the order level and are set on Phase 1. | Set per phase | Set once per order (on Phase 1) | | ---------------------------------------------------------------------------------- | ---------------------------------------- | | Contract period and end date | Start date | | Billing frequency | Currency | | Payment terms | Pricing display | | Product, plan, bricks, and quantities | First charge or invoice date | | Usage pools | Terms and conditions, commercial terms | | Discounts: sales, one-time, duration, coupons, and contract discounts | Renewal type and renewal contract period | | [Ramping](/orders/ramping-structures) and [custom billing](/orders/custom-billing) | | Rules that always hold: * **Phases are contiguous.** Each phase starts the day after the previous phase ends. There are no gaps and no overlaps, and you can't reorder phases. * **The order ends when the last phase ends.** The order's contract period is the sum of its phases. * **Each phase is priced on its own length.** A 6 month phase is priced at monthly rates even when it sits inside a 24 month contract, because the phase, not the order, decides whether annual pricing applies. * **Phase names are optional.** Unnamed phases display as "Phase 1", "Phase 2", and so on. Names can be up to 50 characters. ## Building a multi-phase order Start a new order as usual. Under **Phases**, the first phase is the order you already know how to build: set its contract period, billing frequency, payment terms, product, plan, and bricks. See [Building an Order](/quickstart-guide/building-an-order) for each field. The **Add phase** button only appears once the last phase has an end date, so set the contract period first. Click **Add phase**. Salesbricks appends a blank phase that starts the day after the previous phase ends. It defaults to a 12 month contract period billed annually. Nothing else carries over, so the new phase starts with no product, plan, or bricks selected. Expand the phase and fill it in the same way as Phase 1: * **Contract period:** pick a number of months, or choose **Custom end date** to end the phase on a specific day. The start date is read-only and shows **Continues from previous phase**. * **Billing frequency:** the options offered depend on the phase's length. A 3 month phase can't be billed annually. * **Payment terms:** each phase has its own. * **Product, plan, and bricks:** each phase can sell a different plan, or the same plan with different bricks and quantities. * **Discounts:** click **Add discount** to apply sales, one-time, duration, or coupon discounts to this phase only. Changing an earlier phase's end date shifts every later phase forward by the same amount, so each phase keeps its length. Open the menu on any phase's header: * **Rename phase** gives the phase a label your customer will see on the order form, for example "Pilot" or "Year 2". * **Duplicate phase** appends a copy at the end of the order with the same product, plan, bricks, discounts, and custom billing schedule, on a fresh 12 month span. Duration discounts and ramping windows aren't copied, since they're tied to the original phase's dates. * **Remove phase** deletes the phase. Phase 1 can't be removed. The **Phases** heading shows a running summary, for example "2 phases ยท 18 months total", and a callout confirms the phases are contiguous with no gaps or overlaps. Each phase header shows its date range, length, and phase total. Save the order and share it as you normally would. On a trial order, Phase 1 carries a **Trial** badge. Set Phase 1 to the trial plan at no charge and Phase 2 to the paid plan, and the customer signs once for both. ## What your customer sees On a multi-phase order, the order form groups everything by phase. Under "Products and services", a line explains that each phase is self-contained, and then each phase gets: * A header with the phase number and name, and the phase's date range. * Its own **Contract period**, **Billing frequency**, and **Payment terms**. * Its own line items, usage commitments, and one-time charges. * A **Phase N summary** box with the subtotal, any duration or contract discounts, and the **Phase total**. The billing schedule on the order form is grouped by phase as well. During checkout, the pricing breakdown shows one card per phase with that phase's total and billing cadence. When Phase 1 is free, the order summary adds a callout such as "Pricing changes on Jul 15, 2026" so the customer knows when the paid phase begins. ## Billing and invoicing Each phase generates its own invoices from its own billing frequency and payment terms: * **Billing periods never cross a phase boundary.** The first invoice of a phase falls on that phase's start date, whatever the previous phase's cadence was. * **Payment terms are per invoice.** Two invoices on the same order can carry different Net terms if their phases differ. * **A custom end date creates a partial period.** If a phase ends partway through a billing period, the final period of that phase is billed as a partial period according to your team's partial period setting. After the order closes, phases appear across billing: | Surface | What you see | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Order details** | A **Phases** card with one entry per phase, showing its plan, date range, billing frequency, payment terms, and a status of Upcoming, Active, Completed, Terminating, or Terminated. Order-level billing frequency and payment terms read **Varies by phase**. | | **Billing table** | The phase name under each invoice number. | | **Billing statement** | A **Phase** row in the invoice summary. | | **Billing schedule editor** | One tab per phase. The header reports **All phases balanced** or how many phases are unbalanced when custom billing amounts don't match the phase total. | ## Discounts and coupons Every discount belongs to a phase: * **Sales, one-time, and contract discounts** apply to the phase they're added to. If a phase's discount expires or its minimum spend isn't met, that phase loses its discounts while the other phases keep theirs. * **[Duration discounts](/orders/duration-discounts)** are measured from the phase's start date. * **Coupons** are redeemed per phase. Applying a coupon to two phases counts as two uses against the coupon's usage limit. * **Apply on renewal** is only offered on the last phase, since the renewal is based on the last phase. Duration discount date ranges are validated against the whole contract, not the phase they belong to. Two duration discounts on different phases can't cover the same dates. ## Upgrades, renewals, and recasts ### Upgrades An [upgrade](/orders/order-types#upgrade) inherits every phase from the current contract, so the customer's timeline stays intact. In the upgrade builder: * **Add phase** and **Remove phase** aren't available. * Each phase's end date and billing frequency are read-only. You can move a phase's start date, but only within that phase's original date range. * Bricks and quantities can be added per phase. Quantities can't be reduced. * Contract-wide and one-time discounts from the base order are cleared on each phase of the upgrade, so re-add any that should carry over. ### Renewals A renewal is built from the **last phase only**. It inherits the last phase's plan, bricks, ramping, billing frequency, payment terms, and length. A contract with a 12 month ramp phase followed by a 24 month steady phase renews as a 24 month order at the steady phase's terms. You can add phases to a renewal while building it, so a renewal can itself become a multi-phase order. ### Recasts A [recast](/orders/order-types#recast) also starts from the last phase's bricks. Rebuild the phases you need before sharing the recast. ## Reports, subscription management, and CRM * **Orders list:** multi-phase orders carry an "N phases" badge, and each row expands to show one line per phase with its dates and contract value. * **MRR report and CSV export:** a **Phase** column appears after **Brick**. A brick sold in more than one phase reports under its earliest phase. * **Subscription page:** the entitlements card shows which phase is current. Usage bricks get one tab per phase they were sold in, and usage can only be recorded for dates inside a phase that includes that brick. * **Milestones:** grouped by phase on the customer page. * **CRM field mapping:** three phase fields become available for [mapping](/integrations/crm-field-mapping) when multi-phase orders are enabled. At the order level, `phase_count` and `phase_summary` (one line per phase with its name, dates, and total). At the line item level, `phase_index`. HubSpot receives one line item per brick per phase, with the phase name and dates appended to the line item description. ## Limitations * **Pausing isn't supported.** A multi-phase subscription can't be paused. The Pause action is disabled with the message "Pausing multi-phase subscriptions is not yet supported. Please contact support for assistance." * **Phases can't be reordered.** Remove and re-add a phase to change the sequence. * **Duration discounts are validated across the whole contract.** See [Discounts and coupons](#discounts-and-coupons). ## API Subscriptions created through the REST API can include a `phases` array on the following endpoints: ### Subscriptions * [Create a subscription](/api-reference/subscriptions/create-a-subscription) * [Retrieve a susbcription](/api-reference/subscriptions/retrieve-a-subscription) * [Update a subscription](/api-reference/subscriptions/update-a-subscription) * [Estimate a subscription](/api-reference/subscriptions/estimate-a-subscription) ### Subscription State * [List all subscription bricks](/api-reference/subscription-state/list-all-subscription-bricks) * [Retrieve current subscription state](/api-reference/subscription-state/retrieve-current-subscription-state) * [Update details for a closed subscription](/api-reference/subscription-state/update-details-for-a-closed-subscription) ### Subscription Recasts * [Create a subscription recast](/api-reference/subscription-recasts/create-a-subscription-recast) * [Update a subscription recast](/api-reference/subscription-recasts/update-a-subscription-recast) * [Estimate a subscription recast](/api-reference/subscription-recasts/estimate-a-subscription-recast) ### Subscription Upgrades * [Create a subscription upgrade](/api-reference/subscription-upgrades/create-a-subscription-upgrade) * [Update a subscription upgrade](/api-reference/subscription-upgrades/update-a-subscription-upgrade) * [Estimate a subscription upgrade](/api-reference/subscription-upgrades/estimate-a-subscription-upgrade) When `phases` is present, the phases own the timeline, billing frequency, and bricks. The order-level `starts_at`, `contract_length`, `billing_frequency`, and `bricks` become optional and are derived from the phases when omitted. ### Phase fields | Field | Required | Notes | | ------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `phase_position` | Yes | 0-based. Positions must be unique and contiguous, and each must equal its index in the array. | | `bricks` | Yes | The bricks in this phase. Every phase needs at least one. | | `contract_length` | Create, estimate, recast | Whole months. Not accepted on upgrades, which inherit each phase's end date. | | `billing_frequency` | Create, estimate, recast | `MONTHLY`, `QUARTERLY`, `SEMI_ANNUALLY`, `ANNUALLY`, or `ALL_UPFRONT`. Inherited on upgrades. | | `starts_at` | No | Phase 0 defaults to the order-level `starts_at`. Later phases derive from the previous phase's end date plus one day. Sending a date that leaves a gap or overlap returns `400`. | | `plan_id` | No | Lets a phase sell a different plan. Defaults to the order-level `plan_id`. A payload with no plan at either level returns `400`. | | `payment_terms` | No | Days until due. Defaults to the order-level value. | | `discount_coupons` | No | Coupon codes for this phase. Only the first is applied. On a multi-phase payload, coupons must be set per phase rather than at the order level. | Upgrades send only the phases being changed. Each `phase_position` must match a phase on the current contract, and omitted positions are inherited unchanged. Sending `phases` when multi-phase orders aren't enabled for your account returns `400` with the message "Multi-phase orders are not enabled." ### Example: estimate a two-phase subscription A 6 month pilot on a Starter plan billed monthly, followed by 12 months on a Growth plan billed annually. ```bash cURL theme={null} curl -X POST https://api.salesbricks.com/api/v2/subscriptions/estimate \ -H "X-SALESBRICKS-KEY: " \ -H "Content-Type: application/json" \ -d '{ "starts_at": "2026-10-01", "phases": [ { "phase_position": 0, "contract_length": 6, "billing_frequency": "MONTHLY", "plan_id": "p9q0r1s2-0d44-4b50-8888-8dd25736052a", "bricks": [ { "brick_id": "b3c4d5e6-0d44-4b50-8888-8dd25736052a", "quantity": 10 } ] }, { "phase_position": 1, "contract_length": 12, "billing_frequency": "ANNUALLY", "plan_id": "g7h8i9j0-0d44-4b50-8888-8dd25736052a", "bricks": [ { "brick_id": "c4d5e6f7-0d44-4b50-8888-8dd25736052a", "quantity": 25 } ] } ] }' ``` ```json JSON (truncated) theme={null} { "starts_at": "2026-10-01", "ends_at": "2028-03-31", "grand_total": 4200000, "phases": [ { "phase_position": 0, "starts_at": "2026-10-01", "ends_at": "2027-03-31", "billing_frequency": "MONTHLY", "payment_terms": 30, "sub_total": 600000, "grand_total": 600000, "line_items": ["..."], "billing_schedule": ["..."] }, { "phase_position": 1, "starts_at": "2027-04-01", "ends_at": "2028-03-31", "billing_frequency": "ANNUALLY", "payment_terms": 30, "sub_total": 3600000, "grand_total": 3600000, "line_items": ["..."], "billing_schedule": ["..."] } ] } ``` ### Reading phases back [Retrieve a subscription](/api-reference/subscriptions/retrieve-a-subscription) and [Retrieve current subscription state](/api-reference/subscription-state/retrieve-current-subscription-state) include a `phases` array only when the order has more than one phase. Each entry carries `phase_position`, `starts_at`, `ends_at`, `billing_frequency`, `payment_terms`, `sub_total`, `grand_total`, `line_items`, and that phase's `billing_schedule`. When `phases` is absent, the order has a single phase and the order-level fields describe it. Phase input takes `contract_length`, while output reports `ends_at`. To edit a phase you read back, convert the end date to whole months from the phase's start. In the GraphQL API, every order exposes a `phases` list and each order brick carries a `phasePosition`. [Briq](/agents/briq) and the [Salesbricks MCP server](/integrations/mcp) also accept phases when drafting orders. ## Related topics - [Estimate a subscription](/api-reference/subscriptions/estimate-a-subscription.md) - [Create a subscription recast](/api-reference/subscription-recasts/create-a-subscription-recast.md) - [Create a subscription](/api-reference/subscriptions/create-a-subscription.md)