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
• SSO — Agents

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

1

Customer logs in and starts mobile plan checkout

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

2

Brand account ID is passed via SSO

Customer’s brand account identifier is passed securely to Reach via SSO attributes.

3

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

Reach calls the brand’s Customer Information Check API.

4

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.

5

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 for event flags and sequencing.

6

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.

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.

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:

{
  "accountId": "726236434348",
  "firstName": "Susan",
  "lastName": "Jones",
  "emailId": "[e-mail]",
  "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:

{
  "event": "A",
  "accountId": "ACC123456",
  "accountStatus": "ACTIVE",
  "totalActiveLines": 2,
  "totalPurchasedLines": 2,
  "impactedLines": [
    "LINE-UUID-001"
  ],
  "lines": {
    "LINE-UUID-001": {
      "firstName": "John",
      "lastName": "Doe",
      "emailId": "[e-mail]",
      "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:

{
  "accountId": "726236434348",
  "newAccountId": "546612546466",
  "emailId": "[e-mail]",
  "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

1

Review docs and confirm rules

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

2

Build brand-side APIs

Implement:

• Customer Information Check (GET)
• Mobile Account Management (POST) (see MAM API Overview)

3

Align resources and timelines

Confirm your development timeline with Reach at [e-mail]. Reach shares lower-environment credentials once resourcing is aligned.

4

Integrate and test in non-production

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

5

Go live and monitor

Go live in production and monitor lifecycle events via the reporting suite.

Questions or clarification? Reach out to your respective account manager or email at [e-mail] for help and support.