> 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/technical/bolt-on-setup/product-bundle-integration.md).

# Product Bundle Integration

Integrate mobile + legacy services with Reach via SSO and APIs. Check eligibility at checkout, apply bundle discounts, and sync lifecycle events (Customer Info Check, MAM, Account Update)

Bundle mobile service with legacy services using SSO identity linking and APIs.

### Overview

Product Bundle Integration connects a brand’s mobile service with legacy services (for example, broadband) using SSO and secure API integration.

Qualifying customers automatically receive a bundle discount at checkout.

This integration is API-driven. It covers real-time eligibility checks, discount application, and account lifecycle management.

### Key concepts (search terms)

* **Bundle discount / converged offer**: Discounted mobile pricing for eligible legacy customers.
* **Eligibility check API**: Reach calls the brand in real time during checkout.
* **Brand SSO**: Passes a trusted brand account ID to link accounts.
* **Lifecycle sync**: Activation, plan changes, disconnects, and reconnects.
* **Legacy account ID**: Identifier used to validate eligibility and maintain the relationship.

### Key benefits

* **Customer loyalty**. Discounts across mobile and legacy services strengthen retention.
* **Seamless experience**. Real-time eligibility checks and automatic discounting reduce friction.
* **Flexible integration**. API-based integration supports customization and scaling.
* **Transparent operations**. Clear rules for applying, removing, and re-validating discounts reduce disputes.
* **Reduced overhead**. Automated lifecycle management minimizes manual work and support cost.
* **Dual discounting (optional)**. Customers can receive discounted mobile pricing and, optionally, discounts on the legacy bill (brand-dependent).

### Prerequisite: Brand SSO (identity linking)

SSO on web and app is required for Product Bundle Integration. Eligibility validation, discount enforcement, and account linking depend on a trusted customer identity at the start of the buy flow.

See:

* [SSO — End Customers](/technical/bolt-on-setup/sso-end-customers.md)
* [SSO — Agents](/technical/bolt-on-setup/sso-agents.md)

### How it works (end-to-end eligibility and discount flow)

{% stepper %}
{% step %}

#### Customer logs in and starts mobile plan checkout

Customer signs in to the brand portal (Reach-hosted) and starts a plan purchase.
{% endstep %}

{% step %}

#### Brand account ID is passed via SSO

Customer’s brand account identifier is passed securely to Reach via SSO attributes.
{% endstep %}

{% step %}

#### Bundle eligibility is checked in real time (Customer Information Check API)

Reach calls the brand’s Customer Information Check API.
{% endstep %}

{% step %}

#### Discount is applied (or the flow is blocked)

* If `isHSIDiscount=true`, bundle discounted pricing is applied and customer details are pre-filled at checkout.
* If `isHSIDiscount=false`, the flow is blocked and a configurable message is shown.
  {% endstep %}

{% step %}

#### Purchase completes and lifecycle sync begins

Customer completes purchase.

Lifecycle events (activation, changes, disconnection) are sent to the brand via the Mobile Account Management (MAM) API.

See [MAM API Overview](/technical/api/product-lifecycle-api-overview.md) for event flags and sequencing.
{% endstep %}

{% step %}

#### Discounts are removed or restored as eligibility changes

If the legacy service is disconnected, the brand notifies Reach to remove the mobile discount (effective next bill cycle).

Customers can re-validate eligibility via My Account or an agent to restore discounts.
{% endstep %}
{% endstepper %}

### Purchase flow and business rules (bundle discount rules)

Purchase behavior is governed by:

* `isHSIDiscount` from the Customer Information Check API
* `custType` returned for the customer

#### Eligibility and discount rules

| Customer type             | `isHSIDiscount` | Outcome                                                                                 |
| ------------------------- | --------------- | --------------------------------------------------------------------------------------- |
| Residential or Commercial | `true`          | Discounted pricing is applied. Purchase proceeds.                                       |
| Residential or Commercial | `false`         | Purchase is blocked. A configurable message is displayed.                               |
| Employee                  | Any             | `isHSIDiscount` is stored but ignored. Employee discount is applied. Purchase proceeds. |

#### Notes

* Discounts for Residential, Commercial/SMB, and Employee are mutually exclusive.
* Logged-out users see Residential discounted pricing as the default on plan cards.
* Logged-in users see pricing based on `isHSIDiscount` and `custType`.

#### Pricing configuration example

| Plan   | Standard price | Bundle discount | Bundle price | Commercial/SMB price | Employee price |
| ------ | -------------: | --------------: | -----------: | -------------------: | -------------: |
| Plan A |         $50.00 |          $15.00 |       $35.00 |               $25.00 |         $25.00 |
| Plan B |         $30.00 |          $10.00 |       $20.00 |               $20.00 |         $10.00 |

Notes:

* Other promotions can apply in addition to bundle discounts, per their own eligibility rules.
* If the brand has not defined a discount, disconnecting the legacy service may not change pricing.

### Customer type definitions

| `custType`    | Description                                             |
| ------------- | ------------------------------------------------------- |
| Residential   | Standard retail customer                                |
| CommercialSMB | Commercial customers (up to 25 lines maximum)           |
| Employee      | Brand employees, eligible for an employee discount tier |

#### Changing customer type

Brands use the Account Update API to update `custType`.

Discount changes take effect next bill cycle only.

If active lines exceed the new `custType` limit:

* Existing lines are grandfathered.
* No new lines can be added until the total is within the limit.

If `custType` changes from Employee to Residential and `isHSIDiscount=false`, bundle discounts stop next bill cycle. Brands should set `isHSIDiscount=true` if the account remains eligible.

### Checkout and account details

Reach uses Customer Information Check API fields to pre-fill checkout. Most fields are read-only at checkout. Updates after purchase must be made via the Account Update API.

* `accountId`: Used during SSO to link the brand legacy account ID to the Reach group account ID.
* `firstName`, `lastName`: Pre-filled at checkout (read-only).
* `emailId`: Used for communications (read-only at checkout).
* Service address: Default SIM shipping address (read-only at checkout).
* Billing address: Used for taxes (editable at checkout).
* `custType`: Determines discount tier.
* `isHSIDiscount`: Indicates bundle discount eligibility.

Default rule: if `isHSIDiscount=false`, purchase is declined. This can be configured to allow purchase if the brand opts in at launch.

### Discount removal and re-validation

#### Removing the bundle discount after legacy service disconnects

When the legacy service is disconnected, the brand must notify Reach to remove the mobile discount. Removal takes effect from the next bill date.

Customers receive communications when a bundle discount is removed.

#### Re-validating eligibility

Customers can re-validate via My Account (web/app) or through an agent.

* Re-validation CTA appears in My Account and in Reach Central on removal.
* Customer/agent enters the Brand Account ID.
* Reach calls the eligibility check API.
* If eligible, Reach restores the relationship and discount.
* If ineligible, a message is shown and retries are allowed.

Defaults:

* 3 self-serve attempts per day
* Unlimited retries for agents (configurable).

If re-validation happens in the same bill cycle, discount reinstates immediately. Otherwise, discount applies from the next bill generation date.

#### Other account management scenarios

* **Account transfer**. Brand updates the global account ID and notifies Reach via Account Update API.
* **Email change**. If a secondary line becomes primary, brand credentials must be updated to keep SSO working.
* **Address change**. Brand sends updated address via Account Update API.
* **Account type change**. Brand updates `custType` via Account Update API. Discount and line-count rules apply as above.

### API integration (eligibility, lifecycle sync, and account updates)

Product Bundle Integration uses three API touchpoints.

Two are brand-owned endpoints. One is Reach-owned.

All APIs use HTTPS and API keys.

| API                             | Owner | Method | Primary direction | Purpose                                                                                  |
| ------------------------------- | ----- | ------ | ----------------- | ---------------------------------------------------------------------------------------- |
| Customer Information Check      | Brand | `GET`  | Reach → Brand     | Eligibility + checkout pre-fill data (Reach calls using `accountId` from SSO).           |
| Mobile Account Management (MAM) | Brand | `POST` | Reach → Brand     | Lifecycle event notifications sent from Reach to the brand.                              |
| Account Update                  | Reach | `POST` | Brand → Reach     | Brand notifies Reach of account updates (address, `custType`, service disconnect, etc.). |

For lifecycle event meanings and sequencing, use [MAM API Overview](/technical/api/product-lifecycle-api-overview.md).

Reach calls the brand API during checkout to validate HSI eligibility and pre-fill account details.

If `isHSIDiscount=false`, Reach blocks purchase by default.

Sample Customer Information Check response:

```json
{
  "accountId": "726236434348",
  "firstName": "Susan",
  "lastName": "Jones",
  "emailId": "susan.jones@mail.com",
  "addresses": [
    {
      "type": "Service",
      "address1": "525 Junction Rd",
      "address2": "",
      "city": "Madison",
      "state": "WI",
      "zip": "53717"
    },
    {
      "type": "billing",
      "address1": "525 Junction Rd",
      "address2": "Suite 51",
      "city": "Madison",
      "state": "WI",
      "zip": "53717"
    }
  ],
  "isHSIDiscount": true,
  "custType": "Residential / Employees / CommercialSMB"
}
```

Reach calls the brand MAM endpoint when mobile lifecycle events occur for eligible accounts.

The first `A` event establishes the relationship between the brand account ID and the Reach group account.

Sample Mobile Account Management request:

```json
{
  "event": "A",
  "accountId": "ACC123456",
  "accountStatus": "ACTIVE",
  "totalActiveLines": 2,
  "totalPurchasedLines": 2,
  "impactedLines": [
    "LINE-UUID-001"
  ],
  "lines": {
    "LINE-UUID-001": {
      "firstName": "John",
      "lastName": "Doe",
      "emailId": "john.doe@example.com",
      "status": "ACTIVE",
      "reachNumber": "8001112222",
      "reachPlanId": "Smartphone & Tablet 2GB",
      "isPrimary": true,
      "imei": "111111111111111",
      "activationDate": "2023-10-18T13:05:00.164Z",
      "purchaseDate": "2023-10-18T12:21:50.924Z",
      "disconnectionDate": "2023-10-19T13:05:00.164Z",
      "reconnectionDate": "2023-10-20T13:05:00.164Z",
      "simPreference": "PHYSICAL_SIM",
      "isPortIn": true
    }
  }
}
```

The brand calls Reach to update account ID, email, addresses, discount eligibility, or `custType`.

Sample Account Update request:

```json
{
  "accountId": "726236434348",
  "newAccountId": "546612546466",
  "emailId": "amber.walker@email.com",
  "isHSIDiscount": true,
  "addresses": [
    {
      "address1": "string",
      "address2": "string",
      "city": "string",
      "country": "string",
      "name": "string",
      "phone": "string",
      "state": "string",
      "type": "service",
      "zip": "string"
    }
  ],
  "custType": "Residential"
}
```

### Integration setup and environments (non-production, staging, production)

Reach recommends at least two environments: non-production and production.

| Brand environment | Reach environment |
| ----------------- | ----------------- |
| Non-production    | Dev / QA / Stage  |
| Production        | Prod              |

* Reach provides keys and URLs for Dev/QA/Stage first.
* Production keys and URLs are provided after non-production sign-off.

### Next steps

{% stepper %}
{% step %}

#### Review docs and confirm rules

Review this page and the API specs. Share your bundle discount rules and plan configurations with Reach for validation.
{% endstep %}

{% step %}

#### Build brand-side APIs

Implement:

* Customer Information Check (`GET`)
* Mobile Account Management (`POST`) (see [MAM API Overview](/technical/api/product-lifecycle-api-overview.md))
  {% endstep %}

{% step %}

#### Align resources and timelines

Confirm your development timeline with Reach at `accounts@reachmobile.com`. Reach shares lower-environment credentials once resourcing is aligned.
{% endstep %}

{% step %}

#### Integrate and test in non-production

Test against Dev/QA/Stage using the provided keys. Complete sign-off before requesting production credentials.
{% endstep %}

{% step %}

#### Go live and monitor

Go live in production and monitor lifecycle events via the reporting suite.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
Questions or clarification? Reach out to your respective account manager or email at <accounts@reachmobile.com> 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/technical/bolt-on-setup/product-bundle-integration.md?ask=<question>&goal=<user_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.