# SureBright Documentation

# Authentication

Source: https://docs.surebright.com/api-reference/authentication

> Learn how to authenticate your requests to the SureBright API

## Overview

The SureBright API uses a private API key for authenticating requests to secure endpoints. This key must be included in the request header using the X-SureBright-Access-Token field. You can view and manage your API key through the SureBright Merchant Portal under Account Settings.

<Note>
🔒 Important: 

Your API key grants privileged access—treat it as sensitive information. Never expose your API key in public repositories (e.g., GitHub) or embed it in client-side code.
</Note>

All API requests must be made over HTTPS. Requests sent over plain HTTP will be rejected.


Authentication is required only for secure endpoints, such as those involving order details, claims, and other sensitive merchant or customer data. Public or non-sensitive endpoints may not require authentication.

| Type |  API key
|------|----------------------|
| Header Parameter Name | X-SureBright-Access-Token |

## Example Request

### Sandbox Environment

```bash
curl -X POST \
 https://{HOST_NAME}/platform/api/v1/order \\
  -H 'Accept: application/json' \\
  -H 'Content-Type: application/json' \\
  -H 'X-SureBright-Access-Token: {sandbox access token}'

```

## Required Credentials

The following values will be provided as part of the SureBright Integration Kit for both staging and production environments:

- `storeId`
- `X-SureBright-Access-Token`
- `HOST_NAME`

---

# Cancel Contracts for Whole System Warranty

Source: https://docs.surebright.com/api-reference/endpoint/order/cancel-contract-whole-system-warranty

> This endpoint cancels an existing warranty contract for a whole system order. Provide the contract ID obtained from the Create Contracts for Whole System Warranty endpoint. The API returns the cancellation status of the warranty contract.

## Headers

| Header | Description | Required |
|--------|-------------|----------|
| X-SureBright-Access-Token | Access token for authentication | Yes |

## Overview

This endpoint cancels warranty contract for a whole system order.

<Note>
A contract can only be cancelled within 30 days after the date of sale of purchase.
</Note>

---

# Create Contracts for Order

Source: https://docs.surebright.com/api-reference/endpoint/order/create-contract

> This endpoint is used to create warranty contracts for a specific order. 🛠️ **Contract Creation Logic** Warranty contracts are created in a 1:1 ratio with the quantity of the associated product purchased. The warranty quantity is automatically inferred from the product quantity. Contracts are only created for the exact number of products purchased—warranty coverage cannot exceed or fall short of the product quantity. 🏷️ **Using policySKU** The `policySKU` is a required field that determines the parameters of each warranty contract, including: - Coverage Type (e.g., accidental damage, mechanical breakdown) - Tenure (duration of coverage) - Country (to apply relevant terms and conditions) - Category (product type classification) Merchants must ensure that the appropriate `policySKU` is used for each product to ensure accurate coverage assignment. 🔁 **Handling Updates** If this endpoint is called for an order where contracts already exist: - Existing contracts will be updated if the quantity or details have changed. - Warranty price, tenure, and coverage type are handled automatically based on the provided `policySKU`.

## Headers

| Header | Description | Required |
|--------|-------------|----------|
| X-SureBright-Access-Token | Access token for authentication | Yes |
| Content-Type              | application/json                | Yes |

---

# Create / Update Contracts for Whole System Warranty

Source: https://docs.surebright.com/api-reference/endpoint/order/create-contract-whole-system-warranty

> This endpoint creates or updates a warranty contract for a whole system order. Line items, total covered amount, and warranty duration are derived from the sales lead identified by `sbSalesLeadId`. Provide the warranty quote details and customer information; the API returns the contract ID. If a contract already exists for the given sales lead, the existing contract is updated instead of creating a new one.

## Headers

| Header | Description | Required |
|--------|-------------|----------|
| X-SureBright-Access-Token | Access token for authentication | Yes |
| Content-Type              | application/json                | Yes |

## Overview

This endpoint creates or updates a warranty contract for a whole system order. It is used after obtaining warranty quotes from the **List Quotes for Whole System Warranty** endpoint.

### Flow

1. First, call the **List Quotes for Whole System Warranty** endpoint to get available warranty quotes for your system order
2. Select the desired warranty plan from the returned `warrantyQuoteItemList`
3. Submit the selected warranty details and customer information to this endpoint. Line items, total covered amount, and warranty duration are read from the sales lead identified by `sbSalesLeadId` — they do not need to be sent in the request.

### Request Details

- **`sbSalesLeadId`** - The sales lead Id obtained from the List Quotes API response. The contract's covered line items, purchase price, and warranty duration are derived from this lead.
- **`warrantyQuoteId`** - The unique quote Id received from the quote endpoint
- **`warrantyQuoteItemId`** - The unique identifier for the warranty quote item obtained from the quote endpoint

<Note>
`sbSalesLeadId` is required and is the source of truth for line items. Generate the lead first via the **List Quotes for Whole System Warranty** endpoint; do not send a `lineItemList` — any value is ignored.
</Note>

<Note>
**Updating Existing Contracts**

If a contract already exists for the provided `sbSalesLeadId`, calling this endpoint will update the existing contract instead of creating a new one:
- Updates to line items are not permitted beyond **30 days** from the date of sale.
 
- **Customer details** and other non-line item fields can be updated at any time
</Note>

### Validations

The endpoint performs the following cross-checks before creating or updating a contract. Each failed check returns the listed error code and short-circuits the request before any side effect.

| Check | Error |
|-------|-------|
| `sbSalesLeadId` exists **and** belongs to the requesting `storeId` (lookup is keyed by both) | `515` Sales Lead Not Found |
| `warrantyQuoteId` matches the `sbQuoteId` carried on the lead's line items | `518` Quote ID Mismatch |
| The quote document is retrievable from DDB by `warrantyQuoteId` | `513` No Quote Found |
| The store exists for the requesting `storeId` | `514` Store Not Found |
| `warrantyQuoteItemId` resolves to an item inside the quote | `519` Quote Item Not Found |
| `warrantyCoverageYears` equals the resolved quote item's `coverageYears` | `520` Warranty Coverage Years Mismatch |
| (Existing-contract update path) The contract referenced by the lead's `contractIdList` exists in DDB | `516` Contract Not Found |
| (Existing-contract update path) Covered line items unchanged once 30 days have elapsed since purchase | `517` Line Items Update Not Allowed |

These gates run **before** any user account creation, contract write, or notification, so a rejected request leaves no partial state behind.

### Response

On success, you will receive:
- **`contractId`** - The unique identifier for the warranty contract created

---

# Overview

Source: https://docs.surebright.com/api-reference/endpoint/order/index

The **Order entity** serves as the foundational record that captures detailed information about the line items purchased by a customer. Each line item within an order represents a product eligible for various warranty offerings, such as:

- Product protection plans
- Shipping warranties

The **SureBright Order API** is designed to transmit sold contract details to our system and to manage related operations such as order updates and cancellations. It acts as the primary interface for creating, updating, or canceling warranty contracts associated with your sales.

---

## 🔧 Key Functions of the Order API

### ✅ Create Warranty Contracts

When a new order is submitted:

- The API checks if the `partnerOrderId` exists in SureBright’s records.
- If it **does not exist**, the API automatically generates **warranty contracts** for the order’s line items based on the provided details.

### ♻️ Update Existing Contracts

When the `partnerOrderId` **already exists**:

- Use the **`PUT method`** to update the existing order and its associated warranty contracts.
- If a lower quantity is specified for any line item compared to the original order, the system will **automatically cancel** the corresponding number of warranty contracts to reflect the reduced coverage.

### ❌ Cancel Specific Line Items

To cancel warranty coverage on a particular product line:

- Set the `warrantyQuantity` field to `0` for that line item in the `lineItemList` via the `PUT` method.
- This action cancels **only** the warranty contracts for that specific line item, leaving the rest of the order unaffected.

---

## 🧾 Summary of API Capabilities

| Operation                 | Description                                                                                                                                                          |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Create Order (POST)**   | Generates new warranty contracts if the order is not yet recorded (`partnerOrderId` not found).                                                                      |
| **Update Order (PUT)**    | Modifies existing warranty contracts and adjusts quantities. Cancels contracts if quantity decreases.                                                                |
| **Cancel Line Item(PUT)** | To cancel a specific line item, Using PUT method of order API set the field "warrantyQuantity" in lineItem inside lineItemList to 0 as part of the lineItem details. |

---

This API provides a robust way to keep your warranty contracts in sync with your order lifecycle, ensuring **accurate coverage management** across sales, returns, and cancellations.

---

# Cancel / Update contracts for Order

Source: https://docs.surebright.com/api-reference/endpoint/order/update-contract

> This endpoint is used to create, update, or cancel warranty contracts for a specific order. 🔄 **Updating Line Item Quantities** If the quantity of a product in the original order is changed (e.g., reduced), the corresponding warranty contract quantity is automatically adjusted to match the updated product quantity. To reduce or cancel warranty coverage for a line item, update the `quantity` field inside the relevant `lineItem` object in the `orderLineItemList`. ❌ **Cancelling Line Items** To cancel warranty coverage for a specific line item, set its `quantity` to 0 in the `orderLineItemList`. Once cancelled, a warranty contract cannot be reactivated. This applies to both partial cancellations (some items in the order) and full order cancellations. 🧾 **Handling Full Order Cancellation** For full order cancellations, merchants have two options: - Remove the `planDetails` object entirely from the request payload. - Set the `quantity` of each relevant `lineItem` in `orderLineItemList` to 0. ⚙️ **Automatic Price and Tenure Updates** Any changes to warranty price or tenure (e.g., due to product updates or plan revisions) are handled automatically by the system.

## Headers

| Header | Description | Required |
|--------|-------------|----------|
| X-SureBright-Access-Token | Access token for authentication | Yes |
| Content-Type              | application/json                | Yes |

---

# Overview

Source: https://docs.surebright.com/api-reference/endpoint/quote/index

A **Quote** represents the dynamically generated pricing and coverage details for an extended warranty plan when a user inquires about protection for a specific product variant or product category.

It serves as a core object in the warranty flow, allowing customers to view and select the most relevant protection plans at the point of sale.

---

## 🧩 How Quotes Are Generated

Quotes can be generated in two ways:

### 🔹 For a Specific Product Variant

Provides **precise pricing and plan options** tailored to the exact product configuration (e.g., brand, model, price).

- Ideal for **product detail pages** or **checkout flows**

### 🔹 For a Product Category

Returns a **price range** that reflects variability across products within the selected category (e.g., Televisions, Home Appliances).

- Includes **multiple tenure and coverage options**
- Helps users understand **general cost and protection level**

---

## 🌍 Geographic Sensitivity

Quotes are **region-aware** and vary based on:

- **Country**  
  Warranty pricing, tax, regulations, and coverage terms may differ by country.

- **Province/State (within a Country)**  
  Localized pricing or regulations may apply.  
  _Example: California vs Texas, or Ontario vs Quebec._

---

## 📦 Quote & QuoteItem Structure

Each quote is uniquely identified by a `quoteId`.  
A `quoteId` may include **multiple plan options**, each represented by a unique `quoteItemId`.

Each `quoteItemId` includes:

- **Coverage Type** – e.g., Accidental Damage, Breakdown, or both  
- **Tenure** – Duration of coverage (e.g., 12, 24, 36 months)  
- **Price** – Fixed cost (variant-level) or price range (category-level)  
- **Deductible** – Optional customer-paid portion per claim  
- **Region** – Country and, if applicable, province/state  
- **Currency & Locale** – Ensures accurate regional pricing  
- **Terms & Conditions URL** – Link to the full warranty policy  

---

## 🚀 Usage

Quotes enable both customers and merchant systems to:

- Dynamically present **warranty options** based on user location and product context  
- Power **product detail pages**, modals, or embedded widgets with tailored protection plans  
- Drive **upsell logic** that reflects jurisdiction-specific compliance and pricing logic

---

# By Category

Source: https://docs.surebright.com/api-reference/endpoint/quote/list-warranty-quotes-by-category

> This endpoint retrieves a list of warranty quotes for a specific store and category. The response includes detailed warranty options, pricing, and coverage information.

## Headers

| Header | Description | Required |
|--------|-------------|----------|
| X-SureBright-Access-Token | Access token for authentication | No |



## Country and State Codes

- Country codes (Alpha 2): [IBAN Country Codes](https://www.iban.com/country-codes)
- US State codes: [FIPS State Codes](https://en.wikipedia.org/wiki/Federal_Information_Processing_Standard_state_code)

---

# For all price bands of a category

Source: https://docs.surebright.com/api-reference/endpoint/quote/list-warranty-quotes-by-category-for-all-price-bands

> Retrieves a list of warranty quotes for all price bands based on Category. The response includes price bands details and warranty quotes details.

## Note
<Note>
    The payload parameter must be sent as a Base64-encoded query string for secure transmission.
</Note>
## Headers

| Header | Description | Required |
|--------|-------------|----------|
| X-SureBright-Access-Token | Access token for authentication | No |



## Country and State Codes

- Country codes (Alpha 2): [IBAN Country Codes](https://www.iban.com/country-codes)
- US State codes: [FIPS State Codes](https://en.wikipedia.org/wiki/Federal_Information_Processing_Standard_state_code)

---

# By Product

Source: https://docs.surebright.com/api-reference/endpoint/quote/list-warranty-quotes-by-product

> This endpoint retrieves a list of warranty quotes for a specific product and its price.

## Headers

| Header | Description | Required |
|--------|-------------|----------|
| X-SureBright-Access-Token | Access token for authentication | No |



## Country and State Codes

- Country codes (Alpha 2): [IBAN Country Codes](https://www.iban.com/country-codes)
- US State codes: [FIPS State Codes](https://en.wikipedia.org/wiki/Federal_Information_Processing_Standard_state_code)

---

# By Product Details

Source: https://docs.surebright.com/api-reference/endpoint/quote/list-warranty-quotes-by-product-details

> This endpoint retrieves a list of warranty quotes based on product details (title, description, and price). The response includes detailed warranty options, pricing, and coverage information similar to other quote endpoints.

## Headers

| Header | Description | Required |
|--------|-------------|----------|
| X-SureBright-Access-Token | Access token for authentication | No |
| Content-Type              | application/json                | Yes |

## Country and State Codes

- Country codes (Alpha 2): [IBAN Country Codes](https://www.iban.com/country-codes)
- US State codes: [FIPS State Codes](https://en.wikipedia.org/wiki/Federal_Information_Processing_Standard_state_code)

---

# By Url

Source: https://docs.surebright.com/api-reference/endpoint/quote/list-warranty-quotes-by-url

> This endpoint fetches all warranty quotes for the product category to which product in the sent URL belongs.

## Headers

| Header | Description | Required |
|--------|-------------|----------|
| X-SureBright-Access-Token | Access token for authentication | No |



## Country and State Codes

- Country codes (Alpha 2): [IBAN Country Codes](https://www.iban.com/country-codes)
- US State codes: [FIPS State Codes](https://en.wikipedia.org/wiki/Federal_Information_Processing_Standard_state_code)

---

# For Whole System Warranty

Source: https://docs.surebright.com/api-reference/endpoint/quote/list-warranty-quotes-for-whole-system

> This endpoint generates warranty quotes for an entire system order. It accepts store, proposal, and detailed line-item information as inputs, along with the installer’s warranty duration. The API returns available warranty offers, product coverage details, and a link to the specific terms and conditions for the warranty-eligible products

## Headers

| Header | Description | Required |
|--------|-------------|----------|
| X-SureBright-Access-Token | Access token for authentication | No |
| Content-Type              | application/json                | Yes |

## Country and State Codes

- Country codes (Alpha 2): [IBAN Country Codes](https://www.iban.com/country-codes)
- US State codes: [FIPS State Codes](https://en.wikipedia.org/wiki/Federal_Information_Processing_Standard_state_code)

---

<Note>
To regenerate quotes for the same proposalId / lead, provide one of the following identifiers:

- `partnerProposalId` (this corresponds to your system's proposal Id)
- `sbSalesLeadId` (returned in the first List Quotes API response)
</Note>

---

# Overview

Source: https://docs.surebright.com/api-reference/endpoint/store-category/index

> A Store Category represents a distinct grouping of products within a specific store that are eligible for extended warranty coverage.

It is used to determine applicable protection plans based on:

- Product type
- Usage patterns
- Risk profiles

This classification enables stores to tailor warranty offerings to their unique catalog and customer base.

---

## Unique Identification

Each store category is uniquely defined by:

- **Store ID**
- **Product Category**

This ensures that the same product category (e.g., _Televisions_) can have customized warranty rules across different stores—allowing flexibility in **coverage**, **pricing**, and **eligibility**.

---

## Examples of Store Categories

Products within a store category typically share functional or physical characteristics. Common examples include:

- **Consumer Electronics**
  - Smartphones, tablets, laptops
- **Home Appliances**
  - Microwaves, washing machines
- **Major Appliances**
  - Refrigerators, ovens
- **Mobility**
  - E-bikes, hoverboards, electric scooters
- **Furniture**
  - Indoor furniture, outdoor furniture, mattresses, rugs

---

## Coverage Options

Warranty coverage associated with a store category may include:

- **Accidental Damage Protection**
  - Drops, spills, and other unintentional physical damage
- **Mechanical or Electrical Breakdown**
  - Failures occurring after the manufacturer's warranty expires
- **Configurable Plan Features**
  - Deductible options
  - Custom warranty durations

---

ℹ️ **Recommendation:**\
The **store category-based quotes** functionality is primarily recommended for **POS (Point-of-Sale) stores** that do not have complete product-level information available in their catalog. This approach enables these stores to offer warranty coverage based on broader product classifications rather than individual SKUs.

---

# List Category

Source: https://docs.surebright.com/api-reference/endpoint/store-category/list-category

> Retrieves a list of store categories based on storeId . The response includes category details, and labels based on the authorization status

## Headers

| Header | Description | Required |
|--------|-------------|----------|
| X-SureBright-Access-Token | Access token for authentication | No |

---

# HTTP Status Codes

Source: https://docs.surebright.com/api-reference/http-status-codes

<ResponseField name="511" type="string">
  Insufficient Parameters
</ResponseField>

<ResponseField name="512" type="string">
  Validation Failed for Input Parameters
</ResponseField>

<ResponseField name="513" type="string">
  Product Not Found
</ResponseField>

<ResponseField name="514" type="string">
  No Quote Found
</ResponseField>

<ResponseField name="515" type="string">
  Store Not Found
</ResponseField>

<ResponseField name="516" type="string">
  Not Eligible
</ResponseField>

<ResponseField name="517" type="string">
  Category Not Found
</ResponseField>

<ResponseField name="200" type="string">
  Quotes Found
</ResponseField>

<ResponseField name="500" type="string">
  Something Unexpectedly Went Wrong
</ResponseField>

---

# Introduction

Source: https://docs.surebright.com/api-reference/introduction

### Offer Seamless Protection with SureBright

**SureBright’s API-first platform empowers merchants to offer comprehensive product protection, including:**

- **Accidental Damage**
- **Extended Warranty**
- **Shipping Protection**

Our proprietary technology handles the full lifecycle—from categorizing products and capturing contract sales to powering dynamic UI and managing post-purchase customer experiences.

---

### Why SureBright

- **API-first & Developer-friendly**: Built for fast, flexible integrations.
- **End-to-End Coverage**: We manage everything—from backend logic to the customer experience.
- **AI-Driven Efficiency**: Reduces integration time, operational workload, and ongoing maintenance by up to **95%**.
- **Dynamic Pricing Engine**: Available **on request**, this feature enables real-time pricing optimization to boost customer conversions.

---

### Seamless Customer Experience

**Consumers can purchase protection plans at key points in the shopping journey:**

- **Product Page** – Offer protection alongside the product for early decision-making.
- **Cart Popup** – Reinforce protection at a high-intent moment.
- **Cart Page** – Final chance to add protection before checkout.

On the **cart page**, customers are also offered the option to:

- **Protect all items in the cart using Shipping Protection**, ensuring comprehensive coverage for their order.

---

### Easy Integration with Full UI Control

SureBright’s solution is designed for seamless integration while giving you:

- **Full control over the widget UI** to ensure a consistent and branded customer experience
- **Dynamic, context-aware display** of protection offers tailored to your catalog
- **Zero backend maintenance** – we handle pricing updates, logic, and product changes so you don’t have to

---

### Comprehensive API Suite for Full Program Visibility

SureBright provides a full gamut of APIs that give merchants complete visibility and control over their product protection programs. Merchants can:

- **Push orders and contracts** seamlessly to SureBright’s platform
- **Retrieve and manage store product categories** for accurate protection mapping
- **Check quotes for any product** in real time to offer dynamic, up-to-date protection plans

This API suite ensures you have full transparency and operational control throughout the entire customer protection lifecycle.

---

# Over the Phone Sales using Draft Order Extension

Source: https://docs.surebright.com/draft-order-guide/shopify-draft-order

> This document describes how to use Shopify’s Draft Orders to record over the phone sales

A Draft Order in Shopify allows merchants to manually create orders for custom or over the phone sales outside the regular checkout process. It benefits merchants by providing personalized orders, flexible payment options, and the ability to review an invoice before payment. Draft orders reserve inventory, enabling quick adjustments like adding items or modifying quantities. They also allow for special discounts and act as quotations, offering transparency in pricing.

## Sales Use Cases/ Scenarios

We have listed the common scenarios/use cases below. Please feel free to directly jump to the scenario which is applicable to you.

1. Selling product and the warranty plan in one single order through Draft Orders 
2. Selling a warranty plan for a customer who has already bought the product that he wants to cover using Shopify
3. Selling a warranty plan for the case when the customer had already bought the product but not on Shopify. Though the product is listed in your Shopify store.
4. Selling a warranty plan for the case when the customer had already bought the product but not on Shopify. Though the product is NOT listed on your Shopify store.

## Prerequisite

### Installing SureBright Extension for Draft Orders

<Note>
  **Note:** The SureBright Draft Order extension for Shopify requires permission to create draft orders.
</Note>

Follow these steps to access the SureBright Draft Order extension:

1. Open any one of your existing draft orders or created orders.
2. If you don’t have an existing draft order, simply click on ‘Create order’ and add any product to it. Click ‘Save’ — only then will the next step become available.

   ![Draft Order1 Pn](/images/draft_order1.png)
3. On the order page, click on the **More actions** dropdown (located at the top of the page).
4. From the dropdown, select **SureBright - Product Protection Draft Order**.

   ![More Actions Dropdown](/images/more-actions-surebright.png)
5. On first use, you will be redirected to a Shopify authentication screen for sharing necessary permissions. Please proceed with the same.
6. Once authenticated, the SureBright popup will open and you can begin adding warranty plans to your line items.

## 

### Sales Use Case 1: Selling a Product and Warranty Plan in a Single Order through Draft Orders

You can create a draft order that sells both a product and its associated warranty plan in single transaction.

<Steps>
  <Step title="Create a New Draft Order">
    - In your Shopify admin, go to Orders \> Drafts \> Create Order.

      ![Draft Order1 Pn](/images/draft_order1.png)
  </Step>
  <Step title="Add the Product">
    - Search for the product by clicking “Browse” button and add it to the draft order.

      ![Draft Order3 Pn](/images/draft_order3.png)
  </Step>
  <Step title="Save the Draft Order">
    - Click Save on the top.

      ![Draft Order4 Pn](/images/draft_order4.png)
  </Step>
  <Step title="Add Warranty Plan">
    - In the draft order page, click on the **More actions** dropdown (located at the top of the order page).
    - From the dropdown, select **SureBright - Product Protection Draft Order**.

      ![More Actions Dropdown](/images/more-actions-surebright.png)
    - A popup will open. For the respective line items, select the appropriate warranty plan from the drop-down menu and click **Save**.

      ![SureBright Product Protection Popup](/images/surebright-product-protection-popup.png)
  </Step>
  <Step title="Complete the Draft Order:">
    - Confirm the product and warranty are added.
    - Choose the payment method or send an invoice to the customer.
    - Fulfill the order once payment is completed.
  </Step>
</Steps>

### Sales Use Case 2: Selling a Warranty Plan for a Customer Who Already Bought the Product via Shopify

If a customer previously purchased a product from your Shopify store and now wants to buy a warranty:

<Steps>
  <Step title="Open the order page">
    - Open Order page with the product sale for which policy is to be purchased.
  </Step>
  <Step title="Add the Warranty Plan">
    - Click on the **More actions** dropdown and select **SureBright - Product Protection Draft Order**.

      ![More Actions Dropdown](/images/more-actions-surebright.png)
    - A popup will open. For the respective line items, select the appropriate warranty plan from the drop-down menu and click **Save**.

      ![SureBright Product Protection Popup](/images/surebright-product-protection-popup.png)
  </Step>
  <Step title="If the Product is Uncategorized">
    - If the product has not been auto-categorized yet, the warranty options dropdown will display **"No Extended Warranty Options Available"**.

      ![No Warranty Options Available](/images/draft-order-existing-no-options.png)
    - Click on the dropdown and select **"No, I will categorize the product"**. A **Select Category** dropdown will appear below.

      ![Categorization Option Selected](/images/draft-order-existing-categorize.png)
    - Choose the appropriate category for the product. A **Fetch Quotes** button will appear — click it to retrieve available warranty policies.

      ![Fetch Quotes Button](/images/draft-order-existing-fetch-quotes.png)
    - Once quotes are fetched, a **Select Policy** dropdown will appear.

      ![Select Policy Dropdown](/images/draft-order-existing-select-policy.png)
    - Choose your preferred warranty policy from the list and click **Save** to complete the process.

      ![Policy Selected](/images/draft-order-existing-policy-selected.png)
  </Step>
  <Step title="Complete the Draft Order">
    - Set the payment terms or send an invoice.
  </Step>
</Steps>

### Sales Use Case 3: Selling a Warranty Plan for a Customer Who Bought the Product Elsewhere, But It’s Listed in Your Shopify Store

If a customer bought a product from another platform but the product is present in your Shopify store, you can still sell them a warranty plan.

<Steps>
  <Step title="Create a New Draft Order">
    - In your Shopify admin, go to Orders \> Drafts \> Create Order.

      ![Draft Order1 Pn](/images/draft_order1.png)
  </Step>
  <Step title="Add the Product">
    - Search for the product by clicking “Browse” button and add it to the draft order. You can add it for record-keeping purposes, even if they already own the product.

      ![Draft Order4 Pn](/images/draft_order4.png)
  </Step>
  <Step title="Save the Draft Order">
    - Click Save on the top.

      ![Draft Order4 Pn](/images/draft_order4.png)
  </Step>
  <Step title="Add the Warranty Plan">
    - Click on the **More actions** dropdown and select **SureBright - Product Protection Draft Order**.

      ![More Actions Dropdown](/images/more-actions-surebright.png)
  </Step>
  <Step title="Select Product Purchase Date">
    - A popup will open prompting you to select the product purchase date. Click on **Select Product Purchase Date** to open the date picker.

    ![Product Purchase Date Prompt](/images/draft-order-popup-date-prompt.png)
  </Step>
  
  <Step title="Choose Purchase Date">
    - The date picker calendar will appear. Select the product purchase date.

      ![Date Picker Calendar](/images/draft-order-popup-calendar.png)
    - Once selected, the chosen date will be displayed. Click **Next** to proceed.

      ![Date Selected](/images/draft-order-popup-date-selected.png)
  </Step>
  
  <Step title="Select Warranty Plan">
    - For the respective line items, select the appropriate warranty plan from the drop-down menu and click **Save**.

      ![Warranty Options Available](/images/draft-order-popup-warranty-options.png)
  </Step>
  <Step title="Remove previously purchased product/line item">
    - The warranty will be added to the draft order alongside the product.

      ![Products with Warranty Added](/images/draft-order-products-with-warranty.png)
    - To remove the line item associated with the selected warranty, click on the ‘Delete’ icon next to the original product. (This step ensures the product is not purchased twice.)
  </Step>
  <Step title="Complete the Draft Order:">
    - The bill will only contain the warranty for the associated product. Set the payment terms. Finalize and fulfill the order once the warranty payment is processed
  </Step>
</Steps>

### Sales Use Case 4: Selling a warranty plan for the customer who bought the product outside Shopify, and the product SKU is not listed in your Shopify Store

In cases where the product is not listed on your Shopify store, but a customer wants to buy a warranty for it:

<Steps>
  <Step title="Add Product SKU in your Shopify Store">
    - If the product SKU selected is not present in your Shopify store, then add it in your Shopify store.

    <Note>
      After adding SKU, please wait a few hours for auto-categorization to work. Only then will the policy options become visible. For immediate assistance, feel free to contact us at [support@surebright.com](mailto:support@surebright.com).
    </Note>
  </Step>
  <Step title="Create a Draft Order">
    - Navigate to Orders \> Drafts \> Create Order

    ![Draft Order1 Pn](/images/draft_order1.png)
  </Step>
  <Step title="Add the Product">
    - Search for the product for which the warranty is to be selected by clicking Browse (which is listed on your Shopify store) and add it to the draft order.

      ![Draft Order3 Pn](/images/draft_order3.png)
    - You can add it for record-keeping purposes, even if they already own the product.
  </Step>
  <Step title="Save the Draft Order">
    - Click Save on the top.

      ![Draft Order4 Pn](/images/draft_order4.png)
  </Step>
  <Step title="Add the Warranty Plan">
    - Click on the **More actions** dropdown and select **SureBright - Product Protection Draft Order**.

      ![More Actions Dropdown](/images/more-actions-surebright.png)
  </Step>
  <Step title="Select Product Purchase Date">
    - A popup will open prompting you to select the product purchase date. Click on **Select Product Purchase Date** to open the date picker.

    ![Product Purchase Date Prompt](/images/draft-order-popup-date-prompt.png)
  </Step>
  
  <Step title="Choose Purchase Date">
    - The date picker calendar will appear. Select the product purchase date.

      ![Date Picker Calendar](/images/draft-order-popup-calendar.png)
    - Once selected, the chosen date will be displayed. Click **Next** to proceed.

      ![Date Selected](/images/draft-order-popup-date-selected.png)
  </Step>
  
  <Step title="No Warranty Options Available">
    - The system will show "No Extended Warranty Options Available" in the warranty options dropdown.

    ![No Warranty Options Available](/images/draft-order-popup-no-options.png)
  </Step>
  
  <Step title="Select Categorization Option">
    - Click on the dropdown and select **"No, I will categorize the product"** to enable manual categorization.
    - A **Select Category** dropdown will appear below.

    ![Categorization Option Selected](/images/draft-order-popup-categorize.png)
  </Step>
  
  <Step title="Category Selection & Fetch Quotes">
    - Choose the appropriate category for your product from the available options.
    - After selecting the category, a **Fetch Quotes** button will appear. Click **Fetch Quotes** to retrieve available warranty policies for the selected category.

    ![Fetch Quotes Button](/images/draft-order-popup-fetch-quotes.png)
  </Step>
  
  <Step title="Select Policy">
    - Once quotes are fetched, a **Select Policy** dropdown will appear.

    ![Select Policy Dropdown](/images/draft-order-popup-select-policy.png)
    - Choose your preferred warranty policy from the list and click **Save** to complete the process.

    ![Policy Selected](/images/draft-order-popup-policy-selected.png)
  </Step>
  <Step title="Remove previously purchased product/line item">
    - The warranty will be added to the draft order alongside the product.

      ![Products with Warranty Added](/images/draft-order-products-with-warranty.png)
    - To remove the line item associated with the selected warranty, click on the ‘Delete’ icon next to the original product. (This step ensures the product is not purchased twice.)
  </Step>
  <Step title="Complete the Draft Order">
    - Set the payment terms or send an invoice. Finalize and fulfill the order once the warranty payment is processed.
  </Step>
</Steps>

<Card title="We've solutions tailored for all sales channels! If you're making sales through various platforms, give us a heads-up, and we'll assist in setting up a solution for each channel you use:" icon="sparkles" cta="We">
  1. **E-Commerce Platform Apps**

  - Shopify
  - WooCommerce
  - BigCommerce
  - Shift4Shop

  2. **Brick and Mortar Store and Over the Phone Sales**

  - Shopify POS
  - Lightspeed POS
  - Dedicated POS portal

  3. **Missed Point of Sales and Marketplace (e.g., Amazon) Sales**

  - Dedicated Online Portal
  - QR Code-based warranty cross-selling
  - 1-click checkout dynamic web links for retailer's post-purchase campaigns
  - Follow up email campaigns

  4. **Independent Websites**

  - Integration via two simple APIs
  - Website widget
</Card>

---

# JavaScript Injection

Source: https://docs.surebright.com/frontend-widget-integration/frontend-widget-kit/javascript-injection

## Selection-Change Callback

SureBright fires a callback whenever the customer's protection selection changes — when they select a plan, switch plans, or deselect. Use it to react to those changes in your own code; for example, to update the price shown on your page so it reflects the selected protection.

The callback lives on the same `window.SureBright` global you use for `initialize`.

### 1. Register a Handler

Pass your handler to `window.SureBright.onSelectionChange`. SureBright invokes it on every selection change and passes a `selectionChange` object that describes what changed. Read the price from that object to update your page — SureBright never modifies your page's price elements for you.

```javascript js
window.SureBright.onSelectionChange(function (selectionChange) {
    if (selectionChange.action === "selected" && selectionChange.pricing) {
        // Protection added — the total now includes the selected plan.
        console.log(selectionChange.pricing.totalPrice, selectionChange.pricing.currency);
    } else {
        // Protection removed — fall back to the base product price.
        console.log(selectionChange.pricing?.basePrice, selectionChange.pricing?.currency);
    }
});
```

`onSelectionChange` returns a function that unsubscribes your handler. Keep a reference to it only if you need to stop listening later.

### 2. Read the Selection Change

Each call receives a single `selectionChange` object describing what the customer did:

<ResponseField name="action" type="string" required>
  The kind of change. Either `selected` or `deselected`.
</ResponseField>

<ResponseField name="source" type="string" required>
  The widget surface the change came from: `pdp`, `quickview`, `cart`, `checkout`, `postPurchase`, `registration`, or `shippingInsurance`.
</ResponseField>

<ResponseField name="quote" type="object | null">
  The selected protection plan. Present on a `selected` action from a surface that exposes a full quote; `null` on `deselected` or where a quote isn't available.
  <Expandable title="properties">
    <ResponseField name="quoteId" type="string">
      Identifier of the quote the plan belongs to.
    </ResponseField>
    <ResponseField name="quoteItemId" type="string">
      Identifier of the selected plan within the quote.
    </ResponseField>
    <ResponseField name="coverageYears" type="number">
      Length of coverage, in years.
    </ResponseField>
    <ResponseField name="coverageType" type="string">
      One of `BREAKDOWN`, `ACCIDENTAL`, `ACCIDENTAL_BREAKDOWN`, or `SHIPPING`.
    </ResponseField>
    <ResponseField name="price" type="number">
      Price of the protection plan.
    </ResponseField>
    <ResponseField name="currency" type="string">
      ISO currency code for the plan price.
    </ResponseField>
    <ResponseField name="variantId" type="string">
      Identifier of the policy product's variant — the protection plan itself, not the covered product.
    </ResponseField>
    <ResponseField name="isDefault" type="boolean">
      Whether this plan is the quote's default selection.
    </ResponseField>
    <ResponseField name="ribbonEnabled" type="boolean">
      Whether the plan shows a highlight ribbon (e.g. a "Best Seller" badge).
    </ResponseField>
    <ResponseField name="ribbonText" type="string">
      Text shown on the highlight ribbon.
    </ResponseField>
    <ResponseField name="manufacturerWarrantyYears" type="number">
      Length of the manufacturer's warranty, in years. Optional.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="product" type="object | null">
  The product the customer was viewing. `null` when product data isn't available at selection time.
  <Expandable title="properties">
    <ResponseField name="productId" type="string">
      Identifier of the covered product.
    </ResponseField>
    <ResponseField name="selectedVariantId" type="string">
      Identifier of the selected variant.
    </ResponseField>
    <ResponseField name="productTitle" type="string">
      Display title of the product.
    </ResponseField>
    <ResponseField name="currency" type="string">
      ISO currency code for the product price.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pricing" type="object | null">
  Computed price breakdown for the selection. `null` when the base product price is unknown.
  <Expandable title="properties">
    <ResponseField name="basePrice" type="number">
      Price of the product without protection.
    </ResponseField>
    <ResponseField name="warrantyPrice" type="number">
      Price of the selected protection plan.
    </ResponseField>
    <ResponseField name="totalPrice" type="number">
      Sum of the base price and the protection price.
    </ResponseField>
    <ResponseField name="currency" type="string">
      ISO currency code for the amounts above.
    </ResponseField>
  </Expandable>
</ResponseField>

---

# Brand Managed Campaign

Source: https://docs.surebright.com/klaviyo-integration/brand-managed-campaign-guide

> Follow the steps below to configure a Klaviyo Flow that targets customers eligible for warranty upsell emails using your own email templates and messaging

<Warning>
  Access credentials must be shared and initial configuration steps completed as outlined in the [Klaviyo Integration Guide](/klaviyo-integration/integration-guide). Once setup is complete, you may proceed with this guide.
</Warning>

## Seamless Integration

To power these campaigns, SureBright automatically sends enriched customer and order data to your Klaviyo account once you have shared access as mentioned in <Tooltip tip="Link to Klaviyo Integration guide">integration guide</Tooltip>. This includes:

- Warranty plan details
- Order and product information
- Coverage summary
- Personalized post-purchase journey links

This enables you to craft dynamic, timely, and relevant messages to drive conversions and enhance customer trust.

## Flow Configuration

### Overview

To engage customers with eligible warranty options, you'll set up a custom flow in Klaviyo based on SureBright's eligibility events. This involves:

- Creating a new flow tailored for warranty outreach.
- Selecting the specific **SureBright: Eligible Order** event as the trigger.
- Filtering the trigger to target only eligible orders.
- Designing email steps that leverage SureBright Event data for personalized messaging.
- Inserting dynamic links and details from the events to enhance relevance.
- Test the functionality end-to-end by creating an order with SureBright Warranty Eligible product.

  <Note>
    All post-purchase emails must be approved by the SureBright team to ensure brand and compliance alignment.
  </Note>

### 1. Navigate to the Flow Builder

- Log in to your Klaviyo account.
- Go to **Flows** from the left-hand menu.
- Click [**Create Flow**](https://help.klaviyo.com/hc/en-us/articles/115002774932-Getting-Started-with-Flows).
- Choose **Build your own**, and name your flow something like `SureBright Post-Purchase Warranty`.

---

### 2. Set the Trigger

- For the **Trigger**, select **Metric**.
- In the dropdown, \*\*choose \*\*`SureBright: Eligible Order`.

<Warning>
  _Do not use the generic "Placed Order" trigger—this will not capture warranty-eligible events._
</Warning>

---

### 3. Add a Trigger Filter

- After selecting the trigger, click **"Trigger Filters"**.
- Add a condition:
  - **Field:** `is_eligible`
  - **Condition:** `equals`
  - **Value:** `true`

<Check>
  This ensures that only orders eligible for a post-purchase warranty offer are included.
</Check>

---

<img
  src="/SBTriggerExample.png"
  alt="SB Trigger Example Pn"
  title="SB Trigger Example Pn"
  className="mx-auto"
  style={{ width:"86%" }}
/>

**4. Build Your Flow**

- Add your **email step(s)** to the flow as desired.
- Use **SureBright event data** to personalize your messaging.

### 5. Personalize Using Event Attributes

In your email content, you can dynamically insert values from the SureBright event payload. One key attribute to include is:

- `{{ event.post_purchase_url }}` – This is a unique, customer-facing link where protection plans can be directly purchased.

You can also use additional attributes like:

- `{{ event.order_id }}`
- `{{ event.product_title }}`
- `{{ event.coverage_options }}`
- `{{ event.person.first_name }}`

### 6. Submit for Review

Before activating the flow, please submit a preview or test email to the SureBright team for compliance review and approval.

## Event Details

### **Event - SureBright: Eligible Order**

This event is triggered when a customer purchases a product that is eligible for a SureBright warranty. Here are the attributes available to you in Klaviyo about SureBright eligibility on your store's orders:

<ParamField path="order_id" type="string">
  Platform Order Id (Example: Shopify Order Id)
</ParamField>

<ParamField path="order_amount" type="string">
  Total Order Amount
</ParamField>

<ParamField path="currency_code" type="string">
  Currency code (Example: "USD")
</ParamField>

<ParamField path="order_created_at" type="datetime">
  Timestamp of order creation
</ParamField>

<ParamField path="merchant_logo_url" type="string">
  URL of the merchant's logo
</ParamField>

<ParamField path="surebright_logo_url" type="string">
  Url for SureBright's Logo
</ParamField>

<ParamField path="merchant_name" type="string">
  Name of the merchant
</ParamField>

<ParamField path="post_purchase_url" type="string">
  URL for post-purchase warranty actions
</ParamField>

<ParamField path="product_title" type="string">
  Title of the purchased product
</ParamField>

<ParamField path="is_eligible" type="boolean">
  Whether the order is warranty eligible
</ParamField>

<ParamField path="coverage_type" type="string">
  Indicates type of coverage
</ParamField>

<ParamField path="coverage_option_title" type="string">
  Coverage based dynamic title
</ParamField>

<ParamField path="coverage_options" type="array">
  Array of Coverage options provided with the warranty.

  <Expandable title="object">
    <ParamField path="icon_url" type="string">
      Icon for the particular coverage text

      <ParamField path="text" type="string">
        Coverage text
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

**Example Payload:**

```json SureBright: Eligible Order [expandable]
    {
      "order_id": "1234567890",
      "order_amount": "199.99",
      "currency": "USD",
      "created_at": "2025-04-10T14:57:11.451046",
      "merchant_logo_url": "https://yourstore.com/logo.png",
      "merchant_name": "Your Store Name",
      "post_purchase_url": "https://yourstore.com/?quoteLeadId=1234567890",
      "product_title": "Sample Product Name",
      "is_eligible": true,
      "coverage_type": "AD",
      "coverage_option_title": "Your Accidental Damage Protection Plan ensures:",
      "coverage_options": [
        {
          "icon_url": "https://cdn.example.com/icons/damage.png",
          "text": "Protection against unforeseen damage such as drops, spills, and falls."
        },
        {
          "icon_url": "https://cdn.example.com/icons/breakdown.png",
          "text": "Coverage for mechanical and electrical breakdowns, including power surges."
        },
        {
          "icon_url": "https://cdn.example.com/icons/repair.png",
          "text": "Full coverage for parts, labor, and repairs."
        },
        {
          "icon_url": "https://cdn.example.com/icons/wear.png",
          "text": "Protection against wear and tear impacting functionality."
        },
        {
          "icon_url": "https://cdn.example.com/icons/replace.png",
          "text": "If it can't be repaired, it will be replaced."
        }
      ]
  }
```


### **Event - SureBright: Policy Purchased**

This event is triggered when a customer successfully purchases a warranty for their product. Most merchants use this event to stop further warranty marketing once coverage has been bought.

Here are the attributes available in Klaviyo when a policy is purchased:

<ParamField path="order_id" type="string">
  Platform Order Id (Example: Shopify Order Id)
</ParamField>

<ParamField path="contract_id" type="string">
  Unique identifier for the SureBright warranty contract
</ParamField>

<ParamField path="product_title" type="string">
  Title of the product covered by the warranty
</ParamField>

<ParamField path="policy_tenure" type="string">
  Duration of the warranty coverage (e.g., 1 year, 2 years)
</ParamField>

<ParamField path="policy_price" type="string">
  Price paid by the customer for the warranty
</ParamField>

<ParamField path="warranty_purchase_date" type="datetime">
  Timestamp when the warranty was purchased
</ParamField>

<ParamField path="coverage_type" type="string">
  Type of warranty coverage (e.g., AD for Accidental Damage, B for Breakdown)
</ParamField>

**Example Payload:**

```json SureBright: Policy Purchased [expandable]
    {
      "order_id": "1234567890",
      "contract_id": "4efcf6ce8f7b465da14fe1d65c64dsd",
      "product_title": "Sample Product Title",
      "policy_tenure": "1 year",
      "policy_price": "29.99",
      "warranty_purchase_date": "2025-04-10T15:00:41.301007",
      "coverage_type": "AD"
}
```

## Implementation Use Cases

### SureBright: Eligible Order

Use this event to drive engagement and conversion among customers who didn't buy a warranty at checkout:

- **Timed Drip Flows:** Create flows that trigger based on time elapsed since purchase, nudging non-buyers at key intervals.
- **Follow-up Campaigns:** Send reminder emails prompting customers to purchase protection for eligible products.
- **Direct to Purchase:** Use the `post_purchase_url` to guide customers to a pre-filled, personalized warranty offer page.

### SureBright: Policy Purchased

Leverage this event to build customer trust and extend your brand experience post-purchase:

- **Acknowledge and Appreciate Your Customers:** Brand's customized thank-you message.
- **Stop further communications:** Scheduled communications can be terminated based on this event.

## Flow Example

![FlowChart Example](/images/klaviyo-flowchart.png)

## Best Practices

Ensure your campaign delivers maximum value and conversion by following these recommendations:

- **Dynamic Personalization:** Use attributes like `product_title`, `coverage_type`, and `policy_price` to tailor messaging.
- **Contextual Journeys:** Differentiate your flows based on warranty type—e.g., breakdown vs. accidental damage—to increase relevance.

### FAQs

<Accordion title="Can I send post-purchase emails to all of my previous customers?" iconType="duotone">
  Event Data from SureBright begins flowing into Klaviyo only after the integration is enabled. This means that any historical SureBright Data—captured prior to activation—will not be available within Klaviyo.
</Accordion>

<Accordion title="Why can't I see the SureBright metric or data in Klaviyo to be used in creating a flow?" iconType="duotone">
  Once SureBright has completed the configuration on your account, the relevant events (e.g., SureBright: Eligible Order, SureBright: Policy Purchased) and associated data will appear in Klaviyo. If you've already shared access but still don't see the events, please wait for confirmation from the SureBright team or contact support for an update.
</Accordion>

## [**​**](https://surebrighttechnologiesinc.mintlify.app/klaviyo-integration/klaviyoIntegrationGuide#implementation-use-cases)Support

Need help with setup or strategy? Reach out to your **SureBright Representative**,  email us at [support@surebright.com](mailto:support@surebright.com), or your **Klaviyo account manager** for hands-on support.

---

# Integration Guide

Source: https://docs.surebright.com/klaviyo-integration/integration-guide

> SureBright enables you to engage customers who did not purchase a warranty at the time of checkout by sending personalized post-purchase emails across multiple channels.

### Program Options

We offer two flexible modes to support your campaign:

1. **White-Glove Campaigns (Recommended)**\
   Our team will handle everything—from setup to execution—for all eligible customers. This is the most hands-off option and ensures high-performing campaigns aligned with best practices.
2. [**Brand-Managed Campaigns**](/klaviyo-integration/brand-managed-campaign-guide)\
   For brands that prefer to control their customer experience, we enable you to use your own email templates and messaging. SureBright provides the necessary data; you bring the creative.

## Steps to Enable Access

To enable the SureBright integration, we require your **Klaviyo Public and Private API Keys**. Follow [this quick guide](https://app.storylane.io/share/gmb05pqr5zbj) to generate and share the keys.

<Note>
  For Brand-Managed Campaigns, refer to the [Brand-Managed Campaign Guide](/klaviyo-integration/brand-managed-campaign-guide) for step-by-step instructions on flow creation, event parameters, and best practices.
</Note>

## Support

Need help with setup or strategy? Contact your SureBright representative, email us at [support@surebright.com](mailto:support@surebright.com), or reach out to your Klaviyo account manager for hands-on support.

---

# Disable/Enable Module

Source: https://docs.surebright.com/magento/disable-guide

> Guide to disable/enable SureBright module.

## **Disable SureBright Module**


### 1. Turn off SureBright Module

Run this command to disable SureBright module.

> php bin/magento module:disable Surebright_Integration --clear-static-content

### 2. Rebuild Code

Run following command to rebuild code

> bin/magento setup:di:compile

### 3. Clear Cache

Run this to clean up the cache:

> bin/magento cache:clean

## ✅ **All Set\! SureBright Integration Disabled**

🎉 You’ve successfully **disabled** the SureBright Integration on your Magento store\!

## **Enable SureBright Module**

### 1. Turn on SureBright Module

Run this to enable the module:

> php bin/magento module:enable Surebright_Integration

### 2. Rebuild Code

Run following command to rebuild code

> bin/magento setup:di:compile

### 3. Clear Cache

Run this to clean up the cache:

> bin/magento cache:clean

## ✅ **All Set\! SureBright Integration Enabled**

🎉 You’ve successfully **enabled** the SureBright Integration on your Magento store\!

---

# Installation Guide

Source: https://docs.surebright.com/magento/install-guide

> Installation guide for SureBright Magento module to enable product and shipping protection on you website. 

## Installation Steps

### A. Module Installation Steps

<Accordion title="Access the Server" iconType="duotone">
  Use the terminal (putty/ any ssh client) on your computer to connect to your Magento server (this is called SSH)

  > ssh [username@your.server.ip](mailto:username@your.server.ip)

  - Replace **username** with your actual username
  - Replace \*\*your.server.ip \*\*with your server IP address or website domain name. e.g. (127.0.0.1 / [mystore.com](http://mystore.com))
  - Windows users please download putty, you can visit this link to download putty https://www.wikihow.com/Use-Putty-in-Windows
</Accordion>

<Accordion title=" Go to the Magento folder" iconType="duotone">
  Once you're connected, go to the main folder where all your store’s files are kept.

  **Usually, it's /var/www/html**

  > cd /path/to/magento/root
</Accordion>

<Accordion title=" Add the module" iconType="duotone">
  Run this command to install the integration.

  > composer require surebright/integration
</Accordion>

<Accordion title="Update and Prepare Magento" iconType="duotone">
  > bin/magento setup:upgrade
  >
  > bin/magento setup:di:compile
</Accordion>

<Accordion title="Setup your store visuals" iconType="duotone">
  Deploy static files (like images and styles) by running

  > bin/magento setup:static-content:deploy -f -j5
</Accordion>

<Accordion title="Clear the cache" iconType="sharp-solid">
  Refresh Magento so everything works properly by running:

  > bin/magento cache:clean
</Accordion>

After completing these steps, the integration should be successfully installed.

**You can follow the steps below to activate your SureBright Product Protection app**

### B. Activation Steps

<AccordionGroup>
  <Accordion title=" Login to your Magento Admin Panel">
    ![Screenshot2025 05 30at16 06 45sure Bright Magento App Installation Guide Pn](/images/Screenshot2025-05-30at16-06-45SureBrightMagentoAppInstallationGuide.png)
  </Accordion>
</AccordionGroup>

<Accordion title=" Navigate to Integrations" iconType="duotone">
  Click on the Integrations option within the Extensions heading of your System menu item

  ![Screenshot2025 05 30at16 07 21sure Bright Magento App Installation Guide Pn](/images/Screenshot2025-05-30at16-07-21SureBrightMagentoAppInstallationGuide.png)
</Accordion>

<Accordion title=" Authorize SureBright" iconType="duotone">
  Look for SureBright Product Protection line item and click on Activate / Reauthorize option

  ![Screenshot2025 05 30at16 07 29sure Bright Magento App Installation Guide Pn](/images/Screenshot2025-05-30at16-07-29SureBrightMagentoAppInstallationGuide.png)

  Please authorize/reauthorize the SureBright app that would help it access details like catalogue and order information required for running the warranty program

  ![Screenshot2025 05 30at16 07 38sure Bright Magento App Installation Guide Pn](/images/Screenshot2025-05-30at16-07-38SureBrightMagentoAppInstallationGuide.png)
</Accordion>

### C. Login to SureBright

You can now login to SureBright Merchant portal using the credentials shared. This would give you complete visibility into the warranty program. If you have not received the credentials, please reach out to your Account Manager.

![Screenshot2025 05 30at16 07 57sure Bright Magento App Installation Guide Pn](/images/Screenshot2025-05-30at16-07-57SureBrightMagentoAppInstallationGuide.png)

<AccordionGroup>
  <Accordion title="Add Payment Method" iconType="duotone">
    Click on Add Payment Method to provide payment details. This allows SureBright to charge for the cost of the warranty plans sold to customers, through your store. We charge at a weekly/monthly frequence as per your preference.

    ![Screenshot2025 05 30at16 08 07sure Bright Magento App Installation Guide Pn](/images/Screenshot2025-05-30at16-08-07SureBrightMagentoAppInstallationGuide.png)
  </Accordion>
</AccordionGroup>

## ✅ **All Set\! SureBright Integration Completed**

🎉 You’ve successfully **installed** the SureBright Integration on your Magento store\!

---

# Re-Install Guide

Source: https://docs.surebright.com/magento/reinstall-guide

> Re-install guide to disable and re-enable SureBright module for Magento.

## Re-Installation Steps

### A. Uninstall SureBright module

<Accordion title=" Turn Off SureBright Integration">
  Run this command to disable the module and remove old files:

  > php bin/magento module:disable Surebright_Integration --clear-static-content
</Accordion>

<Accordion title=" Rebuild Code" iconType="duotone">
  Run this to rebuild the necessary files:

  > bin/magento setup:di:compile
</Accordion>

<Accordion title=" Remove the Integration" iconType="duotone">
  Run this to remove the SureBright integration:

  > composer remove surebright/integration
</Accordion>

<Accordion title="Update Magento" iconType="duotone">
  Run this to apply the changes

  > bin/magento setup:upgrade
</Accordion>

<Accordion title=" Clear Cache" iconType="duotone">
  Run this to clean up the cache and setup your store visuals:

  > bin/magento setup:static-content:deploy -f -j5

  > bin/magento cache:clean
</Accordion>

### B. Re-Install Steps

<Accordion title="Re-Install SureBright">
  Run this to add SureBright again:

  > composer require surebright/integration:v1.3.11
</Accordion>

<Accordion title=" Turn SureBright Back On">
  Run this to enable the module:

  > php bin/magento module:enable Surebright_Integration
</Accordion>

<Accordion title=" Update Magento and Rebuild Code" iconType="duotone">
  Run this to finalize the reinstall:

  > bin/magento setup:upgrade

  > bin/magento setup:di:compile
</Accordion>

### C. Clear Cache

Run these commands to apply schema updates, recompile dependency injection, and flush the cache:

```bash
bin/magento setup:static-content:deploy -f -j5

php bin/magento cache:flush
```

## ✅ **All Set! SureBright Integration Completed**

🎉 You’ve successfully **reinstalled**  the SureBright Integration on your Magento store!

---

# Business Manager Setup

Source: https://docs.surebright.com/salesforce-commerce-cloud/BusinessManagerSetup

> Step-by-step guide for setting up SureBright integration in SFCC Business Manager including cartridge upload, metadata import, and catalog configuration.

# Business Manager Setup

The integration follows SFRA’s extensibility and modularity principles and is built on top of app_storefront_base and related modules. It must be implemented in an environment that adheres to SFRA guidelines.

<Info>
  **Prerequisites**: Ensure you have administrative access to your SFCC Business Manager instance before proceeding with these steps.
</Info>

---

## Upload Cartridge & Include in Cartridge Path

1. Upload the **surebright_sfra** cartridge to your SFRA sandbox environment.
2. Go to Business Manager **→** Administration **→** Site **→** Manage Sites. Select your desired site and go to Settings.
3. At the beginning of the Cartridge Path, add `surebright_sfra:` to include the cartridge in your current site's configuration.

![SFRA Cartridge Configuration](/images/sfra_cartridge.png)

<Warning>
  **Important**: Always test in your sandbox environment first before deploying to production. Ensure the cartridge is compatible with your SFCC version.
</Warning>

---

## Import Metadata

1. Go to Business Manager **→** Administration **→** Site Development **→** Import & Export
2. Upload the following files from the SureBright integration package:
   - **system-objecttype-extensions.xml**
   - **custom-objecttype-definitions.xml**
3. Go to Business Manager **→** Administration **→** Site Development **→** Import & Export **→** Metadata **→** Import
4. You should see both files as available for import. Proceed to importing both files.
![SFRA Cartridge Configuration](/images/sfra_systemobject.png)

<Note>
  These files contain custom object definitions and system extensions required for the SureBright integration to function properly.
</Note>

---

## Import Custom Jobs

1. Go to Business Manager **→** Administration **→** Operations **→** Import & Export
2. Upload the following file: **jobs.xml**
3. Go to Business Manager **→** Administration **→** Operations **→** Import & Export **→** Jobs **→** Import
4. You should see the jobs file as available for import. Proceed to importing it.

<Info>
  The jobs file contains automated job definitions for product synchronization, order processing, and contract creation. These will be configured in detail in the [Jobs Guide](./Jobs).
</Info>


## Import SureBright Product Catalog

1. Select your site integrating with SureBright
2. Go to Business Manager **→** Merchant Tools **→** Products and Catalogs **→** Inventory List Import
3. Upload the following file: **catalog.xml**
4. This will import variant products according to unique warranty tenure and price.

<Info>
  We recommend keeping the surebright products as a separate master catalog for better visibility and management.
</Info>

---

## Verify Installation

After completing all import steps, verify the installation by checking:

### 1. Cartridge Status
- Go to `Administration → Sites → [Your Site] → Cartridges`
- Verify `surebright_sfra` cartridge is listed and active
- Check for any compatibility warnings or conflicts


### 2. Job Definitions
- Go to `Administration → Jobs → Job Definitions`
- Verify SureBright jobs are imported:
  - `SureBrightProductsExport`
  - `SureBrightOrdersCreation`


### 3. Product Catalog
- Go to `Merchant Tools → Products → Product Catalog`
- Verify warranty products are imported with correct SKUs
- Check that products are assigned to your site's catalog

---

## Next Steps

Once you have completed the Business Manager setup:

1. **Configure User Access**: Follow the [Configuration Guide](./Configuration) to set up API clients and user accounts
2. **Set Up Data Sync**: Use the [Jobs Guide](./Jobs) to configure automated synchronization jobs
3. **Test Integration**: Run comprehensive tests using the [Testing Guide](./Testing)

---

## Troubleshooting

### Common Issues

**Cartridge Upload Fails**
- Verify you have administrative permissions
- Check cartridge compatibility with your SFCC version
- Ensure sufficient disk space in your sandbox

**Metadata Import Errors**
- Verify XML file format and structure
- Check for existing conflicting custom objects
- Review import logs for specific error messages

**Product Catalog Import Issues**
- Verify inventory list and pricebook assignments
- Check product SKU naming conventions
- Ensure site configuration is complete

### Getting Help

If you encounter issues during setup:

1. Check the [FAQs](./FAQs) for detailed answered questions
2. Contact your SureBright representative for immediate assistance
3. Email [support@surebright.com](mailto:support@surebright.com) for technical support

---

## ✅ Setup Complete

Great job! You have successfully completed the Business Manager setup phase. The SureBright integration foundation is now in place and ready for configuration.

**What's Next**: Proceed to the [Jobs Guide](./Jobs) to configure automated data synchronization jobs.

---

# Configuration

Source: https://docs.surebright.com/salesforce-commerce-cloud/Configuration

> User and API configuration guide for SureBright SFCC integration including user account creation, API client setup, and credential management.

# Configuration

This phase involves setting up proper user access and API credentials within your SFCC Account Manager to enable the SureBright integration.

<Info>
  **Prerequisites**: Ensure you have completed the [Business Manager Setup](./BusinessManagerSetup) before proceeding with configuration.
</Info>

---

## Integration Approaches

Choose the configuration approach that best fits your team's technical capabilities:

<CardGroup cols={2}>
  <Card title="Full Business Manager Access" icon="shield-check">
    **Recommended for most merchants**
    
    SureBright handles all technical configurations while you focus on business requirements.
    
    *Best for: Merchants with limited technical resources*
  </Card>
  <Card title="API-Only Access" icon="code">
    **For technical teams**
    
    Your development team handles SFCC configuration while SureBright provides integration support.
    
    *Best for: Merchants with dedicated SFCC development teams*
  </Card>
</CardGroup>

---

## Full Business Manager Access

This approach provides SureBright with comprehensive access to your SFCC environment, enabling our team to handle all technical configurations.

<Warning>
  This approach requires granting SureBright administrative access to your SFCC Business Manager. All activities will be logged and auditable.
</Warning>

### Create SureBright User Account

**Purpose**: Create a dedicated SFCC user account for SureBright with appropriate permissions for integration management.

**Step-by-Step Instructions**:

1. **Access Account Manager**
   - Log into your SFCC Account Manager (separate from Business Manager)
   - Navigate to `Administration → Users and Roles`
   - Click "Add User" button to create a new user account
![SFRA Add User](/images/sfra_adduser.png)
   

2. **Configure User Details**
   - **Username**: `surebright-integration` (must be unique)
   - **Email**: Use the email address provided by your SureBright representative
   - **First Name**: `SureBright`
   - **Last Name**: `Integration`
   - **Password**: Create a strong password (you'll share this securely with SureBright)
   - **Status**: Set to "Active" to enable immediate access

3. **Assign Required Roles**
   In the "Roles" section, select these specific roles:
   - **Administrator**: Provides full access to Business Manager configuration, cartridge management, and system settings
   - **API User**: Enables programmatic access to SFCC APIs for data synchronization
   - **Job Manager**: Allows import/export operations and job management for data sync processes

4. **Verify and Save**
   - Review all user details and role assignments
   - Click "Save" to create the user account
   - Note the username and password for secure sharing with SureBright

<Warning>
  **Security Note**: This user account will have administrative access to your SFCC instance. Only share credentials through secure, encrypted channels and verify the recipient's identity before sharing.
</Warning>

### Configure API Client

**Purpose**: Create an API client that enables programmatic access to your SFCC instance for data synchronization and integration management.

**Step-by-Step Instructions**:

1. **Access API Settings in Account Manager**
   - In your Account Manager, navigate to `Administration → API Settings`
   - Click "Create API Client" button
   - You'll need Account Manager administrative access to perform this step

2. **Configure Client Settings**
   Fill in the following information:
   - **Client Name**: `SureBright Integration`
   - **Client Type**: Select "Public" (this allows the client to be used by external applications)
   - **Description**: `API access for SureBright Product Protection integration`
   - **Redirect URI**: Leave blank (not required for this integration type)

![SFRA API Client](/images/sfra_apiclient.png)

3. **Assign Required OAuth Scopes**
   In the "Scopes" section, check the following boxes to grant necessary permissions:
   - `sfcc.catalogs.rw` - Read/Write access to product catalogs (allows product data sync)
   - `sfcc.products.rw` - Read/Write access to product data (enables product management)
   - `sfcc.orders.rw` - Read/Write access to order information (for warranty order processing)
   - `sfcc.custom-objects.rw` - Read/Write access to custom objects (for warranty data structures)
   - `sfcc.jobs.rw` - Read/Write access to job management (for data synchronization jobs)

4. **Save and Retrieve Credentials**
   - Click "Save" to create the API client
   - **Important**: Copy and securely store these values immediately:
     - **Client ID**: Unique identifier for API authentication (you'll need this)
     - **Client Secret**: Secret key for API authentication (you'll need this)
     - **Organization ID**: Found in `Administration → Organization → Organization Settings`
     - **Realm**: Part of your SFCC URL (e.g., if URL is `https://your-realm.demandware.net`, realm is `your-realm`)
     - **Short Code**: Your site identifier (found in `Administration → Sites → [Your Site] → Settings`)

<Info>
  **Finding Your Organization Details**: If you're unsure about Organization ID, Realm, or Short Code, refer to the FAQ section in the [FAQs Page](./FAQs) for detailed instructions.
</Info>

### Share Credentials Securely

**Purpose**: Provide SureBright with the necessary credentials to establish secure API connectivity with your SFCC instance.

**Required Information**:
```
Client ID: [Your Client ID]
Client Secret: [Your Client Secret]
Organization ID: [Your Organization ID]
Realm: [Your Realm]
Short Code: [Your Short Code]
```

**Security Requirements**:
- Use encrypted communication channels (encrypted email or secure file sharing)
- Never share credentials via unsecured email or chat platforms
- Consider using a password manager or secure note-sharing service
- Verify the recipient's identity before sharing sensitive information

<Warning>
  These credentials provide access to your SFCC instance. Treat them as sensitive business information and ensure they are shared only with authorized SureBright personnel.
</Warning>

---

## API-Only Access

This approach is designed for merchants with dedicated SFCC development teams who prefer to maintain full control over their SFCC environment.

<Info>
  This approach requires your development team to have experience with SFCC cartridge deployment, job management, and custom object configuration.
</Info>

### Create SFCC API Client

**Purpose**: Create an API client that enables SureBright to provide integration support and data synchronization guidance.

**Development Team Tasks**:

1. **Access Account Manager**
   - Navigate to `Account Manager → Administration → API Settings`
   - Click "Create API Client"

2. **Configure API Client**
   ```
   Client Name: SureBright Integration
   Client Type: Public
   Description: API access for SureBright Product Protection integration support
   ```

3. **Assign Required OAuth Scopes**
   ```
   sfcc.catalogs.rw     - Read/Write access to product catalogs
   sfcc.products.rw     - Read/Write access to product data
   sfcc.orders.rw       - Read/Write access to order information
   sfcc.custom-objects.rw - Read/Write access to custom objects
   sfcc.jobs.rw         - Read/Write access to job management
   ```

4. **Document Credentials**
   - Securely store all generated credentials
   - Prepare for secure sharing with SureBright team

### Share Integration Information

**Purpose**: Provide SureBright with necessary credentials and site configuration details for integration support.

**Required Information**:
```
API Credentials:
- Client ID: [Your Client ID]
- Client Secret: [Your Client Secret]
- Organization ID: [Your Organization ID]
- Realm: [Your Realm]
- Short Code: [Your Short Code]

Site Configuration:
- Inventory List ID: [Your Inventory List ID]
- Pricebook ID: [Your Pricebook ID]
- Site ID: [Your Site ID]
```

**Prerequisites**:
- Ensure inventory list and pricebook are properly assigned to your site
- Verify all site configurations are complete and active
- Confirm API client has been tested and is functional

<Warning>
  Share this information only through secure, encrypted channels. Verify the recipient's identity before sharing sensitive credentials.
</Warning>

---

## Integration File Distribution

For API-Only Access, SureBright will provide your development team with all necessary integration files and detailed technical documentation for SFCC deployment.

### Integration Package Contents

**Package Contents**:

1. **SureBright Integration Cartridge**
   - Complete SFCC cartridge with warranty functionality
   - Compatible with your SFCC version
   - Includes all necessary controllers, models, and templates

2. **Data Import XML Files**
   - **Job Import XMLs**: Product sync and order sync job configurations
   - **Custom Fields XML**: Line item and product attribute definitions
   - **Pricing XML**: Warranty plan pricing configurations
   - **Inventory XML**: Warranty product availability settings

3. **Technical Documentation**
   - Detailed deployment instructions
   - Configuration parameters and settings
   - API integration specifications


---

## Next Steps

Once you have completed the configuration:

1. **Set Up Data Sync**: Use the [Jobs Guide](./Jobs) to configure automated synchronization jobs
2. **Test Integration**: Run comprehensive tests using the [Testing Guide](./Testing)
3. **Go Live**: Deploy to production and monitor.

---

### Getting Help

If you encounter issues during configuration:

1. Check the [FAQs Page](./FAQs) for detailed solutions
2. Contact your SureBright representative for immediate assistance
3. Email [support@surebright.com](mailto:support@surebright.com) for technical support

---

## ✅ Configuration Complete

Great job! You have successfully completed the configuration phase. The SureBright integration is now ready for data synchronization setup.

**What's Next**: Proceed to the [Business Manager Setup](./BusinessManagerSetup) to set up Business Manager.

---

# FAQs

Source: https://docs.surebright.com/salesforce-commerce-cloud/FAQs

> Frequently asked questions about SureBright SFCC integration including setup, configuration, and common issues.

---

## General Integration Questions

<Accordion title="What SFCC permissions does SureBright need?">
SureBright requires specific OAuth scopes for full integration functionality:

**Required Scopes**:
- `sfcc.catalogs.rw` - Read/Write access to product catalogs
- `sfcc.products.rw` - Read/Write access to product data
- `sfcc.orders.rw` - Read/Write access to order information
- `sfcc.custom-objects.rw` - Read/Write access to custom objects
- `sfcc.jobs.rw` - Read/Write access to job management

**User Roles Required** (for Full Access approach):
- Administrator (for cartridge deployment and configuration)
- API User (for programmatic access)
- Job Manager (for import/export operations)
</Accordion>

<Accordion title="Will the SureBright cartridge conflict with my existing cartridges?">
The SureBright cartridge is designed to be compatible with most SFCC setups, but we take precautions:

**Compatibility Measures**:
- Cartridge is tested with common SFCC cartridges
- Proper cartridge priority configuration prevents conflicts
- Namespaced code prevents function and variable conflicts
- Modular design allows selective feature activation

**If Conflicts Occur**:
- SureBright will adjust cartridge priority settings
- We can modify specific functions if needed
- Alternative deployment methods are available
- Your existing functionality remains unaffected
</Accordion>
<Accordion title="How do I find my Organization ID, Realm, and Short Code in SFCC?">
These values are located in different parts of your SFCC Business Manager:

**Organization ID**:
- Go to `Administration → Organization → Organization Settings`
- Look for "Organization ID" field

**Realm**:
- Found in your SFCC instance URL: `https://[realm].demandware.net`
- Also visible in `Administration → Organization → Organization Settings`

**Short Code**:
- Go to `Administration → Sites → [Your Site] → Settings`
- Look for "Site ID" or "Short Code" field
- Usually matches your site's identifier
</Accordion>
---

## Technical Setup Questions



<Accordion title="What if I don't have access to create API clients in Account Manager?">
You'll need to request access from your SFCC administrator or use the Full Business Manager Access approach:

**Required Permissions**:
- Account Manager access with API client creation rights
- User management permissions for creating SureBright user account
- Business Manager administrative access

**Alternative Solutions**:
- Request temporary elevated permissions for integration setup
- Use the Full Business Manager Access approach instead
- Have your SFCC administrator create the API client and share credentials
- Contact Salesforce support for permission escalation if needed
</Accordion>

<Accordion title="How do I verify my inventory list and pricebook are properly assigned?">
Follow these steps in your SFCC Business Manager:

**Check Inventory List Assignment**:
1. Go to `Merchant Tools → Inventory → Inventory Lists`
2. Select your inventory list
3. Check "Sites" tab to ensure your site is assigned
4. Note the Inventory List ID for sharing with SureBright

**Check Pricebook Assignment**:
1. Go to `Merchant Tools → Pricing → Price Books`
2. Select your pricebook
3. Check "Sites" tab to ensure your site is assigned
4. Note the Pricebook ID for sharing with SureBright

**Verify Site Configuration**:
1. Go to `Administration → Sites → [Your Site] → Settings`
2. Confirm inventory list and pricebook are properly configured
3. Check that the site is active and properly set up
</Accordion>

<Accordion title="What SFCC version is required for the integration?">
The SureBright integration is compatible with SFCC versions that support SFRA (Storefront Reference Architecture). 

**Minimum Requirements**:
- SFCC version 20.1 or later
- SFRA-based storefront
- Business Manager administrative access

**Recommended**:
- Latest SFCC version for optimal performance
- Sandbox environment for testing before production deployment
</Accordion>


<Accordion title="How are Surebright products created in my SFCC catalog?">
SureBright creates warranty products using SFCC's standard product creation process:

**Product Creation Process**:
- Surebright products are created as regular SFCC products
- They're assigned to a dedicated warranty category
- Custom attributes define warranty plan types and coverage
- Products are linked to your main products via relationships

**Product Configuration**:
- SKUs follow a consistent naming convention
- Pricing is dynamically calculated based on product value
- Inventory is managed through your existing inventory system
- Products are automatically assigned to your site's catalog

**Merchant Control**:
- You can modify warranty product descriptions
- Product availability can be controlled via inventory lists
- Warranty products integrate with your existing product management workflow
</Accordion>


<Accordion title="How often does product data sync between SFCC and SureBright?">
Product data synchronization follows this schedule:

**Product Export Job**:
- Runs daily (recommended)
- Can be configured for different frequencies
- Exports all merchandisable products
- Updates product information in SureBright system

**Order Synchronization**:
- Real-time processing (every 15-30 minutes)
- Immediate order data transfer
- Contract creation processing
- Status updates and tracking

**Manual Sync**:
- Available for immediate updates
- Useful for testing and troubleshooting
- Can be triggered from Business Manager
</Accordion>



---

## Storefront Display Questions

<Accordion title="What should I do if warranty products don't appear on my storefront?">
This is usually a cartridge priority or configuration issue. Follow these steps:

**Immediate Checks**:
1. **Verify Cartridge Priority**: Ensure SureBright cartridge has proper priority in Business Manager
2. **Check Site Assignment**: Confirm warranty products are assigned to your site
3. **Review Product Status**: Ensure warranty products are active and available
4. **Check Inventory**: Verify inventory levels are sufficient

**Business Manager Steps**:
1. Go to `Administration → Sites → [Your Site] → Cartridges`
2. Check that SureBright cartridge is listed and active
3. Verify cartridge priority is set correctly
4. Check for any error messages or conflicts

**If Issues Persist**:
- Contact SureBright support with specific error details
- Provide screenshots of Business Manager configuration
- Share any error logs from your SFCC instance
- Test in a different browser or incognito mode
</Accordion>



## Still Have Questions?

If you don't see your question answered here, we're here to help:

<CardGroup cols={2}>
  <Card title="Contact Support" icon="envelope">
    **Email Support Team**
    
    [support@surebright.com](mailto:support@surebright.com)
    
    *For detailed technical questions and assistance*
  </Card>
  <Card title="Contact Your Representative" icon="headset">
    **Direct Support**
    
    Contact your assigned SureBright representative for immediate assistance.
    
    *For urgent issues and business questions*
  </Card>
</CardGroup>

---

# SFCC Integration Guide

Source: https://docs.surebright.com/salesforce-commerce-cloud/IntegrationGuide

> Complete guide to onboard SureBright Product Protection within Salesforce Commerce Cloud (SFCC) SFRA store. This guide covers both scenarios: when SureBright gets Business Manager access and when only API access is provided.

The SureBright Product Protection integration with Salesforce Commerce Cloud (SFCC) follows a structured, phase-based approach designed to ensure successful deployment and configuration. This guide provides comprehensive instructions for merchants to integrate warranty and protection plans directly within their SFCC storefront.

<Info>
  **Integration Timeline**: The complete setup typically takes 2-3 business days, depending on your SFCC environment complexity and chosen integration approach.
</Info>

## Integration Overview

SureBright Product Protection seamlessly integrates with Salesforce Commerce Cloud (SFCC) to enable merchants to offer comprehensive product protection plans directly within their e-commerce storefront. This integration leverages SFCC's robust API framework and cartridge system to provide a native shopping experience for warranty products.

## Choose Your Integration Path

Based on your team's technical capabilities and security requirements, select the most appropriate integration approach:

<CardGroup cols={2}>
  <Card title="Full Business Manager Access" icon="shield-check">
    **Recommended for most merchants**
    
    SureBright handles the complete SFCC configuration including cartridge deployment, job setup, and custom object creation.
    
    *Best for: Merchants with limited technical resources*
  </Card>
  <Card title="API-Only Access" icon="code">
    **For technical teams**
    
    Your development team handles SFCC configuration while SureBright provides integration files and technical guidance.
    
    *Best for: Merchants with dedicated SFCC development teams*
  </Card>
</CardGroup>

## Prerequisites

Before beginning the integration, ensure you have access to:

<Steps>
  <Step title="Account Manager Permissions">
    Ability to create users and API clients in Account Manager
  </Step>
  <Step title="SFCC Business Manager Access">
    Administrative access to your SFCC Business Manager instance
  </Step>
  <Step title="Product Catalog Data">
    Your complete product catalog with SKUs, pricing, and categories
  </Step>
  <Step title="Site Configuration Details">
    Your site's inventory list ID and pricebook assignments
  </Step>
</Steps>


## Quick Start Checklist

<Steps>
  <Step title="Configure User Access">
    Use the [Configuration Guide](./Configuration) to set up API clients and user accounts.
  </Step>
  <Step title="Complete Business Manager Setup">
    Follow the [Business Manager Setup Guide](./BusinessManagerSetup) to upload cartridges and import metadata.
  </Step>
  <Step title="Set Up Data Sync Jobs">
    Configure automated jobs using the [Jobs Guide](./Jobs) for product and order synchronization.
  </Step>
  <Step title="Test Integration">
    Run comprehensive tests using the [Testing Guide](./Testing) to validate all functionality.
  </Step>
  <Step title="Go Live">
    Deploy to production and refer to the [FAQs](./FAQs) for common questions and answers.
  </Step>
</Steps>

---

## What's Next

Great job! Now that you have uploaded the necessary files from the cartridge, you will begin configuring the various settings for your SureBright offerings. First, you will tackle the SureBright products you just uploaded, and then work with the various different Custom Preferences available within the integration.

**Next Steps:**
1. Configure your [User and API Settings](./Configuration)
2. Complete the [Business Manager Setup](./BusinessManagerSetup)
3. Set up [Data Synchronization Jobs](./Jobs)
4. Run [Integration Tests](./Testing)

---

## Support and Resources

### Getting Technical Support

If you encounter any issues during the integration process, we provide comprehensive support through multiple channels:

<CardGroup cols={2}>
  <Card title="Immediate Support" icon="headset">
    **Contact Your SureBright Representative**
    
    For urgent issues or immediate assistance during integration setup.
    
    *Response time: Within 2 hours during business hours*
  </Card>
  <Card title="Technical Support" icon="envelope">
    **Email Support Team**
    
    [support@surebright.com](mailto:support@surebright.com)
    
    *For detailed technical issues and documentation requests*
  </Card>
</CardGroup>

### Additional Resources

  **Salesforce Commerce Cloud Resources**:
  - [SFCC Developer Center](https://developer.salesforce.com/docs)
  - [SFCC API Documentation](https://documentation.b2c.commercecloud.salesforce.com/)
  - [SFCC Business Manager Guide](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/content/b2c_commerce/topics/admin/business_manager.html)

---

**What's Next**: Proceed to the [Configuration Guide](./Configuration) to set up user access and API credentials.

---

# Jobs

Source: https://docs.surebright.com/salesforce-commerce-cloud/Jobs

> Data synchronization jobs configuration for SureBright integration including product export and order processing jobs.

This guide covers the configuration and management of automated jobs that synchronize data between your SFCC instance and the SureBright system.

<Info>
  **Prerequisites**: Ensure you have completed the [Business Manager Setup](./BusinessManagerSetup) and [Configuration](./Configuration) phases before configuring jobs.
</Info>

---

## SureBright Products Export

This job uses SureBright's API to traverse the entire storefront catalog and export each Simple and Variant Product that is, at the time of the job run, merchandisable (online and in stock).

### Configuration Steps

1. Go to Business Manager **→** Administration **→** Operations **→** Jobs. Select the **SureBright Products Export** job.
2. Go to Job Steps and select **Scope**. Configure this to run in the scope of the site integrating with SureBright.
3. Ensure this job is triggered at least once without errors and notify SureBright after the successful run. SureBright will confirm if the product sync was successful.
4. Schedule this to run at the preferred cadence (SureBright recommends once per day), at a time that's most suitable for a recurring job setup, ideally after the catalog is being updated.

### Job Parameters

| Parameter | Description | Default Value |
|-----------|-------------|---------------|
| **Scope** | Site scope for product export | Your site identifier |
| **Frequency** | How often to run the job | Daily |
| **Time** | Preferred execution time | After catalog updates |
| **Error Handling** | Retry and notification settings | 3 retries, email notification |

![SFRA Product Export](/images/sfra_productexport.png)

<Info>
  **Best Practice**: Schedule this job to run during low-traffic hours to minimize impact on storefront performance.
</Info>

---

## SureBright Orders Creation

This job uses SureBright's Orders API to consume the orders. When this job is triggered, it sends an Order generation request to SureBright and SureBright will generate any necessary service contracts or lead tokens (for Post Purchase flow).


### Configuration Steps

1. Go to Business Manager **→** Administration **→** Operations **→** Jobs. Select the **SureBright Orders Creation** job.
2. Configure the job scope to your site integrating with SureBright.
3. Set the job to run at frequent intervals (recommended: every hour) for real-time order processing.
4. Configure error handling and retry mechanisms.

### Job Parameters

| Parameter | Description | Default Value |
|-----------|-------------|---------------|
| **Scope** | Site scope for order processing | Your site identifier |
| **Frequency** | How often to run the job | Every hour |
| **Queue Processing** | Number of orders to process per run | 50 orders |
| **Error Handling** | Retry and notification settings | 3 retries, email notification |

---

## Job Monitoring and Management

### Monitoring Job Execution

1. **Job Status**: Go to `Administration → Jobs → Job Status` to monitor job execution
2. **Job Logs**: Review job logs for errors and performance metrics

### Common Job Issues

**Job Execution Failures**
- Check job logs for specific error messages
- Verify API connectivity and credentials
- Ensure sufficient system resources

**Data Synchronization Issues**
- Verify product data format and structure
- Check order data completeness
- Review contract creation parameters



## Next Steps

Once you have configured all necessary jobs:

1. **Test Integration**: Run comprehensive tests using the [Testing Guide](./Testing)
2. **Go Live**: Deploy to production and monitor job execution

---

## Troubleshooting

### Common Job Issues

**Job Execution Failures**
- Check job logs for specific error messages
- Verify API connectivity and credentials
- Ensure sufficient system resources

**Data Synchronization Issues**
- Verify product data format and structure
- Check order data completeness
- Review contract creation parameters

### Getting Help

If you encounter issues with job configuration:

1. Contact your SureBright representative for immediate assistance
2. Email [support@surebright.com](mailto:support@surebright.com) for technical support

---

## ✅ Jobs Configuration Complete

Great job! You have successfully configured all necessary data synchronization jobs. The SureBright integration is now ready for testing and validation.

**What's Next**: Proceed to the [Testing Guide](./Testing) to run comprehensive integration tests.

---

# Testing

Source: https://docs.surebright.com/salesforce-commerce-cloud/Testing

> Comprehensive testing and validation guide for SureBright SFCC integration including product sync, order processing, and storefront functionality testing.

Now that you have setup all the necessary elements, you can test the functionalities on storefront. Ensure the product catalog has been exported and SureBright Product Protection is enabled on product from the Merchant Portal.

<Info>
  **Prerequisites**: Ensure you have completed the [Business Manager Setup](./BusinessManagerSetup), [Configuration](./Configuration), and [Jobs](./Jobs) phases before running tests.
</Info>

---

## Storefront Display and User Experience

Go to any Surebright Covered Simple or Variant Product. Select a variant and you will be presented with Surebright Offering Widget to select option.

![SFRA Offering Widget](/images/sfra_offering.png)

### Test Scenarios

#### 1. Product Page Display
- Check warranty options appear on product pages
- Verify warranty plan descriptions and pricing
- Test warranty selection and configuration
- Confirm mobile responsiveness

#### 2. Cart and Checkout Integration
- Verify warranty products add to cart correctly
- Check cart display and warranty information
- Test checkout flow with warranty products
- Confirm order summary accuracy




---



### Getting Help

If you encounter issues during testing:

1. Contact your SureBright representative for immediate assistance
2. Email [support@surebright.com](mailto:support@surebright.com) for technical support

---

## ✅ Testing Complete

Great job! You have successfully completed comprehensive testing of the SureBright integration. The system is now ready for production deployment.

**What's Next**: Proceed to the [FAQs](./FAQs) for any questions.

---

# SureBright’s update claim and service status API for Servify

Source: https://docs.surebright.com/servify/update-claim-service-status

Payload to be encrypted by SureBright's pub key.

---

# Create discount excluding SureBright Products

Source: https://docs.surebright.com/shopify/create-discount-excluding-surebright-products

## Steps to create discount excluding SureBright Products
<Steps>
    <Step title="Create a Smart Collection">
        **Name:** 
        - **Example:** All products except Surebright
        
        **Conditions:**
        - Product vendor → is not equal to → Surebright

        <img
        src="/images/img_shopifydiscount_1.jpeg"
        alt="Surebright-Sales-channel-Step-1"
        title="Surebright-Discount-Step-1"
        className="mx-auto"
        style={{ width:"86%" }}
        />
    </Step>

    <Step title="Create the Discount">
        **Path:** Shopify Admin → Discounts → Create discount → Amount off products

        <img
        src="/images/img_shopifydiscount_2.jpeg"
        alt="Surebright-Sales-channel-Step-1"
        title="Surebright-Discount-Step-1"
        className="mx-auto"
        style={{ width:"86%" }}
        />
        
        In **Applies To**, select Specific Collections:
        - Search for the collection (All products except Surebright) you named excluding Surebright Products

        <img
        src="/images/img_shopifydiscount_3.jpeg"
        alt="Surebright-Sales-channel-Step-1"
        title="Surebright-Discount-Step-1"
        className="mx-auto"
        style={{ width:"86%" }}
        />
        
    </Step>

    <Step title="Add other details as per requirements">
    </Step>

    <Step title="Save the discount">
        Complete the discount setup and save your changes.
    </Step>
</Steps>

---

# Enable SureBright Cart Validator

Source: https://docs.surebright.com/shopify/enable-surebright-cart-validator

> Prevent unauthorized warranty purchases with built-in fraud protection by enabling the SureBright Cart Validator in your Shopify store.

## Prevent Unauthorized Warranty Purchases with Built-in Fraud Protection

The SureBright Cart Validator acts as a fraud prevention layer within your Shopify store, designed to block the purchase of warranty products through unauthorized or unintended channels.

Warranty plans are meant to be purchased alongside their corresponding products. However, in certain cases, customers may attempt to add and purchase warranty policies independently — leading to invalid coverage, operational challenges, and potential misuse.

To address this, SureBright establishes intelligent checkout validation rules that enforce correct purchase behavior.

Once enabled, the Cart Validator ensures that:

- Warranty products cannot be purchased as standalone items
- Each warranty policy is always tied to an eligible product in the cart
- Invalid or suspicious checkout attempts are automatically blocked

By enforcing these rules at checkout, you not only maintain data integrity but also protect your store from misuse, ensuring that every warranty sold is valid and compliant.


## Follow the steps below to enable this validation in your store.


<Steps>
    <Step title="Open Settings">
        Navigate to your Shopify Admin dashboard and click on **Settings** from the bottom-left corner of the sidebar.
        <img
            src="/images/enable-surebright-cart-validator/sb-cart-validator-step-1.png"
            alt="Settings option in the bottom-left corner of the Shopify Admin sidebar"
            title="Open Settings"
            className="mx-auto"
            style={{ width: "40%" }}
        />
    </Step>

    <Step title="Navigate to Checkout Settings">
        In the Settings menu, click on **Checkout** from the left-hand navigation panel. Scroll down to the bottom of the page to locate the **Checkout rules** section.
        <img
            src="/images/enable-surebright-cart-validator/sb-cart-validator-step-2.png"
            alt="Checkout rules section"
            title="Checkout Rules Section"
            className="mx-auto"
            style={{ width: "86%" }}
        />
    </Step>

    <Step title="Select the SureBright Cart Validator">
        In the **Checkout rules** section, click the **Add rule** button. A list of available checkout rule extensions will appear. Locate the **SUREBRIGHT - EXTENDED WARRANTY** section and click on **sb-cart-validator** to select it.
        <img
            src="/images/enable-surebright-cart-validator/sb-cart-validator-step-3.png"
            alt="Select sb-cart-validator under SureBright Extended Warranty"
            title="Select SureBright Cart Validator"
            className="mx-auto"
            style={{ width: "86%" }}
        />
    </Step>

    <Step title="Configure the Rule">
        The **Checkout rule for sb-cart-validator** page will open with an **Inactive** status. Enter a **Title** for the rule. Leave the **Block checkout if app experiences a problem** option unchecked, so that orders are still processed even if the validation app encounters an issue.
        <img
            src="/images/enable-surebright-cart-validator/sb-cart-validator-step-4.png"
            alt="Checkout rule configuration page with Title field and fallback option"
            title="Configure Rule"
            className="mx-auto"
            style={{ width: "86%" }}
        />
    </Step>

    <Step title="Activate the Rule">
        Click the status dropdown next to the Title field and change it from **Inactive** to **Active**.
        <img
            src="/images/enable-surebright-cart-validator/sb-cart-validator-step-5.png"
            alt="Set the checkout rule status to Active from the dropdown"
            title="Activate Rule"
            className="mx-auto"
            style={{ width: "86%" }}
        />
    </Step>

    <Step title="Save the Changes">
        Click **Save changes** to apply the rule. Once saved, the page header will display the rule title with an **Active** status badge.
        <img
            src="/images/enable-surebright-cart-validator/sb-cart-validator-step-6.png"
            alt="Checkout rule saved and shown as Active"
            title="Rule Saved and Active"
            className="mx-auto"
            style={{ width: "86%" }}
        />
    </Step>

    <Step title="Verify the Setup">
        Navigate back to the **Checkout rules** section in your Checkout settings. The rule will now appear with an **Active** status badge. To confirm everything is working correctly, perform a test by completing a basic user journey through to the checkout page. Attempt to add a SureBright warranty product without its associated product to verify that the validation is triggered as expected.
        <img
            src="/images/enable-surebright-cart-validator/sb-cart-validator-step-7.png"
            alt="Surebright Product Protection rule shown as Active under Checkout rules"
            title="Cart Validator Active"
            className="mx-auto"
            style={{ width: "86%" }}
        />
    </Step>
</Steps>

<Note>
    If the cart validator app encounters an error, the checkout will still proceed normally as long as the **"Block checkout if app experiences a problem"** option is left unchecked. This ensures a seamless customer experience at all times.
</Note>

---

# Add Online Sales Channel to any Product

Source: https://docs.surebright.com/shopify/online-sales-channel

## Steps to add Online Sales channel
<Steps>
    <Step title="On product page on Shopify dashboard, click on three dots of Publishing">
        <img
        src="/images/Surebright-Sales-channel-Step-1.jpeg"
        alt="Surebright-Sales-channel-Step-1"
        title="Surebright-Sales-channel-Step-1"
        className="mx-auto"
        style={{ width:"86%" }}
        />
    </Step>

    <Step title="Select Online Store from the list and click done">
        <img
            src="/images/Surebright-Sales-channel-Step-2.jpeg"
            alt="Surebright-Sales-channel-Step-2"
            title="Surebright-Sales-channel-Step-2"
            className="mx-auto"
            style={{ width:"86%" }}
        />
    </Step>
    <Step title=" ✅ All Set! Online Sales Channel Enabled">
        🎉 You've successfully enabled the Online Sales Channel on your Shopify store!
    </Step>
</Steps>

---