> For the complete documentation index, see [llms.txt](https://docs.reachplatform.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.reachplatform.com/core-product-structure/product-catalog-offering/promotions.md). # Promotions Types, configuration inputs, and governance rules for BAU promotions. ### Overview Promotions are used to drive **acquisition**, reward **loyalty**, and support **bundle pricing**. This section covers what the platform supports in **business-as-usual (BAU)**, as well as the rules you must follow when launching and operating promos. {% hint style="warning" %} Promotions apply only to the plan's **Monthly Recurring Charge (MRC)**. They do **not** discount add-ons, one-time fees, shipping, or device charges. All promotions must be configured per tenant in the Reach Catalog using the **Promo BAU Configuration Sheet**. Please reach out to your Account Manager whenever you would like to create a promotion for your customers. {% endhint %} ### What you can do (BAU) * Create **coupon code** and **systematic promotions** * Limit promotions by **plan**, **customer type**, **user type**, and **number choice** * Control **stacking** and **priority** when stacking is allowed * Support **bundle-triggered discounts** via API, for product bundle only > - **Coupon-Based Promotion:** Agent-applied promotion using a code or catalog selection, subject to eligibility, stackability, and lifecycle controls. > - **Systematic Promotion:** System-applied promotion triggered automatically based on predefined eligibility rules, with no agent action or override. ### Promotion types | Type | How it works | Operational behavior | | ------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | Coupon code | Customer or agent enters a promo code at checkout. | Once applied to an account, it cannot be removed. Validate configuration before publishing the code. | | Systematic | Discount auto-applies when eligibility rules match. | Removed only when eligibility is no longer met. Manual removal is not supported. | | API — product bundle only | Discount triggers when the customer meets brand-defined product bundle eligibility. | Requires an active Product Bundle API integration. Treated as the base promo with the highest priority (P0). | ### Standard configuration inputs The platform expects the fields below for every promo. | Field | Required | Allowed values | Notes | | ----------------------- | ----------- | ------------------------------------------------ | ----------------------------------------------------------------------------- | | Promo Name | Mandatory | Free text, max 15 chars | Customer-facing label used across Web/App/RC and billing views. | | Promo Code | Mandatory | Free text, max 15 chars | Coupon: must be unique. Systematic: can match Promo Name. Shows in reporting. | | Promo Reason Code | Mandatory | Free text, max 15 chars | Used for reporting and reconciliation. | | Application Duration | Mandatory | Purchase / Activation | Purchase applies at checkout. Activation applies when the line activates. | | Promo Start Date | Mandatory | MM-DD-YYYY | First day the promo can apply. | | Promo End Date | Optional | MM-DD-YYYY | Leave blank for open-ended promos. | | Promo Type | Mandatory | Systematic / Coupon / API (product bundle only) | Defines how the promo is triggered. | | User Type | Mandatory | New User / Existing (Add line) / Both | Promo applies to new purchases only (even for add-a-line). | | Customer Type | Mandatory | Residential / Business / Employee / combinations | Allowed combinations: Res+Bus, Res+Emp, Bus+Emp, Res+Bus+Emp. | | Plans | Mandatory | All / specific plan names | Use exact plan names when scoping. | | Number Preference | Mandatory | New Number / Port-In / Both | Controls eligibility by number choice. | | Frequency | Mandatory | # bill/renewal cycles or Recurring-infinite | Examples: One-time, Recurring (6 cycles), Recurring-infinite. | | Value | Mandatory | $ amount or % (≤ 100%) | Example: $10 off, 100% off. | | Line Criteria | Mandatory | Primary / Secondary / Both / specific lines | Controls which lines the promo targets on a multi-line account. | | Usage Limit | Mandatory | Numeric value or # lines on account | Max number of applications. | | Account / Plan Level | Conditional | Account / Plan | Required for multi-line discounting logic. | | Promo Stacking Allowed | Mandatory | Allowed / Not Allowed | Whether other promos can coexist. | | Promo Stacking Priority | Conditional | Priority order + promo list | Required only when stacking is allowed. | | Promo Description | Mandatory | Free text, max 20–25 chars | Short customer-facing description on the plan card. | | Invoice Display Name | Optional | Free text, max 15 chars | If blank, invoice uses Promo Name. | ### Stacking and priority When stacking is enabled, promos are applied in a fixed priority order. * **P0** — product bundle discount (API; always highest priority) * **P1** — 1st line free / employee discount * **P2** — BOGO * **P3** — coupon codes and other stackable promos {% hint style="info" %} Stackability determines whether multiple promotions can apply simultaneously to the same account or line. * When stacking is enabled, only compatible promotions are applied together. * If multiple promotions are eligible, they are applied in a fixed order of priority (P0 → P3). * Higher-priority promotions are applied first and may override or block lower-priority ones. * Non-stackable promotions cannot coexist and must be replaced with conflicting promos. * Selective stackable promotions can coexist only with the promo types allowed in the catalog. * The final set of applied promotions is determined after resolving eligibility, conflicts, and priority rules. {% endhint %} ### Governance rules (non-negotiables) | Rule | Policy | | -------------------------- | ------------------------------------------------------------------------------------------------- | | When promos can be applied | Only during a new purchase flow. You cannot add a promo to an already-active plan after purchase. | | Coupon removal | Not supported once applied to an account. | | Systematic removal | Happens only when the account no longer matches eligibility. Manual removal is not supported. | | Effective date of removal | Any removal takes effect starting the **next** billing cycle. No retroactive adjustments. | | Non-BAU configurations | Anything outside these rules is treated as custom work. | ### BAU use cases (templates) Use the examples below as reference templates when completing the Promo BAU Configuration Sheet. This list is indicative and not exhaustive of all promotion types supported in the catalog. #### Use case 1 — 1st line discount via coupon | Field | Value | | -------------------- | -------------------- | | Promo Name | First line discount | | Promo Code | FIRST10OFF | | Promo Type | Coupon | | Application Duration | Purchase | | User Type | New User | | Customer Type | Residential | | Plans | All Plans | | Value | $10 off | | Frequency | Recurring – 6 months | | Line Criteria | Primary | | Usage Limit | 1 (Account level) | | Promo Stacking | Allowed — P1 | | Number Preference | New Number | | Invoice Display Name | First line discount | #### Use case 2 — BOGO (buy one, get one) | Field | Value | | -------------------- | ------------------------ | | Promo Name | BOGO Feb 2026 | | Promo Code | BOGO Feb 2026 | | Promo Type | Systematic | | Application Duration | Activation | | User Type | Existing (Add line) | | Customer Type | Residential + Employee | | Plans | All Plans | | Value | 100% off | | Frequency | Recurring – 3 months | | Line Criteria | Every 2nd line (2, 4, …) | | Usage Limit | 2 (Plan level) | | Promo Stacking | Not Allowed | | Number Preference | Both | | Invoice Display Name | 1 Unlimited Line Free | #### Use case 3 — 1st line free (systematic) | Field | Value | | -------------------- | --------------------- | | Promo Name | 1st Line free | | Promo Code | 1st Line free | | Promo Type | Systematic | | Application Duration | Activation | | User Type | New User | | Customer Type | All | | Plans | Unlimited Plans Only | | Value | 100% off | | Frequency | Recurring – 12 months | | Line Criteria | Primary | | Usage Limit | 1 (Plan level) | | Promo Stacking | Allowed — P2 | | Number Preference | Both | | Invoice Display Name | 1st Line free | #### Use case 4 — employee discount | Field | Value | | -------------------- | ------------------------------------ | | Promo Name | Employee discount | | Promo Code | Employee discount | | Promo Type | Systematic | | Application Duration | Purchase | | User Type | Both | | Customer Type | Employee | | Plans | All Plans | | Value | 100% off Line 1 / $X off other lines | | Frequency | Recurring – Infinite | | Line Criteria | Both | | Usage Limit | # lines on account (Account level) | | Promo Stacking | Not Allowed | | Number Preference | Both | | Invoice Display Name | Employee discount | {% hint style="info" %} Questions or clarification? Reach out to your respective account manager or email us at for help and support. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.reachplatform.com/core-product-structure/product-catalog-offering/promotions.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.