# SureBright Documentation # Abandoned Cart Recovery Source: https://docs.surebright.com/abandoned-cart-guide/abandoned-cart > Win back shoppers who left checkout by offering them a protection plan, free or discounted, with a single-use code. Learn how offers are prepared and sent, and how to read the results. When a shopper fills a cart, starts checkout and leaves without paying, that checkout is an **abandoned cart**. SureBright captures it for you. Once the cart has been quiet long enough, an offer is prepared for it: a protection plan for each product that can be covered and, when your offer has a discount, a single-use discount code that makes that plan free or cheaper. The offer then goes to the shopper as a Shopify invoice email, or through your own Klaviyo or Omnisend if you connect one. You choose how offers go out. Prepare and send each offer yourself from the cart, through the channel you chose for your emails. Or switch on [automatic follow-ups](/abandoned-cart-guide/automatic-follow-ups), and SureBright prepares and sends every follow-up for you. **Using customer segments?** Each kind of shopper gets its own offer, message and timing: high-value carts get information first and a free plan later, small carts a single reminder. See [Customer segments](/abandoned-cart-guide/customer-segments) for who gets what. The discount code only applies to the protection plan, never to your own products. The discount comes out of your margin on the plan. SureBright charges you only its cost for the plan, as usual, no matter how much the shopper pays. ## How a cart becomes a recovered order A shopper starts checkout and leaves. SureBright records the cart automatically. It appears in the **Carts** tab as **Watching**. Once no activity has happened for the time you set in **Settings**, the cart counts as abandoned and becomes **Ready to prepare**. The protection plan is chosen for each covered product, from your offer rule or the cart's customer segment, and, when the offer has a discount, the discount code is created. With automatic follow-ups on, SureBright does this for you within minutes. With them off, open the cart and press **Prepare offer**. The cart is now **Ready to send**. **With automatic follow-ups on**, SureBright sends each follow-up when it is due, through the channel you chose for your emails. It follows your setup: on stores with customer segments, each segment's steps, with that step's timing, offer and message; on other stores, a first email after the hours you set and, if you switch on **One reminder before the discount code ends**, one Shopify invoice reminder in the code's last day. Your limits still apply: emails per day, quiet hours and who can receive an offer. When Klaviyo or Omnisend sends your emails, SureBright hands each offer to it and your flow or automation sends the email. **With automatic follow-ups off**, you send each offer yourself: open the cart, change the plan or the discount if you want, then press **Send now**. Either way, the shopper gets an email with a checkout link that already holds the plan and any discount. You can still open any cart to change its offer or send it sooner. When the shopper completes the order, the cart becomes **Recovered with warranty** if they kept the plan, or **Recovered** if they bought without it. Any follow-ups still to come stop. ## Before you start Abandoned Cart is switched on for your store in two steps. Your SureBright contact helps with both. **1. Get the page.** If **Abandoned Cart** is not in your menu, or the page says *This feature is not switched on for this store yet*, write to [support@surebright.com](mailto:support@surebright.com) and ask for access. **2. Request sending.** Once you have the page, everything in it is yours to explore straight away: your own abandoned checkouts, customer groups and timing. Until SureBright switches sending on, a blue band at the top of every tab says so, and nothing reaches a shopper. ![The band shown until sending is switched on](/images/abandoned-cart-not-switched-on.png) Press **Request Abandoned Cart** in that band, or on the **Settings** tab. Add a note if there is anything SureBright should know, for example the email tool you already use or the carts you want to start with, then press **Send request**. Your request goes straight to the SureBright team, who switch sending on and let you know. Meanwhile the band shows the date you asked. ![Requesting Abandoned Cart](/images/abandoned-cart-request-dialog.png) ### Let SureBright create discount codes Each offer's code is a Shopify discount, so Shopify must let SureBright create discounts in your store. SureBright asks for this only once Abandoned Cart is switched on for your store (see [Store access](/platforms/store-access)). Until you allow it, your abandoned checkouts are still captured, but offers cannot be prepared, and an orange band says so. ![The band shown until Shopify lets SureBright create discount codes](/images/abandoned-cart-grant-permission.png) To allow it, sign out of the portal, then sign in again through Shopify, or open the SureBright app from your Shopify admin. Shopify asks you to approve the new permission. Then open **Abandoned Cart** again: the band is gone. ### Have an offer ready for every cart On stores without customer segments you also need at least one **active** offer rule. A rule decides the discount and the plan, so with none active no cart can be prepared. Stores with customer segments get their offer from each segment instead. See [Offer rules and settings](/abandoned-cart-guide/offer-rules-and-settings). ## Where to find each task | You want to | Open in the portal | Read | |---|---|---| | See what your carts say and what to try next | **Overview** (stores with customer segments) | [Results](/abandoned-cart-guide/results#see-who-leaves-carts-and-where) | | See every captured checkout, prepare offers and send them | **Carts** | [Manage carts and offers](/abandoned-cart-guide/carts-and-offers) | | Have follow-ups sent for you | **Follow-ups → Automatic follow-ups** | [Automatic follow-ups](/abandoned-cart-guide/automatic-follow-ups) | | Set the offer each cart gets, on stores without customer segments | **Follow-ups → Offer rules** | [Offer rules and settings](/abandoned-cart-guide/offer-rules-and-settings) | | Decide who gets which offer and follow-ups | **Follow-ups → Customer segments** | [Customer segments](/abandoned-cart-guide/customer-segments) | | Try two versions of a segment's follow-ups | **Follow-ups → A/B tests** | [A/B tests and templates](/abandoned-cart-guide/offer-tests-and-templates) | | Write the words your emails use | **Messages → Templates** | [A/B tests and templates](/abandoned-cart-guide/offer-tests-and-templates#write-and-test-your-message-templates) | | Choose who sends your emails: Shopify, Klaviyo or Omnisend | **Messages → Connected tools** | [Channels and tools](/abandoned-cart-guide/channels) | | See every email that went out, and retry any that failed | **Messages → Message log** | [Manage carts and offers](/abandoned-cart-guide/carts-and-offers#check-what-was-sent) | | Set when a cart counts as abandoned, plan defaults and recipients | **Settings** | [Offer rules and settings](/abandoned-cart-guide/offer-rules-and-settings#choose-your-store-wide-settings) | | See what recovery produced and how much of your margin the discounts used | **Results** | [Results](/abandoned-cart-guide/results) | | Find out why something didn't go out | | [FAQs and common issues](/abandoned-cart-guide/faqs-and-common-issues) | Older links to the previous tab names (**Rules**, **Performance**) still open the right screen. **Overview**, **Customer segments**, **A/B tests** and **Cohorts** appear only on stores with customer segments. ## What you'll see in Shopify Abandoned Cart works inside your Shopify store, so you will find its work in your Shopify admin: | In Shopify | What it is | What to do | |---|---|---| | **Draft orders** tagged `SureBright` and `AbandonedCart` | The cart and the offered plan, with the discount, that each offer email links to. Abandoned Cart sends its offers as Shopify draft order invoices | With automatic follow-ups on, or when Klaviyo or Omnisend sends your emails, SureBright removes unused drafts some time after the code ends or the shopper buys through their own checkout. Otherwise you can delete unused ones | | A draft order also tagged `Test` | A test send from **Messages → Templates** | Safe to delete | | **Discounts** named with your prefix, for example `SBOFFER-XXXXX` | Each cart's single-use discount code | Nothing. Each one works once, only on the protection plan, and stops working when the offer ends | ## Related Read each cart's status, prepare and send an offer, and check what was sent. Let SureBright prepare and send every follow-up within your limits. Give each kind of shopper its own offer, message and timing. Why an offer didn't go out, and answers to common questions. --- # Automatic follow-ups Source: https://docs.surebright.com/abandoned-cart-guide/automatic-follow-ups > Have SureBright prepare every offer and send each follow-up when it is due, through your chosen channel and within the limits you set, and follow each cart on its timeline. With automatic follow-ups on, SureBright does the work of the **Carts** tab for you. It prepares an offer for each abandoned cart within a few minutes and sends each follow-up when it is due, through the channel you chose for your emails. You can still open any cart to change its offer or send it sooner; see [Manage carts and offers](/abandoned-cart-guide/carts-and-offers). ## Send follow-ups automatically **Follow-ups → Automatic follow-ups** holds one switch, **Send follow-ups automatically**, and its limits. ![Automatic follow-ups](/images/abandoned-cart-automatic-followups.png) | Switch | What happens | |---|---| | **On** | SureBright prepares an offer for each abandoned cart within a few minutes and sends each follow-up step when it is due, with the same checks as your Send button | | **Off** | You prepare and send each offer yourself: **Send now** in the cart, or, on stores with customer segments, **Send step N now** on the cart's timeline | Below the switch, **Last checked** says when SureBright last ran for your store and how many carts it prepared, sent and recovered, and a preview counts the follow-up steps due in the next 24 hours. When nothing can go out, it says why: it is inside your quiet hours, or sending is paused by SureBright. Offers are prepared automatically only for carts left within the hours set under **Settings → Prepare offers automatically for carts left in the last (hours)**. Open an older cart and press **Prepare offer** to send it one yourself. ## What gets sent | Your store | What goes out | |---|---| | With customer segments | Each cart follows its segment's steps, with each step's own timing, offer and message. Every cart, including **All other carts**, follows its segment; there is no store-wide first email or reminder. See [Customer segments](/abandoned-cart-guide/customer-segments) | | Without customer segments | A first email **First email after (hours)** (4 by default) after the cart counts as abandoned, with the offer from your [offer rules](/abandoned-cart-guide/offer-rules-and-settings#set-your-offer-rules). With **One reminder before the discount code ends** on (it is off by default), one more Shopify invoice email in the code's last day, to shoppers who have not bought yet | When a connected tool sends your emails, the switch reads differently: SureBright prepares the offer and hands it to the tool, and your automation there sends the email. Your tool gets offers automatically only while automatic follow-ups are on; an offer you send from a cart still goes to it. See [Channels and tools](/abandoned-cart-guide/channels). ## Set the limits **Limits for automatic sends** apply only to automatic sends (press **Save limits** after changing them); your own Send button is held back by the gap between two emails, never by the daily limit or quiet hours. | Limit | What it does | |---|---| | **Emails per day, at most** | Across all automatic sends for the store. 200 by default | | **Hours between two emails to the same shopper** | The reminder and your own **Resend now** wait at least this long after the previous email to that shopper. Customer segment steps keep their own timing. 0 means no wait | | **Quiet hours** and **Time zone** | No automatic email between these times; due steps wait until they end. Events to connected tools still go out when they happen, so set quiet hours in the tool too | Who can receive an offer at all, including marketing consent and addresses you never contact, is set under **Settings**; see [Choose who can receive an offer](/abandoned-cart-guide/offer-rules-and-settings#choose-who-can-receive-an-offer). ## Follow each cart on its timeline Open any cart in a segment on the **Carts** tab. The top of the panel shows its segment and its **Follow-up sequence**, and whether automatic follow-ups are on. ![A cart's follow-up timeline](/images/abandoned-cart-cart-timeline.png) | You see | What it means | |---|---| | ✓ beside a step | Sent. The line names the offer it carried, the tool that sent it, when, and whether you or automatic follow-ups sent it | | ● beside a step, and **step N is next** in the heading | The next step to go out. Its line says **due** and the time, or **due now**. **Send step N now** sends it straight away | | ○ beside a step | A later step, not due yet | | – beside a step | Skipped, with the reason, for example the shopper has not opted in to marketing emails | | **Not started yet** | The steps start once this cart's offer is prepared | | **Waiting**, **Held back** or **Paused** | A step is due but held for now, with the reason: *Waiting: it is inside your quiet hours.*, *Waiting: today's limit on automatic emails is reached.*, *Held back: another email reached this shopper recently.*, *Paused: the segment … is switched off*, or *Waiting: the last try did not go out*, with the time of the next try. It goes out as soon as the reason clears | | **Stopped:** | The sequence is over: the shopper bought, the offer ended, you skipped the cart, or the shopper started a newer cart that carries the conversation | | **Control group** | The cart is held back on purpose so you can measure what the sequence adds. It is never contacted automatically. **Send anyway** sends to it if you choose | ## Related - [Manage carts and offers](/abandoned-cart-guide/carts-and-offers) - [Customer segments](/abandoned-cart-guide/customer-segments) - [Channels and tools](/abandoned-cart-guide/channels) - [FAQs and common issues](/abandoned-cart-guide/faqs-and-common-issues) --- # Manage carts and offers Source: https://docs.surebright.com/abandoned-cart-guide/carts-and-offers > Find a cart, read its status, and step in when you want to: prepare an offer, change its plan or discount, send it yourself, and check every message that went out. The **Carts** tab lists every abandoned checkout SureBright captured, with the offer each one gets and where it stands. With [automatic follow-ups](/abandoned-cart-guide/automatic-follow-ups) on, SureBright prepares and sends the offers for you and this is where you watch them. With them off, this is where you prepare and send each offer yourself. ## Work through your carts Each row is one captured checkout. ![Carts tab](/images/abandoned-cart-carts-tab.png) The columns are **Last active**, **Customer details**, **Cart value**, **Product to cover** (the product that can be covered), **Warranty plan and price** (the plan being offered and what the shopper pays) and **Status**. Under **Warranty plan and price** you will see two figures, for example ~~$49.99~~ **$25.00**. The struck-through price is the plan's retail price. Your discount comes out of your margin; SureBright charges you only its cost for the plan, as usual. ### What each cart status means The chips across the top filter the list. Click one to see only those carts. | Status | What it means | What you should do | |---|---|---| | **Watching** | The checkout was captured but has not been quiet long enough yet | Nothing. Wait | | **Ready to prepare** | The cart has gone quiet and can be worked on | With automatic follow-ups on, nothing: it is prepared for you within minutes, if it was left within the hours set under **Prepare offers automatically for carts left in the last (hours)**. Otherwise open it and press **Prepare offer** | | **Needs a plan** | The offer was prepared but no plan was attached automatically | Open it, press **Add plan** on the product line, choose a plan, then press **Create discount code** | | **Ready to send** | The offer is ready: a plan and, when the offer has a discount, its code | With automatic follow-ups on, nothing: it goes out when its follow-up is due. Otherwise review it and press **Send now** | | **Sent** | The offer email has gone to the shopper | Wait. You can send again up to the limit your offer allows | | **Recovered with warranty** | The shopper came back, paid, and kept the protection plan | Nothing. This is the win | | **Recovered** | The shopper came back and paid, but without the plan | Nothing. The order is recovered, the plan was not taken | | **Bought on their own** | They completed the purchase before you sent anything | Nothing. Recovery played no part | | **Expired** | The code ran out before they used it, or the offer was ended | Open it and press **Extend by 24 hours**. The shopper keeps the same code and the cart goes back to **Ready to send**. Then press **Resend now**. When the offer ended because a follow-up without a discount was sent, the panel says so instead | | **Send limit reached** | The cart has had every send its offer allows, so the offer ended | Nothing more goes out for this cart | | **Not eligible** | The cart did not meet your rules, for example nothing in it can be covered, it is worth less than your minimum, or the shopper ordered recently | Read the reason shown beside the status | | **Skipped** | You chose to skip this cart | Nothing will be sent for it | | **Could not create offer** | The discount code could not be created in Shopify | Open the cart, read the reason, fix it, then press **Create discount code** | Press the refresh button at the top right of the list to check your carts for new purchases and for codes that have run out. With automatic follow-ups on, or when Klaviyo or Omnisend sends your emails, SureBright also checks about every 10 minutes; otherwise statuses only change when you refresh or open a cart. **Bought on their own** carts are hidden from the **All** list on purpose, because there are usually many of them and there is nothing to do. Click their own chip when you want to see them. ### Find a specific cart - **Search** by shopper email, name, product, SKU or discount code. - **Any rule** narrows the list to carts matched by one offer rule. On stores with customer segments it is replaced by **Customer segment**, **Follow-up step**, **Control group** and **A/B test**. - **Eligible product only** hides carts where nothing can be covered. - **No-email carts** reveals carts captured before the shopper entered an email. They count in your reporting, but nothing can be sent to them. --- ## Prepare and send an offer With automatic follow-ups on, SureBright prepares and sends your offers for you, so this section is for when you want to step in: send one cart yourself, change its plan or discount before it goes, or send sooner. With automatic follow-ups off, this is how every offer goes out. Click any cart row to open it. ### Prepare the offer ![The cart panel before preparing the offer](/images/abandoned-cart-drawer-before-prepare.png) The panel tells you plainly where the cart stands and what the next step is. Nothing has been chosen and nothing has been emailed. Press **Prepare offer**. ### Review what the shopper will get ![The cart panel with the offer ready to send](/images/abandoned-cart-drawer-ready-to-send.png) After you prepare, you can see everything the shopper will get: - **What the shopper gets** and **Cart items**: each product, the plan chosen for it, and what the shopper pays. If the shopper had picked a plan themselves, the panel says so. - **Why this cart qualified**: how far the shopper got, when it was abandoned, and which rule or segment matched. - **Discount code**: the single-use code and when it expires. **Expire discount code** ends it now; **Extend by 24 hours** gives the shopper one more day with the same code. - **Checkout link with your offer**: the same link the shopper gets in the email, with **Copy link** and **Open it**. Until that link is made, the card shows **The shopper's original checkout** instead. - **Messages for this cart** and **Changes made to this cart**: every email for this shopper, and every plan or offer you changed by hand. ![The discount code and the checkout link](/images/abandoned-cart-drawer-code-and-link.png) On stores with customer segments, the top of the panel also shows the cart's follow-up timeline; see [Follow each cart on its timeline](/abandoned-cart-guide/automatic-follow-ups#follow-each-cart-on-its-timeline). ### Change the plan for a product Press **Change** on any line to see every plan available for that product. ![Choosing a different protection plan](/images/abandoned-cart-plan-picker.png) Each card shows **what the shopper pays** in bold and the plan's retail price struck through beside it. Pick the one you want and confirm. **Remove** takes the plan off that line. If your store offers both **Accidental damage** and **Extended protection** for a product, the picker shows a tab for each. Stores with only one kind of cover see no tabs. You can change a plan after the offer was already emailed. The cart then shows **You changed this, resend** so you know the shopper has the old version. If the shopper changes their own cart after the email, it shows **Cart changed, resend**. ### Change the discount for one cart Sometimes one shopper deserves a better offer than everyone else gets. Click **Change the discount for this cart** to open it. ![Changing the discount on a single cart](/images/abandoned-cart-change-discount.png) Choose one of three, then press **Save offer**: | Choice | What the shopper gets | |---|---| | **Free** | Pays nothing for the protection plan | | **% off** | A percentage off the plan's price | | **Amount off** | A fixed amount off the plan's price | This affects **this cart only**. Your rule or segment is untouched and no other cart changes. On carts whose offer comes from a rule, **Back to the rule's offer** undoes it. The heading always shows the offer currently in force, so you can see it without opening the section. Saving creates a **new** discount code for this cart. Any code you already sent stops working, so send the offer again afterwards. ### Send the offer Press **Send now**. The offer goes out through whoever sends your emails: a Shopify invoice email by default, or your own Klaviyo or Omnisend flow (see [Channels and tools](/abandoned-cart-guide/channels)). After the first send the button reads **Resend now**. **Edit**, beside **Sending**, lets you change this one send: ![Choosing what this send carries and who sends it](/images/abandoned-cart-send-options.png) | Option | What it does | |---|---| | **What to send** | **Their cart with your offer** (the products plus the plan at your discount, with the code), or **Cart items only** (just the products, no plan and no code) | | **Send by** | Which connected tool sends it | | **Saved message** | A template from **Messages → Templates**, or the default message | - **Change the email message** lets you write a one-off subject and message for this cart. - The line beside the button tells you how many sends this cart is allowed, for example *Sent 1 time, last 21h ago · 6 left*. - After an email, you can send to the same shopper again only after **Hours between two emails to the same shopper** (48 by default, set under **Automatic follow-ups**). The panel tells you when. - To send several at once, tick the carts in the list and press **Send to N selected** above the table. A message then lists any carts that were not sent, and why. - **Skip this cart** marks it as deliberately left alone. **Put back in the list** undoes it. If **Send now** is unavailable, the panel says why in plain words, for example: no email address on the checkout, no plan picked on any line, no discount code created yet, too soon after the last email, no marketing consent where you require it, or the send limit reached. --- ## Check what was sent **Messages → Message log** lists every send, reminder and retry, with its delivery status. ![Message log](/images/abandoned-cart-messages-tab.png) Filter by kind or by status, search by recipient, discount code or sender, and use **Export CSV** to download the rows on the page. Open any row to read the message exactly as it was sent: the email as the shopper saw it, who sent it, the plan and code it carried, and its timeline. If one failed, **Retry send** sends it again and appears as a new row linked to the original. ![A message opened from the Message log](/images/abandoned-cart-message-detail.png) ## Related - [Automatic follow-ups](/abandoned-cart-guide/automatic-follow-ups) - [Offer rules and settings](/abandoned-cart-guide/offer-rules-and-settings) - [FAQs and common issues](/abandoned-cart-guide/faqs-and-common-issues) --- # Channels and connected tools Source: https://docs.surebright.com/abandoned-cart-guide/channels > Choose who sends your abandoned-cart follow-up emails, connect Klaviyo, Omnisend or a webhook, test the connection, and see the events your tool can build automations on. By default SureBright sends every abandoned-cart offer as a Shopify invoice email, as described in [Abandoned Cart Recovery](/abandoned-cart-guide/abandoned-cart). If you already email shoppers from your own tool, you can have that tool send the offers instead. SureBright still finds the cart, picks the plan and, when the follow-up carries a discount, creates the single-use code. Your tool sends the message with your design, your sending domain and your reporting. You set this up in the Merchant Portal under **Abandoned Cart → Messages → Connected tools**, on stores where Abandoned Cart is switched on. ## Who sends your follow-up emails The first card asks **Who sends your abandoned-cart follow-up emails?** ![Connected tools](/images/abandoned-cart-connected-tools.png) | Choose | What happens | |---|---| | **SureBright, by Shopify invoice email** | SureBright sends each follow-up as a Shopify invoice email when it is due. Nothing to set up | | **Your Klaviyo flow** | Each follow-up reaches your Klaviyo account as the event **SureBright: Offer sent**, which starts your flow. Connect Klaviyo first | | **Your Omnisend automation** | SureBright adds the offer to the shopper's Omnisend contact, or sends the same event. You choose which on the Omnisend card. Connect Omnisend first | Press **Save** after choosing. If you disconnect the tool that sends your follow-up emails, no follow-up email goes out until you choose a sender again. If you keep your own abandoned-cart emails running, choose your tool here or switch yours off, so shoppers do not get two emails. When your Klaviyo flow or Omnisend automation sends them, a **Right now:** line under the choice says how offers reach shoppers. Your tool gets offers automatically only while automatic follow-ups are switched on; an offer you send from a cart still goes to it (see [Automatic follow-ups](/abandoned-cart-guide/automatic-follow-ups)). If SureBright finds live Klaviyo flows that already email abandoned carts, it lists them here, so you can avoid two emails. ## What each connected tool does | Tool | What it does for you | What you need | |---|---|---| | **Shopify invoice email** | Shopify emails the shopper a checkout link with their protection plan and your offer | Nothing | | **Klaviyo** | Your flow emails the shopper. SureBright sends events while your Klaviyo flow sends your follow-up emails, and can keep your segments as Klaviyo lists | A **Private API key** with **Events: Full access** (required); **Accounts**, **Flows** and **Metrics: Read-only**; **Lists** and **Profiles: Full access** only if you sync segments; **Campaigns** and **Templates: Full access** only if you send campaigns | | **Omnisend** | Your automation emails the shopper. SureBright sends events or adds the offer to the contact | An **API key** from Omnisend's store settings, with access to Contacts, and to Events if Omnisend gets the offer as an event | | **Webhook** | SureBright posts each event to a web address you own, for Zapier, Make or your own system | An https **Endpoint URL** that answers with a success response | ![The connected tool cards](/images/abandoned-cart-connected-tools-cards.png) Each card shows the tool's status (**Connected**, **Not connected**, **Needs attention**) and the account it is connected as. Once connected, an **Insights** section lists the flows in your tool triggered by SureBright events in the last 7, 30 or 90 days with **Triggered**, **Delivered**, **Opened**, **Clicked**, **Orders** and **Revenue**, using the tool's own numbers. ![Klaviyo insights](/images/abandoned-cart-klaviyo-insights.png) ## Connect a tool **Manage** on a connected tool's card opens its window, with each step and a tick once it is done. ![Managing the Klaviyo connection](/images/abandoned-cart-klaviyo-manage.png) Press **Connect** on the tool's card, paste the key or endpoint URL and follow **Where to find it in** the tool. Klaviyo's window asks **Should your Klaviyo flow send your follow-up emails?** Answer **Yes, my Klaviyo flow sends them** to make it the sender. For Omnisend, choosing how it gets the offer makes it the sender; see [How Omnisend gets the offer](#how-omnisend-gets-the-offer) below. You can change this later under **Who sends your abandoned-cart follow-up emails?** For Klaviyo, and Omnisend with **Send as event**, **SureBright: Offer sent** is always on: it starts your follow-up email. Tick an optional extra event only if you will build a flow on it. For the Webhook, tick the events you want posted. With customer segments on, **Keep your segments in Klaviyo** turns each enabled segment into a Klaviyo list named **SB · segment name**, updated every hour while Klaviyo sends your follow-up emails. Its key needs Lists and Profiles full access. Press **Connect Klaviyo**, **Connect Omnisend** or **Connect Webhook** at the bottom of the window. Connecting sends nothing to shoppers. Open the tool's window again with **Manage**. **Send a test** (button **Send test**) sends one **SureBright: Offer sent** event (Klaviyo, Omnisend's event path) or **SureBright: Offer prepared** event (Webhook) for an email address you enter, so the event appears in the tool. When Omnisend gets the offer on the contact, this step is **Try it on a contact** instead. Save changes first so the test runs the way you just chose. In Klaviyo's window, **Build your email in Klaviyo** lists the steps to build the flow on **SureBright: Offer sent**, the subject line and email body to paste, and every event property you can use in your own template. ![Building the Klaviyo email](/images/abandoned-cart-klaviyo-build-flow.png) ### Connect a webhook Press **Connect** on the **Webhook** card to open **Connect Webhook**. SureBright posts each abandoned-cart event, as JSON, to a web address you own. ![Connecting a webhook](/images/abandoned-cart-webhook-connect.png) 1. **Your web address**: paste your https **Endpoint URL** and press **Continue**. It must answer with a success (2xx) response. 2. **Events sent to your web address**: tick the events you want posted. 3. Press **Connect Webhook**. Connecting sends nothing to shoppers. 4. **Send a test** opens once you are connected: it posts one sample event so you can check your endpoint receives it. After you connect, a signing secret is shown **once**, so copy it then. If it is lost, **Replace secret** in the webhook's window makes a new one. Give it to your developer so your endpoint can check that each request came from SureBright. The request format is on [Notifications and webhooks](/api-reference/notifications-and-webhooks). ## How Omnisend gets the offer Omnisend can carry the offer in two ways. Press **Manage** on the Omnisend card; step 2 of its window, **How your Omnisend emails get the offer**, holds the choice. Either way, your Omnisend automation sends the emails, not SureBright. ![Choosing how Omnisend gets the offer](/images/abandoned-cart-omnisend-manage.png) | Choose | What you do | |---|---| | **Write to contact properties** (use your existing Abandoned checkout automation) | Keep your automation and its timing. SureBright adds the offer to each shopper's Omnisend contact as `sb_` fields: the code, a checkout link with the plans already added, the discount, the plans and their prices, and when the code ends. Paste the personalization tags the card gives you into your email. The card also gives you a block that shows nothing when an email goes out before the offer is ready. SureBright sends no email of its own. With customer segments, each cart gets one offer and the segment's follow-up steps don't run | | **Send as event** (start a new automation from SureBright's event) | Build an automation in Omnisend triggered by the custom event **SureBright: Offer sent**, which arrives each time a follow-up step is due. Set the trigger's frequency so it can start every time, and write the email with the event's tags (code, checkout link, plan, discount, prices, code end, which follow-up, and SureBright's subject and message for the step). With customer segments, each follow-up step sends its own offer. Turn off your Abandoned checkout automation, or shoppers get two emails | The rest of the window walks you through building your email in Omnisend, the events it gets, and a test. Press **Save changes** when you are done. Omnisend automations started by a custom event also email contacts who are not subscribed, unless you change that in the trigger's channel settings. Either way, switch off Shopify's own abandoned checkout email in Shopify. **Try it on a contact** (**Add sample properties**) puts sample offer fields on a contact you name, ideally your own, so you can preview the email. Remove them with **Remove the sample properties** when you are done. When you disconnect Omnisend you choose **Remove the offers first, then disconnect** or **Disconnect and leave them**. The step-by-step version is on [Omnisend](/integrations/omnisend). ## Events your tool receives Klaviyo and Omnisend receive these events only while they send your follow-up emails, and never **Reminder due**; with **Write to contact properties**, Omnisend receives none. The Webhook receives every event. The names match what appears in the tool. **Cart abandoned**, **Offer prepared**, **Reminder due** and **Code expiring** go out only while automatic follow-ups are on, never for a cart in a control group, and never for a shopper without marketing consent when Settings asks for it. | Event | Arrives when | |---|---| | **SureBright: Cart abandoned** | A checkout has been quiet long enough to count as abandoned. Carries the cart value, checkout step, checkout link, segment and items | | **SureBright: Offer prepared** | A plan and a single-use code were made for the cart. Carries the code, when it expires, the plan, what the shopper pays and the offer link | | **SureBright: Offer sent** | A follow-up went out through this tool. Carries the step number, the offer, and the subject and body for the step. The Webhook hears of every send on any channel | | **SureBright: Reminder due** | SureBright sent the cart's automatic reminder in the code's last day | | **SureBright: Code expiring** | Once per cart, when an unused offer has 24 hours or less left | | **SureBright: Cart recovered** | A shopper who was sent an offer placed the order, with or without the plan. Carries the order number and value and whether the plan was attached | The full field list for each event is in the **Event catalog** at the bottom of the Connected tools screen. Open it to see, for each event, what to use it for, when it is sent and every field it carries, so you know which tags you can put in your email or automation. ![The event catalog](/images/abandoned-cart-event-catalog.png) Every event also carries the shopper and the cart: their email, phone and name, marketing consent, your shop name and currency, the cart total and items, the checkout step reached, the customer segment, and how many messages were sent so far. ## Send a campaign to a segment With customer segments on and Klaviyo connected, a segment's panel (open it with **Insights**) offers **Send a campaign** under **Campaigns to this segment**: one message to everyone in the segment at once, created in your Klaviyo account on a synced list. The Klaviyo key needs Campaigns, Templates, Lists and Profiles full access. ![Sending a campaign to a segment](/images/abandoned-cart-segment-campaign.png) Write the subject and message. `{first_name}`, `{product}`, `{plan}`, `{code}` and `{expires}` fill in per shopper, each with their own single-use code. Choose **Now** or **Schedule**, and optionally **Only shoppers who have not bought yet**. For **Now**, the confirmation names the tool, the segment and how many shoppers it will reach. A scheduled campaign can also be cancelled here in the portal. The campaign then appears in Klaviyo's campaign list, where you can also edit or stop it. Only Klaviyo can keep your segments as lists and send campaigns from here. A campaign cannot be recalled once sent. ## Related - [Customer segments](/abandoned-cart-guide/customer-segments) - [Omnisend](/integrations/omnisend) - [Email integrations](/klaviyo-integration/integration-guide) - [Automatic follow-ups](/abandoned-cart-guide/automatic-follow-ups) - [Offer tests and templates](/abandoned-cart-guide/offer-tests-and-templates) --- # Customer segments: who gets which follow-up Source: https://docs.surebright.com/abandoned-cart-guide/customer-segments > SureBright sorts your abandoned carts into customer segments and gives each one its own offer, message and timing. See who falls into each segment, what it sends by default, and how to change it or create your own. Not every shopper who leaves a cart needs the same email. Someone weighing a large purchase wants answers before a discount. Someone with a small accessory cart only needs a reminder. **Customer segments** sort your abandoned carts into groups like these, and SureBright gives each group its own offer, message and timing. Every abandoned cart with an email lands in exactly **one** segment: the first switched-on segment it matches, counted from the top of the list. SureBright gives your store a starting set of segments, built from your own carts. They are examples, not fixed rules. You can change any of them, delete the ones you don't need, and create your own with **New segment**: you decide who is in it, which offer they get, which follow-ups go out and when. See [Create or edit a segment](#create-or-edit-a-segment). Customer segments are available on request. SureBright switches them on per store. Without them, every cart follows your [offer rules](/abandoned-cart-guide/offer-rules-and-settings#set-your-offer-rules) and the store-wide follow-up. ## The starting segments at a glance You find them in the Merchant Portal under **Abandoned Cart → Follow-ups → Customer segments**. The first time you open it, **Set up customer segments** creates the three value segments from your own carts and orders of the last 90 days, and **All other carts** is added below them. The tables below show what each starting segment does until you change it. ![The customer segments list](/images/abandoned-cart-segments-list.png) | Segment | Who is in it | Offer by default | Follow-ups by default | |---|---|---|---| | [High-value carts](#high-value-carts) | Carts at or above your high-value amount | Information first, then the plan free | 2 emails: after 1 day, then on day 7. Code lasts 21 days | | [Mid carts](#mid-carts) | Carts between your two amounts | A reminder, then the plan free | 2 emails: after 4 hours, then after 2 days. Code lasts 7 days | | [Accessory carts](#accessory-carts) | Carts under your lower amount | No discount, plan at full price | 1 email after 2 hours | | [All other carts](#all-other-carts) | Every cart with an email that fits no segment above | The offer your top offer rule had when segments were switched on | 1 email at the hour your store's first email went, plus a reminder if you had reminders on | SureBright also suggests segments when your carts show a group worth its own follow-up. Each suggestion appears under **Suggested from your data** only when enough of your recent carts fit it. | Suggested segment | Who is in it | Offer by default | Follow-ups by default | |---|---|---|---| | [Already chose a plan](#already-chose-a-plan) | Shoppers who added a protection plan themselves, then left | The plan free | 1 email after 12 hours. Code lasts 14 days | | [Comparing two products](#comparing-two-products) | High-value carts holding two or more products that can be covered | No discount | 1 email after 1 day, comparing the products | Carts without an email are not in any segment, because nothing can reach them. They still count on the **Overview**, as **Left before an email**. These are starting points. Change any timing, offer or message, delete the segments you don't need, or replace them with your own. Only **All other carts** stays, because it catches every cart that fits no other segment; switch it off if you don't want those carts followed up. See [What you can change in any segment](#what-you-can-change-in-any-segment). ## How SureBright tailors each segment Each segment differs in four ways. - **The offer.** Some steps carry a single-use code that makes the plan free or cheaper. Others send the plan at full price, so the shopper gets information without you paying for a discount. - **The message.** A step with no discount uses your **Follow-up without a discount** template. The first step uses your **Discount offer** template, and later steps use your **Reminder (later follow-ups)** template. Where you have written a template for that segment, its carts get that one first. See [What each template purpose is for](/abandoned-cart-guide/offer-tests-and-templates#what-each-template-purpose-is-for). - **The timing.** Each step is counted from the moment the cart counts as abandoned, which you set on **Settings**. A considered purchase gets more time between emails than a small one. - **The control group.** Some segments hold back a share of their carts and never contact them, so you can measure what the follow-ups add. The channel is the same for every segment: email steps go out through whoever sends your follow-up emails: a Shopify invoice email by default, or your own Klaviyo flow or Omnisend automation. See [Channels and tools](/abandoned-cart-guide/channels). With **Send follow-ups automatically** on, SureBright sends each segment's steps when they are due, through whoever sends your follow-up emails. With it off, each cart's timeline shows **Send step N now** so you send each step yourself. See [Automatic follow-ups](/abandoned-cart-guide/automatic-follow-ups). --- ## High-value carts **For:** considered purchases, where the shopper wants answers before they buy. | | Default | |---|---| | **Who** | Carts worth at least your high-value amount, with an email | | **Offer** | Step 1 has no discount: the plan is on the checkout link at full price. Step 2 makes the plan free | | **Step 1** | Email after 1 day. The angle: your cart is saved, when it would arrive, what the plan covers, and answers to the questions a big purchase raises | | **Step 2** | Email on day 7. The angle: the plan is free with this order | | **Code lasts** | 21 days | | **Control group** | 10% | **Why it is set up this way:** on a large cart, a free plan costs you little next to the order. But a discount sent too soon pays for sales that were going to close anyway. Information first gives the shopper time to decide. ## Mid carts **For:** everyday purchases, where a nudge is often enough. | | Default | |---|---| | **Who** | Carts worth at least your lower amount and under your high-value amount, with an email | | **Offer** | Step 1 has no discount. Step 2 makes the plan free | | **Step 1** | Email after 4 hours. The angle: your cart is saved, and here is what the plan covers | | **Step 2** | Email after 2 days. The angle: the plan is free if you finish this week | | **Code lasts** | 7 days | | **Control group** | 10% | ## Accessory carts **For:** small carts, where a discount would cost more than it earns. | | Default | |---|---| | **Who** | Carts worth less than your lower amount, with an email | | **Offer** | No discount. The plan is on the checkout link at full price | | **Step 1** | Email after 2 hours. The angle: still want these? Your cart is saved | | **Control group** | None | ## All other carts **For:** every cart with an email that no segment above catches, so no cart goes without a follow-up. | | Default | |---|---| | **Who** | Any cart with an email that fits none of your other switched-on segments. Always checked last | | **Offer** | The offer from your top active offer rule when the segment was created: its discount and its plan choice. With no rule, the plan at full price | | **Step 1** | Email at the hour your store's first follow-up went before customer segments were switched on. Change it in the segment's steps. Uses your **Discount offer** template, or **Follow-up without a discount** when the offer has no discount | | **Step 2** | Only if **One reminder before the discount code ends** was on when segments were switched on: a reminder in the discount code's last day. Uses your **Reminder (later follow-ups)** template | | **Code lasts** | As long as your top offer rule's codes did, 3 days if it set none | | **Control group** | None | This segment is built in. You cannot delete it, rename it, move it or give it conditions. You can edit its steps and offer, or switch it off. Switched off, the carts that reach it get nothing. --- ## Already chose a plan **For:** shoppers who put a protection plan in their cart and then left. They already wanted protection, so the offer makes a plan free. The plan comes from the segment's offer or **Settings → Store default plan**, and replaces the one they picked. | | Default | |---|---| | **Who** | Carts that already hold a SureBright protection plan. If **Leave carts that already have a plan** is on in Settings, these carts never count as abandoned, so this segment gets none | | **Offer** | The plan free | | **Step 1** | Email after 12 hours. The angle: a protection plan is now free with this order | | **Code lasts** | 14 days | | **Control group** | 10% | ## Comparing two products **For:** shoppers choosing between two models. They are deciding, not leaving, and a side-by-side comparison helps more than a discount. | | Default | |---|---| | **Who** | Carts holding two or more products that can be covered, worth at least your high-value amount | | **Offer** | No discount. The plans are on the checkout link at full price | | **Step 1** | Email after 1 day. The angle: the products side by side, what each is for, and which suits them | | **Control group** | 10% | ## How your value amounts are set The two amounts that divide **High-value**, **Mid** and **Accessory** carts come from your own carts. When you set up segments: - the **lower amount** is about where your smallest third of carts ends; - the **high-value amount** is about where your top fifth of carts begins. Both are rounded to tidy figures. A store with fewer than 10 carts starts at **$500** and **$5,000**. Once there are enough carts, SureBright moves the amounts to your own figures, as long as you have not changed them yourself. Open **From your data** under an automatic segment to see the numbers behind it. You can change either amount by editing the segment's **Cart value** condition. Change the matching condition in the neighbouring segment too, so no cart range is left uncovered or caught twice. The editor warns you when two segments compete for the same carts. ## Which segment wins when a cart fits several A cart joins the **first** switched-on segment it matches, from #1 down, and stays there. A suggestion you add goes to #1, above the three value segments. So once you add **Already chose a plan**, a high-value cart with a plan gets the free-plan email after 12 hours, not the High-value sequence. Use the ▲ and ▼ arrows to change the order. **All other carts** is always last. --- ## Manage your segment list **Follow-ups → Customer segments** lists your segments in priority order. | Column | What it tells you | |---|---| | **#** | Priority. The ▲ and ▼ arrows reorder; the change applies to carts that arrive after it | | **Segment** | Name and its one-line purpose | | **Who** | The conditions, in words | | **Follow-up sequence** | The steps, who sends the emails, how long the code lasts, the control group | | **Last 30 days** | Carts that joined, how many became orders and how quickly | | **Actions** | **Insights** (open the segment), **Edit**, and **Delete** (any segment except All other carts). The On/Off switch is under the segment's name | A segment that can never get a cart, because a segment above it catches everything it would, is flagged **Never gets a cart**. ### Add a suggested segment **Suggested from your data** lists segments SureBright thinks you should have, each with **Why** and the evidence behind it. **Add segment** puts the new segment at #1 and moves the others down one place. **Dismiss** removes the suggestion for good. ![Segments suggested from your data](/images/abandoned-cart-suggested-segments.png) ### Switch a segment off Switching a segment off stops new carts joining it. They go to the next segment they fit. For carts already in the segment with steps to go, you choose: | Choice | Effect | |---|---| | **Pause them** | Nothing more is sent to them while the segment is off. When you switch it back on, each cart continues with its next step | | **Let them finish** | They still get the rest of the segment's steps. Only new carts are kept out | Deleting a segment cannot be undone; its carts stop the segment's steps and get no further follow-up. ## Create or edit a segment **New segment** or **Edit** opens the editor. You name the segment, say who is in it, then say what happens to them. ![Editing a segment](/images/abandoned-cart-segment-editor.png) ### Choose who is in the segment A cart is in the segment when **every** condition is true. Conditions are built from: | Condition | You can set | |---|---| | Products in the cart (by name) | include, include none of; comma-separated words from the product names, for example model names | | Cart value | at least, under | | Furthest checkout step | is, is not: **Started checkout**, **Contact entered**, **Address and shipping entered**. A condition saved with the old payment step shows as **Reached payment (no longer tracked)**: pick another step | | Coverable products in cart | at least, under | | Email captured | yes or no | | Marketing consent | yes or no | | Has ordered before | yes or no | | Chose a plan in checkout | yes or no | As you build, the editor counts how many of your last 30 days' carts match and their value, warns **Overlaps with other segments** when a cart could fit more than one (the higher segment wins), and says **This segment will never get a cart** when a segment above catches all of them. ### Build the follow-up sequence ![The follow-up steps of a segment](/images/abandoned-cart-segment-editor-steps.png) Under **What happens to them** you build the sequence: a list of steps counted from the moment the cart counts as abandoned. Steps go out in the order listed, so a step cannot be timed before the one above it. | Setting | What it does | |---|---| | **After** N hours, send time | When the step is due, optionally held to a time of day | | **send via** | Every step is an email, sent by whoever sends your follow-up emails; the editor names it, for example **Shopify invoice email** or **your Klaviyo flow** | | **Message** | This segment's own message, the store default, or a template picked by name | | **What this step is for** | A label shown on each cart's timeline, never sent to the shopper | | **Subject line (optional)** | Replaces only the message's subject. Any [template placeholder](/abandoned-cart-guide/offer-tests-and-templates#placeholders-you-can-use-in-a-template) is filled in. On a step with no discount, a subject using `{code}`, `{expires}`, `{discount}` or `{plan_price}` is not used, and the message's own subject goes out | | **Offer** | **Same as segment default**, **Plan at full price, no discount**, **Cart items only, no plan**, or **Custom offer**: a **Discount on the plan** (**Plan free**, **Percent off the plan** or **Amount off the plan**) and **Which plan** | | **Default offer for this segment** | What steps set to **Same as segment default** send. Left empty: no discount (the plan at full price, with no code) and the plan from **Settings → Store default plan** | | **The discount code lasts** | Days, counted from when the code is created (1 to 60). Longer for considered purchases. When no step sends a discount it reads **The offer lasts**: the full-price offer ends that many days after it is prepared | | **Control group** | Share of the segment that is not contacted, so what the sequence adds can be measured. Up to 50%; 0 turns it off | | **Segment is on** | On a new segment: off keeps it on the list but it catches no carts. An existing segment is switched on or off from its row in the list | | **Order** | Its place in the list | The editor warns when a later step offers less than an earlier one, because the earlier email's checkout link would then show the smaller offer. ## What you can change in any segment | You can change | Where | How-to | |---|---|---| | Who is in it: cart value, furthest checkout step, has ordered before, marketing consent, email captured, products in the cart (by name), coverable products in cart, chose a plan in checkout | **Who is in it** | [Choose who is in the segment](#choose-who-is-in-the-segment) | | The steps, their timing and send time | **What happens to them** | [Build the follow-up sequence](#build-the-follow-up-sequence) | | The offer on each step: the segment's default, plan at full price, no plan, or your own discount and plan | Each step's **Offer** | [Build the follow-up sequence](#build-the-follow-up-sequence) | | Which plan is attached and the segment's default discount | **Default offer for this segment** | [Choose which plan is attached](/abandoned-cart-guide/offer-rules-and-settings#choose-which-plan-is-attached) | | How long the discount code lasts | **The discount code lasts** (**The offer lasts** when no step sends a discount) | | | The share held back to measure results | **Control group** | [Measure what your sequence adds](/abandoned-cart-guide/results#measure-what-your-sequence-adds) | | The words the segment's shoppers read | **Messages → Templates**, written for this segment | [Write a template](/abandoned-cart-guide/offer-tests-and-templates#write-a-template) | | Its place in the order, or switch it off | The segment list | [Switch a segment off](#switch-a-segment-off) | | Try a different version on half of its new carts | **Follow-ups → A/B tests** | [Test two versions of a sequence](/abandoned-cart-guide/offer-tests-and-templates#test-two-versions-of-a-sequence) | Every segment except **All other carts** can be edited, reordered, switched off or deleted. **All other carts** can be edited and switched off, but not deleted. A deleted segment cannot be brought back, and a deleted automatic segment does not come back on its own. A segment with an A/B test running cannot be deleted until the test ends, and its steps cannot be changed meanwhile; its name, who is in it and its place in the list still can. A new segment starts with one condition (cart value at least 500), one email after 24 hours with no discount, an offer that lasts 7 days and a 10% control group. Change any of it before you save. Unless a segment sets its own plan, steps with an offer attach the plan chosen under **Settings → Store default plan**. If Omnisend gets the offer by **Write to contact properties** (your existing Abandoned checkout automation sends the emails), each cart gets **one** offer on the shopper's contact instead of the email steps: the segment's **Offer on the shopper's Omnisend contact**. The three value segments start with no discount there, so set one if you want those shoppers to get a discount. See [How Omnisend gets the offer](/abandoned-cart-guide/channels#how-omnisend-gets-the-offer). ## See how one segment is doing Press **Insights** on a segment to open its panel. The arrows beside the name step through your other segments, and **Edit the follow-up sequence** takes you back to the segment list, where **Edit** opens the editor. ![A segment's Insights panel](/images/abandoned-cart-segment-insights.png) | Part | What it tells you | |---|---| | **This segment at a glance** | Carts in the last 30 days, the value left in them, the products most often left behind, where shoppers stopped in checkout, where they ship to, when they leave, how many became orders and how many had ordered from you before | | **How soon these carts became orders** | The share that turned into an order within 1, 3, 7, 14 and 30 days of leaving checkout. Carts too new for a bar are left out of it | | **Show follow-up results and store comparison** | Opens the results so far (carts messaged, bought after a message, bought with no message, agreed to marketing, average order), this segment against your whole store, and how the shoppers arrive (where checkout started, discount codes used, items per cart) | | **The people, most recent first** | The shoppers in this segment with their cart value and status. **All their carts** opens the Carts tab | | **Do next** | The one action the data suggests, with its button: for example starting a suggested A/B test, switching the sequence on, or sending a campaign to the segment through your own tool | | **Follow-up sequence** | The segment's steps in short, whether the sequence is on, how long the code lasts, the control group, and how many were sent and recovered | **Campaigns to this segment** sends one message to everyone in the segment at once through your Klaviyo account, on top of the sequence. See [Send a campaign to a segment](/abandoned-cart-guide/channels#send-a-campaign-to-a-segment). ## Related Send each segment's steps when they are due, within your limits. A/B test a segment's sequence and write its messages. See each segment's results week by week against its control group. Choose who sends the emails: Shopify, Klaviyo or Omnisend. --- # FAQs and common issues Source: https://docs.surebright.com/abandoned-cart-guide/faqs-and-common-issues > Find out why an offer didn't go out or a cart looks wrong, and get answers to common questions about sending, discount codes and what SureBright charges. Start with the cart. Open it on the **Carts** tab: its status, the line beside the **Send now** button and its follow-up timeline say in plain words what is happening and why. ## Why an offer didn't go out | What you see | Why | What to do | |---|---|---| | An orange band: *Shopify has not yet let SureBright create discount codes* | Shopify has not given SureBright permission to create discounts in your store, so no offer can be prepared | Sign out of the portal and sign in again through Shopify, or open the SureBright app from your Shopify admin, and approve the permission. See [Let SureBright create discount codes](/abandoned-cart-guide/abandoned-cart#let-surebright-create-discount-codes) | | A blue band: *Sending is not switched on for this store yet* | SureBright has not switched sending on for your store | See [Before you start](/abandoned-cart-guide/abandoned-cart#before-you-start) | | **Send now** is unavailable | The panel says why, for example: no email address on the checkout, no plan picked on any line, no discount code created yet, too soon after the last email, no marketing consent where you require it, or the send limit reached | Fix what it names, or wait until the time it gives | | The cart stays **Ready to prepare** with automatic follow-ups on | It was left before the hours set under **Prepare offers automatically for carts left in the last (hours)** | Open it and press **Prepare offer** | | A step shows **Waiting**, **Held back** or **Paused** | Quiet hours, today's limit on automatic emails, another email reached this shopper recently, or the segment is switched off | Nothing: it goes out as soon as the reason clears. See [Follow each cart on its timeline](/abandoned-cart-guide/automatic-follow-ups#follow-each-cart-on-its-timeline) | | A step shows *Not sent: this shopper has not opted in to marketing emails* | Your **Who can receive an offer** setting, or the shopper's country, requires marketing consent | Nothing, if that is your rule. See [Choose who can receive an offer](/abandoned-cart-guide/offer-rules-and-settings#choose-who-can-receive-an-offer) | | A step shows *Not sent: no plan matches this step's plan choice* | No plan in your store matched the step's plan choice for these products | Pick a plan for a line; the next step goes out with it | | The status line says *Automatic sending is paused by SureBright right now* | SureBright has paused automatic sending | Nothing: your steps stay scheduled and go out once it resumes. If it lasts, write to [support@surebright.com](mailto:support@surebright.com) | | **Not eligible** | The cart did not meet your rules, for example no product in it has protection available, it is worth less than your minimum, or the shopper ordered recently | Read the reason shown beside the status when you open the cart | | **Needs a plan** | The offer was prepared but no plan was attached, for example a fixed term the product does not offer | Press **Add plan** on the line, choose a plan, then **Create discount code** | | **Could not create offer** | The discount code could not be created in Shopify, for example because SureBright is not yet allowed to create discounts | Open the cart, read the reason, fix it, then press **Create discount code**. Carts that failed before you fixed it stay as they are until you do this | | A message shows **Failed** in **Messages → Message log** | The email could not be delivered | Open the row and press **Retry send**. If it is not offered, the row says why | | A connected tool shows **Needs attention** | SureBright cannot reach your tool with the details it has | Open it with **Manage** and follow what the window says. See [Connect a tool](/abandoned-cart-guide/channels#connect-a-tool) | ## Shoppers got two emails Only one sender should write to a shopper about an abandoned cart. If you use Klaviyo or Omnisend for your follow-ups, switch off Shopify's own abandoned checkout email in Shopify, and switch off any abandoned-cart automation in your tool that SureBright does not start. See [Channels and tools](/abandoned-cart-guide/channels#who-sends-your-follow-up-emails). ## Abandoned checkouts with only a plan in them Many abandoned checkouts holding only a protection plan, often at different prices, can be bots testing stolen cards. Low-priced items such as plans attract them. SureBright does not create checkouts on your store. See [Plans in your order tools](/learn/plans-in-your-order-tools) for what to do. ## Common questions Only if you want to. With automatic follow-ups on, SureBright prepares each offer and sends every follow-up when it is due, through the channel you chose, following your offer rules or customer segments and within your limits. With them off, you send each offer yourself, from the cart panel or by selecting carts in the list. Turn them on under **Follow-ups → Automatic follow-ups**. The discount code only applies to the protection plan, never to your own products. The discount comes out of your margin on the plan. SureBright charges you only its cost for the plan, as usual, no matter how much the shopper pays. No. The discount code only applies to the protection plan, never to your own products. The cart gets your offer, and your offer's plan replaces the one they chose, at your discount. If the two are the same plan, the panel tells you the shopper gets that same plan for less. To leave these carts alone, switch on **Leave carts that already have a plan** in Settings. Not until you send again. The cart shows **You changed this, resend** as a reminder. The code ran out before the shopper used it, or the offer was ended. Open the cart and press **Extend by 24 hours**: the shopper keeps the same code for one more day. Then press **Resend now**. If the offer ended because a follow-up without a discount was sent, or the cart reached its send limit, the panel says so instead. With automatic follow-ups off, purchases and expiries are checked when you refresh the Carts list or open a cart. With them on, or when Klaviyo or Omnisend sends your emails, SureBright also checks about every 10 minutes. Each offer is a Shopify draft order with a single-use discount code. See [What you'll see in Shopify](/abandoned-cart-guide/abandoned-cart#what-youll-see-in-shopify). ## Related - [How it works](/abandoned-cart-guide/abandoned-cart) - [Manage carts and offers](/abandoned-cart-guide/carts-and-offers) - [Automatic follow-ups](/abandoned-cart-guide/automatic-follow-ups) --- # Offer rules and settings Source: https://docs.surebright.com/abandoned-cart-guide/offer-rules-and-settings > Set the offer each cart gets on stores without customer segments, and choose your store-wide settings: when a cart counts as abandoned, the default plan, and who can receive an offer. Offer rules decide the discount and the plan each cart gets on stores without customer segments. The **Settings** tab holds the store-wide defaults every store uses: when a cart counts as abandoned, which plan is attached, and who can receive an offer. ## Set your offer rules On stores without customer segments, rules live under **Follow-ups → Offer rules**. Stores with customer segments get their offers from each segment instead; see [Customer segments](/abandoned-cart-guide/customer-segments). A rule answers three questions, in this order: 1. **Which carts qualify.** Does this rule apply to the cart at all? 2. **How big the discount is.** How much of the plan's price you give away. 3. **Which plan is attached.** Which plan each covered product gets. ![Rules tab](/images/abandoned-cart-rules-tab.png) Rules are checked in **priority order**, lowest number first. The **first** rule that matches a cart wins and decides its whole offer. No other rule is looked at. One exception: a rule that tightens the abandonment definition. If the cart fails that rule's stricter definition, the next rule is checked; if the cart hasn't been quiet long enough for it yet, the cart waits. A cart matched by no rule ends up **Not eligible**. Each rule is **Active**, **Paused** or a **Draft**. **Pause** stops it matching new carts; codes it already issued keep working. **Delete** removes it for good. Press **Edit** on a rule, or **+ New rule** to add one. A new rule is saved with **Save and activate**, or **Save draft** to finish it later. ![Rule editor](/images/abandoned-cart-rule-editor.png) ### Name the rule and its discount codes | Field | What it does | |---|---| | **Rule name** | Shown on every cart this rule matches and in the message log. Name it for what it does, for example "Free 3-year cover on TVs" | | **Discount code prefix** | 4 to 12 letters or digits. Every cart gets its **own** code, `PREFIX-XXXXX`, which can be redeemed once. One shopper's code cannot be reused on another cart | ### Choose which carts qualify Four choices. Pick the one that describes who the offer is for. ![Targeting selected products](/images/abandoned-cart-rule-targeting.png) | Choice | The rule applies when… | Use it when | |---|---|---| | **Any eligible product** | The cart holds **anything** you can cover | You want one blanket offer across the store | | **Selected categories** | The cart holds a product in one of the SureBright categories you tick | You want a campaign on a whole product family, such as all TVs | | **Selected products** | The cart holds one of the exact products you search for and add | A campaign on specific items, such as one hero product | | **Cart value floor** | The cart subtotal is at or above the amount you enter | You only want to give a discount on baskets worth recovering | With **Selected products** you search by title or SKU. The rule follows the product itself (the product ID shown beside each name), so renaming a product later does not break the rule. If you choose a targeted option and add nothing, the save button stays disabled and the footer tells you: *"Choose at least one category, product, or a cart floor."* **Selected categories** needs SureBright categories set up for your store. If none are, the editor says so, and you should use **Any eligible product** or **Selected products** instead. ### Choose the discount This is how much of the **protection plan's** price you give away. It never touches your own products' prices. | Choice | The shopper pays | Comes out of your margin | |---|---|---| | **Free protection** | Nothing for the plan | The whole plan price | | **Percent off** | The plan's price minus your percentage (1–100) | That percentage of the plan's price | | **Amount off** | The plan's price minus a fixed sum in your store currency | That fixed sum | The discount code only applies to the protection plan, never to your own products. The discount comes out of your margin on the plan. SureBright charges you only its cost for the plan, as usual, no matter how much the shopper pays. ### Choose which plan is attached Left alone, the rule uses your store default from **Settings**. The closed toggle tells you what that default currently is, for example *"Store default: Default preselected plan, every eligible line."* Turn on **Override the store default for this rule** when this campaign needs a different plan from the rest of the store. ![Plan selection inside a rule](/images/abandoned-cart-rule-plan-selection.png) **Plan strategy** decides how the plan's length is chosen: | Option | What it picks | |---|---| | **Default preselected plan** | The middle term on offer, which is what your product page preselects by default | | **Fixed term** | Exactly the term you choose. A **Term** dropdown appears: 1, 2, 3, 4 or 5 years. A product without that term gets no plan | | **Cheapest plan** | The lowest-priced plan available for that product | | **Longest plan** | The longest term available for that product | **Coverage type** only matters if your store offers both kinds of cover for a product: | Option | Meaning | |---|---| | **Store default** | Use whatever your store setting says | | **Extended protection** | Covers mechanical and electrical breakdown | | **Accidental damage** | Also covers drops, spills and similar accidents | **When several lines qualify** decides which products get a plan when a cart holds more than one that can be covered: | Option | Which lines get a plan | |---|---| | **Every eligible line** | All of them. The most generous, and the most discount you give away | | **Highest-value line only** | Just the most expensive product in the cart | | **Only lines the rule names** | Just the products or categories this rule targets. Other coverable items in the cart are left alone. If the rule uses **Any eligible product** or **Cart value floor** it names no products, so this behaves the same as **Every eligible line** | **Your offer's plan replaces a plan the shopper already chose.** If they had put a 3-year plan in the cart themselves and your rule says "cheapest", the offer carries the cheapest plan instead, longer or shorter. Choose a strategy that suits shoppers who already picked a plan, or switch on **Leave carts that already have a plan** in Settings. ### Set code validity and send limits | Field | What it does | |---|---| | **Discount code valid for** | How long the shopper has to use the code, from **24 hours** to **30 days**, counted from the moment the code is created, not from when you send it | | **Max sends per cart** | 1 to 10. Every email to that cart counts: your own sends, automatic sends and reminders | | **Priority** | Lower wins when a cart matches several rules | | **Tighten the abandonment definition for this rule** | Lets this one rule wait longer, or demand a bigger cart, than your store setting. It can only be **stricter**, never looser | You cannot pause or delete your **only** active rule. With none active, no new cart can be prepared. Add or activate another one first. --- ## Choose your store-wide settings The **Settings** tab holds your store-wide defaults. Each row shows the current choice in one sentence; **Change** opens it and **Done** closes it. Your changes are kept only when you press **Save** in the bar at the bottom of the page; **Discard** drops them. An offer rule or a customer segment can override most of them for its carts. ![The Settings tab](/images/abandoned-cart-settings-overview.png) ### Decide when a cart counts as abandoned ![Abandonment settings](/images/abandoned-cart-settings-abandonment.png) Open **When a cart counts as abandoned**. | Setting | What it does | |---|---| | **Quiet for** | How long a checkout must be quiet before an offer can be prepared. From **30 minutes** to **3 days**; 1 hour by default | | **Reached at least** | Only count carts that reached a given step: **Any step**, **Contact entered**, or **Address and shipping entered**. Later steps mean fewer carts but warmer ones | | **Worth at least** | Ignore small carts. Leave empty to include every value | | **Needs an email** | Carts without one are still captured for your reporting, but nothing can ever be sent to them | | **Leave carts that already have a plan** | Off by default, so these carts get your offer too, and its plan replaces the one the shopper chose. Turn on to leave those carts alone | | **Leave carts with another discount** | Turn on to avoid stacking your recovery code on a promotion already running | | **Leave shoppers who ordered in the last (days)** | Exclude recent buyers. Empty means no exclusion | | **Prepare offers automatically for carts left in the last (hours)** | From 1 to 168 hours. Only used when automatic follow-ups are on. Carts left earlier are not prepared automatically; open one and press **Prepare offer** | Changing these affects carts from now on. Carts you have already prepared keep the offer they were given. ### Choose the default plan Open **Store default plan**. ![The store default plan](/images/abandoned-cart-settings-default-plan.png) It offers the same choices as a rule: **How the plan is picked** (plus **Term** when you choose Fixed term), **Coverage** and **When several lines qualify**. They apply whenever a rule or segment does not say otherwise. Every cart's plan still stays editable per line in the cart panel. If your choice finds no plan for a product, for example a fixed 3-year term the product does not offer, that product gets no plan. Pick one by hand in the cart if you want to add it. **Coverage** here reads **What the product page offers first** rather than "Store default", because at store level there is no higher default to fall back to. On stores with customer segments, **Discount code prefix** sets the start of every code, for example `SBOFFER-`. ### Choose who can receive an offer Open **Who can receive an offer, and how**. ![Who can receive an offer](/images/abandoned-cart-settings-recipients.png) | Setting | What it does | |---|---| | **Who** | **Anyone who left an email**, or **Only with marketing consent**. Choose against your own marketing rules | | **Countries where marketing consent is required** | Type a country's name or code to add it. A shopper shipping to one of these countries who did not opt in to marketing is not emailed, even under **Anyone who left an email** | | **Earliest send time for every segment** | On stores with customer segments: no segment step goes out sooner than this many hours after the cart is abandoned, so shoppers get time to come back on their own. 0 means each segment's own step times apply | | **How** | Who sends your follow-up emails. A Shopify invoice email by default: Shopify sends a checkout link carrying the cart and the already-discounted plan, using Shopify's layout with your subject and message. **Choose who sends your emails** opens [Connected tools](/abandoned-cart-guide/channels) | **Never contact** holds addresses that must never receive an offer, whatever their consent setting. Add them yourself. ### Write what the email says The words your emails use are written under **Messages → Templates**; see [A/B tests and templates](/abandoned-cart-guide/offer-tests-and-templates#write-and-test-your-message-templates). You can always see the exact message on a cart before you send it, and you can send yourself a test email first. ## Related - [Customer segments](/abandoned-cart-guide/customer-segments) - [Automatic follow-ups](/abandoned-cart-guide/automatic-follow-ups) - [Manage carts and offers](/abandoned-cart-guide/carts-and-offers) --- # Offer tests and templates Source: https://docs.surebright.com/abandoned-cart-guide/offer-tests-and-templates > Run an A/B test between two versions of a segment's follow-up sequence and keep the winner, and write, preview and test-send the message templates your follow-ups use. Two screens help you improve your abandoned-cart follow-ups. With **A/B tests** you compare two versions of a segment's follow-up sequence on new carts and see which one recovered more. With **Templates** you write the subject lines and messages your follow-ups send, so a change to the words is made once. A/B tests come with customer segments, which SureBright switches on per store (see [Customer segments](/abandoned-cart-guide/customer-segments)). ## Test two versions of a sequence **Follow-ups → A/B tests** lists tests in four groups: **Running**, **Drafts** (built by you, not started), **Suggested** (built by SureBright from your numbers, each saying what it expects and why) and **Past tests**. Nothing changes for your shoppers until you start a test. ![A/B tests](/images/abandoned-cart-ab-tests.png) ### How an A/B test works A test runs on one segment. **Version A** is the segment's steps as they are. **Version B** is the same steps with what you change. From the moment you start, new carts in the segment are split half and half between the two versions; carts already in a sequence carry on as they were. One test runs per segment at a time. ### Build an A/B test Choose the segment. A test on a segment with a running test is refused. Choose **One thing**, so the result tells you exactly what made the difference, or **A few things together**, for changes you think work best as a set. Then pick what changes: **Offer**, **Send time**, **Subject line**, **Message** or **Add or remove a step**. Each step shows what version A sends now. Only the things you ticked can change; a step added in version B is marked **New step, only in version B**. The editor checks version B against your choice and says what is different, or what you ticked but have not changed yet. **End when each version has a number of carts**, **End on a date**, or both, whichever comes first. Once each version has its carts, no new carts join and the test waits for those carts to finish their steps; on the date it ends at once. Then the numbers freeze and you choose which version to keep. Name it, then **Start A/B test**, or **Save as draft** to keep it as a draft. **New A/B test** opens the editor. Below, version B changes only the **Offer**, so each step shows what version A sends now and lets you pick a different offer for version B. ![Building an A/B test that changes the offer](/images/abandoned-cart-ab-test-editor.png) The line beside the buttons tells you what still needs doing, for example *You picked Offer but version B does not change it yet.* **Start A/B test** stays unavailable until version B is really different from version A. ### Read a running test and keep the winner Each running test shows **Running since** its start date, then one row per version, with how many carts each version has toward its finish line, with **Abandoned carts**, **Contacted**, **Became orders** and **Order value**. The version with the higher share of orders is marked **Ahead so far**. When the test ends, it says which version won, or **No clear winner** and that keeping version A is the safe choice. While it runs you can end it now and decide later (**End now, decide later**), or end it and decide at once (**End and apply "Version B"**, **End and keep Version A (no change)**). After it ends, **Apply "Version B"** makes it the segment's follow-up steps, and **Keep Version A (no change)** leaves them as they are. The chosen version is marked **Kept** in **Past tests**, and the numbers stay there. A test you built can be copied with **Duplicate and edit**. ### Start from a suggested test SureBright proposes tests from your own carts and orders, for example sending the first step inside your store's buying hours instead of a fixed number of hours after abandonment. Each says what it expects and **Why** (*N% of your abandoned carts were left outside that window*). **Start test** opens it to check and start; **Dismiss** removes it for good. With automatic follow-ups off, a test's steps go out only when you send them from each cart, so its results build slowly. Turn them on under **Follow-ups → Automatic follow-ups**. A/B tests are off when Omnisend gets offers by **Write to contact properties**. ## Write and test your message templates ![Messages → Templates](/images/abandoned-cart-templates.png) **Messages → Templates** holds the words each follow-up sends. A follow-up step or a cart can pick a template by name; otherwise SureBright uses the template written for the cart's customer segment, then the default for that purpose. ### What each template purpose is for | Purpose | When SureBright picks it by itself | |---|---| | **Cart abandoned (connected tool)** | Given to a connected tool with its *cart abandoned* event | | **Follow-up without a discount** | A follow-up with no discount, and information campaigns | | **Discount offer** | The first follow-up with a discount, **Send now** on a cart, and discount campaigns | | **Reminder (later follow-ups)** | Later follow-up steps and the reminder before a discount code ends | | **Discount code about to expire** | Given to a connected tool with its *code expiring* event, and last-call campaigns | | **Comparison campaign** | Comparison campaigns only | | **Picked by name only** | Never picked by itself; only when a step or cart names it. No longer offered for new templates | ### Write a template **New template**, or **Edit** on a template card, opens the editor. ![Writing a new template](/images/abandoned-cart-template-editor.png) | Field | What to enter | |---|---| | **Name** | Shown wherever a step or cart picks a template | | **What it is for** | One of the purposes above. **Picked by name only** stays on older templates that have it but cannot be chosen for a new one | | **Type** | **Email** | | **Written for** | **Everyone**, or one customer segment, whose carts use it first | | **Subject** and message | The words. **Insert a placeholder** adds one of the placeholders below | | **Use as the default "…" email** | Makes it the fallback for that purpose, for example **Use as the default "Discount offer" email** | **Insert a placeholder** on the right adds one where your cursor is, in the subject or the message, and says what each one shows when the cart has no value for it, for example *there* for a missing first name. The **Preview** below it fills the template with a sample shopper, product and plan so you can read it as the customer would. Each template card lists where it is **Used in**. A template named by a segment step or by a draft or running A/B test cannot be deleted. ### Placeholders you can use in a template | Placeholder | Fills with | |---|---| | `{first_name}` | The shopper's first name, or *there* | | `{product}` | The covered product's name | | `{plan}` | The plan attached, for example *3-year protection plan* | | `{code}` | The single-use discount code | | `{expires}` | The day the code ends | | `{shop}` | Your store's name | | `{discount}` | What the offer takes off the plan, for example *50% off* | | `{plan_price}` | What the plan costs with the offer | | `{checkout_link}` | The checkout SureBright prepared, with the plan at the offer price | When a step sends no discount, `{code}`, `{expires}`, `{discount}` and `{plan_price}` cannot be filled (and `{plan}` too on a **Cart items only, no plan** step). The template card says so, and SureBright sends its built-in words for that step instead. ### Send yourself a test email The **Send yourself a test** card sends the Shopify invoice email a shopper would get to your own address, using the template you pick under **Which template** or your top offer rule's words. A $1 test item stands in for the cart and no discount code is made, so `{code}` reads *your code*. The draft order it creates in Shopify is tagged **Test** and safe to delete. Only email templates can be test-sent here. If Omnisend gets the offer by **Write to contact properties**, SureBright's templates are not used and **Templates** is hidden. If your Klaviyo flow or Omnisend automation sends the emails from **SureBright: Offer sent**, the template's subject and message travel with that event, and your email shows them only where its template uses those event properties. Test from the tool's window under **Connected tools**; see [Channels](/abandoned-cart-guide/channels). ## Related - [Customer segments](/abandoned-cart-guide/customer-segments) - [Automatic follow-ups](/abandoned-cart-guide/automatic-follow-ups) - [Channels and connected tools](/abandoned-cart-guide/channels) - [Abandoned Cart Recovery](/abandoned-cart-guide/abandoned-cart) --- # Results Source: https://docs.surebright.com/abandoned-cart-guide/results > See what recovery produced and how much of your margin the discounts used, who leaves carts and where, what each segment's follow-ups add week by week, and whether your setup is healthy. **Results → Performance** shows what recovery produced on every store. Stores with customer segments also get the **Overview** tab, **Results → Cohorts** and the **Program health** panel. ## See what recovery earned and cost **Results → Performance** shows what recovery produced, and how much of your margin the discounts used. Switch between **7 days**, **30 days** and **90 days**. On stores with customer segments you can see the whole store or one segment. ![Results tab](/images/abandoned-cart-performance-tab.png) The four figures at the top: | Figure | Meaning | |---|---| | **Recovered order value** | Total value of orders that came back after an offer | | **Warranty revenue attached** | The retail price of the plans those orders kept, before your discount | | **Discount you funded** | Your discounts on plans, taken from your margin | | **Net on warranties** | What shoppers paid for plans, before SureBright's charge | The **Funnel** shows each stage as a share of abandoned carts in the period: abandoned, how many had a product that could be covered, how many got an offer, how many were sent, how many came back, and how many kept the plan. **By rule** (or **By customer segment**) and **By plan term** show which offer and which plan length are actually working. ## See who leaves carts and where The **Overview** tab tells you what your store's carts say and what to try next. ![The Overview tab](/images/abandoned-cart-overview-tab.png) | Panel | What it shows | |---|---| | Four figures for the period | **Abandoned**, **Reachable**, **Recovered** and **Warranty revenue, net** | | **Most money left here** | Where the most money is left, and a button to act on it | | **Who is leaving carts** | Every segment with its carts, value, reachable share, how many became orders and how soon | | **Where and when carts are left** | The checkout step, the hour of day against your buying hours, and the day of week | | **What your carts say** | Findings, each with **What to do** and **How we know** | | **Recommended for your store** | What to try next, each with where to do it | Switch **Abandoned carts** to **Recovery results** to see each segment's recovered carts and value by month. ## Measure what your sequence adds ![Results → Cohorts](/images/abandoned-cart-cohorts.png) **Results → Cohorts** groups abandoned carts by the week they were left (Monday to Sunday) and shows, for each week, how many were **Contacted**, how many were in the **Control group**, how many were **Recovered**, and the share recovered within 3, 7, 14 and 30 days for the follow-up group against the control group. The difference between the two groups is the measured effect of your sequence. Pick the segment and **4**, **8** or **12 weeks** at the top. A row reading *Segment created on …: its follow-ups start here.* marks where the segment's follow-ups begin, and similar rows mark each change. Click a week's name to see what each step did that week: how many shoppers each step was sent to, and how many recovered after it. *Recovered after it* means it was the last step the shopper received before buying, not proof that it caused the purchase; the difference from the control group is the measured effect. ![What each step did in one week](/images/abandoned-cart-cohorts-week.png) **View sequence** beside a week shows the exact sequence that was live then: its version, when it started, what changed, each step with its timing, offer, message and label, how long the code lasted and the control group. ![The sequence that was live in a week](/images/abandoned-cart-cohorts-sequence.png) **Changes to this segment's follow-ups sequence** lists each time you changed the sequence and compares the weeks before and after. Each week is measured on carts recovered within 14 days, so older weeks don't look better just because they've had more time. Weeks with a change part-way through, or an A/B test running, are left out of the comparison. ## Check your setup with Program health ![Program health, opened](/images/abandoned-cart-program-health.png) The **Program health** panel, above your segment list on **Follow-ups → Customer segments**, checks your segments, sequences and connected tools for setups that would send twice, stop sending, or leave results unmeasured. Each finding is a **Blocker**, a **Check** or a **Note** with **Why this matters**. **Who catches what** draws each segment's cart-value range in matching order so you can see where two segments compete for the same carts. All clear reads: no two segments share carts, every step's tool is connected, no step sends an expired code, and only one sender writes to each shopper. ## Related - [Customer segments](/abandoned-cart-guide/customer-segments) - [A/B tests and templates](/abandoned-cart-guide/offer-tests-and-templates) - [FAQs and common issues](/abandoned-cart-guide/faqs-and-common-issues) --- # Claude connector for merchants Source: https://docs.surebright.com/ai-agents/merchant-connector > Connect Claude to your SureBright Merchant Portal account: what you can ask it, how to connect, how every change is previewed and confirmed, and how to disconnect. Connect Claude to your SureBright Merchant Portal account and you can ask it about your sales, invoices, products and plan prices in plain language, and have it make changes for you. Claude shows you a preview of every change and makes it only after you say yes. Anyone on your store's Merchant Portal account can connect. Each person connects under their own sign-in, and Claude acts as that person. ## What you can ask Claude to do | Area | Ask Claude to | With your confirmation, Claude can also | |---|---|---| | Sales | Summarise sales, shipping protection sales and attach rate for a period, list sales, show the cover on an order, and tell you what a cancellation would refund | Correct the covered product on a plan | | Analytics | Show order insights, Warranty Intelligence, plan activation, coverage gaps, widget test results, price performance and the Abandoned Cart report | | | Billing | List your invoices, open one, give you a download link for its PDF, and list your payment methods | Change your default payment method or remove one | | Products and prices | List products and categories, show plan prices, price history and the status of a price publish | Turn protection on or off for a product, set its manufacturer warranty, publish category prices, set a product price | | Leads | List recent orders you could sell a plan on and check a draft order | Quote a plan for a lead, create a draft order, send its payment link, mark it paid | | Order Resolution | List open cases with their order lines and notes, orders missing a contract and orders waiting on a shipment | Answer a case, add a note, keep a case for yourself or hand it back, run a Lightspeed order sync | | Abandoned Cart | List carts and messages and show how the programme is set up | Prepare and send offers, change a cart's plan or discount code, manage rules, templates and connected tools | | Widget | Check whether a product can carry a plan, show your widget settings and preview a design on your own pages | Change the widget's theme, wording, placement and layout in a draft, then publish it or go back to an earlier version | | Account and help | Summarise your store, say which portal features are on, search the Merchant Portal help, and list what has been done through the connector | Update your store's contact details, revoke an API key | If a feature is not switched on for your store, Claude says so and points you to SureBright support. ## Connect Claude to your store The connector's address is: ``` https://mcp.surebright.com/store-admin ``` In Claude, open **Settings → Connectors → Add custom connector**, paste the address above and click **Add**, then **Connect**. A **Sign in to SureBright** page opens. It names the app asking for access and says where you will be sent back to. Either enter **Your Shopify store address** (`your-store.myshopify.com`) and click **Continue with Shopify**, or click **I'm already signed in to the Merchant Portal** to use the portal sign-in you already have open. After the portal sign-in a page asks whether to allow the app, by name, **to read your store** or **to read and change your store**, and names your store. Click **Allow**. **Cancel** sends you back to the app with nothing connected. Back in Claude the connector shows **Connected**. Open its tool list to see what it offers for your account, or just ask Claude about your store. Good to know: - You must sign in with an account that is on the store's Merchant Portal account. Any other sign-in is refused: **Sign in with an account that can open your store's SureBright app.** - A sign-in link that sits unused for ten minutes expires. Start again from the app. - The connector works in Claude on the web and on desktop, and in other AI apps that support remote connectors with sign-in. ### Read only, or read and change The **Allow** page tells you which kind of access you are giving: | The page says | Claude can | |---|---| | **read your store** | Look things up. It is never offered a way to change anything | | **read and change your store** | Look things up and make changes, each one only after you confirm it. This is what Claude asks for | ## How Claude makes a change 1. You ask for a change. 2. Claude shows you a preview of exactly what would change. Nothing has happened yet. 3. You say yes, and Claude makes that change once. If you say no, or do not answer within a few minutes, nothing changes. Claude can only confirm the preview you saw: a confirmation cannot be reused for a different change. Widget changes never reach shoppers straight away. They go into a draft of your widget settings. Claude can show the draft on your own product and cart pages (`preview_design`), publish it after your confirmation (`publish_draft`), throw it away (`discard_draft`) or bring back an earlier version (`rollback_config`). Before new wording is saved, Claude checks it against SureBright's wording rules for the widget (`check_content_compliance`). Asking for coverage on a product or category (`request_coverage`) sends a request for SureBright to review; it does not grant coverage. SureBright can switch changes off, for all stores, for one store or for one kind of change, without notice, for example while a change is under review. Looking things up continues to work. ## What Claude cannot get - **Bulk export files.** The sales export and the billed-orders export are not offered through the connector. Download them from the Merchant Portal. - **Links that work without a sign-in**, such as a bank account's verification page. These are removed from Claude's answers. Shoppers' names, notes and product text that appear in results are treated as information, never as instructions to Claude. ## Disconnect Claude from your store In Claude, open **Settings → Connectors**, choose the SureBright connector and remove it. Claude's access to your store ends. Reconnecting starts the sign-in again. Each connection is separate. If you connected from a second app, or a colleague connected under their own sign-in, remove each one on its own. ## Troubleshooting | You see | Do this | |---|---| | The tool list looks out of date | Claude remembers a connector's tools. Open the connector's menu in **Settings → Connectors** and choose **Refresh tools list** | | A change did not happen | Check that you confirmed the preview; the first step only shows what would change. Claude may also ask for your approval before it makes a change. Approve it and ask again | | Claude cannot connect to a store (`connect_store` is refused) | The account you signed in with is not on that store's Merchant Portal account, or the store is not yet set up in SureBright | | Widget tools say the store is not set up | Your store has no widget set up in the Merchant Portal's **Widget Studio** yet. Set it up there first | ## Connector tools by area Claude names the tool it is using. This table tells you what each one belongs to. Tools in the last column make a change and always ask for your confirmation first. | Area | Looks things up | Makes a change | |---|---|---| | Account | `get_store_summary` | `update_store_contact` | | Billing | `list_invoices`, `get_invoice`, `get_invoice_pdf`, `list_payment_methods` | `update_default_payment_method`, `delete_payment_method` | | Developers | `list_api_keys` | `delete_api_key` | | Analytics | `get_sales_summary`, `get_shipping_summary`, `get_order_insights`, `get_warranty_intelligence`, `get_warranty_activation`, `get_coverage_gaps`, `get_widget_experiments`, `get_pricing_performance`, `get_cart_recovery_report` | | | Sales | `list_sales`, `get_cancellation_refund_quote`, `list_shipping_contracts`, `get_order_coverage` | `update_covered_product` | | Products and prices | `list_products`, `get_plan_prices`, `list_categories`, `get_category_prices`, `get_price_publish_status`, `list_price_history` | `update_product_warranty_status`, `update_manufacturer_warranty`, `update_category_prices`, `update_product_price_override` | | Leads | `list_leads`, `get_draft_order_status` | `create_lead_quote`, `create_draft_order`, `send_draft_order_invoice`, `update_draft_order_paid` | | Order Resolution | `list_resolution_cases`, `list_case_order_lines`, `list_case_notes`, `list_missing_contracts`, `list_pending_fulfillment`, `list_lightspeed_pending_warranties` | `update_case_answer`, `update_case_hold`, `create_case_note`, `create_lightspeed_order_sync` | | Abandoned Cart | `list_carts`, `get_cart`, `list_cart_messages`, `get_recovery_setup`, `check_abandonment_rule` | `update_cart_line_plan`, `update_cart_offer`, `create_cart_offer`, `send_cart_offer`, `send_bulk_cart_offers`, `update_discount_code`, `cancel_cart_follow_up`, `send_message_retry`, `send_access_request`, `update_recovery_settings`, `update_offer_rule`, `delete_offer_rule`, `update_message_template`, `delete_message_template`, `update_tool_settings`, `delete_tool_connection`, `send_test_message` | | Features and help | `get_store_features`, `search_help_articles` | | | Widget | `connect_store`, `get_integration_status`, `resolve_product`, `check_product_support`, `check_coverage`, `get_coverage_request`, `get_widget_config`, `get_change_history`, `get_draft_diff`, `list_design_presets`, `preview_design`, `check_content_compliance` | `update_widget_theme`, `update_widget_content`, `update_widget_placement`, `set_widget_layout`, `update_cart_widget`, `apply_design_preset`, `publish_draft`, `discard_draft`, `rollback_config`, `request_coverage` | | Connector | `get_connector_activity` | | The lookup tools answer with the same figures and records the Merchant Portal shows, including the portal's own notes on how each figure is counted. `get_invoice_pdf` returns a download link that works for a limited time. `get_connector_activity` lists every call made through the connector for your store: who, which tool, when, and the outcome. ## Related The assistant inside the Merchant Portal. What each section of the portal is for. The connector is a remote MCP server with OAuth sign-in, so it also works in any MCP client that supports OAuth. The read permission is the `store.read` scope and is always granted; the change permission is `store.write` and is granted when the client asks for it. A client without `store.write` is never shown a change tool. Every change tool takes an extra `confirm_token` argument: called without it, the tool returns a preview and a token; called again with the same arguments and the token, it makes the change. A token stands for exactly that preview, lasts a few minutes and works once. Dates in tool inputs are `YYYY-MM-DD` in the store's day. Removing the connector revokes the connection, and the access and refresh tokens issued for it stop working. --- # AI agents Source: https://docs.surebright.com/ai-agents/overview > What SureBright exposes to AI agents today: a Claude connector for merchants, purchase connectors for ChatGPT and Muse, and WebMCP tools in the storefront SDK, with the status of each. SureBright exposes three surfaces to AI agents. One is for you, the merchant, and two are for shoppers. All three speak the Model Context Protocol (MCP) or its in-page variant, WebMCP, so an assistant calls named tools rather than scraping pages. This page says what each surface does and which are live. Connect Claude to your Merchant Portal account and ask about sales, billing, products and the widget, or make changes with a confirmation step. ChatGPT and Muse call SureBright tools to quote and sell a plan for a product a shopper already owns, handing off to a SureBright checkout. The SureBright SDK on your storefront registers page tools a browser agent can call to quote protection and add it to the cart. ## At a glance | Surface | Who calls it | What it can do | Status | |---|---|---|---| | Claude connector for merchants | You, from Claude or any MCP client with OAuth sign-in | Read your Merchant Portal data; preview and confirm changes; edit and publish the widget's design | Live | | Purchase connectors for ChatGPT and Muse | AI assistant platforms, with a key from SureBright | Quote a plan for a product the shopper owns, read a receipt, hand off to a SureBright checkout page, report status | Early access | | WebMCP storefront tools | Browser agents on your storefront | List protection plans for a product or the cart's shipping protection; add a chosen plan to the cart | Early access, enabled per store | ## How they fit together **Merchant side.** The Claude connector sits in front of the same Merchant Portal your team signs in to. It reads what the portal shows and changes what the portal lets you change, under your own sign-in and with a preview-and-confirm step before every change. It does not see shoppers' sessions and it is not visible on your storefront. **Shopper side, off your store.** The purchase connectors serve a shopper who is already talking to ChatGPT or Muse about a product they own. The assistant quotes a SureBright plan and hands the shopper to a SureBright checkout page; the plan is then activated with a receipt, the same way a SureBright Anywhere purchase is. Your store is not involved. **Shopper side, on your store.** WebMCP tools live inside the SureBright SDK that already renders your widget. When a browser agent is shopping on your storefront on the shopper's behalf, the tools let it see the same plans the widget offers and add the one the shopper picks, with the same quote and cart lines the widget would create. Attribution to your store is unchanged. ## Shared rules - **Read before write.** Every surface separates reading (quotes, lists, status) from acting (adding to a cart, starting a checkout, changing a setting). Reading tools are marked read-only to the agent. - **A person decides.** A plan is added or bought only after the shopper chooses it; a merchant change is made only after you confirm the preview. The agent cannot skip the step. - **Data is data.** Product titles, notes and page content returned by a tool are treated as information, never as instructions to the agent. - **Nothing new to install.** The merchant connector is a URL you add to Claude. WebMCP ships inside the SDK you already load and is switched on per store. The purchase connectors are hosted by SureBright for the assistant platforms. ## What is not exposed - No surface sells a plan without a person choosing it, and none bypasses your store's own pricing or coverage rules: an agent sees the plans your widget would show, at the prices it would show them. - The merchant connector does not offer bulk exports of sales or billed orders, and strips links that act for your store without a sign-in. - The purchase connectors do not take card details; payment happens on a SureBright checkout page. - WebMCP tools do not write to the cart on their own; `add_protection_to_cart` runs only when the agent calls it with a plan the shopper picked. ## Which page to read | You want to | Read | |---|---| | Ask Claude about your sales, invoices or widget | [Claude connector for merchants](/ai-agents/merchant-connector) | | Understand what a shopper sees when ChatGPT or Muse offers a SureBright plan | [Purchase connectors](/ai-agents/purchase-connectors) | | Know what a browser agent can do on your storefront | [WebMCP storefront tools](/ai-agents/webmcp) | | Know where a plan sold by an agent ends up for the shopper | [Customer portal](/customer-portal/overview) | ## Asking for access The Claude connector is open to any store's Merchant Portal account. For WebMCP on your storefront, or to integrate an assistant platform with the purchase connectors, ask your SureBright contact. --- # Purchase connectors for ChatGPT and Muse Source: https://docs.surebright.com/ai-agents/purchase-connectors > How an AI assistant platform sells a SureBright plan for a product a shopper already owns: the tools it calls, the order they run in, the statuses a purchase moves through, and the hand-off to a SureBright checkout page. Early access. Ask your SureBright contact to enable this for your store. SureBright runs MCP connectors for ChatGPT and for Muse. A shopper who tells the assistant about a product they bought can get a SureBright protection plan quoted, read from a receipt, and bought, without leaving the conversation until payment. Payment and activation then follow the same path as a SureBright Anywhere purchase. This page is for assistant platforms integrating a connector and for merchants who want to know what the shopper experiences. The connectors are hosted by SureBright; each platform is registered with its own key and calls the tools below by name. ## The flow The assistant calls `quote_protection` with what it knows about the product: title, category, price paid, country and currency, purchase date, condition, manufacturer and the manufacturer warranty. Missing details come back as a status asking for them. The reply lists the plans available, each with its term and price, and a reference to the purchase in progress. `show_protection_options` renders the plans to the shopper as a card inside the assistant, so the shopper picks from what SureBright quoted rather than from text the model wrote. When the shopper has a receipt, `upload_receipt` sends it (PDF, PNG, JPEG or WebP) and SureBright reads the products, prices and purchase date from it. The quote is re-run on what the receipt says. A receipt is what activates the plan later, so uploading it here saves the shopper a step. On ChatGPT, `create_checkout_handoff` returns a SureBright checkout page for the chosen plan. The shopper pays there, through Stripe Checkout, and the assistant never handles card details. On Muse, `prepare_purchase` and `purchase_protection` complete payment inside the assistant. `get_purchase_status` reports where the purchase stands and what the shopper can do next. `cancel_pending_purchase` (Muse) abandons a purchase that has not been paid. ## Tools | Tool | ChatGPT | Muse | Purpose | |---|---|---|---| | `quote_protection` | Yes | Yes | Quote plans for one product, from typed details or from a receipt line. Starts or updates a purchase in progress. | | `show_protection_options` | Yes | | Display the quoted plans to the shopper as a card. | | `upload_receipt` | Yes | Yes | Send a receipt for SureBright to read; the product details and purchase date are taken from it. | | `create_checkout_handoff` | Yes | | Return the SureBright checkout page for the chosen plan. | | `prepare_purchase` | | Yes | Prepare an in-assistant payment for the chosen plan. | | `purchase_protection` | | Yes | Complete the in-assistant payment. | | `get_purchase_status` | Yes | Yes | Where the purchase stands, and the next actions available. | | `cancel_pending_purchase` | | Yes | Abandon an unpaid purchase. | A tool called on a platform that does not offer it is refused as not available for that channel. Quoting and reading a receipt never charge the shopper; only the checkout hand-off or the Muse payment does. ## Purchase statuses `get_purchase_status` and the write tools report one of these. | Status | Meaning | What the assistant does | |---|---|---| | `needs_product_details` | Required product details are missing or unclear. | Ask the shopper and quote again. | | `needs_category_choice` | The product fits more than one category. | Offer the choices and quote again. | | `needs_receipt_item` | The receipt lists several products; one must be chosen. | Ask which product to protect. | | `receipt_conflict` | The receipt disagrees with the details given. | Ask the shopper to accept the receipt's details or correct them. | | `unsupported_market` | The purchase is outside the United States and Canada. | Explain that plans are not sold there. | | `no_offers` | No plan is available for this product. | Explain that it cannot be covered. | | `quoted` | Plans are available. | Show the options; hand off when the shopper chooses. | | `displayed` | The options card was rendered. | Wait for the shopper's choice. | | `requires_review` | SureBright must look at the purchase before it can go ahead. | Point the shopper to SureBright support. | | `cancelled` | The purchase was abandoned. | Start again if the shopper wants to. | A purchase that has been handed off to checkout is locked: quoting again or changing the product is refused until the checkout is checked. Every write carries a request key so a retried call returns the saved answer rather than doing the work twice; the same key with different inputs is refused. ## After payment Payment lands the shopper on a SureBright confirmation and SureBright emails the coverage terms and claim instructions. The plan is active once SureBright holds a matching receipt: immediately when one was uploaded during the conversation, otherwise after the shopper uploads it in the [customer portal](/customer-portal/overview), where reminder emails and the **Activate** step work exactly as for Anywhere. Plans sold this way are not attributed to any merchant store. ## Eligibility the shopper sees The same rules as SureBright Anywhere apply: purchases in the United States or Canada only, a plan bought within 90 days of the product's purchase date (30 days for accidental damage plans), a product category SureBright covers, and a manufacturer warranty on the product. ## Status of the connectors Both connectors are deployed and answer the tool list above. Live purchases through them are not yet switched on in production, and Muse's in-assistant payment is available in SureBright's test environment only. Platform teams who want to integrate, and merchants who want to know when plans sold this way can be tied to their store, should ask their SureBright contact. --- # WebMCP storefront tools Source: https://docs.surebright.com/ai-agents/webmcp > The page tools the SureBright SDK registers on your storefront for browser agents: what each tool returns, how a plan is added to the cart, and how to switch it on. Early access. Ask your SureBright contact to enable this for your store. WebMCP lets a web page offer tools to an AI agent running in the shopper's browser, through `document.modelContext`. When WebMCP is switched on for your store, the SureBright SDK that already renders your widget registers three tools: two that read protection options and one that adds a chosen plan to the cart. An agent shopping on your storefront can then offer SureBright protection the same way the widget does, with the same quotes, the same cart lines and the same attribution to your store. There is nothing to install. The tools ship inside the SDK; SureBright turns them on per store. They are off by default. ## Where the tools appear The tools follow your widget's own offering, so an agent never sees a plan the widget would not show. | Tool | Registered when | |---|---| | `get_product_protection_options` | Product protection is on for your store, or the page is a post-purchase page | | `get_shipping_protection_options` | Shipping protection is on for your store | | `add_protection_to_cart` | Either of the above | The SDK registers the tools at page load and keeps trying for ten seconds, because the page's WebMCP support can arrive after the SDK does. On Shopify, Shopify's own WebMCP tools (search, product, cart) run alongside SureBright's. The SDK recognises a cart write made by Shopify's agent tools and does not treat it as the shopper's own, so the widget does not fight the agent. Today the tools are called by browser agents that implement the WebMCP draft, which Chrome ships as an origin trial on Shopify storefronts. Which assistants actually use page tools changes quickly; expect few calls while the standard settles. ## Tools ### get_product_protection_options Read-only. Quotes SureBright plans for one product through the widget's own quote path. Pass `product_handle` and `variant_id` for a product, a cart item's `variant_id` alone, or nothing for the product page's current variant. On a post-purchase page with no input it lists the order's items. | Reply field | Meaning | |---|---| | `status` | `ok`, `not_eligible` or `temporarily_unavailable` | | `product` | The product title | | `plans` | One entry per plan: `plan_id`, `term_years`, `price`, `currency`. Prices are per unit in the shopper's currency; with 2 units in the cart the plan adds 2 × price. | | `is_bundle`, `covers` | For a bundle product, one plan covers the whole bundle; `covers` lists the components. | | `coverage_summary` | Up to six lines of what the plan covers | | `terms_url` | A link to the plan's terms | | `note` | A reminder to the agent that the plan is optional and is added only if the shopper chooses it | ### get_shipping_protection_options Read-only. Returns the one shipping protection plan for the current cart, which covers the whole order against loss, theft and damage in transit. Takes no input. | Reply field | Meaning | |---|---| | `status` | `ok`, `not_eligible`, `declined`, `cart_empty` or `temporarily_unavailable` | | `plan_id`, `price`, `currency` | The plan to add and what it costs, in USD | | `covers` | The cart items the plan protects | | `coverage_summary` | Up to six lines of what the plan covers | | `is_in_cart` | Whether shipping protection is already in the cart | | `reason` | When declined: `cart_value_over_limit`, `no_eligible_items` or `not_offered_for_this_cart` | The price follows the cart. An agent should call this again after the cart changes. ### add_protection_to_cart Consequential. Adds a plan the shopper chose, by a `plan_id` from one of the two reading tools. A product plan needs its product in the cart first and covers each unit of it; on a post-purchase page it covers the units bought. Adding a different term for a product that already has a plan replaces the existing plan and says so. Shipping protection is one plan for the order; if the cart changed since it was quoted, nothing is added and the new plan comes back to confirm. | `status` | Meaning | |---|---| | `added` | The plan is in the cart. The reply gives `quantity`, `plan_total` and `currency`. | | `already_present` | The same plan was already in the cart. | | `replaced` | A different plan for the product was swapped out; `replaced_plan` describes it so the agent can tell the shopper. | | `product_not_in_cart` | Add the product first, then call again with the same `plan_id`. | | `price_changed`, `coverage_changed` | Shipping only: the cart changed, so the plan did. Confirm the new `price` and `covers` with the shopper, then call again with the returned `plan_id`. | | `unknown_plan` | The `plan_id` is not from a current quote. Call the reading tool again. | | `invalid_input` | `plan_id` is missing or not a string. | | `not_eligible` | The plan can no longer be offered. | | `remove_unconfirmed` | The new plan is in the cart but the previous one may still be there. | | `failed` | The cart write did not land; `reason` says why. `cart_busy` means the shopper's own cart update is in flight; try again shortly. | | `cancelled` | The agent aborted the call. | | `temporarily_unavailable` | The quote service did not answer. | Adds run one at a time, so two agent calls cannot race each other or the shopper's own cart changes. ## What the shopper sees A plan added by an agent is a normal SureBright line in the cart, priced and labelled as the widget would price and label it, and it checks out like any other. The SDK records the add with the source WebMCP, so it can be told apart from a plan the shopper added through the widget. When Shopify's own agent tools add a product to the cart on a product page and the product has no plan yet, the SDK offers the shopper a plan in the widget's coverage modal once the add has landed, one product at a time, and never over an offer the shopper opened themselves. The shopper decides as usual. ## Switching it on Ask your SureBright contact to enable WebMCP for your store. No theme or checkout change is needed. To check it is on, open your storefront in a browser that supports WebMCP with the SDK's debug logging on: the SDK logs `Tools registered` with the three tool names when the flag is on, and `WebMCP disabled for this store` when it is off. --- # Use these docs with AI assistants Source: https://docs.surebright.com/api-reference/ai-assistants > Feed the SureBright docs to an AI assistant or coding agent: llms.txt, the full-text llms-full.txt, a Markdown version of every page, and the OpenAPI spec. Every page on docs.surebright.com is also published in forms an AI assistant or coding agent can read directly. Point your tool at one of them instead of pasting pages in by hand. ## What is available | File | What it holds | Use it for | |---|---|---| | [`/llms.txt`](/llms.txt) | An index of every page with a one-line summary, starting with the pages to read first | Letting an agent pick the pages it needs | | [`/llms-full.txt`](/llms-full.txt) | The text of every page in one file | Giving an assistant the whole docs in one go | | `.md` | The Markdown source of one page. Add `.md` to any page URL, for example [`/api-reference/authentication.md`](/api-reference/authentication.md) | Giving an assistant one exact page | | [`/api-reference/openapi.json`](/api-reference/openapi.json) | The OpenAPI spec for the public endpoints | Generating a client or letting an agent check request and response shapes | On every page, the **Copy page** menu copies the page as Markdown, opens the Markdown version, or opens the page in ChatGPT with a prompt to read it. ## Examples **In a coding agent** (Claude Code, Cursor, GitHub Copilot and similar), give the index and the spec in your prompt: ```text Read https://docs.surebright.com/llms.txt and https://docs.surebright.com/api-reference/openapi.json. Then write a server-side function that gets SureBright quotes for a product by category and price, and another that creates contracts for a paid order with isTestOrder set to true. ``` **In a chat assistant**, link the page you have a question about: ```text Using https://docs.surebright.com/merchant-portal/how-billing-works.md, explain what SureBright invoices me for and when. ``` ## Keep the agent honest - Point it at [Authentication](/api-reference/authentication) first: only the Order endpoints need a key, and there is no sandbox, so test orders must carry `"isTestOrder": true`. - Keep API keys out of prompts and out of browser code. Order calls belong on your server. - If an answer disagrees with a docs page, the docs page is right. Tell us at [support@surebright.com](mailto:support@surebright.com) if a page is unclear. --- # Authentication Source: https://docs.surebright.com/api-reference/authentication > Learn how to authenticate your requests to the SureBright API ## Overview Only the **Order** endpoints under `/partner/api/v1/order` need credentials. They accept a merchant API key in the `X-SureBright-Access-Token` request header. [Set or revert fulfillment dates](/api-reference/endpoint/order/fulfillment) is separate: it takes its own server-to-server token, described on that page. Quote endpoints (`/quote/api/quote/...`, `/quote/api/whole-system/listQuotes`) and the store category endpoint (`/quote/api/storeCategory/listStoreCategories`) are public: they take no credentials and do not read `X-SureBright-Access-Token`. Do not add an `Authorization` header to these calls; a request that carries one can be answered `401`. | Type | API key | |------|---------| | Header | `X-SureBright-Access-Token` | | Key format | `sb_live_` followed by a random secret. This is the only prefix; see [Live keys and testing](#live-keys-and-testing) | 🔒 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. All API requests must be made over HTTPS. Requests sent over plain HTTP will be rejected. ## Getting a key Keys are self-serve in the **SureBright Merchant Portal**, on the **Developers** page (also linked from the **Developers and API** card under **Settings** once the Developer API is enabled on your account): Enter a label (for example "Production server") and click **Generate new key**. The full key is shown once, in a one-time reveal dialog with a copy button. After you close it, the portal only ever shows a masked form (`sb_live_abc123••••••••wxyz`), so copy it to your secret store first. **Rotate** revokes the existing key immediately and issues a new one with the same label. The new key is shown once, like a freshly created key. **Revoke** disables a key immediately. Requests made with a revoked key return `401`. A key is scoped to your SureBright account (all stores under the same store parent). Merchants onboarded with a SureBright Integration Kit can keep using the access token issued in that kit; it is accepted in the same header. ## Live keys and testing Every key created on the **Developers** page starts with `sb_live_`. There is no separate development or test key, and no sandbox mode that a key switches on. | You want to | What to do | |---|---| | Check your ids and see real responses without writing data | Call the category and quote endpoints. They need no key. The **API playground** on the **Developers** page runs them against your store. | | Try the Order endpoints without recording a real sale | Send `"isTestOrder": true` in the order body. The order is recorded as a test order and its rows carry a **Test** badge on **Sales**. | | Work against a staging environment | Staging and production use different hosts and different keys. Ask your SureBright contact for the staging host and credentials. | A request made with an `sb_live_` key reaches your live account. Without `isTestOrder`, **Record an order** in the playground and `POST /partner/api/v1/order` from your server both create real contracts. On a test order, put an email address you control in `customerDetails.customerEmail`, because order emails can still be sent. ## Example Request ```bash curl -G https://{HOST_NAME}/partner/api/v1/order \ --data-urlencode 'storeId={storeId}' \ --data-urlencode 'partnerOrderId={orderId}' \ -H 'Accept: application/json' \ -H 'X-SureBright-Access-Token: sb_live_YOUR_API_KEY' ``` This is the read-only lookup, [Get Contracts for Order](/api-reference/endpoint/order/get-contracts), so it is safe to run while you check a key. A `401` means the key was not accepted. A `404` with `errorCode: ORDER_NOT_FOUND` means the key was accepted and there is no such order yet. `POST` and `PUT` on the same path take the same header plus `Content-Type: application/json`. Send the key, or your Integration Kit token, in `X-SureBright-Access-Token` only. The Order endpoints do not accept an API key in an `Authorization` header, so leave that header out. See [Request conventions](/api-reference/endpoint/order/request-conventions) for the rules the Order endpoints share. ## Errors | Status | Body | Cause | |--------|------|-------| | `401` | `{"message": "Unauthorized! x-surebright-access-token header is required."}` | Header missing | | `401` | `{"message": "Unauthorized! Invalid or revoked API key."}` | Key unknown, or revoked / rotated | | `401` | `{"message": "Unauthorized! Invalid token."}` | Integration-kit token not recognised | | `401` | `{"message": "Unauthorized! Invalid or expired token.", "error": "..."}` | Integration-kit token malformed or expired | The whole system warranty endpoints answer a missing header with `{"isError": true, "errorType": 401, "message": "X-SureBright-Access-Token header is required"}` instead. ## Required Credentials To call the Order endpoints you need: - `storeId` – shared as part of the SureBright Integration Kit - `X-SureBright-Access-Token` – created on the Merchant Portal Developers page (or issued in the Integration Kit) - `HOST_NAME` – the SureBright API host. The production host is `api.surebright.com`, as shown in the curl snippet of the **API playground**. The staging host is shared by your SureBright contact or in the Integration Kit. ## Related - [Developers: API keys and playground](/merchant-portal/developers) - [Integrate with the API](/api-reference/integration-tutorial) - [Request conventions](/api-reference/endpoint/order/request-conventions) - [HTTP status codes](/api-reference/http-status-codes) --- # 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. `POST https://{HOST_NAME}/partner/api/v1/order/whole-system/cancel?contractId={contractId}` Use this endpoint to cancel a whole-system contract, the one created by [Create / Update Contracts for Whole System Warranty](/api-reference/endpoint/order/create-contract-whole-system-warranty). You identify it by the `contractId` that call returned. Contracts created through `POST /partner/api/v1/order` are not cancelled here. Cancel those by lowering the line's quantity with [Cancel / Update contracts for Order](/api-reference/endpoint/order/update-contract). ## Headers | Header | Description | Required | |--------|-------------|----------| | X-SureBright-Access-Token | Access token for authentication | Yes | ## Overview This endpoint cancels the warranty contract for a whole system order. It takes the contract ID and, optionally, a reason. You send the same request for every contract. Which rule applies depends on how the contract was created: | The contract was created | When you can cancel it | Who can cancel it | |---|---|---| | With your own key, under your own account | Within 30 days of the date its order was created. After that the request returns `505` | The account that owns the contract. Another account's key gets `503` | | By a platform for a connected installer, with `sbAccountId` | While the contract is active. There is no 30-day limit. The request is refused while the contract has an active claim, or when no refund is due on it | The platform that created it, while the installer's connection is active and still grants `sales.write` for that location | For the second case see [Creating for a connected installer](/api-reference/endpoint/order/create-contract-whole-system-warranty#creating-for-a-connected-installer). ## Request | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `contractId` | query | string | Yes | The contract to cancel, as returned by **Create / Update Contracts for Whole System Warranty**. | | `cancellationReason` | body | string | No | Free-text reason. Recorded for contracts created for a connected installer. Ignored for contracts created with your own key. | No other body is needed. The contract ID goes in the query string, not in the body. A platform does not send `sbAccountId` or `sbStoreId` here: the contract already records which installer and location it belongs to. ## Example request ```bash curl -X POST 'https://{HOST_NAME}/partner/api/v1/order/whole-system/cancel?contractId={contractId}' \ -H 'Accept: application/json' \ -H 'X-SureBright-Access-Token: sb_live_YOUR_API_KEY' ``` ## Example response `200`: ```json { "isError": false, "cancelledContractId": "5233a92bfcc04a77920abfa1fe52194a" } ``` | Field | Type | Meaning | |-------|------|---------| | `isError` | boolean | `false` when the contract was cancelled. Check it on every `200`, because some failures are also returned with `200`. | | `cancelledContractId` | string | The contract that was cancelled. Same value as the `contractId` you sent. | | `message` | string | Present when `isError` is `true`. See **Errors**. | ## Errors ### Contracts created with your own key Errors raised before the cancellation is attempted have this shape, with `errorType` equal to the HTTP status: ```json { "isError": true, "errorType": 505, "errorCode": "CANCELLATION_WINDOW_EXPIRED", "message": "Contract can be cancelled only within 30 days from order creation date" } ``` | Status | `errorCode` | `message` | Cause and what to do | |--------|-------------|-----------|----------------------| | `400` | `CONTRACT_ID_REQUIRED` | `contractId is required` | Add `contractId` to the query string. | | `401` | | `X-SureBright-Access-Token header is required` | The key is missing. A key that is not valid returns the bodies listed on [Authentication](/api-reference/authentication). | | `504` | `CONTRACT_NOT_FOUND` | `contract not found` | No contract has that ID. Check that you are sending the `contractId` from the create response. | | `503` | `CONTRACT_ACCESS_DENIED` | `contract access denied` | The contract does not belong to your account. Use the key of the account that created it. | | `505` | `CANCELLATION_WINDOW_EXPIRED` | `Contract can be cancelled only within 30 days from order creation date` | The 30-day window has passed. Ask your SureBright contact. | | `505` | `CANCELLATION_WINDOW_EXPIRED` | `Something went wrong` | The contract has no readable order creation date, so the window cannot be checked. Ask your SureBright contact. | | `200` | | `Contract already cancelled` | `isError` is `true`. The contract was cancelled earlier; treat it as done. | | `200` | | `Contract cancellation failed to persist` | `isError` is `true`. The contract is still active. Send the request again. | | `502` | | `Something went wrong` | SureBright could not complete the request. Send it again. | | `500` | | `Internal Server Error` | Unexpected failure. Send it again. | `503`, `504` and `505` are application codes on this endpoint, not gateway errors. Read the `errorCode` in the body before you retry: only `502` and `500` are worth retrying unchanged. ### Contracts created for a connected installer These bodies carry `isError: true`, a `message` and, where shown, a `code`. The `505` window error does not apply to these contracts. | Status | `code` | `message` | Cause and what to do | |--------|--------|-----------|----------------------| | `403` | | `Store integration is inactive` | The installer has disconnected your platform. Ask the installer to connect again, or to cancel the plan in their portal. | | `401` | `invalid_api_key` | `Partner authentication failed` | The key does not belong to the platform that created the contract. Use that platform's key. | | `403` | `insufficient_scope` | `The sales.write scope is required` | The installer no longer grants `sales.write`. Ask the installer to approve again. | | `403` | `access_denied` | `The selected location is not authorized` or `The selected location is not active` | The contract's location is no longer approved for your platform, or is no longer active. | | `403` | `access_denied` | `The merchant authorization is no longer active` | The person who approved the connection is no longer an active owner or administrator. Ask a current owner or administrator to connect again. | | `403` | `PARTNER_CONTRACT_ACCESS_DENIED` | `Contract is not available to this connection` | The contract does not belong to this connection and location. | | `400` | | `Contract has already been cancelled` | Treat it as done. | | `400` | | `Refund not available. An active claim exists for this contract.` | The contract has an active claim. It cannot be cancelled until the claim is closed. | | `400` | | `Sorry, you are not eligible for a refund` | No refund is due on the contract, for example because it has reached its end date. It is not cancelled. | | `400` or `500` | | `Something went wrong. Please try again later` | The contract could not be cancelled. Check the `contractId`, then send the request again. | | `502` | | `Unable to reach the target service` | Send the request again. | | `503` | | `Merchant authorization is unavailable` | SureBright could not check the connection. Send the request again. | A successful cancellation of a connected installer's contract returns the same `200` body as above, with `isError: false` and `cancelledContractId`. ## Behaviour notes - **One contract covers the whole system.** A whole-system sale is a single contract that covers every line item on the proposal. There are no separate per-product contracts to cancel, so cancelling the contract ends cover for all of its line items at once. - **No partial cancellation.** You cannot cancel one covered product here. To change which products are covered, update the contract through [Create / Update Contracts for Whole System Warranty](/api-reference/endpoint/order/create-contract-whole-system-warranty), within the limits described on that page. - **The 30-day window** applies to contracts created with your own key. It is counted from the date and time the contract's order was created, which for a whole-system contract is when you first created it. After that the request returns `505`. Contracts created for a connected installer have no 30-day window. - **Cancelling twice is harmless.** The second call returns `200` with `isError: true` and `Contract already cancelled`, or `400` with `Contract has already been cancelled` for a connected installer's contract. - **The customer is told.** SureBright normally emails the customer a cancellation confirmation. ## Related The whole flow for platforms and installers. Create the contract, or change its covered products. Price a whole-system plan for a proposal. Cancel ordinary order contracts. Credentials and rules shared by the Order endpoints. --- # 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`. `POST https://{HOST_NAME}/partner/api/v1/order` Use this endpoint to record an order on which you sold protection plans through your own checkout or sales tool. You send the order, its line items and, for each covered line, the plan the customer bought. SureBright creates one contract per covered unit and returns the contract IDs. Send an order here the first time. To change quantities or cancel plans later, use [Cancel / Update contracts for Order](/api-reference/endpoint/order/update-contract). To read back what exists, use [Get Contracts for Order](/api-reference/endpoint/order/get-contracts). Whole-system sales have their own endpoint, [Create / Update Contracts for Whole System Warranty](/api-reference/endpoint/order/create-contract-whole-system-warranty). ## Headers | Header | Description | Required | |--------|-------------|----------| | X-SureBright-Access-Token | Merchant API key (`sb_live_...`) or integration-kit access token | Yes | | Content-Type | application/json | Yes | See [Authentication](/api-reference/authentication) for how to get a key, and [Request conventions](/api-reference/endpoint/order/request-conventions) for the rules shared by every Order endpoint. ## Request body ### Order | Name | Type | Required | Description | |------|------|----------|-------------| | `storeId` | string | Yes | Your SureBright store ID, from your Integration Kit. | | `orderId` | string | Yes | Your own identifier for the order. You pass the same value as `partnerOrderId` to **Get Contracts for Order**. | | `orderPurchaseDate` | string | Yes | When the customer placed the order. ISO 8601 date and time with `Z` or a UTC offset, for example `2025-06-16T11:24:00.000Z` or `2025-06-11T06:09:17-08:00`. A date without a time is rejected. | | `orderLineItemList` | object[] | Yes | The order's line items. Must not be empty. | | `customerDetails` | object | Yes | The customer and their address. | | `manufacturerWarrantyDuration` | integer | No | Manufacturer warranty in months, applied to the line items of this order. | | `totalOrderValue` | number | No | Order total. Must not be negative. | | `taxAmount` | number | No | Tax on the order. Must not be negative. | | `discount.discountAmount` | number | No | Order-level discount. Must not be negative. | | `isTestOrder` | boolean | No | `true` marks the contracts as test contracts. Accepts a boolean or the strings `"true"` and `"false"`. Defaults to `false`. | ### Line item (`orderLineItemList[]`) | Name | Type | Required | Description | |------|------|----------|-------------| | `lineItemId` | string | Yes | Your identifier for the line. It is returned on every contract and error for that line. | | `quantity` | number | Yes | Units of the product bought. Must not be negative. A covered line gets one contract per unit. | | `productTitle` | string | Yes | Name of the product. | | `productId` | string | Yes | Your product identifier. | | `productSKU` | string | Yes | Your SKU for the product. | | `salePrice` | number | Yes | Price paid per unit. Must not be negative. | | `optionId` | string | No | Your variant identifier. When you send it, SureBright matches the line to its contracts by `optionId`; otherwise by `productId`. Send the same value on every later request for the order. | | `listPrice` | number | No | List price per unit. Must not be negative. | | `productURL` | string | No | Link to the product page. | | `planDetails` | object | No | The plan bought for this line. Leave it out for a line sold without a plan. | ### Plan (`planDetails`) `policyPurchaseDate` is always required. Then identify the plan in one of two ways. | Name | Type | Required | Description | |------|------|----------|-------------| | `policyPurchaseDate` | string | Yes | When the customer bought the plan. Same format as `orderPurchaseDate`. | | `quoteId` | string | With `quoteItemId` | The `quoteId` of the plan the customer chose, from [By Category](/api-reference/endpoint/quote/list-warranty-quotes-by-category). | | `quoteItemId` | string | With `quoteId` | The `quoteItemId` of that plan. | | `policySKU` | string | With `policyPrice` | A plan SKU that SureBright shared for your store. The line's `salePrice` has to fall inside the price band that SKU is set up for. | | `policyPrice` | number | With `policySKU` | Price the customer paid for the plan. Must be greater than zero and less than `salePrice`. | If a line carries both pairs, `quoteId` and `quoteItemId` are used and the SKU is ignored. ### Customer (`customerDetails`) | Name | Type | Required | Description | |------|------|----------|-------------| | `firstName`, `lastName` | string | Yes | Customer name. | | `customerEmail` | string | Yes | Must look like an email address (`name@domain.tld`). | | `addressLine1` | string | Yes | First line of the address. | | `addressLine2` | string | No | Second line of the address. | | `city` | string | Yes | City. | | `state` | string | Yes | State or province code, for example `NY`. | | `country` | string | Yes | Two-letter country code, for example `US`. | | `zipCode` or `pinCode` | string | Yes, one of them | Postal code. See below. | | `mobileNumber` | string | No | Customer phone number. | Required customer fields have to be non-empty strings. ## Customer postal code `customerDetails` must carry the postal code as **either** `zipCode` **or** `pinCode`; the two names are aliases and SureBright stores whichever one you send. If both are missing, the request fails validation with `Customer details missing required fields: ... zipCode`. ## Example request ```bash curl -X POST 'https://{HOST_NAME}/partner/api/v1/order' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -H 'X-SureBright-Access-Token: sb_live_YOUR_API_KEY' \ -d '{ "storeId": "{storeId}", "orderId": "83737121380", "orderPurchaseDate": "2026-01-07T10:15:30Z", "orderLineItemList": [ { "lineItemId": "line-1", "quantity": 2, "productTitle": "Example Wood Chipper", "productId": "6673746231399", "productSKU": "ALH05", "salePrice": 899.99, "planDetails": { "policyPurchaseDate": "2026-01-07T10:15:30Z", "quoteId": "33f21a29-95ca-4150-b5df-afe36f5ef537", "quoteItemId": "a7defcbd-aa07-4e01-9076-c1935af20a98" } } ], "customerDetails": { "firstName": "Dana", "lastName": "Reyes", "customerEmail": "dana@example.com", "addressLine1": "123 Example Street", "city": "New York", "state": "NY", "country": "US", "zipCode": "10005" } }' ``` ## Example response `200` when every covered line was processed: ```json { "storeId": "{storeId}", "orderId": "83737121380", "contractList": [ { "lineItemId": "line-1", "contractId": "abc12345-6789-4abc-bcde-ef1234567890", "isCancelled": false }, { "lineItemId": "line-1", "contractId": "def67890-1234-4def-8abc-0123456789ab", "isCancelled": false } ] } ``` | Field | Type | Meaning | |-------|------|---------| | `storeId`, `orderId` | string | Echoed from the request. | | `contractList` | object[] | One entry per contract, so a line with `quantity` 2 appears twice. | | `contractList[].lineItemId` | string | The line the contract belongs to. | | `contractList[].contractId` | string | The contract's identifier. Store it against the order line. | | `contractList[].isCancelled` | boolean | `false` for an active contract. `true` appears on updates that cancel contracts. | | `errorList` | object[] | Present only when something failed. See **Errors**. | To confirm what was created, call **Get Contracts for Order** (`GET /partner/api/v1/order?storeId=...&partnerOrderId=...`) with the same key. ## Errors The status code tells you how much of the order went through. | Status | Meaning | |--------|---------| | `200` | Every covered line was processed. No `errorList`. | | `207` | Some contracts were created and some lines failed. Read both `contractList` and `errorList`. | | `400` | Nothing was created. `errorList` says why. | | `401` | The key is missing or not valid. See [Authentication](/api-reference/authentication). | | `500` | SureBright could not complete the request. | Request validation runs before anything is created. If any line item, the customer details or an optional field fails validation, the whole request is rejected with `400`. Entries in `errorList` do not all have the same shape, so read whichever message key is present: | Shape | When | |-------|------| | `{"errorMessage": "..."}` | The request as a whole failed validation. | | `{"lineItemId": "...", "error": "..."}` | A line item failed validation. | | `{"field": "...", "error": "..."}` | The customer details or an optional field failed validation. | | `{"error": "..."}` | The store, the order or a plan SKU could not be resolved. | | `{"lineItemId": "...", "errorType": 504, "errorMessage": "..."}` | The quote for a line could not be found. | | Status | Message | Cause and what to do | |--------|---------|----------------------| | `400` | `X-SureBright-Access-Token header is required` | The `X-SureBright-Access-Token` header is missing. Send your key in that header. | | `400` | `Missing required fields: ...` | One of `storeId`, `orderId`, `orderPurchaseDate`, `orderLineItemList`, `customerDetails` is absent or empty. | | `400` | `orderPurchaseDate must be a valid ISO date, e.g., 2025-06-11T06:09:17-08:00` | Wrong date format. Include the time and `Z` or an offset. | | `400` | `orderLineItemList must be a non-empty array` | Send at least one line item. | | `400` | `Line item at index N missing required fields: ...` | A line lacks `lineItemId`, `quantity`, `productTitle`, `productId`, `productSKU` or `salePrice`. | | `400` | `quantity must be a positive number`, `salePrice must be a non-negative number`, `listPrice must be a non-negative number` | Send these as JSON numbers, not strings, and not negative. | | `400` | `planDetails.policyPurchaseDate is required` or `... must be a valid ISO date ...` | Add the plan purchase date in the same format as `orderPurchaseDate`. | | `400` | `planDetails must contain one of the following: ...` | Send `quoteId` with `quoteItemId`, or `policySKU` with `policyPrice`. | | `400` | `planDetails.policyPrice must be less than salePrice` | Check that you did not swap the two prices. | | `400` | `Customer details missing required fields: ...` | Fill in the listed customer fields. | | `400` | `Invalid email format in customerDetails` | Fix `customerEmail`. | | `400` | `discountAmount must be a non-negative number` (also `totalOrderValue`, `taxAmount`) | Send a number that is not negative, or leave the field out. | | `400` | `Invalid storeParentId: Store Parent not found` | `storeId` is not a store SureBright knows. Use the ID from your Integration Kit. | | `400` | `Order ... does not exist for store ... on platform ...` | The store is connected to an e-commerce platform and SureBright has not received this order from it. Check `orderId`. | | `400` or `207` | `No Quote Found` (`errorType: 504`) | The `quoteId` is unknown. Request the quote with `quoteSyncMode=SYNC` so that it is saved before you create the contract. | | `400` or `207` | `The specified Quote Item ID is not found within the provided quote.` (`errorType: 504`) | `quoteItemId` does not belong to `quoteId`. Send both from the same quote. | | `400` or `207` | `Invalid policy SKU: ... for line item N` | The SKU is not set up for your store, or `salePrice` is outside its price band. | | `500` | `Failed to process order with internal service` | The request did not complete in time or failed part-way. See the retry note below. | | `500` | `Internal server error occurred while processing the request` | Unexpected failure. See the retry note below. | ## Behaviour notes - **One contract per unit.** A covered line with `quantity` 3 creates three contracts that share the `lineItemId`. - **Lines without a plan create nothing.** A line with no `planDetails`, or an empty one, is accepted and ignored. - **Repeating a create is safe.** If you send the same order again, SureBright finds the active contracts it already holds for each line and returns them with the same `contractId` values. You get `200`, not an error, and no duplicates. - **One line per product.** Contracts are matched to a line by `optionId` when you send it, otherwise by `productId`, and counted across the order. Do not split the same product over two lines; send one line with the total quantity. - **`POST` and `PUT` behave the same.** Both compare what you send with the active contracts on the order. A `POST` for an order that already has contracts can therefore create more or cancel some, exactly as described on [Cancel / Update contracts for Order](/api-reference/endpoint/order/update-contract). - **Retry one request at a time.** After a `500`, the order may still have been processed. Look it up with **Get Contracts for Order** before you send it again, and send one request per order at a time. ## Related Change quantities or cancel plans on an order. Read back the active contracts on an order. Get the quote IDs to send in planDetails. Credentials, methods and the postal code alias. --- # 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 proposal. Provide sbProposalId, the selected warranty quote and plan details, and customer information. The covered line items, total covered amount, and installer warranty duration come from the proposal. If a contract already exists for the proposal, it is updated. Covered line items can be updated within 90 days from the original sale date; updates do not restart this window. Customer details and other non-line item fields can still be updated afterward, subject to the usual request validations. Backward compatibility: Existing integrations can provide sbSalesLeadId instead of sbProposalId. If both are supplied, their values must match; otherwise, the endpoint returns HTTP 400 with errorType 512. For new integrations, use sbProposalId. ## 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. One proposal has at most one contract, and that contract covers every eligible line on the proposal. For the whole flow, read the [Whole System Warranty guide](/api-reference/whole-system-warranty). ### Flow 1. Call the **List Quotes for Whole System Warranty** endpoint to get available warranty plans for your proposal. 2. Select the desired plan from the returned `warrantyQuoteItemList`. 3. Submit `sbProposalId`, the selected warranty details, and customer information to this endpoint. The covered line items, total covered amount, and installer warranty duration come from the proposal. ### Request Details | Field | Required | Notes | |-------|----------|-------| | `storeId` | Yes | Your SureBright store id. The proposal must belong to it | | `sbProposalId` | Yes | The SureBright proposal ID returned by the List Quotes API. A non-empty string of at most 200 characters | | `warrantyQuoteId` | Yes | The quote ID returned by the List Quotes API. It must be a quote that is still on the proposal | | `warrantyQuoteItemId` | Yes | The ID of the selected plan within that quote | | `warrantyCoverageYears` | Yes | Must equal the selected plan's `coverageYears` | | `warrantyPrice` | Yes | The price the customer was charged for the plan. A number, zero or more. Your margin is this price less the plan's `planCost` from the quote | | `customerDetails.customerFirstName` | Yes | | | `customerDetails.customerLastName` | Yes | | | `customerDetails.customerEmail` | Yes | The plan confirmation is sent here | | `customerDetails.customerPhone`, `customerAddress1`, `customerAddress2`, `customerCity`, `customerState`, `customerZipCode`, `customerCountry` | No | Send the address. A contract created without `customerAddress1` waits for the customer's address. See [Why a contract is on hold](/contracts/holds) | | `isTestOrder` | No | Boolean. `true` records a test contract. See [Test orders](#test-orders) | | `sbAccountId` | Connected platforms | The connected installer's account id. See [Creating for a connected installer](#creating-for-a-connected-installer) | | `sbStoreId` | Connected platforms | The installer's location. Always required with `sbAccountId` | | `partnerId` | No | For platforms: your `client_id`. When sent, SureBright takes your store from it, and a `storeId` sent with it must be that same store | Provide `sbProposalId` and use the quote and plan IDs from the same quote response. `sbProposalId` is required to identify the proposal whose covered products will be used for the contract, subject to the backward-compatibility exception below. Obtain this ID from the **List Quotes for Whole System Warranty** endpoint. Do not send `lineItemList`; any supplied value is ignored. ### How the contract is dated The contract's purchase date is the day you create it. You do not send a date. Cover begins on that purchase date and runs to the end of the term. For a breakdown, the manufacturer warranty and the installer's installation warranty apply first. Create the contract when the customer has bought and the installation is complete. See [When coverage starts](/contracts/effective-dates). ### Updating existing contracts If a contract already exists for the provided proposal, calling this endpoint updates that contract and returns the same `contractId`. It never creates a second contract for the proposal, so repeating a request that timed out is safe. - Covered line items can be updated within **90 days of the contract's purchase date**, the day it was first created. Updating the contract does not restart this window. - After the window, a request that would change the covered line items returns HTTP `400` with `errorType: 517` and nothing changes. - **Customer details** can still be updated after this window, subject to the usual request validations. To change covered products, first request updated quotes for the same proposal, then submit the selected quote and plan details to this endpoint. ### Test orders Send `"isTestOrder": true` to try the call without recording a real sale. The value must be a boolean; anything else returns `400` with `isTestOrder must be a boolean`. The contract is flagged as a test contract and its charge is waived. The customer email can still be sent, so use an address you control in `customerEmail`. There is no separate test key; see [Live keys and testing](/api-reference/authentication#live-keys-and-testing). ## Creating for a connected installer A platform that sells on behalf of installers does not use the installer's key. The installer connects to the platform once through [Partner sign-in (OIDC)](/api-reference/endpoint/partner/sso), and the platform then calls this endpoint with **its own** key and two extra fields. Direct integrations leave both out. | Field | Value | |-------|-------| | `sbAccountId` | The id returned to you when the installer connected. Its format is `sb_int_` followed by a UUID, for example `sb_int_3f9d2c7b-1a4e-4b6d-9c0f-5e8a7d6b2c10`. At most 200 characters | | `sbStoreId` | The `locationId` of the installer's location that made the sale, taken from the `locations` you received. Always required, including when the installer approved one location only | | `storeId` | Still your own store id, the one you quoted with | ```bash curl -X POST 'https://{HOST_NAME}/partner/api/v1/order/whole-system' \ -H 'X-SureBright-Access-Token: sb_live_YOUR_PLATFORM_KEY' \ -H 'Content-Type: application/json' \ -d '{ "storeId": "{yourPlatformStoreId}", "sbAccountId": "sb_int_{uuid}", "sbStoreId": "{locationId}", "sbProposalId": "{sbProposalId}", "warrantyQuoteId": "{warrantyQuoteId}", "warrantyQuoteItemId": "{warrantyQuoteItemId}", "warrantyCoverageYears": 3, "warrantyPrice": {priceChargedToTheCustomer}, "customerDetails": { "customerFirstName": "{firstName}", "customerLastName": "{lastName}", "customerEmail": "{email}" } }' ``` A connected request succeeds only while all of these are true: 1. The connection named by `sbAccountId` was made with your application and is active. 2. The installer granted the `sales.write` scope, which allows you to create and cancel contracts for the locations they approved. 3. `sbStoreId` is one of the locations the installer approved, and that location is still active. 4. The person who approved the connection is still an active owner or administrator of the installer's account. On success the proposal and its contract move into the installer's account under that location, and the contract appears in the installer's portal under **Sold plans**. From then on: - send the same `sbAccountId` and `sbStoreId` whenever you update the contract; - re-quote the proposal with `sbProposalId`, not with `partnerProposalId` alone; - an update keeps the contract's original purchase date and its test flag. A proposal that already has a contract under your own account cannot be moved to an installer afterwards. **Backward compatibility:** Existing integrations can provide `sbSalesLeadId` instead of `sbProposalId` when creating or updating contracts. If both are supplied, their values must match; otherwise, this endpoint returns HTTP `400` with `errorType: 512`. For new integrations, use `sbProposalId`. ## Response On success (`200`), you will receive: - **`isError`** - `false`. - **`contractId`** - The unique identifier for the warranty contract created or updated. Store it: you need it to cancel, and there is no call that reads a whole-system contract back. ## Errors ### Requests with your own key A failed check returns HTTP `400`. The code is in the `errorType` field of the body, not in the HTTP status: ```json { "isError": true, "errorType": 517, "message": "Line items cannot be updated after 90 days of purchase date" } ``` | HTTP status | `errorType` | `message` | Check that failed | |-------------|-------------|-----------|-------------------| | `400` | `512` | `Validation Failed for Input Parameters` | A required field is missing or malformed. The `errors` array names each one, for example `warrantyPrice is required`, `customerEmail is required` or `isTestOrder must be a boolean` | | `400` | `513` | `No Quote Found` | The selected quote no longer exists. Request quotes again | | `400` | `514` | `Store Not Found` | `storeId` is not a store set up for Whole System Warranty | | `400` | `515` | `Sales Lead Not Found` | No proposal has that `sbProposalId` on that `storeId`, or the proposal now belongs to a connected installer and the request did not carry `sbAccountId` and `sbStoreId` | | `400` | `516` | `Contract not found` | The proposal's existing contract could not be found when updating it | | `400` | `517` | `Line items cannot be updated after 90 days of purchase date` | Covered line items changed after the 90-day window | | `400` | `518` | `Quote ID mismatch` | `warrantyQuoteId` is not a quote on this proposal, for example because the proposal was re-quoted since | | `400` | `519` | `Quote item not found` | `warrantyQuoteItemId` is not a plan within the selected quote | | `400` | `520` | `Warranty coverage years do not match quote item` | `warrantyCoverageYears` differs from the selected plan's `coverageYears` | | `400` or `500` | `500` | `Something Unexpectedly Went Wrong` | Unexpected failure. Send the request again; a repeat does not create a second contract | | `401` | `401` | `X-SureBright-Access-Token header is required` | The key is missing. A key that is not valid returns the bodies listed on [Authentication](/api-reference/authentication) | | `403` | | `API credential does not belong to this partner` | `partnerId` was sent with a key that does not belong to that application | | `502` | `502` | `Unable to reach the target service` | SureBright could not complete the request. Send it again | ### Requests for a connected installer These bodies carry `isError: true`, a `message` and, where shown, a `code`. | HTTP status | `code` | `message` | Cause and what to do | |-------------|--------|-----------|----------------------| | `400` | | `sbAccountId must be a non-empty identifier` | `sbAccountId` is empty, not a string or over 200 characters | | `400` | `invalid_request` | `sbStoreId is required` | Send the installer's `locationId` as `sbStoreId` | | `400` | | `sbStoreId is only supported for a SureBright Connect account` | `sbAccountId` is not an id returned by the installer's connection. Send the `sbAccountId` you received when the installer connected | | `400` | | `Use sbAccountId instead of merchantStoreId` | `merchantStoreId` is not accepted on this endpoint | | `401` | `invalid_api_key` | `Partner authentication failed` | The connection is not active, or it was not made with your application. Ask the installer to connect again | | `403` | `insufficient_scope` | `The sales.write scope is required` | The installer did not grant `sales.write`. Request it and ask the installer to approve again | | `403` | `access_denied` | `The selected location is not authorized` | `sbStoreId` is not a location the installer approved | | `403` | `access_denied` | `The selected location is not active` | The location has been closed or deactivated | | `403` | `access_denied` | `The merchant authorization is no longer active` | The person who approved is no longer an active owner or administrator. Ask a current owner or administrator to connect again | | `403` | `access_denied` | `The supplied storeId does not belong to the authenticated partner` | `storeId` must be your own store id | | `403` | | `Proposal does not belong to the authenticated partner account` | The proposal was not quoted with your `storeId` | | `403` | | `Proposal is not available to this connection` | The proposal already belongs to a different connection or location | | `400` | | `Sales Lead Not Found` | No proposal has that `sbProposalId` | | `409` | | `sbProposalId and sbSalesLeadId must identify the same proposal` | Both were sent with different values. Send `sbProposalId` only | | `400` | `PARTNER_QUOTE_SELECTION_INVALID` | `The selected quote does not belong to this proposal` or `warrantyCoverageYears does not match the selected quote` | Re-quote and send the IDs and term from that response | | `409` | `PARTNER_QUOTE_SELECTION_INVALID` | `warrantyPrice must be a non-negative number` | Fix `warrantyPrice` | | `400` | `CUSTOMER_DETAILS_REQUIRED` | `Customer name and email are required` | Send the three required `customerDetails` fields | | `400` | | `Validation Failed for Input Parameters` | `warrantyPrice`, `warrantyCoverageYears` or a required `customerDetails` field is missing | | `400` | | `isTestOrder must be a boolean` | Send `true` or `false`, or leave it out | | `400` | | `The selected quote has no covered products` | No line on the selected quote is covered | | `400` | `INVALID_COVERED_LINE_ITEMS` | A message that covered items need a price and quantity above zero | Covered lines need a price and a quantity greater than zero, and product quantities must be whole numbers. Re-quote with corrected lines | | `400` | | `restrictionType: PRODUCT_ELIGIBILITY_BLACKLIST` with an `ineligibleItemList` | A line is a product SureBright does not accept. Remove it and re-quote | | `409` | | `Partner quote and merchant account currencies must match` | The proposal was quoted in a different currency from the installer's account | | `409` | | `A contracted proposal cannot be transferred` | The proposal already has a contract under your own account | | `409` | | `Proposal changed. Reload the quote before submitting.` | The proposal was re-quoted while the request was in flight. Re-quote and send the request again | | `409` | | `Contract creation is still in progress` | An earlier create for this proposal has not finished. Wait and send the request again | | `410` | `PROPOSAL_EXPIRED` or `PROPOSAL_DELETED` | | The proposal can no longer be sold. Quote the job again as a new proposal | | `502` | | `Unable to reach the target service` | Send the request again | | `503` | | `Merchant authorization is unavailable`, or a `code` of `PARTNER_LOOKUP_UNAVAILABLE` | SureBright could not check the connection. Send the request again | An update of a contract that already exists for a connected installer returns the `errorType` codes `512` to `520` from the first table, with HTTP `400`. ## Related The whole flow for platforms and installers. Price a whole-system plan for a proposal. Cancel the contract this endpoint created. How an installer connects to your platform. --- # Set or revert fulfillment dates Source: https://docs.surebright.com/api-reference/endpoint/order/fulfillment > Open a contract's coverage window when the product ships, or take it back when the shipment is cancelled, on stores where coverage starts at fulfillment. Server-to-server endpoint. SureBright's Shopify and BigCommerce integrations call it for you; direct integrations are enabled per store by SureBright. `POST https://{HOST_NAME}/order/api/v1/contract/fulfillment` On a fulfillment-based store a contract is created with blank effective and expiration dates and held with `AWAITING_FULFILLMENT` until the product ships. This endpoint is the step that dates the contract (`SET`) or clears the dates again after a cancelled shipment (`REVERT`). The rules that turn a shipment date into coverage dates are described in [When coverage starts](/contracts/effective-dates); you only need this endpoint if your platform is not one SureBright already listens to. ## Headers | Header | Description | Required | |--------|-------------|----------| | Authorization | `Bearer` followed by the server-to-server token SureBright issues for your integration. This is not the merchant API key (`sb_live_...`) and it is not read from `X-SureBright-Access-Token`. | Yes | | Content-Type | `application/json` | Yes | A missing or malformed token returns `401 {"message": "Unauthorized"}`. ## Request body The SureBright contract IDs to date or revert. Send the contracts for the units that shipped (or whose shipment was cancelled). Contracts that are already dated are reported as skipped, so it is safe to resend contracts from an earlier shipment. `SET` stamps the coverage dates from `fulfillmentDate`. `REVERT` clears them. Case-insensitive; any other value is rejected. The shipment date and time, ISO 8601 (for example `2026-11-05T14:32:00Z`). Required for `SET`, ignored for `REVERT`. Optional free text for `REVERT` (for example the platform's cancellation reason). It is echoed back in the result and stored with the review case. ## What SET does For each contract: 1. If the contract already has a fulfillment or effective date it is left alone and reported with `skipped: true`. **First fulfillment wins**; a later shipment never re-dates a contract. 2. Otherwise the effective date is computed from `fulfillmentDate` using the store's dating rules, the expiration date is the effective date plus the plan term, and the shipment date is stored as the contract's fulfillment date. 3. The `AWAITING_FULFILLMENT` hold clears and, if the customer's confirmation email was deferred at order time, it is sent now. ## What REVERT does For each contract that has dates: 1. The effective, expiration and fulfillment dates are cleared, exactly as they were before the product shipped. 2. The contract returns to the `AWAITING_FULFILLMENT` hold. It is **not** cancelled; a cancelled shipment is usually a re-ship, and the next `SET` dates it again. 3. SureBright opens a review case for the contract so the cancelled shipment can be checked. Contracts that are already cancelled, or that have no dates to take back, are reported with `skipped: true` and are not changed. ## Example ```bash curl -X POST https://{HOST_NAME}/order/api/v1/contract/fulfillment \ -H 'Authorization: Bearer {SERVICE_TOKEN}' \ -H 'Content-Type: application/json' \ -d '{ "contractIds": ["SB-7F3A9C21", "SB-7F3A9C22"], "action": "SET", "fulfillmentDate": "2026-11-05T14:32:00Z" }' ``` ```bash curl -X POST https://{HOST_NAME}/order/api/v1/contract/fulfillment \ -H 'Authorization: Bearer {SERVICE_TOKEN}' \ -H 'Content-Type: application/json' \ -d '{ "contractIds": ["SB-7F3A9C21"], "action": "REVERT", "reason": "Shipment cancelled by carrier" }' ``` ## Response The call is processed contract by contract. It returns `200` when every contract succeeded or was skipped, and `500` with the same body shape when at least one contract failed. Check `results[]` either way. `true` when any entry in `results` has `isError: true`. `Fulfillment dates updated`, `Fulfillment dates reverted`, `One or more contracts failed to update` or `One or more contracts failed to revert`. One entry per contract in `contractIds`, in the same order. The contract this entry is about. `true` when the contract was not dated. Present and `true` when the contract already had dates. Set on skipped and failed entries, for example `Dates already set — skipped (first fulfillment wins)`, `Contract not found` or `Version conflict — not dated after 3 attempt(s)`. Coverage start, `MM/DD/YYYY`. Coverage end, `MM/DD/YYYY`. Whether the contract still has something to resolve. See [Why a contract is on hold](/contracts/holds). The holds left on the contract after dating. The contract this entry is about. `true` when the dates could not be cleared. `true` when the dates were cleared. Present and `true` when there was nothing to revert. On skipped entries: `Contract is cancelled — nothing to revert` or `No fulfillment dates set — already awaiting fulfillment`. The `reason` you sent, if any. Whether the contract has something to resolve. The holds on the contract after the revert; includes `AWAITING_FULFILLMENT`. The contract's lifecycle state. See [Contract statuses](/contracts/lifecycle). The contract's payment state. ```json { "isError": false, "message": "Fulfillment dates updated", "results": [ { "contractId": "SB-7F3A9C21", "isError": false, "effectiveDate": "11/05/2026", "expirationDate": "11/05/2028", "isFixPending": false, "holdReasonList": [] }, { "contractId": "SB-7F3A9C22", "isError": false, "skipped": true, "message": "Dates already set — skipped (first fulfillment wins)", "effectiveDate": "10/28/2026", "expirationDate": "10/28/2028" } ] } ``` ## Errors | Status | Body | Cause | |--------|------|-------| | `400` | `{"isError": true, "message": "contractIds is required"}` | `contractIds` missing or empty | | `400` | `{"isError": true, "message": "action, when provided, must be one of: SET, REVERT"}` | Unknown `action` | | `400` | `{"isError": true, "message": "fulfillmentDate is required"}` | `SET` without a date | | `401` | `{"message": "Unauthorized"}` | Bearer token missing or not recognised | | `500` | `{"isError": true, "message": "One or more contracts failed to update", "results": [...]}` | At least one contract was not found or lost a concurrent write after three attempts; resend those contract IDs | | `500` | `{"isError": true, "message": "Internal Server Error"}` | Unexpected failure | A contract that fails with a version conflict was being written by another process at the same moment (for example a payment capture). Retrying the same request is safe: contracts that were dated in the meantime come back as skipped. --- # Get Contracts for Order Source: https://docs.surebright.com/api-reference/endpoint/order/get-contracts > Returns the order SureBright has on record for a partnerOrderId together with its active (non-cancelled) warranty contracts. Use it to confirm what was created by POST or PUT /partner/api/v1/order. ## Headers | Header | Description | Required | |--------|-------------|----------| | X-SureBright-Access-Token | Access token for authentication | Yes | ## Overview Looks up the order SureBright has on record for one of your orders and returns its **active** warranty contracts. Contracts that have been cancelled are not included. Pass the same `storeId` you used when creating the order, and your own order identifier as `partnerOrderId` (the `orderId` of the create request). ```bash curl -G https://{HOST_NAME}/partner/api/v1/order \ --data-urlencode 'storeId={storeId}' \ --data-urlencode 'partnerOrderId=83737121380' \ -H 'X-SureBright-Access-Token: sb_live_...' ``` This endpoint reads the key from `X-SureBright-Access-Token` only. The same key you use for `POST` and `PUT /partner/api/v1/order` works here. ## Response - `storeId`, `partnerOrderId` – echoed from the request - `data.order` – the order as stored by SureBright - `data.contracts` – the active contracts on that order - `data.processedAt` – when the lookup was served A `404` with `errorCode: ORDER_NOT_FOUND` means no order exists for that `storeId` and `partnerOrderId`. --- # Order API overview Source: https://docs.surebright.com/api-reference/endpoint/order/index > How the Order API creates, updates and cancels protection plan contracts for an order. 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. --- ## What the Order API does ### Create contracts When a new order is submitted: - The API checks if the order's `orderId` already 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 `orderId` **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 one line item To cancel warranty coverage on a particular product line: - Set `quantity` to `0` for that line item in `orderLineItemList` 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 operations | Operation | Description | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Create Order (POST)** | Generates new warranty contracts if the order is not yet recorded (`orderId` 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, use the PUT method and set `quantity` to `0` for that line item in `orderLineItemList`. | --- 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. --- # Request conventions Source: https://docs.surebright.com/api-reference/endpoint/order/request-conventions > The rules shared by every Order endpoint: base path, accepted credentials and headers, HTTP methods, the postal code alias, and the SureBright Connect fields integration partners send on behalf of a merchant. All Order endpoints live under `https://{HOST_NAME}/partner/api/v1/order`. This page collects the behaviour they share so the individual pages can stay short. Read [Authentication](/api-reference/authentication) first; this page only adds what it leaves out. ## Base path and transport - Every request is HTTPS with `Content-Type: application/json` and a JSON body (except `GET`). - Responses are JSON. Partial success on a multi-line order is `207` with an `errorList`; see [HTTP status codes](/api-reference/http-status-codes). - `{HOST_NAME}` is the SureBright API host from your Integration Kit; staging and production use different hosts and different keys. ## Credentials The Order endpoints accept one of three credentials. All resolve to your SureBright account (store parent); the `storeId` in the body then has to belong to that account. | Credential | Where to send it | Notes | |---|---|---| | Self-serve developer key, `sb_live_...` | `X-SureBright-Access-Token: sb_live_...` | Created on the merchant portal **Developers** page. Send it in this header only; an API key is not accepted in `Authorization`. | | Integration Kit access token | `X-SureBright-Access-Token` only | Issued by SureBright during onboarding. Not accepted in `Authorization`. | | Partner's own key (SureBright Connect) | As for the key type above | An integration partner authenticates with its own key (self-serve or Integration Kit) and identifies the merchant in the body. See below. | A request that carries an `sb_live_` key which is unknown, revoked or rotated fails with `401 {"message": "Unauthorized! Invalid or revoked API key."}` and does not fall through to the other credentials. ## Methods | Path | Methods | Notes | |---|---|---| | `/v1/order` | `POST` create, `PUT` update or cancel line items, `GET` look up | See [Create](/api-reference/endpoint/order/create-contract), [Update](/api-reference/endpoint/order/update-contract) and [Get contracts](/api-reference/endpoint/order/get-contracts). | | `/v1/order/whole-system` | Any | The route accepts every HTTP method and treats them alike. Use `POST`. | | `/v1/order/whole-system/cancel` | `POST` | `contractId` goes in the query string. | ## Customer postal code `customerDetails` carries the postal code as either `zipCode` or `pinCode`. The two names are aliases; SureBright stores whichever one you send and validates it against the customer's country. If both are absent the request fails validation with `Customer details missing required fields: ... zipCode`. ## SureBright Connect fields An integration partner that sells plans on behalf of merchants does not hold each merchant's API key. Instead the merchant connects to the partner once through [Partner sign-in (OIDC)](/api-reference/endpoint/partner/sso), SureBright returns an `sbAccountId` for that connection, and the partner then calls the whole-system endpoints with **its own** key plus the fields below. These fields are read on `/v1/order/whole-system` and `/v1/order/whole-system/cancel` only. Direct merchant integrations leave all of them out. The merchant's public SureBright account ID, as returned by the token endpoint of the partner sign-in flow. Non-empty, at most 200 characters. Which of the merchant's connected locations the sale belongs to. Use one of the `locations[].locationId` values from the sign-in response. Always required when you send `sbAccountId`. Your partner client ID. Partners that SureBright has registered may send it together with `storeId`; SureBright resolves the pair to your partner store. Optional when you send `sbAccountId`. Your own SureBright store ID (the partner's store, not the merchant's). Everything else in the body is the normal whole-system payload described on [Create / Update Contracts for Whole System Warranty](/api-reference/endpoint/order/create-contract-whole-system-warranty). ```bash curl -X POST https://{HOST_NAME}/partner/api/v1/order/whole-system \ -H 'X-SureBright-Access-Token: sb_live_...' \ -H 'Content-Type: application/json' \ -d '{ "storeId": "{partnerStoreId}", "sbAccountId": "sb_int_3f9d2c7b-1a4e-4c2b-9f6d-8a1e4b7c2d10", "sbStoreId": "LOCATION_ID_FROM_SIGN_IN", "sbProposalId": "PRP-20261105-0042", "warrantyQuoteId": "WQ-7731", "warrantyQuoteItemId": "WQI-7731-3Y", "warrantyCoverageYears": 3, "customerDetails": { "customerFirstName": "Dana", "customerLastName": "Reyes", "customerEmail": "dana@example.com", "zipCode": "94016", "country": "US" } }' ``` ### How a Connect request is authorised 1. Your key authenticates you as the partner. 2. `sbAccountId` is looked up. If it matches a merchant connection, the connection must be `ACTIVE`, the merchant must have granted the `sales.write` scope, and `sbStoreId` must be one of the locations the merchant authorised. 3. If `sbAccountId` does not match an active connection of yours, the request is refused. Ask the installer to connect again through [Partner sign-in](/api-reference/endpoint/partner/sso). On cancel, the contract itself tells SureBright which connection it was sold under; you only send `contractId` (query) and an optional `cancellationReason`. ### Errors specific to Connect requests | Status | Body | Cause | |--------|------|-------| | `400` | `{"isError": true, "message": "Use sbAccountId instead of merchantStoreId"}` | `merchantStoreId` is not accepted on these endpoints | | `400` | `{"isError": true, "message": "sbAccountId must be a non-empty identifier"}` | Empty, non-string or over 200 characters | | `401` | `code: invalid_api_key`, `Partner authentication failed` | The connection does not belong to the partner whose key was used | | `403` | `code: insufficient_scope` | The merchant did not grant `sales.write` | | `403` | `code: access_denied`, `The selected location is not authorized` | `sbStoreId` is not one of the authorised locations | | `403` | `{"isError": true, "message": "Store integration is inactive"}` | Cancel on a contract whose merchant connection has been revoked | | `409` | `code: invalid_request`, `partnerId and storeId must identify the same partner` | `partnerId` and `storeId` resolve to different partners | | `503` | `{"isError": true, "code": "PARTNER_LOOKUP_UNAVAILABLE", ...}` or `Merchant authorization is unavailable` | SureBright could not reach its partner registry; retry | --- # 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. `PUT https://{HOST_NAME}/partner/api/v1/order` Use this endpoint to change an order you have already sent: lower or raise the quantity on a covered line, cancel the plans on a line, or cancel every plan on the order. You send the order again, and SureBright compares each line's `quantity` with the active contracts it holds for that line, then cancels or creates the difference. This is also how you cancel ordinary contracts. There is no separate cancel call for them. Send the order the first time with [Create Contracts for Order](/api-reference/endpoint/order/create-contract), and cancel a whole-system contract with [Cancel Contracts for Whole System Warranty](/api-reference/endpoint/order/cancel-contract-whole-system-warranty) instead. ## Headers | Header | Description | Required | |--------|-------------|----------| | X-SureBright-Access-Token | Merchant API key (`sb_live_...`) or integration-kit access token | Yes | | Content-Type | application/json | Yes | ## Request body The body is the same as on **Create Contracts for Order** and passes the same validation, so every required field has to be present even when you only change one quantity. The full field tables are on [Create Contracts for Order](/api-reference/endpoint/order/create-contract#request-body). The fields that drive an update are: | Name | Type | Required | Description | |------|------|----------|-------------| | `storeId` | string | Yes | The store ID you used when you created the order. | | `orderId` | string | Yes | The order ID you used when you created the order. | | `orderPurchaseDate` | string | Yes | ISO 8601 date and time with `Z` or a UTC offset, for example `2025-06-11T06:09:17-08:00`. | | `customerDetails` | object | Yes | The customer and address, with the same required fields as on create. | | `orderLineItemList` | object[] | Yes | The lines you want SureBright to reconcile. Lines you leave out are not touched. | | `orderLineItemList[].lineItemId`, `productTitle`, `productId`, `productSKU`, `salePrice` | | Yes | Required on every line you send, as on create. | | `orderLineItemList[].optionId` | string | No | Send it if you sent it on create. It is how the line is matched to its contracts. | | `orderLineItemList[].quantity` | number | Yes | How many units of the line should be covered after this request. `0` cancels the line's plans. | | `orderLineItemList[].planDetails` | object | No | The plan for the line. Needed when the request creates contracts. If you leave it out or send it empty, the line is treated as having no plan and its active contracts are cancelled. When present it must carry `policyPurchaseDate`. | ## What each change does | You send, for a line | Result | |----------------------|--------| | `quantity` lower than the number of active contracts | The difference is cancelled. | | `quantity` of `0` | Every active contract on the line is cancelled. | | No `planDetails`, or an empty one | Every active contract on the line is cancelled, whatever the `quantity`. | | `quantity` higher than the number of active contracts, with `planDetails` | The difference is created as new contracts. | | `quantity` equal to the number of active contracts | Nothing changes. The existing contracts are returned. | | The line is not in `orderLineItemList` | Nothing changes for that line. | To cancel every plan on an order, send every covered line with `quantity` `0`, or send them without `planDetails`. ## Customer postal code `customerDetails` must carry the postal code as **either** `zipCode` **or** `pinCode`; the two names are aliases and SureBright stores whichever one you send. If both are missing, the request fails validation with `Customer details missing required fields: ... zipCode`. ## Example request The order was created with two covered units on `line-1`. This request reduces it to one, which cancels one contract. ```bash curl -X PUT 'https://{HOST_NAME}/partner/api/v1/order' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -H 'X-SureBright-Access-Token: sb_live_YOUR_API_KEY' \ -d '{ "storeId": "{storeId}", "orderId": "83737121380", "orderPurchaseDate": "2026-01-07T10:15:30Z", "orderLineItemList": [ { "lineItemId": "line-1", "quantity": 1, "productTitle": "Example Wood Chipper", "productId": "6673746231399", "productSKU": "ALH05", "salePrice": 899.99, "planDetails": { "policyPurchaseDate": "2026-01-07T10:15:30Z", "quoteId": "33f21a29-95ca-4150-b5df-afe36f5ef537", "quoteItemId": "a7defcbd-aa07-4e01-9076-c1935af20a98" } } ], "customerDetails": { "firstName": "Dana", "lastName": "Reyes", "customerEmail": "dana@example.com", "addressLine1": "123 Example Street", "city": "New York", "state": "NY", "country": "US", "zipCode": "10005" } }' ``` ## Example response `200`: ```json { "storeId": "{storeId}", "orderId": "83737121380", "contractList": [ { "lineItemId": "line-1", "contractId": "abc12345-6789-4abc-bcde-ef1234567890", "isCancelled": true }, { "lineItemId": "line-1", "contractId": "def67890-1234-4def-8abc-0123456789ab", "isCancelled": false } ] } ``` | Field | Type | Meaning | |-------|------|---------| | `storeId`, `orderId` | string | Echoed from the request. | | `contractList` | object[] | The contracts this request touched or kept on the lines you sent. | | `contractList[].lineItemId` | string | The line the contract belongs to. | | `contractList[].contractId` | string | The contract's identifier. | | `contractList[].isCancelled` | boolean | `true` for a contract this request cancelled. `false` for one that is still active. | | `errorList` | object[] | Present only when something failed. | If a line you send has no active contracts and no plan to create, it adds nothing to `contractList`. A request that changes nothing returns `200` with the existing contracts, or an empty `contractList`. ## Errors Status codes, `errorList` shapes and validation messages are the same as on [Create Contracts for Order](/api-reference/endpoint/order/create-contract#errors). The ones you are most likely to meet on an update: | Status | Message | Cause and what to do | |--------|---------|----------------------| | `400` | `Missing required fields: ...` or `Customer details missing required fields: ...` | You sent only the changed fields. Send the full order body. | | `400` | `Line item at index N missing required fields: ...` | A line lacks `productTitle`, `productSKU`, `salePrice` or another required field, even though you only meant to change its quantity. | | `400` | `quantity must be a positive number` | `quantity` is negative or not a JSON number. `0` is accepted. | | `400` | `planDetails.policyPurchaseDate is required` | A non-empty `planDetails` needs the purchase date. To cancel, leave `planDetails` out altogether or set `quantity` to `0`. | | `400` or `207` | `No Quote Found` (`errorType: 504`) | The request raises a quantity and the `quoteId` is unknown. Quote again with `quoteSyncMode=SYNC` and send the new IDs. | | `401` | See [Authentication](/api-reference/authentication) | The key is missing or not valid. | | `500` | `Failed to process order with internal service` | The request did not complete. Check the order with **Get Contracts for Order** before you send it again. | ## Behaviour notes - **What this endpoint can change.** The number of active contracts on each line you send: it cancels contracts or creates new ones. - **What it cannot change.** Contracts that already exist are not edited. If you resend a line with the same `quantity` but different `customerDetails`, `salePrice` or `planDetails`, the existing contracts stay as they were. - **Changing the plan on a line.** Cancel the line's contracts first (`quantity` `0`), then send the line again with the new `planDetails`. The new contracts have new IDs. - **A cancelled contract stays cancelled.** It is not reactivated. Sending the line again with a plan creates new contracts. - **You do not choose which contract is cancelled.** When you reduce a quantity, read `contractList` to see which contract IDs now have `isCancelled: true`. - **Keep the product identifiers stable.** Lines are matched to their contracts by `optionId` when you send it, otherwise by `productId`. If these differ from the create request, SureBright sees a new product and creates contracts instead of updating. - **A `PUT` for an unknown order creates it.** `POST` and `PUT` behave the same, so an update for an order SureBright has not seen creates contracts for its covered lines. - **The customer is told.** SureBright normally emails the customer one cancellation confirmation per line item, not one per contract. - **One request at a time.** Do not send two requests for the same order at the same moment. ## Related Full request fields, validation messages and error shapes. Read back the active contracts on an order. Cancel a whole-system contract by its ID. Credentials, methods and the postal code alias. --- # Partner sign-in (OIDC) Source: https://docs.surebright.com/api-reference/endpoint/partner/sso > How an integration partner connects a SureBright merchant to its application with OpenID Connect: pushed authorization requests, consent, token exchange, scopes and claims. SureBright is an OpenID Connect provider for integration partners. A merchant signs in to SureBright once, approves your application for one or more of their store locations, and you receive tokens plus an `sbAccountId` that identifies the connection. From then on you create and cancel contracts for that merchant with your own API key and the `sbAccountId`; see [Request conventions](/api-reference/endpoint/order/request-conventions). Issuer: `https://{HOST_NAME}/site-platform/api/v1/sso`. Every endpoint below is relative to it. Responses carry `Cache-Control: no-store`. ## Before you start SureBright registers your application and gives you a `client_id`. Registration fixes: - the **client type**: `CONFIDENTIAL` (server-side, has a client secret) or `PUBLIC` (browser-based, no secret, calls must come from a registered origin); - the **redirect URIs** you may use (HTTPS, or `http://localhost` for development); - the **scopes** you may request (see below); - a display name and provider label the merchant sees on the consent screen. Only the authorization code flow with PKCE (`S256`) and pushed authorization requests is supported. Check the live values with the discovery document. ## Flow `POST /par` with your client credentials and the request parameters. SureBright stores the request for 60 minutes and returns a `request_uri` and a ready-made `authorization_url`. Redirect the merchant to `authorization_url` (`GET /authorize?client_id=...&request_uri=...`). SureBright answers `302` to its own sign-in and consent page. The merchant signs in, must be an **owner or administrator** of their SureBright organization, picks the locations to connect, and approves or declines. Approval redirects to your `redirect_uri` with `code` and `state`. A decline redirects with `error=access_denied`, `error_description=The merchant declined the connection` and `state`. The code is single use and expires after 5 minutes. `POST /token` with the code, your `code_verifier` and client credentials. You receive an access token, an ID token and the merchant's `sbAccountId`. ## POST /par Client authentication: confidential clients send `Authorization: Basic base64(client_id:client_secret)` or `client_id` and `client_secret` in the form body. Public clients send `client_id` only and must include an `Origin` header that matches a registered origin. Body is `application/x-www-form-urlencoded` or JSON: Must be `code`. One of your registered redirect URIs. Opaque value you check on return. 16 to 512 characters. Returned in the ID token. 16 to 512 characters. PKCE challenge, base64url SHA-256 of your `code_verifier`, 43 to 128 characters. Must be `S256`. Space-separated scopes. Must include `openid` and only scopes your client is registered for. Confidential clients: required. Your own identifier for the merchant's account in your system, at most 200 characters. One SureBright organization can be connected per tenant. Ignored for public clients. Optional, confidential clients only. The user in your system who started the connection, at most 200 characters. Optional. `email`, `fullName`, `businessName`, `businessPhone` (strings, trimmed to 200 characters) to pre-populate SureBright's sign-up form for a merchant who has no SureBright account yet. May be sent as a JSON string. ```bash curl -X POST https://{HOST_NAME}/site-platform/api/v1/sso/par \ -u '{client_id}:{client_secret}' \ -d response_type=code \ -d redirect_uri=https://app.example-pos.com/surebright/callback \ -d state=9f2c1b7e4a6d8c3f0e5b2a7d \ -d nonce=4b8e2d6a1c9f7e3b5d0a8c2e \ -d code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM \ -d code_challenge_method=S256 \ -d 'scope=openid profile email merchant.read sales.write' \ -d external_tenant_id=tenant_48213 ``` Returns `201`: `urn:ietf:params:oauth:request_uri:...` Seconds the request stays valid. `3600`. The URL to send the merchant to. ## GET /authorize `GET /authorize?client_id={client_id}&request_uri={request_uri}`. Responds `302` to SureBright's consent page, or an OAuth error (`invalid_request_uri` when the request is unknown, used or expired; `invalid_client` when your application is no longer active). ## POST /token Same client authentication as `/par`. Must be `authorization_code`. The code from the redirect. Must equal the `redirect_uri` from `/par`. Your PKCE verifier, 43 to 128 characters. ```json { "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...", "token_type": "Bearer", "expires_in": 900, "scope": "openid profile email merchant.read sales.write", "sbAccountId": "sb_int_3f9d2c7b-1a4e-4c2b-9f6d-8a1e4b7c2d10", "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6..." } ``` Both tokens are RS256 JWTs signed with the key published at `/jwks`, valid for 15 minutes, with `aud` equal to your `client_id`. The exchange fails with `invalid_grant` if the code was already used, the verifier does not match, the merchant's approval cannot be confirmed, or the connection has since been revoked, re-scoped or lost one of its locations. Store `sbAccountId` and the `locations` claim; they do not expire with the token. ## Scopes | Scope | Grants | |---|---| | `openid` | Required. Issues the ID token with `sub` (the approving member). | | `profile` | `name` claim. | | `email` | `email` claim (`email_verified` in the ID token). | | `merchant.read` | The merchant claims below. | | `quotes.write` | Request quotes on behalf of the merchant, plus the merchant claims. | | `sales.write` | Create and cancel contracts on behalf of the merchant, plus the merchant claims. | ## Claims Both tokens carry `iss`, `sub`, `aud`, `exp`, `iat`, `jti`, `client_id`, `scope` and `token_use` (`access` or `id`). The ID token adds `nonce` and `at_hash`. With `merchant.read`, `quotes.write` or `sales.write` granted, both tokens also carry: | Claim | Meaning | |---|---| | `sbAccountId` | The connection ID you send as `sbAccountId` on contract calls. | | `locations` | The locations the merchant authorised: `locationId`, `name`, `address` (`addressLine1`, `addressLine2`, `city`, `state`, `zipCode`, `country`). Use a `locationId` as `sbStoreId`. | | `store_parent_id` | The merchant's SureBright organization. | | `sb_member_id` | The member who approved. | | `external_tenant_id` | Your tenant ID from `/par` (public clients: `surebright:` followed by the organization ID). | | `grant_revision`, `consent_version` | Change when the merchant re-approves or SureBright updates the consent text. | ## GET /userinfo `Authorization: Bearer {access_token}`. Returns `sub`, `email`, `name`, `sb_member_id`, `store_parent_id`, `locations` and `sbAccountId` (claims absent from the token are `null`). `401 invalid_token` with `WWW-Authenticate: Bearer realm="SureBright Partner OIDC"` when the token is missing, expired or your application is inactive. ## Discovery and keys - `GET /.well-known/openid-configuration` lists `authorization_endpoint`, `pushed_authorization_request_endpoint`, `token_endpoint`, `userinfo_endpoint`, `jwks_uri`, `response_types_supported: ["code"]`, `grant_types_supported: ["authorization_code"]`, `id_token_signing_alg_values_supported: ["RS256"]`, `token_endpoint_auth_methods_supported: ["none", "client_secret_basic", "client_secret_post"]`, `scopes_supported`, `code_challenge_methods_supported: ["S256"]`, `request_uri_parameter_supported: true` and `require_pushed_authorization_requests: true`. - `GET /jwks` returns the signing key (`kid`, `use: sig`, `alg: RS256`). Cache it and refresh on an unknown `kid`. ## GET /partner/requests/{requestId}/presentation Public. Returns what SureBright's consent page shows for a pending request, so you can render a matching landing page if you host one. `requestId` is the last segment of `request_uri`. ```json { "isError": false, "data": { "client": { "clientId": "example-pos", "name": "Example POS", "provider": "EXAMPLE_POS" }, "prefill": { "email": "owner@example.com" }, "expiresIn": 3600 } } ``` `404 invalid_request` once the request has been approved, declined or has expired. ## Portal session endpoints `GET /session` and `POST /logout` belong to SureBright's own portals. `/session` reads the portal session cookie or a portal bearer token and returns `authenticated` with the member's `sbMemberId`, `storeParentId`, `emailId`, `fullName`, `role`, `shop`, `idp` and `isSbAdmin`, or `{"authenticated": false}`; a partner access token is not a portal token and returns `authenticated: false`. `/logout` clears the portal session cookies and returns `{"success": true}`. You do not need either for a partner integration. ## Errors All errors are `{"error": "...", "error_description": "..."}`. | Status | `error` | When | |---|---|---| | `400` | `invalid_request` | A `/par` parameter is missing or malformed (the description names it, for example `state must contain between 16 and 512 characters`, `PKCE S256 code_challenge is required`, `redirect_uri is not registered for this client`, `external_tenant_id is required`) | | `400` | `unsupported_response_type`, `unsupported_grant_type` | Anything other than `code` / `authorization_code` | | `400` | `invalid_scope` | `openid` missing, or a scope your client is not registered for | | `400` | `invalid_request_uri` | `/authorize` with an unknown, used or expired `request_uri` | | `400` | `invalid_grant` | Code invalid, expired, reused, verifier mismatch, or connection no longer active | | `401` | `invalid_client` | Client authentication failed, a public client sent a secret, or the browser `Origin` is not registered. `WWW-Authenticate: Basic realm="SureBright Partner OIDC"` | | `401` | `invalid_token` | `/userinfo` without a valid bearer token | | `503` | `temporarily_unavailable` | Partner sign-in is not configured in this environment or the client registry is unreachable; retry later | --- # Record or cancel a POS sale Source: https://docs.surebright.com/api-reference/endpoint/partner/transaction-ingest > POST /v1/transaction lets an external POS or ERP record protection-plan sales with SureBright, and cancel them, without anyone typing them into the POS portal. `POST /v1/transaction` is the ingest endpoint behind the SureBright POS. If your stores already run their own point-of-sale or ERP system, call it when a sale that includes a SureBright plan is completed, and again when that sale is cancelled or refunded. SureBright creates one contract per unit sold, emails the customer their coverage, and shows the sale in the POS portal's [Sales History](/pos/sales-history) and your billing. ``` POST {POS_API_BASE}/v1/transaction Content-Type: application/json ``` `{POS_API_BASE}` is the base URL SureBright shares with you when the integration is set up. ## Authentication This endpoint takes no API key or bearer token. It is enabled per merchant: SureBright registers your `merchantId` for ingest, and a request whose `merchantId` is not registered is refused with `403`. Treat your `merchantId` as confidential and send requests only from your server, never from a browser or a till's front end. ## Request body Where the sale was made. Use `OFFLINE` for an external POS or ERP. Other values are reserved for SureBright's own platform integrations and are rejected with `400` unless SureBright has set them up for you. Your SureBright store ID. Must be registered for ingest. Your identifier for the order. Together with `merchantId` and the customer's email it is how SureBright finds the contracts again when you cancel. `"1"` records a sale. `"3"` cancels contracts on an earlier sale. Any other value is accepted and does nothing (`200` with an empty object). Date of the sale as `MM/dd/yyyy`. Coverage dates are derived from it, so send it on every create. If it is missing or unreadable, the date the request is processed is used. Date of the cancellation as `MM/dd/yyyy`. Stamped on each cancelled contract. The order number printed on the customer's receipt, when it differs from `orderId`. Your invoice number for the sale. Identifier of the staff member who made the sale, for your own reporting. The customer. Fields below. One entry per product line that carries a plan. Fields below. ### customerDetails The customer's email. The coverage email goes here, and it is part of the key used to find the sale on cancellation. A create without it fails with `400`. First name. Last name. Phone number. Street address. When it is missing the contract is held for address capture and the customer is asked for it; see [Why a contract is on hold](/contracts/holds). Second address line. City. State or province name. Two-letter state or province code. ZIP or postal code. Country. Plans are sold in the US and Canada. Optional structured shipping address: `firstName`, `lastName`, `address1`, `address2`, `city`, `province`, `provinceCode`, `zip`, `country`, `countryCode`, `phone`. Optional structured billing address: `firstName`, `lastName`, `address1`, `address2`, `city`, `provinceCode`, `zip`, `country`, `phone`. ### orderItems[] Must be `"A"` (active) on a create. Anything else fails the whole request with `400`. Plan term in months, as a numeric string, for example `"36"`. On a cancel it must match the contract being cancelled. Position of the line on the order, as a numeric string (`"1"`, `"2"`, ...). Units sold. One contract is created per unit. `0` creates nothing. Your product identifier. Used as the key in the response. The SureBright plan category code for the product, as given to you by SureBright. Required to price the plan unless `quoteId` and `quoteItemId` are sent. Country of sale, `US` or `CA`. Required to price the plan unless `quoteId` and `quoteItemId` are sent; an unknown value fails with `400`. What the customer paid for the product. Used to price the plan. What the customer paid for the plan. When the plan was quoted through the SureBright quote API, the quote's ID. With `quoteItemId`, the term and category are taken from the quote. The quote line's ID. Product name as shown to the customer. Model number. Manufacturer. Manufacturer warranty in months. Affects when SureBright coverage starts for extended-warranty plans. Serial number. On a cancel it must match the contract being cancelled, so send it on the create too when you have it. `NEW`, `USED`, `REFURBISHED` or `CERTIFIED_REFURBISHED`. Your variant identifier. List price before discounts. Tax charged on the product. Tax charged on the plan. Currency of the amounts, for example `USD` or `CAD`. Till ticket number. Your store location identifier, stored on the contract. Your identifier for the salesperson, stored on the contract. Product image URL, shown in the POS. Your reason code for a cancellation. Stamped on the contract when `transactionReason` is `"3"`. Unknown fields are ignored. ## Example: record a sale ```bash curl -X POST "{POS_API_BASE}/v1/transaction" \ -H "Content-Type: application/json" \ -d '{ "sourcePlatform": "OFFLINE", "merchantId": "your-store-id", "orderId": "INV-10482", "orderNumber": "10482", "transactionReason": "1", "purchaseDate": "11/09/2026", "salesMemberUserId": "staff-17", "customerDetails": { "customerFirstName": "Dana", "customerLastName": "Lee", "customerEmail": "dana.lee@example.com", "customerPhone": "+1 415 555 0199", "customerAddress1": "456 Pine Avenue", "customerCity": "San Francisco", "customerState": "California", "customerProvinceCode": "CA", "customerZipCode": "94101", "customerCountry": "US" }, "orderItems": [ { "contractStatus": "A", "productSequenceNumber": "1", "productId": "SKU-2211", "modelName": "55-inch 4K TV", "manufacturerName": "Acme", "manufacturerWarrantyDuration": 12, "serialNumber": "SN-88211", "productCondition": "NEW", "quantity": 1, "productPurchasePrice": "899.00", "subCategory": "", "insurerCountry": "US", "termMonths": "36", "totalContractCost": "129.00", "contractCurrency": "USD" } ] }' ``` ## Example: cancel a sale Send the same `merchantId`, `orderId` and `customerDetails.customerEmail` as the create, `transactionReason` `"3"`, and one entry per line to cancel. Each entry is matched to active contracts on that order by `serialNumber` and `termMonths`; `quantity` says how many units to cancel. ```bash curl -X POST "{POS_API_BASE}/v1/transaction" \ -H "Content-Type: application/json" \ -d '{ "sourcePlatform": "OFFLINE", "merchantId": "your-store-id", "orderId": "INV-10482", "transactionReason": "3", "cancellationDate": "11/20/2026", "customerDetails": { "customerEmail": "dana.lee@example.com" }, "orderItems": [ { "productId": "SKU-2211", "serialNumber": "SN-88211", "termMonths": "36", "quantity": 1, "cancelReasonCode": "CUSTOMER_RETURN" } ] }' ``` The customer is emailed about the cancellation. Lines that match no active contract return an empty array and are not an error. ## Response `200 OK` with a JSON object keyed by each line's `productId`. The value is the list of contracts created (or cancelled) for that line, one per unit. Contracts for that order line. Each contract has the fields below. SureBright's contract identifier. Quote it to support. Processing status of the contract. Processing stage. `ADDRESS_CAPTURE` when the customer's street address was missing, otherwise `PAYMENT_CAPTURE`. Echo of `sourcePlatform`. Echo of `orderItems[].salesPersonId`. Echo of `orderItems[].locationId`. Echo of `orderItems[].quoteId`. Echo of `orderItems[].quoteItemId`. The contract as issued: `contractNumber`, `contractStatus` (`A` active, `C` cancelled), `termMonths`, `effectiveDate` and `expirationDate` (`MM/dd/yyyy`), `salePurchaseDate`, `orderId`, `orderNumber`, `invoiceNumber`, `productId`, `variantId`, `modelName`, `modelNumber`, `manufacturerName`, `manufacturerWarrantyDuration`, `serialNumber`, `productCondition`, `productPurchasePrice`, `totalContractCost`, `contractCurrency`, `quantity`, `cancellationDate`, `cancelReasonCode`, and `customerDetails` as sent. Store `contractId` against your order line. It is the identifier the POS portal, the customer's documents and SureBright support all use. ## Errors | Status | Body | Cause | |---|---|---| | `400` | `{"data":{"orderId":["Please provide Order_Id"]},"statusCode":1,"statusMessage":"Validation Error"}` | `sourcePlatform` or `orderId` is blank. The `data` map names each failing field. | | `403` | `ERROR: Forbidden for this merchant id` | `merchantId` is missing or not registered for ingest. | | `400` | `ERROR: Invalid or missing arguments in Order_Items` | An item's `contractStatus` is not `"A"`, or `termMonths` or `productSequenceNumber` is not numeric. | | `400` | `Invalid sourcePlatform {VALUE} provided during transaction` | `sourcePlatform` is not one SureBright accepts for you. | | `400` | `ERROR: Invalid country` | `insurerCountry` is not a country SureBright sells in. | | `400` | `ERROR: Invalid or missing arguments` | Anything else: unknown store for `merchantId`, missing `customerDetails.customerEmail`, missing `transactionReason`, or a malformed body. | Error bodies other than the validation error are plain text. A request that fails after some contracts were created is not rolled back; check the response map before retrying. `OFFLINE` sales are not de-duplicated. Sending the same `orderId` twice with `transactionReason` `"1"` creates a second set of contracts, and the customer is emailed twice. Make your retry logic idempotent on your side. --- # Categorize a product Source: https://docs.surebright.com/api-reference/endpoint/product-category/categorize > Find the SureBright category of a product from its page URL or from the product details you already have. A plan is priced by category, so before you can quote a product that is not in a store catalog SureBright has indexed, you need its SureBright category (`sbCategoryId`). These endpoints read a product page or take the details you send, classify the product, and return the category together with what was read. Use the `v2` endpoints; the older ones remain for existing integrations. No authentication header is needed for these endpoints. | Endpoint | Input | Use | |----------|-------|-----| | `GET /quote/api/v2/productCategory/getProductDetails` | Product page URL | Read and classify a page | | `POST /quote/api/v2/productCategory/getProductCategory` | Product details in the body | Classify without fetching the page | | `GET /quote/api/productCategory/getProductDetails` | Product page URL | Previous reader; same shape with a legacy mapping block | | `GET /quote/api/productCategory` | Product page URL | Original classifier; kept for existing callers | ## Classify a product page `GET https://{HOST_NAME}/quote/api/v2/productCategory/getProductDetails` The product page URL, Base64-encoded (UTF-8). Your own reference for this product; echoed back. One is generated when omitted. `0` or `false` to re-read the page instead of returning the cached result for this URL. ```bash URL=$(printf '%s' 'https://www.example-store.com/products/aero-2-electric-scooter' | base64) curl "https://{HOST_NAME}/quote/api/v2/productCategory/getProductDetails?base64ProductURL=${URL}" ``` ### Response `false` when the page was read. The decoded URL. Your reference, or the generated one. What was read and decided about the product. Product title. Product description. Price as shown on the page. Main image. The storefront platform detected. The category path the classifier assigned, broad to narrow. The SureBright category, when the path maps to one. Its name. New, refurbished or used, as inferred from the page. Personal or commercial use, as inferred. `COMPLETED`. Results are cached per URL. The same URL returns the cached result until you pass `useCache=0`. ## Classify from product details `POST https://{HOST_NAME}/quote/api/v2/productCategory/getProductCategory` Use this when you already have the product fields, for example from your own catalog feed, and do not want SureBright to fetch the page. Product title. Product description. Price, for example `"899.00"`. Main image URL. Product page URL. Used as the cache key, so send it when you have it. Your own reference; echoed back. Comma-separated category names from your store, to help the classifier. ```bash curl -X POST 'https://{HOST_NAME}/quote/api/v2/productCategory/getProductCategory' \ -H 'Content-Type: application/json' \ -d '{ "url": "https://www.example-store.com/products/aero-2-electric-scooter", "title": "Aero 2 Electric Scooter", "description": "Foldable commuter e-scooter, 350 W motor, 25 km range.", "price": "899.00", "imageURL": "https://www.example-store.com/cdn/aero-2.jpg", "categories": "Mobility, Electric scooters" }' ``` ### Response The same envelope as above (`isError`, `url`, `vectorId`, `productData`, `status`), plus: `SUCCESS` when a category was assigned, otherwise `FAILED`. The narrowest category label assigned. Legacy mapping block: `classifiedCategory` and `isCoverageAvailable` (`false` when the product fell into an uncovered bucket such as `OTHERS`). The other ids in it are internal. ## Older endpoints `GET /quote/api/productCategory/getProductDetails?base64ProductURL=&vectorId=&useCache=` returns the page reading with the same legacy `insurerCategory` block and `status: "COMPLETED"`. `GET /quote/api/productCategory?base64ProductURL=` (or `?vectorId=` to re-read an earlier result) returns `productData` with a `specifications` map that includes `Classified Category`, the legacy `insurerCategory` block, `status` and `vectorId`. It is slower and should not be used for new work. ## Errors All four endpoints use the same codes. | Code | Body | Meaning | |------|------|---------| | `400` | `{"isError": true, "message": "Insufficient params"}` | `base64ProductURL` (or `vectorId` on the original endpoint) missing | | `400` | `{"isError": true, "message": "Insufficient data"}` | Empty body on the details endpoint | | `400` | `{"isError": true, "message": "Error in getting product details"}` or `"Error in getting product category"` | The page could not be read, or `title`, `description`, `price` or `imageURL` is missing | | `400` | `{"isError": true, "message": "Unable to scrape page"}`, `"No Product Data found"`, `"No Matching vectors found"` | Original endpoint only | | `500` | `Internal Server Error` | Unexpected failure | SureBright logs every request and response on these endpoints for quality review. --- # Coverage text Source: https://docs.surebright.com/api-reference/endpoint/quote/coverage-text > The coverage bullets the widget shows for a category, with and without a priced store category. Every quote carries its coverage bullets in `coverageV1`. When you need the text before you have a quote, for example on a category landing page, a comparison table or a product page where the price is not yet known, use these two endpoints. Both are read-only and need no authentication. | Endpoint | Returns | |----------|---------| | `GET /quote/api/insurerCategory/listCoverageOptions` | The bullets of the one coverage type your store offers for a category | | `GET /quote/api/insurerCategory/listProductCoverage` | Every coverage type the category can carry on your store, with bullets and plan terms, even before the category is priced | ## Coverage options for a category `GET https://{HOST_NAME}/quote/api/insurerCategory/listCoverageOptions` Your store identifier. The SureBright category (from [List Category](/api-reference/endpoint/store-category/list-category) or a quote). Default `SHOPIFY`. ```bash curl 'https://{HOST_NAME}/quote/api/insurerCategory/listCoverageOptions?storeId=example-store.myshopify.com&sbCategoryId=2b7e4f10-9c3a-4d5e-8f61-7a2b3c4d5e6f' ``` ### Response `false` on success. `AD` (accidental damage), `B` (breakdown) or `AB` (both). Bullet text for the inline widget. May contain `
` line breaks.
Bullet text for the details popup. Shorter text for small screens, when provided. Text for the quick-view card, when provided. `COVERAGE_OPTION` for what the plan covers, `WHY_SUREBRIGHT_OPTION` for service promises (claims, cancellation, support). Icon key the widget maps to its icon set, or `null`. A ready-made icon image chosen from the bullet text, or an empty string.
### Errors | Code | Body | Meaning | |------|------|---------| | `400` | `{"isError": true, "message": "Insufficient params"}` | `storeId` or `sbCategoryId` missing | | `500` | `{"isError": true, "message": "Internal server error"}` | The store does not offer this category on this platform, or no coverage text is configured for it | ## Product coverage for a category `GET https://{HOST_NAME}/quote/api/insurerCategory/listProductCoverage` Answers "what protection can this product carry here" from the product's SureBright category alone. It works for a store whose categories are not priced yet, so **By Product** would return no plans, and it can classify a product URL for you when you do not have the category. Your store identifier. The SureBright category. Required unless `base64ProductURL` is sent. A product page URL, Base64-encoded. SureBright classifies it first and uses the resulting category. See [Categorize a product](/api-reference/endpoint/product-category/categorize). Default `SHOPIFY`. `US` or `CA`. Limits the answer to what the store offers in that country. ```bash curl 'https://{HOST_NAME}/quote/api/insurerCategory/listProductCoverage?storeId=example-store.myshopify.com&sbCategoryId=2b7e4f10-9c3a-4d5e-8f61-7a2b3c4d5e6f&country=US' ``` ### Response `false` on success. The category answered for (the classified one when you sent a URL). Its name, or `null` when the store does not offer it. Always `false`: this answer does not depend on a priced store category. One entry per coverage type the store offers for the category. Empty when it offers none. `AD`, `B` or `AB`. Bullets, `{info, iconImageUrl}`, deduplicated by text. The plan terms offered, in years, ascending. ### Errors | Code | Body | Meaning | |------|------|---------| | `400` | `{"isError": true, "message": "Insufficient params: storeId and sbCategoryId (or base64ProductURL)"}` | Missing inputs, or the URL could not be classified | | `404` | `{"isError": true, "message": "No active coverage for this category on this store"}` | The lookup failed | | `500` | `{"isError": true, "message": "Internal server error"}` | Unexpected failure | --- # Get a quote Source: https://docs.surebright.com/api-reference/endpoint/quote/get-quote > Read back a saved quote by its quoteId: the plans it offered, their prices and the coverage text. `GET https://{HOST_NAME}/quote/api/quote/{quoteId}` Use this endpoint to look up a quote you received earlier, for example to show the plan a customer chose, or to check a `quoteId` and `quoteItemId` before you record an order. The quote must have been saved: send `quoteSyncMode=SYNC` on the quoting call, or wait for the asynchronous save to complete. ## Headers No authentication header is needed for this endpoint. ## Path parameters The `quoteId` returned by a quoting endpoint. ## Example request ```bash curl 'https://{HOST_NAME}/quote/api/quote/4d2a9e7c-1b3f-4a6d-9c8e-2f1a3b4c5d6e' ``` ## Response `false` on success. The quote identifier. The store the quote was made for. The platform the quote was requested from. The store category the quote was priced against. Your product reference, when the quote was made for a specific product. Country the quote was priced in. State or province, when it affected the price. The visit the quote was made in. When the quote was created. When the quote was last updated. One entry per plan offered. Plan identifier to send when recording an order. Plan price. Plan term in years. Lower bound of the product price band the plan applies to. Upper bound of that price band. The product price the plan was priced on. Country of the plan. State or province of the plan, when set. Whether the widget preselects this plan. Whether the widget shows a ribbon on this plan. The ribbon label. Whether the plan is still offered. The coverage bullets of the category: `info`, `popup`, `optionType`, `iconType`. Opaque reference to the plan's terms. Build the terms link from it as the widget does. Direct link to the terms document, when one is published for the category. ## Errors | Code | Body | Meaning | |------|------|---------| | `500` | `{"isError": true, "message": "Internal Server Error"}` | No quote with this `quoteId` (not saved yet, or unknown), or an unexpected failure | There is no `404`; treat `500` on a known id as "not saved yet" and retry after the quoting call completes. --- # Quote API overview Source: https://docs.surebright.com/api-reference/endpoint/quote/index > What a quote is, how quotes are generated for a product or a category, and which endpoint to use. 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** --- ## If you only have a product's title and price There is no endpoint that quotes straight from a product's title, description and price. The old **By Product Details** endpoint was retired. Do it in two calls instead: [Categorize a product](/api-reference/endpoint/product-category/categorize) returns its SureBright category, then [By Category](/api-reference/endpoint/quote/list-warranty-quotes-by-category) returns the plans for that category and price. --- ## Prices depend on the country 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._ --- ## What a quote contains 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 --- ## Using a quote 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 --- # Quotes from an invoice Source: https://docs.surebright.com/api-reference/endpoint/quote/invoice-upload > Upload a purchase invoice, get every line item read, categorised and quoted, then correct a line and check eligibility rules. Use these endpoints when a customer brings a receipt instead of a product in your catalog: a direct-to-consumer registration, a service counter, or an in-store sale of a plan for something bought elsewhere. SureBright reads the invoice, categorises each line, prices plans for each line, and keeps the result as a lead you can edit line by line. A separate endpoint applies the eligibility rules on their own. No authentication header is needed for these endpoints. The two invoice endpoints share a limit of 50 requests per minute across all callers. Over the limit they return `429` with a `Retry-After` header (seconds). ## Upload an invoice `POST https://{HOST_NAME}/quote/api/lead/invoice/upload` Send the invoice as `multipart/form-data`. The invoice. PDF, PNG, JPEG, WebP or TIFF, up to 20 MB. Your store identifier. `US` or `CA`. Invoice currency. Your account identifier. Resolved from the store when omitted. State or province, when prices vary by region. Default `CUSTOM`. An existing lead to replace with this invoice instead of creating a new one. ```bash curl -X POST 'https://{HOST_NAME}/quote/api/lead/invoice/upload' \ -F 'file=@receipt.pdf;type=application/pdf' \ -F 'storeId=example-pos-store' \ -F 'country=US' ``` ### Response The lead holding this invoice. Use it to edit lines. Reference to the processed file. What was read from the invoice: `firstName`, `lastName`, `email`, `mobilePhone`, and `address` (`addressLine1`, `addressLine2`, `city`, `state`, `country`, `zip`). Empty strings when not found. One entry per line read from the invoice. Identifier for edits. Product name as read. Description as read. Quantity, default 1. Unit price (the line total when no unit price was printed). The invoice date, applied to every line. SureBright category the line was classified into; empty when classification failed. Name of that category. Classification confidence, when the classifier reports one. One entry per plan term: `tenure`, `price`, `monthlyPrice`. Empty when the line could not be quoted. Why `quotes` is empty: `MISSING_SB_CATEGORY`, `INVALID_PRICE`, `POLICY_BAND_NOT_FOUND`, `INVALID_COUNTRY_`, `QUOTE_FAILED` or `QUOTE_EXCEPTION`. `null` when quotes were produced. When the line was last priced. ### Errors | Code | Body | Meaning | |------|------|---------| | `400` | `{"isError": true, "message": "File is required (field name: 'file')"}` | No file part | | `400` | `{"isError": true, "message": "storeId and country are required"}` | Missing form fields | | `400` | `{"isError": true, "message": "Unsupported file type: ..."}` | MIME type not in the supported list | | `429` | `{"isError": true, "message": "Rate limit exceeded: 50/min. Retry in Ns."}` | Shared limit reached; see `Retry-After` | | `500` | `{"isError": true, "message": "..."}` | The invoice could not be read (including files over 20 MB), or the lead could not be saved | ## Correct a line item `PUT https://{HOST_NAME}/quote/api/lead/{leadId}/invoiceLineItem/{lineItemId}` Send any subset of the editable fields. A changed `productTitle` or `description` re-classifies the line unless you also send `sbCategoryId`, which wins. The line is always re-priced. From the upload response. From `lineItemsList`. New product name. New description. Corrected unit price. Corrected purchase date. Corrected quantity. Force the SureBright category instead of re-classifying. ```bash curl -X PUT 'https://{HOST_NAME}/quote/api/lead/7f3a9c2e-4b1d-4e8f-9a6c-2d5b8e1f0a3c/invoiceLineItem/0c9e8d7b-6a5f-4e3d-2c1b-0a9f8e7d6c5b' \ -H 'Content-Type: application/json' \ -d '{ "productPrice": 1299.00, "productTitle": "Aero 2 Electric Scooter" }' ``` Response: `{"isError": false, "leadId": "...", "lineItem": {...}}` where `lineItem` has the same fields as an entry of `lineItemsList`. | Code | Body | Meaning | |------|------|---------| | `400` | `{"isError": true, "message": "No updatable fields provided"}` | Body had none of the editable fields | | `404` | `{"isError": true, "message": "Lead not found"}` or `"Line item not found"` | Unknown ids | | `429` | as above | Shared limit reached | | `500` | `{"isError": true, "message": "Failed to persist line item update"}` | Save failed | ## Check eligibility rules `POST https://{HOST_NAME}/quote/api/eligibility/evaluate` Runs the eligibility rules for an invoice and its lines without quoting. The rules that apply depend on the calling application, identified by the `site-id` header; SureBright gives you the identifier for yours. The same rules run inside **By Category** when that call carries a `site-id` header: an invoice-level block returns `422`, and blocked lines are listed in `blacklistedItems`. | Header | Description | Required | |--------|-------------|----------| | site-id | Your application identifier | Yes | | Content-Type | application/json | Yes | `purchaseDate` (`MM/DD/YYYY` or `YYYY-MM-DD`), and optionally `retailerName` and `totalAmount`. Each with `productTitle` and `manufacturerName`; other fields are passed through unchanged. ```bash curl -X POST 'https://{HOST_NAME}/quote/api/eligibility/evaluate' \ -H 'site-id: YOUR_APP_ID' -H 'Content-Type: application/json' \ -d '{ "invoice": { "purchaseDate": "2026-10-20" }, "lineItemList": [ { "productTitle": "Aero 2 Electric Scooter", "manufacturerName": "Aero" } ] }' ``` ### Rules | Rule | Error code | Severity | Fires when | |------|-----------|----------|------------| | `INVOICE_AGE_LIMIT` | `WARRANTY_WINDOW_EXCEEDED` | `BLOCK_INVOICE` | `invoice.purchaseDate` is more than 90 days ago | | `PRODUCT_BLACKLIST` | `PRODUCT_NOT_SUPPORTED` | `BLOCK_LINE_ITEM` | The product is one SureBright does not cover | | `MANUFACTURER_BLOCK` | `MANUFACTURER_NOT_SUPPORTED` | `BLOCK_LINE_ITEM` | The manufacturer is one SureBright does not cover | A rule is skipped, not failed, when the field it needs is missing (`purchaseDate` for the age rule, `productTitle` for the product rule, `manufacturerName` for the manufacturer rule). Not every application runs the age rule. ### Response Returned with `200` for eligible and ineligible results alike. `isEligible`, `error` (the invoice-level hit or `null`), `notices`. Your lines, each with `isEligible`, `error` (the blocking hit or `null`) and `notices`. Empty when the invoice itself is blocked. `blockedInvoice`, `blockedLineItemCount`, and `userMessage`, a sentence you can show the customer. A hit is `{ruleId, errorCode, severity, message, match}`. | Code | Body | Meaning | |------|------|---------| | `400` | `errorCode: MISSING_SITE_ID` | Header missing | | `400` | `errorCode: INVALID_REQUEST` | `lineItemList` is not an array | | `400` | `errorCode: UNKNOWN_APP` | `site-id` is not registered | | `500` | `errorCode: INTERNAL_ERROR` | Unexpected failure | --- # Cart quotes Source: https://docs.surebright.com/api-reference/endpoint/quote/list-cart-quotes > Price a protection plan for a cart, so one plan covers every eligible item the shopper has added. `POST https://{HOST_NAME}/quote/api/cart/listQuotes` Use this endpoint when the widget sits on the cart page or in a cart drawer and you want one plan that covers the eligible items in the cart, instead of one plan per product. SureBright reads the cart, works out which items are eligible, prices the plan on their combined value, and returns the same quote object the product endpoints return. For a single product on a product page, use **By Product** instead. ## Headers | Header | Description | Required | |--------|-------------|----------| | Content-Type | application/json | Yes | No authentication header is needed for this endpoint. ## Query parameters `SYNC` to have the quote saved before the response is returned. Send it when you will record an order with the returned `quoteId` and `quoteItemId`. Default `ASYNC`. ## Body Your store identifier (the `myshopify.com` domain on Shopify). `shop` is accepted as an alias. One of `SHOPIFY`, `BIGCOMMERCE`, `SHIFT4SHOP`, `LIGHTSPEED`, `LIGHTSPEED_R_SERIES`, `MAGENTO`, `WOOCOMMERCE`. Two-letter country code of the shopper, `US` or `CA`. The visit identifier returned by the widget configuration call for this shopper session. The platform cart token. When sent, SureBright reads the cart lines from the platform. Required unless you send `productId`, `variantId` and `quantity`. Product being added to the cart. Required with `variantId` and `quantity` when there is no `cartId`. Variant being added to the cart. Quantity being added. Items already covered by a plan in the cart (`productId`, `variantId`, `quantity`). When empty, `policyAmountOffset` on each plan equals the plan price; otherwise it is the difference against the plan already in the cart. ## Example request ```bash curl -X POST 'https://{HOST_NAME}/quote/api/cart/listQuotes?quoteSyncMode=SYNC' \ -H 'Content-Type: application/json' \ -d '{ "storeId": "example-store.myshopify.com", "platform": "SHOPIFY", "country": "US", "visitId": "6a0d0c1e-2b4f-4d8e-9f21-3c5e7a9b1d2f", "cartId": "c1-0f4a9b2e7d6c5b4a3f2e1d0c9b8a7f6e", "cartItemList": [] }' ``` ## Response The body is the standard quote object. The fields below are specific to cart quotes; the rest are described on **By Product**. Quote identifier. Send it with the selected `quoteItemId` when you record the order. `POLICY_FETCHED_SUCCESSFULLY` when plans were found. Otherwise the reason, for example `STORE_DETAILS_NOT_FOUND` or `POLICY_BAND_NOT_FOUND`. One entry per plan. Each carries `quoteItemId`, `price`, `monthlyPrice`, `coverageYears`, `deductibleAmount`, `defaultSelection`, and the store's plan `productId` and `variantId` to add to the cart. What the shopper pays on top of the plan already in the cart. Equals `price` when `cartItemList` is empty. Option values of the plan product to add (BigCommerce and similar platforms). Modifier that carries the covered items on platforms that use product modifiers. The cart items the plan covers: `productId`, `variantId`, `quantity`, `sku`, `price`. `true` when SureBright changed the plan line already in the cart to match the new covered items. The cart line of the plan SureBright added or updated, when `isCartModified` is `true`. Echo of `productId`. Echo of `variantId`. Coverage bullets for the widget: `info`, `popup`, `MOBILE_INFO`, `QUICK_VIEW_INFO`, each a list of `{coverageName, optionType, iconType}`. Link to the plan's terms. ## Errors | Code | Body | Meaning | |------|------|---------| | `200` | `statusMessage` other than `POLICY_FETCHED_SUCCESSFULLY`, empty `PolicyData` | No plan for this cart (store, product or price not covered) | | `400` | `{"isError": true, "message": "Insufficient params"}` | `country`, `visitId`, `platform` or `storeId` missing, or neither `cartId` nor `productId` + `variantId` + `quantity` sent | | `500` | `{"isError": true, "message": "Internal Server Error"}` | Unexpected failure | Responses are not cached. Each call returns a fresh quote. --- # Product quotes in bulk Source: https://docs.surebright.com/api-reference/endpoint/quote/list-product-quotes > Quote several Shopify products in one call, for point-of-sale and other screens that list many products. `POST https://{HOST_NAME}/quote/api/quote/listProductQuotes` Use this endpoint when one screen shows many products and you need a plan price for each, for example a Shopify POS tile or a recommendation panel. You send product ids; SureBright quotes every listed variant (or every variant of a product when you leave `variantId` out) in the store's own country and returns one quote object per variant. Shopify stores only. For a single product with the shopper's country, use **By Product**. ## Headers | Header | Description | Required | |--------|-------------|----------| | Content-Type | application/json | Yes | No authentication header is needed for this endpoint. ## Query parameters `SHOPIFY`. Any other value returns an empty list. Your `myshopify.com` store identifier. ## Body Shopify product id. Entries without it are skipped. Shopify variant id. Leave it out to quote every variant of the product. ## Example request ```bash curl -X POST 'https://{HOST_NAME}/quote/api/quote/listProductQuotes?platform=SHOPIFY&storeId=example-store.myshopify.com' \ -H 'Content-Type: application/json' \ -d '{ "productList": [ { "productId": "8011223344556", "variantId": "44011223344556" }, { "productId": "8011223344999" } ] }' ``` ## Response A JSON array with one standard quote object (see **By Product**) per variant, in request order, plus: The product quoted. The variant quoted. The country the quote was priced in: the store's country, or the point-of-sale country SureBright has set for the store. One entry per plan, with `quoteId`, `quoteItemId`, `price`, `monthlyPrice`, `coverageYears`, `deductibleAmount` and the plan `productId` and `variantId` to add to the sale. `POLICY_FETCHED_SUCCESSFULLY`, or why a variant got no plan (for example `POLICY_BAND_NOT_FOUND`). A variant that fails outright is left out of the array. ```json [ { "quoteId": "4d2a9e7c-1b3f-4a6d-9c8e-2f1a3b4c5d6e", "productTitle": "Aero 2 Electric Scooter", "ProductPrice": 899, "statusMessage": "POLICY_FETCHED_SUCCESSFULLY", "PolicyData": [ { "quoteItemId": "a1b2c3d4-0001", "price": 89.99, "monthlyPrice": 3.75, "coverageYears": 2, "deductibleAmount": 0, "defaultSelection": true } ], "storeProductId": "8011223344556", "storeVariantId": "44011223344556", "country": "US" } ] ``` ## Errors | Code | Body | Meaning | |------|------|---------| | `200` | `[]` | The store was not found or has no country set | | `400` | `[]` | Body, `platform` or `storeId` missing, or `platform` is not `SHOPIFY` | | `500` | `[]` | Unexpected failure | Responses are not cached. Each request and response is logged by SureBright for support. --- # Registration quotes Source: https://docs.surebright.com/api-reference/endpoint/quote/list-registration-quotes > Quote a plan for a product a customer bought earlier and is now registering, matched by title or product id. `POST https://{HOST_NAME}/quote/api/quote/listRegistrationQuotes` Use this endpoint on a product registration page: the customer already owns the product and gives you its name (or you know its product id) and the purchase date. SureBright finds the product in your catalog, prices the plan on the purchase price when it can, and checks that the purchase is still inside the post-purchase window. The response is the standard quote object. For plans offered on an existing order rather than a registration, see [Order quotes](/api-reference/endpoint/quote/order-quotes). ## Headers | Header | Description | Required | |--------|-------------|----------| | Content-Type | application/json | Yes | No authentication header is needed for this endpoint. ## Query parameters Your store identifier. `shop` is accepted as an alias. Two-letter country code of the customer, `US` or `CA`. The visit identifier for this session. Quote platform. Defaults to `REGISTRATION_POST_PURCHASE`; leave it out. The platform your catalog lives on. Default `SHOPIFY`. Restrict to one coverage type when the category offers more than one. `fr` returns French coverage text where it exists. `SYNC` to save the quote before responding. Send it when you will record an order with the returned ids. ## Body The body is the registration as the customer entered it. SureBright stores it with the quote and reads these fields: Product name. When `productId` is missing, SureBright matches the product by title; when no product matches, no quote is returned. Product id in your catalog. When sent, the first variant of the product is quoted. Variant id, when known. Purchase date (ISO 8601). When sent, the registration is rejected if it is older than the store's post-purchase window (30 days unless SureBright has set a different window for your store). ## Example request ```bash curl -X POST 'https://{HOST_NAME}/quote/api/quote/listRegistrationQuotes?storeId=example-store.myshopify.com&country=US&visitId=6a0d0c1e-2b4f-4d8e-9f21-3c5e7a9b1d2f"eSyncMode=SYNC' \ -H 'Content-Type: application/json' \ -d '{ "productTitle": "Aero 2 Electric Scooter", "dateOfPurchase": "2026-10-28", "email": "customer@example.com" }' ``` ## Response The standard quote object (see **By Product**), plus: The product SureBright matched. The variant SureBright quoted. One entry per plan, with `quoteItemId`, `price`, `monthlyPrice`, `coverageYears`, `deductibleAmount` and `defaultSelection`. `POLICY_FETCHED_SUCCESSFULLY`, or the reason no plan was found. ## Errors Business outcomes are returned with HTTP `200`, so read `isError` and `statusMessage`. | Code | Body | Meaning | |------|------|---------| | `200` | `{"isError": true, "message": "Registration post purchase quotes are not available for more than 30 days"}` | `dateOfPurchase` is outside the post-purchase window (the number of days is the store's window) | | `200` | `statusMessage` such as `PRODUCT_DETAILS_NOT_FOUND`, empty `PolicyData` | No product matched the title or id, or the product is not covered | | `400` | `{"isError": true, "message": "Insufficient params"}` | `storeId`, `country` or `visitId` missing | | `500` | `{"isError": true, "message": "Internal Server Error"}` | Unexpected failure | Responses are not cached. --- # By Category Source: https://docs.surebright.com/api-reference/endpoint/quote/list-warranty-quotes-by-category > Get the protection plans and prices for a SureBright category and product price, without a product in your catalogue. Parameters, example request and response, and errors. `GET https://{HOST_NAME}/quote/api/quote/category/listQuotes` Use this endpoint to price protection plans from a category and a product price, when the item is not a product SureBright can look up in your store's catalogue. It suits quoting tools, in-store sales and custom checkouts. One call can price several items, and the IDs it returns are the ones [Create Contracts for Order](/api-reference/endpoint/order/create-contract) accepts. Get the category IDs from [List Category](/api-reference/endpoint/store-category/list-category) first. If the item is in your store's catalogue, [By Product](/api-reference/endpoint/quote/list-warranty-quotes-by-product) or [By Url](/api-reference/endpoint/quote/list-warranty-quotes-by-url) is simpler, and for a whole cart use [Cart quotes](/api-reference/endpoint/quote/list-cart-quotes). ## Note All quote inputs go inside the `payload` JSON, which is sent Base64-encoded (UTF-8) as a query parameter. Send `quoteSyncMode=SYNC` when you will record an order with the returned `quoteId` and `quoteItemId`. ## Headers No authentication header is needed for this endpoint. ## Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `payload` | string | Yes | The JSON object described below, UTF-8, Base64-encoded, then URL-encoded like any query value. | | `quoteSyncMode` | string | No | `SYNC` saves the quote before the response returns. Any other value, or none, is treated as `ASYNC`, which saves it in the background. Send `SYNC` when you will pass the IDs to **Create Contracts for Order** straight away. | ## Payload fields | Name | Type | Required | Description | |------|------|----------|-------------| | `country` | string | Yes | Two-letter country code of the customer, for example `US` or `CA`. It has to match the country of the category you are quoting, or that entry returns no plan. | | `visitId` | string | Yes | Any unique identifier for the shopper session. | | `platform` | string | Yes | The platform you are calling from, for example `OFFLINE_PORTAL` as in the example below. `SHOPIFY` changes the response format (see **Behaviour notes**). | | `storeId` | string | Yes, unless `storeParentId` is sent | Your store identifier. | | `storeParentId` | string | Yes, unless `storeId` is sent | Your SureBright account identifier. Required when an entry is quoted by `sbCategoryId`. | | `province` | string | No | State or province of the customer. | | `storeCategoryList` | object[] | Yes | One entry per item to quote. Must not be empty. | | `storeCategoryList[].sbCategoryId` | string | One of `sbCategoryId` or `storeCategoryId` | SureBright category ID from **List Category**. Used only when the payload also carries `storeParentId`. | | `storeCategoryList[].storeCategoryId` | string | One of `sbCategoryId` or `storeCategoryId` | Store category ID from **List Category**. | | `storeCategoryList[].productPrice` | number | No | Price of the item. With it, you get the plans for the price band that contains it. Without it, you get every price band of the category. | | `storeCategoryList[].sbProductId` | string | No | A product reference. It is stored on the quote and returned with it. | | `storeCategoryList[].manufacturerWarrantyDuration` | integer | No | Manufacturer warranty of the item, in months. | ## Example request The payload before encoding: ```json { "storeParentId": "{storeParentId}", "country": "US", "visitId": "3d99a4ae-5cf0-4d87-8436-46c0cdc03676", "platform": "OFFLINE_PORTAL", "storeCategoryList": [ { "sbCategoryId": "4c3103e4-38dc-4171-96e5-b4b77ab0e96f", "productPrice": 899.99 } ] } ``` Encode it and call the endpoint. `--data-urlencode` takes care of the `+`, `/` and `=` characters in the Base64 string. ```bash PAYLOAD=$(printf '%s' '{"storeParentId":"{storeParentId}","country":"US","visitId":"3d99a4ae-5cf0-4d87-8436-46c0cdc03676","platform":"OFFLINE_PORTAL","storeCategoryList":[{"sbCategoryId":"4c3103e4-38dc-4171-96e5-b4b77ab0e96f","productPrice":899.99}]}' | base64 | tr -d '\n') curl -G 'https://{HOST_NAME}/quote/api/quote/category/listQuotes' \ --data-urlencode "payload=${PAYLOAD}" \ --data-urlencode 'quoteSyncMode=SYNC' ``` ## Example response `200`, trimmed to the fields you are most likely to use: ```json { "quoteList": [ { "quoteId": "33f21a29-95ca-4150-b5df-afe36f5ef537", "sbCategoryId": "4c3103e4-38dc-4171-96e5-b4b77ab0e96f", "storeCategoryId": "ecca4210-09a4-446c-ad87-5e65bd50df12", "country": "US", "productPrice": 899.99, "coverageType": "AD", "quoteItemList": [ { "quoteId": "33f21a29-95ca-4150-b5df-afe36f5ef537", "quoteItemId": "a7defcbd-aa07-4e01-9076-c1935af20a98", "coverageYears": "1", "policyPrice": "79", "lowerPrice": 749.99, "upperPrice": 999.99, "storeProductVariantPrice": "899.99" } ], "coverageList": [ { "optionType": "COVERAGE_OPTION", "info": "Coverage bullet shown to the shopper", "popup": "Coverage bullet shown in the details popup" } ] } ] } ``` | Field | Type | Meaning | |-------|------|---------| | `quoteList` | object[] | The quotes for the entries that could be priced. | | `quoteList[].quoteId` | string | Identifies the quote. Send it as `planDetails.quoteId` when you create the contract. | | `quoteList[].sbCategoryId`, `storeCategoryId` | string | The category the quote was priced under. Use these to match a quote back to the entry you sent. | | `quoteList[].coverageType` | string | Coverage type of the plan, for example `AD`. | | `quoteList[].quoteItemList` | object[] | One entry per plan, sorted by tenure. | | `quoteItemList[].quoteItemId` | string | Identifies the plan. Send it as `planDetails.quoteItemId` when you create the contract. | | `quoteItemList[].coverageYears` | string | Length of the plan in years. | | `quoteItemList[].policyPrice` | string | Price of the plan. | | `quoteItemList[].lowerPrice`, `upperPrice` | number | The product price band this plan price applies to. Most useful when you did not send `productPrice`. | | `quoteItemList[].storeProductVariantPrice` | string | The `productPrice` you sent. | | `quoteItemList[].deductibleAmount` | number | Amount the customer pays per claim, when the plan has one. | | `quoteList[].coverageList` | object[] | Coverage text for display. Each entry has an `optionType` (`COVERAGE_OPTION` or `WHY_SUREBRIGHT_OPTION`) and the text in `info` and `popup`. | ## Errors | Status | Body | Cause and what to do | |--------|------|----------------------| | `400` | `{"isError": true, "message": "Insufficient params"}` | `country`, `visitId` or `platform` is missing, neither `storeId` nor `storeParentId` was sent, or `storeCategoryList` is missing or empty. | | `200` | `{"quoteList": []}`, or fewer quotes than entries | No plan for one or more entries. See **Behaviour notes**. | | `200` | A plain-text message instead of JSON | `payload` is missing or does not decode to JSON. Treat any response without a `quoteList` array as a failure and fix the encoding. | ## Behaviour notes - **An entry with no plan is left out.** The call still returns `200`. If nothing can be priced, `quoteList` is empty. Do not match quotes to entries by position; use `sbCategoryId` or `storeCategoryId`. - **What stops an entry being priced.** The category ID is not set up for your store, `country` differs from the category's country, no price band contains `productPrice`, or the entry carries `sbCategoryId` while the payload has no `storeParentId`. - **Every call creates new quotes.** Each priced entry gets a fresh `quoteId` on every call. - **Use `SYNC` before creating contracts.** With the default mode the quote is saved in the background, so a create call sent immediately afterwards may not find it. - **`sbCategoryId` wins.** When an entry has both IDs and the payload has `storeParentId`, the entry is quoted by `sbCategoryId`. - **`platform: SHOPIFY`.** Each quote comes back in the storefront widget format instead, with plans under `PolicyData` as described on [Cart quotes](/api-reference/endpoint/quote/list-cart-quotes). ## 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) ## Related Get the category IDs to quote against. Record the sale with the returned quote IDs. Quote a product from your store's catalogue. Status codes for the quote endpoints. --- # By Product Source: https://docs.surebright.com/api-reference/endpoint/quote/list-warranty-quotes-by-product > Get the protection plans and prices for a platform product and variant in a given country. Parameters, example request and response, and errors. `GET https://{HOST_NAME}/quote/api/quote/listWarrantyQuotes` Use this endpoint to price protection plans for one product variant, for example on a product page. You identify the product by the `productId` and `variantId` it has in your store. SureBright returns the plans it can offer for that variant, each with a price, a tenure and the plan product to add to the cart. The product has to be in the catalogue SureBright holds for your store. Pick the quote endpoint by what you know about the item: | You have | Use | |----------|-----| | The product ID and variant ID | This page | | Only the product page URL | [By Url](/api-reference/endpoint/quote/list-warranty-quotes-by-url). It is the same endpoint with `productUrl` in place of the two IDs | | A category and a price, with no product in the catalogue | [By Category](/api-reference/endpoint/quote/list-warranty-quotes-by-category) | | A cart, and you want one plan across its eligible items | [Cart quotes](/api-reference/endpoint/quote/list-cart-quotes) | ## Headers | Header | Description | Required | |--------|-------------|----------| | X-SureBright-Access-Token | Access token for authentication | No | ## Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `storeId` | string | Yes | Your store identifier. On Shopify this is the `myshopify.com` domain. | | `productId` | string | Yes | The product's ID in your store. Not needed when you send `productUrl` instead (see **By Url**). | | `variantId` | string | Yes | The variant's ID in your store. Send it with `productId`. | | `country` | string | Yes | Country of the shopper. Must be exactly `US` or `CA`, in upper case. Any other value returns `502`. | | `platform` | string | No | Your store platform: `SHOPIFY`, `BIGCOMMERCE`, `SHIFT4SHOP`, `LIGHTSPEED`, `LIGHTSPEED_R_SERIES`, `MAGENTO` or `WOOCOMMERCE`. Defaults to `SHOPIFY`. | | `state` | string | No | State code of the shopper. Accepted, but not used to price the quote. | ## Example request ```bash curl 'https://{HOST_NAME}/quote/api/quote/listWarrantyQuotes?platform=SHOPIFY&storeId=example-store.myshopify.com&productId=8606368530686&variantId=45667967238398&country=US' ``` ## Example response `200`, trimmed to the fields you are most likely to use: ```json { "warrantyQuoteId": "929d14dd-2937-4290-9818-8fca2a00a9a3", "productTitle": "Example Espresso Machine", "categoryName": "Small Home Appliance", "sbCategoryId": "4c3103e4-38dc-4171-96e5-b4b77ab0e96f", "coverageWidgetHeading": "Add premium product protection", "warrantyQuoteItemList": [ { "warrantyQuoteItemId": "8c78bc1a-0790-4cd3-a3f9-5ed97bbe59f5", "warrantyTenure": 2, "warrantyPrice": 64.99, "warrantyProductId": 7080029454439, "warrantyVariantId": 40937702359143, "policyProductSKU": "SBW-1U-SHAB-2900" } ], "coverageList": [ { "coverageItemType": "COVERAGE_OPTION", "coverageItemTitle": "Your warranty plan provides,", "coverageItemList": ["Coverage bullet shown to the shopper"] }, { "coverageItemType": "WHY_SUREBRIGHT_OPTION", "coverageItemTitle": "Why Surebright?", "coverageItemList": ["Benefit bullet shown to the shopper"] } ], "tncLink": "https://customer.surebright.com/t-c/..." } ``` | Field | Type | Meaning | |-------|------|---------| | `warrantyQuoteId` | string | Identifies this quote. | | `warrantyQuoteItemList` | object[] | One entry per plan on offer. | | `warrantyQuoteItemList[].warrantyQuoteItemId` | string | Identifies the plan within the quote. | | `warrantyQuoteItemList[].warrantyTenure` | number | Length of the plan in years. | | `warrantyQuoteItemList[].warrantyPrice` | number | Price of the plan. | | `warrantyQuoteItemList[].warrantyProductId`, `warrantyVariantId` | number or string | The plan product and variant in your store's catalogue. Add this variant to the cart when the shopper picks the plan. | | `warrantyQuoteItemList[].policyProductSKU` | string | SKU of the plan product. | | `warrantyQuoteItemList[].deductibleAmount` | number | Amount the customer pays per claim, when the plan has one. | | `coverageList` | object[] | Coverage text grouped for display. `coverageItemType` is `COVERAGE_OPTION` or `WHY_SUREBRIGHT_OPTION`; `coverageItemList` holds the bullet points. | | `coverageWidgetHeading`, `coveragePopupHeading` | string | Headings for the offer and for the details popup. | | `productTitle`, `productImageURL` | string | Title and image of the product being covered. | | `categoryName`, `sbCategoryId` | string | The SureBright category the product was priced under. | | `tncLink` | string | Link to the plan's terms. | ## Errors Every error has the shape below. The HTTP status code and `errorType` carry the same value. ```json { "isError": true, "errorType": 504, "errorMessage": "PRODUCT_NOT_ELIGIBLE" } ``` | Status | `errorMessage` | Cause and what to do | |--------|----------------|----------------------| | `501` | `Insufficient Params. Mandatory Params missing` | `storeId` or `country` is missing, or you sent neither `productUrl` nor both `productId` and `variantId`. | | `502` | `Validation failed for input params` | `country` is not exactly `US` or `CA`. | | `504` | `PRODUCT_DETAILS_NOT_FOUND` | SureBright has no record of that product for the store, or the variant has no price. Check the IDs and the `platform` value. | | `504` | `PRODUCT_NOT_ELIGIBLE` | The product is marked as not eligible for a plan. Do not show an offer. | | `505` | `POLICY_BAND_NOT_FOUND` | No plan is priced for this product's category at its price. Do not show an offer. | | `500` | `UNKNOWN_EXCEPTION` | No plan can be offered for another reason, for example the store is not recognised, protection is switched off for the product, the price is zero, or plans are not offered in that country for your store. Retrying returns the same answer. | | `500` | `Something unexpectedly went wrong` | Unexpected failure, or a `platform` value that is not in the list above. | See [HTTP status codes](/api-reference/http-status-codes) for the full list shared with **By Url**. ## Behaviour notes - **No plan is an error, not an empty list.** When a product cannot be covered you get one of the `504`, `505` or `500` bodies above instead of an empty `warrantyQuoteItemList`. Hide the offer on any status other than `200`. - **What makes a product ineligible.** The product is missing from the catalogue SureBright holds for your store, it is marked as not eligible, protection is switched off for it, its price is zero or missing, there is no plan priced for its category and price, or plans are not offered in the shopper's country for your store. - **Quotes can be reused.** Calling again for the same store, product, variant and country can return the same `warrantyQuoteId` and item IDs. - **`state` does not change the price** on this endpoint. - **Recording the sale yourself.** This endpoint takes no `quoteSyncMode`. If you create contracts through [Create Contracts for Order](/api-reference/endpoint/order/create-contract), quote with [By Category](/api-reference/endpoint/quote/list-warranty-quotes-by-category), which can save the quote before it responds. ## 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) ## Related Quote from a product page URL. Quote from a category and a price. One plan across the eligible items in a cart. Status codes for the quote endpoints. --- # By Url Source: https://docs.surebright.com/api-reference/endpoint/quote/list-warranty-quotes-by-url > Get the protection plans and prices SureBright offers for a product, from its product page URL. Parameters, example request and response, and errors. ## Headers No authentication header is needed for this endpoint. ## How the product is resolved SureBright resolves the product from the URL you send, so the store's catalog must already be indexed by SureBright. - **Shopify stores**: send the plain product page URL containing `/products/`. If the product has more than one variant, include `?variant=`; otherwise the URL is rejected with `503 Invalid Url`. - **Custom storefronts** that SureBright has enabled for URL quotes: send the URL Base64-encoded. A value that cannot be decoded returns `400 Invalid website URL`. This is the same endpoint as **By Product**. Send `productUrl` instead of `productId` and `variantId`; `storeId` and `country` are required in both cases. ## Error codes The HTTP status code and the `errorType` in the body carry the same value. | Code | Meaning | |------|---------| | `501` | Insufficient parameters (`storeId`, `country`, and `productUrl` or `productId` + `variantId`) | | `502` | Validation failed: `country` must be `US` or `CA` | | `503` | Invalid URL: the product or variant could not be resolved from `productUrl` | | `504` | Product not found, or not eligible for a warranty | | `505` | No price band configured for the product's category and price | | `500` | Something unexpectedly went wrong | ## 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 a whole system order. Provide your store, product line items, and installer warranty duration to receive available warranty plans, prices, product coverage details, and terms and conditions. When quotes are available, SureBright saves them and your product details as a proposal that you can update or use to create a contract. For the whole flow, from the first quote to a cancelled plan, read the [Whole System Warranty guide](/api-reference/whole-system-warranty). ## Headers | Header | Description | Required | |--------|-------------|----------| | X-SureBright-Access-Token | Access token for authentication | No | | Content-Type | application/json | Yes | ## Country This endpoint prices plans for the United States only. The request carries no country or state field. If your account has no United States Whole System Warranty set up, the call returns `512`. If you sell in Canada, ask your SureBright contact. --- ## Request fields | Field | Required | Notes | |-------|----------|-------| | `storeId` | Yes | Your SureBright store id | | `lineItemList` | Yes | Every line on the proposal. See the next table | | `installerWarrantyDuration` | Yes | The installer's own installation warranty, as a number of months. See [Installer warranty duration](#installer-warranty-duration) | | `partnerProposalId` | No | Your own proposal reference. Keep it unique to one proposal on your `storeId` | | `sbProposalId` | No | Leave out of the first request. Send it to re-quote an existing proposal. A non-empty string of at most 200 characters | | `sbAccountId` | No | For platforms quoting for a connected installer: the installer's `sbAccountId`. It is stored with the proposal as a reference and does not change the price. See [Acting for an installer](/api-reference/whole-system-warranty#acting-for-an-installer-connect-to-surebright) | | `partnerId` | No | For platforms: your `client_id`. When sent, SureBright takes your store from it, and a `storeId` sent with it must be that same store | | `sbSalesLeadId` | No | Older name for `sbProposalId`. See the backward-compatibility note | Each `lineItemList` entry: | Field | Required | Notes | |-------|----------|-------| | `title` | Yes | The product name | | `unitPrice` | Yes | Price of one unit | | `quantity` | Yes | Number of units | | `description` | No | Helps SureBright recognise the product | | `categoryTag` | No | Your own category for the product. Helps SureBright recognise it | | `productId`, `variantId` | No | Your own ids for the line. Stored with the proposal | ### Installer warranty duration | You send | Result | |----------|--------| | `3`, `6` or `12` | Priced on that length | | Any other value above `3` | Priced on the nearest length below it: `9` is priced as `6`, `24` as `12`. A plan created from the quote is dated with that same length | | Less than `3` | `513` with `No Quote Found` | | Nothing | `511` with `installerWarrantyDuration is required` | ## Requesting Quotes Send `storeId`, `lineItemList`, and `installerWarrantyDuration` to request warranty quotes for your products. Leave `sbProposalId` out of the initial request. You can include a new `partnerProposalId` to associate the proposal with an ID from your system. Reusing an existing ID on the same `storeId` updates that proposal, so never use one reference for two different jobs. When quotes are available, the response includes the warranty plans and `sbProposalId`. Save this ID to request updated quotes or create a contract. ## How line items are priced Each line is assessed for eligibility, and only eligible lines are priced. | Response field | Meaning | |----------------|---------| | `lineItemList[].isCovered` | `true` when the line is eligible and counts towards the price. `false` when it is not: the line is not part of the plan | | `lineItemList[].sbCategoryName` | The SureBright category of a covered line. Empty for a line that is not covered | | `totalCoveredAmount` | `unitPrice` times `quantity`, added up across the covered lines only. The plans are priced on this figure | | `warrantyQuoteItemList[]` | One entry per plan term (2, 3 and 5 years) with `warrantyQuoteItemId`, `coverageYears` and `quotePrice`, the suggested customer price | | `warrantyQuoteItemList[].planCost` | What SureBright charges you for that plan. Left out when it is not available | If no line is covered the call returns `516`. If the covered lines add up to zero it returns `515`. There is no separate line type for installation labour on this endpoint: a labour line is assessed like any other line, so read its `isCovered` value. ## Updating Quotes for an Existing Proposal Include `sbProposalId` or `partnerProposalId` with your current line items and installer warranty duration to request updated quotes for the same proposal. If you provide both, they must refer to the same proposal. A conflicting `partnerProposalId` returns HTTP `409` with code `PROPOSAL_ID_MISMATCH`. Quotes are recalculated using the submitted product details and current pricing and coverage. If the products, classification, installer warranty duration, pricing, and coverage are unchanged, the existing quote and plan IDs are returned. If these details change, the proposal and its quotes are updated, and the IDs from the earlier quote for that installer warranty duration can no longer be used to create a contract. A proposal keeps one quote per installer warranty duration. Quoting the same proposal with a different duration adds a quote for that duration and leaves the others in place. The `warrantyQuoteId` you send when you create the contract decides which one applies. Once a platform has created a contract for a connected installer from a proposal, re-quote that proposal with `sbProposalId`. A request that carries only `partnerProposalId` does not find it and starts a new proposal. To create or update a contract, submit `sbProposalId`, `warrantyQuoteId`, and the selected `warrantyQuoteItemId` to the **Create / Update Contracts for Whole System Warranty** endpoint. Use the quote and plan IDs from the same response. Updating quotes does not automatically update an existing contract. **Backward compatibility:** The response also includes `sbSalesLeadId` with the same value as `sbProposalId`. Existing integrations can use it to request updated quotes or create and update contracts. Leave it out of the initial quote request. If you provide both `sbProposalId` and `sbSalesLeadId`, their values must match; otherwise, this quote endpoint returns HTTP `409` with code `SB_PROPOSAL_ID_MISMATCH`. Any supplied `partnerProposalId` must refer to the same proposal. For new integrations, use `sbProposalId`. ## Errors Error bodies are `{"isError": true, "message": "..."}`. They carry no `errorType` field. A `code` is added on the rows that show one; on the `403`, `404`, `409` and `502` rows it is present when the request carried `sbProposalId` or `sbSalesLeadId`. | Status | `code` | `message` | Cause and what to do | |--------|--------|-----------|----------------------| | `511` | | `Insufficient Parameters` | The body, `storeId` or `lineItemList` is missing | | `511` | | `installerWarrantyDuration is required` | Send the installer warranty duration in months | | `512` | | A message that the store has no active Whole System Warranty set up for the country | Your account is not set up for Whole System Warranty in the United States. Ask your SureBright contact | | `513` | | `No Quote Found` | `installerWarrantyDuration` is below `3`, a line has no `title`, or no plan matched the covered total | | `514` | | `Store Not Found` | `storeId` is not known | | `515` | | `Not Eligible` | The covered lines add up to zero. Check `unitPrice` and `quantity` | | `516` | | `Category Not Found` | No line was recognised as eligible | | `400` | `INVALID_SB_PROPOSAL_ID` | `sbProposalId must be a non-empty string of at most 200 characters` | Fix `sbProposalId`, or leave it out to start a new proposal | | `400` | `INVALID_SB_SALES_LEAD_ID` | `sbSalesLeadId must be a non-empty string of at most 200 characters` | Fix `sbSalesLeadId`, or leave it out | | `404` | `SB_PROPOSAL_NOT_FOUND` | `Proposal Not Found` | No proposal has that `sbProposalId` | | `409` | `PROPOSAL_ID_MISMATCH` | `sbProposalId and partnerProposalId must identify the same proposal` | Send the pair that belongs together, or only `sbProposalId` | | `409` | `SB_PROPOSAL_ID_MISMATCH` | `sbProposalId and sbSalesLeadId must identify the same proposal` | Send one of the two, or the same value in both | | `409` | `PARTNER_PROPOSAL_RESERVED` | `Contract creation is in progress. Retry the proposal update after it finishes.` | A contract is being created from this proposal. Retry when the create call has returned | | `403` | `PARTNER_PROPOSAL_ACCESS_DENIED` | `Proposal does not belong to the supplied partner store` | The proposal has moved to a connected installer, and the `storeId` you sent is not the one the contract was created with | | `502` | `QUOTE_PERSISTENCE_FAILED` | `Could not persist the partner quote` | The quote could not be saved. Request quotes again before you create or update a contract | | `500` | `QUOTE_REQUEST_FAILED` | `Unable to process the quote request` | A re-quote failed unexpectedly. Send it again | | `500` | | `Something Unexpectedly Went Wrong` | Unexpected failure. Send it again | Requests that carry `partnerId` can also return: | Status | `code` | `message` | Cause | |--------|--------|-----------|-------| | `400` | `INVALID_PARTNER_ID` | `partnerId must be a valid client identifier` | `partnerId` is not a well-formed `client_id` | | `404` | `PARTNER_NOT_FOUND` | `Partner is unavailable` | No active application has that `client_id` | | `409` | `PARTNER_STORE_MISMATCH` | `partnerId and storeId must identify the same partner` | The `storeId` you sent is not your application's store. Leave `storeId` out or correct it | | `503` | `PARTNER_STORE_UNAVAILABLE` or `PARTNER_LOOKUP_UNAVAILABLE` | | SureBright could not look your application up. Retry | `511` to `516` are application codes on this endpoint, not gateway errors. Read the `message` before you retry: only `500`, `502` and `503` are worth retrying unchanged. ## Related The whole flow for platforms and installers. Turn a quote into a contract. --- # Order quotes (post-purchase) Source: https://docs.surebright.com/api-reference/endpoint/quote/order-quotes > List the plans still available for the items on an existing order, after the customer has bought. Use these endpoints to offer protection after checkout: on the order status page, in a follow-up email, or in a registration flow. You identify the order; SureBright reads its lines, skips refunded quantities and items that already carry a plan, checks the post-purchase window, and returns one quote per eligible line. There are two endpoints, depending on where the order lives. | Order recorded by | Endpoint | |-------------------|----------| | Your e-commerce platform (Shopify, WooCommerce, Shift4Shop, Magento, BigCommerce) | `GET /quote/api/quote/{platform}/order/listQuotes` | | The SureBright Order API (point-of-sale and custom stores) | `GET /quote/api/order/listQuotes` | No authentication header is needed for either endpoint. Responses are not cached. ## Platform orders `GET https://{HOST_NAME}/quote/api/quote/{platform}/order/listQuotes` One of `shopify`, `woocommerce`, `shift4shop`, `magento`, `bigcommerce` (lower case, in the path). Your store identifier on that platform. The platform's order id. `careLeadId` is accepted as an alias. The visit identifier for this session. Required for every platform except Shopify: `WOOCOMMERCE`, `SHIFT4SHOP`, `MAGENTO` or `BIGCOMMERCE`. `SYNC` to save the quotes before responding. Default `ASYNC`. Shopify only. `fr` returns French coverage text where it exists. ```bash curl 'https://{HOST_NAME}/quote/api/quote/shopify/order/listQuotes?shopName=example-store.myshopify.com&leadId=5801234567890&visitId=6a0d0c1e-2b4f-4d8e-9f21-3c5e7a9b1d2f"eSyncMode=SYNC' ``` ### Response One standard quote object (see **By Product**) per order line that was looked at. Lines that are fully refunded are left out. Each entry adds: `POLICY_FETCHED_SUCCESSFULLY` when plans are offered. `POLICY_ALREADY_PURCHASED` when the line already carries a plan (the entry then has an empty `PolicyData`). `POLICY_PURCHASE_WINDOW_EXPIRED` when the order is older than the store's post-purchase window (30 days from the order date unless SureBright has set another window for the store or the order). Quantity bought, net of refunds. `shopifyProductPurchaseQuantity` carries the same value. The price paid for the line, which the plan is priced on. Order date. Fulfillment date, for stores whose coverage starts at shipment. Plans for the line: `quoteId`, `quoteItemId`, `price`, `monthlyPrice`, `coverageYears`, `deductibleAmount`, `quotePlatform` (`PLATFORM_POST_PURCHASE`). Shopify only. `true` with an empty `quoteList` when the order itself could not be quoted; see `statusMessage`. Shopify only, with `isError`: `ORDER_DETAILS_NOT_FOUND`, `STORE_DETAILS_NOT_FOUND`, `INVALID_PROVINCE` (the order ships to a region the store does not cover), `POLICY_PURCHASE_WINDOW_EXPIRED`, or `FULFILLMENT_DATE_NOT_FOUND` (pre-order store, order not yet fulfilled). ### Errors | Code | Body | Meaning | |------|------|---------| | `200` | `{"quoteList": []}` | Nothing to offer, or (non-Shopify) the order or store was not found | | `400` | `{"isError": true, "message": "Insufficient params"}` | `shopName`, `leadId` or `visitId` missing | | `500` | `{"quoteList": []}` | Unexpected failure | ## Orders recorded through the Order API `GET https://{HOST_NAME}/quote/api/order/listQuotes?payload={base64}` For stores that record sales with **Create Contracts for Order** rather than through a platform, this endpoint re-quotes the order's lines by their categories. All inputs go inside the `payload` JSON, Base64-encoded as a query parameter, in the same way as **By Category**. Base64 (UTF-8) of a JSON object: `US` or `CA`. The visit identifier for this session. The platform the order was recorded under. Your store identifier. Required unless `storeParentId` is sent. Your account identifier. Your order id, as sent to the Order API. Required unless `sbOrderId` is sent. SureBright's order id. State or province, when prices vary by region. `SYNC` to save the quotes before responding. ```bash PAYLOAD=$(printf '%s' '{"country":"US","visitId":"6a0d0c1e-2b4f-4d8e-9f21-3c5e7a9b1d2f","platform":"CUSTOM","storeId":"example-pos-store","orderId":"INV-10492"}' | base64) curl "https://{HOST_NAME}/quote/api/order/listQuotes?payload=${PAYLOAD}"eSyncMode=SYNC" ``` ### Response One category quote (as on **By Category**) per order line that has a SureBright category your store sells into, priced on the line's price. The order as SureBright has it, including `orderLineItemList` and `orderPurchaseDate`. ### Errors | Code | Body | Meaning | |------|------|---------| | `200` | `{"isError": true, "message": "Order not found."}` | No order matches `orderId` or `sbOrderId` for this store | | `200` | `{"isError": true, "message": "Store Parent not found."}` or a message that the account has no active categories | The account is not set up for category quotes | | `400` | `{"isError": true, "message": "Insufficient params"}` | `payload` missing, or `country`, `visitId`, `platform`, a store id or an order id missing inside it | | `500` | `Internal Server Error` | Unexpected failure | --- # Shipping protection quote Source: https://docs.surebright.com/api-reference/endpoint/quote/shipping-quote > Price shipping protection for the items in a cart and learn which items are eligible. `POST https://{HOST_NAME}/quote/api/quote/shipping` Use this endpoint on the cart page or in checkout to offer shipping protection for the whole order. Send the cart lines; SureBright drops items that cannot carry shipping protection, prices the rest, and returns the plan product to add to the cart together with the coverage bullets. Shipping protection must be enabled on your store; see [Shipping protection](/shipping-protection/overview). Shipping protection is priced for US shipments. ## Headers | Header | Description | Required | |--------|-------------|----------| | Content-Type | application/json | Yes | No authentication header is needed for this endpoint. ## Body Your store identifier. `shop` is accepted as an alias. Default `SHOPIFY`. Cart currency. Default `USD`. Shopper's two-letter country code. A quote is only returned for `US`. Shopper's state or province code, used for the per-item eligibility check. The visit identifier for this session. The cart lines. Each needs `productId`, `variantId`, `price` and `quantity`; a line missing any of them is returned unpriced. `true` when the call comes from the checkout extension. The per-item product-protection eligibility then follows the checkout settings. ## Example request ```bash curl -X POST 'https://{HOST_NAME}/quote/api/quote/shipping' \ -H 'Content-Type: application/json' \ -d '{ "storeId": "example-store.myshopify.com", "platform": "SHOPIFY", "currency": "USD", "country": "US", "visitId": "6a0d0c1e-2b4f-4d8e-9f21-3c5e7a9b1d2f", "cartItems": [ { "productId": "8011223344556", "variantId": "44011223344556", "price": 349.00, "quantity": 1 }, { "productId": "8011223344999", "variantId": "44011223344999", "price": 29.00, "quantity": 2 } ] }' ``` ## Response Shipping protection quote identifier. Price of the shipping protection plan for this cart. The shipping protection product to add to the cart. The variant of that product priced for this cart. Option values of the plan product, on platforms that use them. Modifier id, on platforms that use product modifiers. The lines the plan covers, as priced. Every line you sent, with the eligibility result. The product's SureBright category, when the product is known. Present and `false` when the item cannot carry shipping protection and was left out of the price. Whether the item can carry product protection, for the checkout extension to decide what else to offer. Why `isEligible` is `false`, for example `Product is not eligible for shipping protection`, `Store does not support this country`, `Product protection is not enabled on checkout for this store`, `Missing product information`. Coverage bullets to show, `{coverageName, optionType, iconType}`. `optionType` is `COVERAGE_OPTION` for the desktop list and `MOBILE_COVERAGE_OPTION` for the mobile list. Your brand logo, when configured on the widget. ## Errors No-quote outcomes come back with HTTP `200` and `isError: true`; `productList` is still returned so you can show per-item eligibility. | Code | Body | Meaning | |------|------|---------| | `200` | `{"isError": true, "message": "Shipping insurance is not enabled for this store", "productList": [...]}` | Shipping protection is off for the store | | `200` | `{"isError": true, "message": "No products eligible for shipping protection", "productList": [...]}` | Every line was dropped | | `200` | `{"isError": true, "message": "Insufficient data in cart items", "productList": [...]}` | No line had all of `productId`, `variantId`, `price`, `quantity` | | `200` | `{"isError": true, "message": "Unable to get Quote."}` or `"Shipping quote service error"` | Pricing failed, including a non-US `country` | | `400` | `{"isError": true, "message": "Insufficient params"}` | `storeId` missing | | `500` | `{"isError": true, "message": "Internal Server Error"}` | Unexpected failure | Responses are not cached. --- # System warranty quotes by account Source: https://docs.surebright.com/api-reference/endpoint/quote/system-warranty-quotes > Price a whole-system plan from a list of priced line items or a total, without saving a proposal. `POST https://{HOST_NAME}/quote/api/quote/systemwarranty/listQuotes` This endpoint prices a whole-system plan for an installed system from the line items (or just the total) and the installer's own warranty term. Unlike **For Whole System Warranty**, it is keyed on your SureBright account rather than a store, and it does not save a proposal or return proposal ids, so its quotes cannot be turned into a contract. New integrations should use **For Whole System Warranty** (`POST /quote/api/whole-system/listQuotes`), which saves the quote as a proposal you can update and convert into a contract. This endpoint backs the pricing shown in the installer portal, where installers quote and record Whole System Warranty sales. It is not used by the Merchant Portal. For the API flow, read the [Whole System Warranty guide](/api-reference/whole-system-warranty). ## Headers | Header | Description | Required | |--------|-------------|----------| | Content-Type | application/json | Yes | No authentication header is needed for this endpoint. ## Query parameters `SYNC` to save the quote before responding. Default `ASYNC`. ## Body Your SureBright account identifier. `USD` prices for the US, `CAD` for Canada. The system's components. Required unless `totalPrice` is sent. Only items with an `sbCategoryId`, a unit price above zero and a quantity above zero count towards the total. SureBright also leaves out an item whose unit price is above the limit it sets; ask your SureBright contact if an item you expected is not counted. SureBright category of the component. Unit price. Quantity. Total system price, used when `lineItemsList` is not sent. The installer's own warranty on the system, in months. Priced terms are `3`, `6` and `12`. Other values round down to the nearest priced term; values below `3` return `513`. ## Example request ```bash curl -X POST 'https://{HOST_NAME}/quote/api/quote/systemwarranty/listQuotes' \ -H 'Content-Type: application/json' \ -d '{ "storeInfo": { "storeParentId": "0f6c1d2e-7a8b-4c9d-8e1f-2a3b4c5d6e7f", "currency": "USD" }, "lineItemsList": [ { "sbCategoryId": "2b7e4f10-9c3a-4d5e-8f61-7a2b3c4d5e6f", "productPrice": 4200, "quantity": 1 }, { "sbCategoryId": "2b7e4f10-9c3a-4d5e-8f61-7a2b3c4d5e6f", "productPrice": 650, "quantity": 2 } ], "installerWarrantyDuration": 12 }' ``` ## Response One standard quote object (see **By Category**) priced on the system total. `PolicyData` carries one entry per plan term with `quoteId`, `quoteItemId`, `price`, `coverageYears` and `deductibleAmount`. The system-warranty category the quote was priced against. ## Errors | Code | Body | Meaning | |------|------|---------| | `400` | `{"isError": true, "message": "Request body is required"}` | Empty body | | `400` | `{"isError": true, "message": "Missing required fields in payload"}` | `storeInfo` missing, or neither `lineItemsList` nor `totalPrice` | | `400` | `{"isError": true, "message": "Missing required store or customer information"}` | `storeParentId` or `currency` missing | | `400` | `{"isError": true, "message": "installerWarrantyDuration is required"}` | Duration missing | | `400` | `{"isError": true, "message": "Invalid total price"}` | The counted items add up to zero | | `400` | `{"isError": true, "message": "Store parent not found"}` or a message that the account has no system-warranty program for this currency | The account is not set up for system warranty in that country | | `513` | `{"isError": true, "message": "No Quote Found"}` | `installerWarrantyDuration` below `3` | | `500` | `{"isError": true, "errorType": 500, "errorMessage": "Something unexpectedly went wrong"}` | Unexpected failure | --- # 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 > Lists the warranty categories active on a store. Send either storeId or storeParentId. Stores on the flat category list get every active category in one array. Stores enabled for the Ln category tree (isLnCategoryEnabled) get one level of the tree per call: omit category for the top level, pass category= for a node's children, or pass view=leaves for every offered leaf at once. Use the returned sbCategoryId when listing quotes by category. ## Headers No authentication header is needed for this endpoint. ## Flat list and Ln category tree Most stores get a **flat list**: one call returns every category active on the store, and `category` / `view` are ignored. Stores that SureBright has enabled for the **Ln category tree** (`isLnCategoryEnabled`) get the tree one level at a time: | Request | Response | |---------|----------| | no `category` | The top-level categories the store sells into | | `category=` | That node's children. A child that is a leaf comes back as the store's priced category (one item per store category and country) | | `view=leaves` | Every offered leaf in one flat array, sorted by `lnPathName` (`category` is ignored) | Every item in a tree response carries `isLnCategory: true`, `lnSbCategoryId`, `lnLevel`, `parentSbCategoryId`, `isLeaf` and `childCount`. Non-leaf nodes have an empty `labelList` and no pricing; pass their `sbCategoryId` as `category` to descend. Leaf items are the same shape as a flat category plus: - `quoteSbCategoryId` – the id quotes resolve against (same value as `sbCategoryId`); send it as `storeCategoryList[].sbCategoryId` when listing quotes by category - `legacySbCategoryIdList` – the flat category ids this leaf replaces, for mapping an existing classification to its leaf - `lnPathName` – the full path, for example `Home Appliances > Small Home Appliance > Air Fryers` Use `view=leaves` when you price items rather than browse. Use the level-by-level walk when you build a category picker. ### Walking the tree ```bash # 1. Top level curl 'https://{HOST_NAME}/quote/api/storeCategory/listStoreCategories?storeId=example-store.myshopify.com' # 2. Children of one node (its sbCategoryId from step 1) curl 'https://{HOST_NAME}/quote/api/storeCategory/listStoreCategories?storeId=example-store.myshopify.com&category=9d2c7e1a-3f4b-4c5d-8e6f-1a2b3c4d5e6f' # 3. Every priced leaf in one call curl 'https://{HOST_NAME}/quote/api/storeCategory/listStoreCategories?storeId=example-store.myshopify.com&view=leaves' ``` A non-leaf node in step 1 or 2 looks like this; pass its `sbCategoryId` as `category` to descend: ```json { "sbCategoryId": "9d2c7e1a-3f4b-4c5d-8e6f-1a2b3c4d5e6f", "sbCategoryName": "Home Appliances", "categoryName": "Home Appliances", "labelList": [], "isLnCategory": true, "lnSbCategoryId": "9d2c7e1a-3f4b-4c5d-8e6f-1a2b3c4d5e6f", "lnLevel": 1, "parentSbCategoryId": null, "isLeaf": false, "childCount": 3 } ``` A leaf carries the store category fields of the flat list plus the tree fields: The leaf's id in the tree. It can differ from `sbCategoryId` when the store's pricing is still configured under a flat category the leaf replaces. The id to send as `storeCategoryList[].sbCategoryId` on **By Category**. The flat category ids this leaf replaces. The full path, for example `Home Appliances > Small Home Appliance > Air Fryers`. Depth in the tree, `1` for a top-level node. The parent node, `null` at the top level. Nodes are sorted by their configured order, then by name; `view=leaves` is sorted by `lnPathName`. A node with no priced leaf beneath it is left out, so the tree only shows what the store sells into. ## Errors | Code | Meaning | |------|---------| | `400` | Neither `storeId` nor `storeParentId` sent; `category` is not a single id; `view` is not `leaves`; or (tree stores) `category` is unknown for this store or has no child categories | | `503` | Tree stores only: the Ln category tree could not be loaded | --- # Platform webhooks SureBright receives Source: https://docs.surebright.com/api-reference/endpoint/webhooks/platform-receivers > The store-platform events SureBright subscribes to on Shopify, BigCommerce, WooCommerce, Magento, Lightspeed and Shift4Shop, the receiver each one is delivered to, how deliveries are authenticated, and what SureBright does with them. When you connect a store, SureBright registers webhooks on your platform so contracts follow your orders without any work on your side. This page is the reference list: which events are subscribed, where they are delivered, and how SureBright checks that a delivery is genuine. It is useful when you audit the webhooks on your store, allow-list outbound traffic, or read your platform's delivery logs. All receivers are under `https://{HOST_NAME}/partner/api`. They are maintained by SureBright; you never call them yourself, and the subscriptions are re-created if they go missing. ## Shopify SureBright subscribes 19 topics when the app is installed and keeps them in sync on every reinstall or scope change. The three privacy topics are declared on the app itself rather than subscribed per store. Every delivery must carry a valid `X-Shopify-Hmac-Sha256` signature over the raw body, computed with the app's secret; a bad or missing signature is answered `400` and ignored. Handlers answer `200` once a delivery is accepted, including deliberate no-ops, so Shopify does not retry them. | Topic | Receiver | What SureBright does | |---|---|---| | `orders/create` | `/v1/webhook/shopify/create` | Records the order; creates one contract per plan unit when the order is paid. | | `orders/updated` | `/v1/webhook/shopify/order` | Delivered trimmed to the fields SureBright reads. Creates contracts when the order becomes paid, updates customer details, cancels on an effectively full refund. | | `orders/edited` | `/v1/webhook/shopify/edited` | Reconciles plan quantities after an order edit. | | `orders/cancelled` | `/v1/webhook/shopify/cancel` | Cancels the order's contracts. | | `refunds/create` | `/v2/webhook/shopify/refund` | Cancels contracts for refunded plan units; raises a case when a covered product was refunded. | | `fulfillments/create`, `fulfillments/update` | `/v2/webhook/shopify/fulfillment` | Marks plan lines fulfilled; on fulfillment-based stores dates the contracts, and takes the dates back when a fulfillment is cancelled. | | `draft_orders/create`, `draft_orders/update` | `/v1/webhook/shopify/draftOrder` | Records the draft order event for the [over-the-phone sales flow](/draft-order-guide/shopify-draft-order). | | `checkouts/create`, `checkouts/update` | `/v1/webhook/shopify/checkout/cart-recovery` | Captures the cart for Abandoned Cart recovery. Discarded for stores without the feature. | | `products/update` | `/v1/webhook/shopify/product` | Refreshes SureBright's copy of the product so it can be quoted. | | `products/create`, `products/delete` | `/v1/shopify-webhook/product-create`, `/v1/shopify-webhook/product-delete` (SureBright catalog service) | Adds or removes the product in SureBright's catalog. | | `bulk_operations/finish` | `/v1/webhook/shopify/bulkOperations/finish` | Completes a catalog sync that was run as a Shopify bulk operation. | | `markets/create`, `markets/update`, `markets/delete` | `/v1/webhook/shopify/markets` | Syncs Shopify Markets so plans are priced per market. | | `app/uninstalled` | `/v1/webhook/shopify/app/uninstall` | Marks the store uninstalled and stops processing for it. | | `customers/data_request`, `customers/redact`, `shop/redact` (app-level) | `/v1/webhook/shopify/customer/data-request`, `/v1/webhook/shopify/customer/redact`, `/v1/webhook/shopify/shop/redact` | Records the privacy request for compliance handling. | ## BigCommerce Registered against your store during the first authorization of the SureBright app. Each subscription carries an `x-surebright-api-key` header that SureBright generates for your store at install time (a signed `platform:store` token). A delivery whose key is missing, fails the signature check or names another platform is rejected. | Scope | Receiver | What SureBright does | |---|---|---| | `store/order/created`, `store/order/updated` | `/v1/webhook/bigCommerce/order` | Creates contracts for paid plan lines; cancels contracts for plan lines removed or cancelled. | | `store/order/refund/created` | `/v1/webhook/bigCommerce/order` | Cancels contracts for refunded plan units. | | `store/shipment/*` | `/v1/webhook/bigCommerce/order/shipment` | Dates coverage on fulfillment-based stores and creates shipping-protection contracts for the shipment. | | `store/product/created`, `store/product/updated` | `/v1/webhook/bigCommerce/product` | Refreshes the product, its categories and images. | | `store/category/created`, `store/category/updated` | `/v1/webhook/bigCommerce/category` | Refreshes the category list used for mapping. | A fifth receiver, `/v1/webhook/bigCommerce/order/refund`, exists for refund events delivered separately; current installs route refunds to `/order`. See [BigCommerce](/bigcommerce/overview) for the install flow. ## WooCommerce Four order webhooks are registered on your store when the SureBright plugin is connected. Each delivery is checked against `x-wc-webhook-signature`, the HMAC WooCommerce computes over the raw body with the webhook's secret, and the store is identified from `x-wc-webhook-source`. A failed signature is answered `400`. | Topic | Receiver | What SureBright does | |---|---|---| | `order.created` | `/v1/webhook/woocommerce/order/create` | Records the order and creates contracts for paid plan lines. | | `order.updated` | `/v1/webhook/woocommerce/order/update` | Re-reconciles the order: creates contracts once it is paid and cancels units for refunded or removed plan lines. | | `order.deleted` | `/v1/webhook/woocommerce/order/delete` | Cancels the order's contracts. | | `order.restored` | `/v1/webhook/woocommerce/order/restore` | Treated as an update: re-reconciles the restored order. | ## Magento The SureBright Magento module sends events itself rather than through native Magento webhooks: it observes product saves and order saves and posts to SureBright. Each event carries a store-bound access token (`sb-access-token` header, or `sbAccessToken` in the body) issued when the module is connected; the token is verified and must name a Magento store. | Module event | Receiver | What SureBright does | |---|---|---| | `product_create_update` | `/v1/webhook/magento/product` | Refreshes the product so it can be quoted. | | `order_create_update` | `/v1/webhook/magento/order` | Fetches the order from your Magento REST API and creates, updates or cancels contracts to match. The body only needs the order ID and token. | | Either, as a typed envelope | `/v1/webhook/magento/events`, `/v1/webhook/magento/svix` | Dispatches on `sbEventType` to the product or order handler above; the `svix` path is for stores whose module delivers through the Svix relay. | See the [Magento install guide](/magento/install-guide). ## Lightspeed | Series | Event | Receiver | What SureBright does | |---|---|---|---| | X-Series | `product.update` | `/v1/webhook/lightspeed/product` | Refreshes the product. | | X-Series | `sale.update` | `/v1/webhook/lightspeed/order` | Creates contracts for completed sales with plan lines; a return cancels the matching contracts. | | R-Series | order sync | `/v1/webhook/lightspeedrseries/order` | Fed by SureBright's own R-Series order sync, not by a Lightspeed webhook. Creates or cancels contracts for the synced sale. | X-Series deliveries are accepted when the body carries Lightspeed's `type`, `domain_prefix` and `payload`; the store is resolved from `domain_prefix` and must be a connected store. ## Shift4Shop | Event | Receiver | What SureBright does | |---|---|---| | Order created, order changed | `/v1/webhook/shift4shop/order` | Reads the order and creates or cancels contracts for its plan lines. | The store is identified from the store URL in the order payload. ## Delivery and retries - A receiver answers `200` when it has accepted a delivery, even when it decides to do nothing (store uninstalled, feature off, nothing relevant changed). Platforms retry only on non-2xx responses, so a `400` from a failed signature is not retried while a `500` from a transient failure is. - Processing is idempotent: the same event delivered twice does not create a second contract. - Deliveries that cannot be parsed or fail validation are recorded with the platform and store so SureBright can investigate; you do not need to resend them. --- # Widget configuration Source: https://docs.surebright.com/api-reference/endpoint/widget-config/bootstrap > The configuration a storefront loads once per page to know what to offer, where, and how it should look. `GET https://{HOST_NAME}/quote/api/storeWidgetConfig/v2/{storeName}` The SureBright storefront SDK calls this endpoint when a page loads, before any quote. The response says which offers are on for your store (product page, cart, checkout, shipping protection, post-purchase, registration), how the widget should look and read, which page elements it attaches to, and which A/B treatment or page-specific design this visitor gets. A headless storefront that renders its own widget reads the same configuration from here. Everything in the response is what you publish from the merchant portal; see [Settings](/merchant-portal/settings). ## Headers No authentication header is needed for this endpoint. ## Parameters Your store identifier. You can send it as the `storeId` or `storeName` query parameter instead and call `/quote/api/storeWidgetConfig/v2`. The visitor's session id from an earlier call. When omitted, SureBright creates a visit and returns its id in `data.visitId`; send that id on every later quote call for the session. Default `SHOPIFY`. The storefront theme the page is rendered with (on Shopify, the theme id). Used by design targeting rules. The page template suffix (on Shopify, the product template suffix). Used by design targeting rules. `false` to read the published configuration directly instead of SureBright's cached copy. Use it to check a change you just published. ## Example request ```bash curl 'https://{HOST_NAME}/quote/api/storeWidgetConfig/v2/example-store.myshopify.com?visitId=6a0d0c1e-2b4f-4d8e-9f21-3c5e7a9b1d2f&themeId=151234567890&pageTemplate=premium' ``` ## Response `0` on success. `success`. Your store identifier. The store name shown in the widget. The platform the configuration is for. Version number of the published configuration. Status of that configuration. The visit id to send on quote calls. Which offers are on. Booleans: `isProductOfferingEnabled`, `isCartOfferingEnabled`, `isCheckoutOfferingEnabled`, `isShippingInsuranceEnabled`, `isPostPurchaseEnabled`, `isProductRegistrationEnabled`, `isBottomCartCTAEnabled`, `isQuickViewEnabled`, `isCartDrawerEnabled`, `isCartNotificationEnabled`, `isRibbonEnabled`, `isNoCoverageOptionVisible`, `isDefaultSelectionEnabled`, `isAnalyticsEnabled`. How the widget looks and reads. One section per concern, each `null` when not customised: `theme`, `offeringCardStyle`, `modalOfferingCardStyle`, `offeringCardLabel`, `pdpLayout`, `popupModalLayout`, `quickViewLayout`, `cartLayout`, `postPurchaseLayout`, `productRegistrationLayout`, `shippingInsuranceLayout`, `content`, `responsive`. List-valued fields are always arrays, never `null`. Identifier of the design this visitor received. Differs from `baseAttributeSetId` when an experiment or a targeting rule applied. Identifier of the published (control) design. How the SDK attaches to your storefront: `selector` (page elements to mount on), `interceptor` (cart and checkout calls to observe), `variantResolution` (how the selected variant is read). Each `null` when the platform defaults apply. Optional behaviours switched on for the store, with their settings in `capabilityParameterMap`. Settings for the enabled capabilities, keyed by capability id. `{experimentId, treatmentId}` when the visitor is in a running A/B test, otherwise `null`. Pass both on your analytics events so results attribute correctly. `null` when the store has no page targeting rules. Otherwise `{isActive: true, matchedRuleId, configId}`; `matchedRuleId` and `configId` are `null` when no rule matched the `themeId` and `pageTemplate` you sent and the live design was served. ## Caching - A successful response is cacheable at the edge and in the browser: `Cache-Control: public, max-age=3600, s-maxage=2592000` (one hour in the browser, 30 days at the edge), with `Vary: CloudFront-Viewer-Country, Accept-Encoding`. SureBright purges the edge copy when you publish. - When the visitor is in an experiment (`experimentTracking` set) or the store has targeting rules (`designTargeting.isActive`), the response is per visitor or per page and is sent with `Cache-Control: no-store`. - SureBright also keeps a server-side copy of the published configuration. `useCache=false` skips it for that request. ## Errors | Code | Body | Meaning | |------|------|---------| | `400` | `{"isError": true, "message": "Store ID is required"}` | No store in the path or query | | `404` | `{"isError": true, "message": "Store not found or V2 config not available"}` | Unknown store, or the store has no published configuration | | `500` | `{"isError": true, "message": "Internal Server Error"}` | Unexpected failure | Error responses are never cached. --- # HTTP status codes Source: https://docs.surebright.com/api-reference/http-status-codes > The status codes and error bodies the quote, category and order endpoints return, and what to do about each. SureBright's quote and category endpoints return the result as the HTTP status code. Where a body carries an `errorType`, it has the same value as the status code. ## Warranty quotes by product or URL `GET /quote/api/quote/listWarrantyQuotes` Quotes Found Insufficient Parameters – `storeId`, `country`, and either `productUrl` or both `productId` and `variantId` are required Validation Failed for Input Parameters – `country` must be a two-letter code and one of `US` or `CA` Invalid URL – the product or variant could not be resolved from `productUrl` (By Url only) Product Not Found, or product not eligible for a warranty Price band not found for the product's category and price Something Unexpectedly Went Wrong ## Quotes by category `GET /quote/api/quote/category/listQuotes` Request processed. When no plan matches, the body still carries `200` with an empty `quoteList` and `isError: true` plus a `statusMessage`. Insufficient params – `country`, `visitId`, `platform`, a non-empty `storeCategoryList`, and `storeId` or `storeParentId` are required inside `payload` Internal Server Error ## Store categories `GET /quote/api/storeCategory/listStoreCategories` Categories listed (an empty list when none are configured) Neither `storeId` nor `storeParentId` sent, invalid `category` or `view`, or (Ln tree stores) unknown `category` for this store Ln category tree unavailable (Ln tree stores only) ## Whole system warranty The whole system endpoints use their own code set (`512`–`520` on contract creation, `400`/`404`/`409`/`502` on quotes). They are listed on the **List Quotes for Whole System Warranty** and **Create / Update Contracts for Whole System Warranty** pages. ## Order endpoints `/partner/api/v1/order` returns standard HTTP codes: `200`, `207` (partial success, see `errorList`), `400`, `401`, `404` (lookup only) and `500`. See the individual Order pages. --- # Integrate with the API Source: https://docs.surebright.com/api-reference/integration-tutorial > The end-to-end path for a custom storefront or back office: list categories, get quotes, show the offer, create contracts when the order is paid, report fulfilment, update or cancel, and look contracts up. This page walks one order through the SureBright API, from the first quote to a cancelled plan. It is for teams selling from their own storefront, app or back office rather than through one of SureBright's platform integrations. Each step names the endpoint, shows a minimal request and lists the response fields the next step needs. The linked reference pages carry the full field lists. ## Before you start You need the API host (`HOST_NAME`), your `storeId` and an API key. [Authentication](/api-reference/authentication) says where each comes from. The category and quote calls in steps 1 to 3 take no key. Make the Order calls from your server, never from the browser, so the key stays private. While you build, keep `"isTestOrder": true` in the order body in step 4. The order is recorded as a test order with a **Test** badge on **Sales**. See [Live keys and testing](/api-reference/authentication#live-keys-and-testing). ## The integration, step by step [List Category](/api-reference/endpoint/store-category/list-category): `GET /quote/api/storeCategory/listStoreCategories` ```bash curl 'https://{HOST_NAME}/quote/api/storeCategory/listStoreCategories?storeId={storeId}' ``` The response is an array. From each entry keep: | Field | Use | |---|---| | `sbCategoryId` | The category to quote against in step 2 | | `sbCategoryName`, `labelList` | Names for mapping your product types to a category | | `storeParentId` | Sent with `sbCategoryId` in step 2 | If your store uses the category tree, the same endpoint returns one level per call, or every priced leaf with `view=leaves`. The reference page explains both. [By Category](/api-reference/endpoint/quote/list-warranty-quotes-by-category): `GET /quote/api/quote/category/listQuotes` All inputs go in one JSON object, sent Base64-encoded as the `payload` query parameter. Send `quoteSyncMode=SYNC` so the quote is saved before the response returns and can be used in step 4 straight away. ```bash PAYLOAD=$(printf '%s' '{ "storeParentId": "{storeParentId}", "country": "US", "visitId": "3d99a4ae-5cf0-4d87-8436-46c0cdc03676", "platform": "OFFLINE_PORTAL", "storeCategoryList": [ { "sbCategoryId": "{sbCategoryId}", "productPrice": 199.99 } ] }' | base64 | tr -d '\n') curl -G 'https://{HOST_NAME}/quote/api/quote/category/listQuotes' \ --data-urlencode 'quoteSyncMode=SYNC' \ --data-urlencode "payload=${PAYLOAD}" ``` `country`, `visitId`, `platform` and a non-empty `storeCategoryList` are required, and `storeParentId` must be present when you quote by `sbCategoryId`. `visitId` is any identifier you generate for the shopper's session. Add `province` when you know the shopper's state or province. Each `storeCategoryList` entry quotes one product. From `quoteList[]` keep: | Field | Use | |---|---| | `quoteId` | The quote. Sent in step 4 | | `quoteItemList[].quoteItemId` | One plan option. Sent in step 4 | | `quoteItemList[].policyPrice`, `coverageYears` | The plan's price and term | | `coverageList` | Coverage text to show beside the plans | An empty `quoteList` means no plan matched that category and price. Show no offer. To quote by your own product and variant ids instead, see [By Product](/api-reference/endpoint/quote/list-warranty-quotes-by-product). It only works for products SureBright already knows. There is no API call in this step. Render one option per `quoteItemList` entry with its term and price, plus a way to decline. When the shopper picks a plan, store its `quoteId`, `quoteItemId` and price on your cart line. To read a saved quote back later, use [Get a quote](/api-reference/endpoint/quote/get-quote). When you render the offer yourself, post shopper interactions to the [Event Collector](/frontend-widget-integration/frontend-widget-kit/event-collector) if you want them in **Sales** analytics. If you would rather not build the offer UI, see [Headless and custom storefronts](/frontend-widget-integration/frontend-widget-kit/headless-and-custom-storefronts). [Create Contracts for Order](/api-reference/endpoint/order/create-contract): `POST /partner/api/v1/order` Call this once payment has succeeded. Contracts are created as soon as the request is accepted. If the request times out, send it again with the same `orderId`; see [Limits, idempotency and versioning](/api-reference/limits-and-versioning#idempotency). ```bash curl -X POST 'https://{HOST_NAME}/partner/api/v1/order' \ -H 'X-SureBright-Access-Token: sb_live_YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "storeId": "{storeId}", "orderId": "ORDER-1001", "orderPurchaseDate": "2026-11-12T10:15:30Z", "orderLineItemList": [ { "lineItemId": "LINE-1", "productId": "PROD-1", "productSKU": "SKU-1", "productTitle": "Sample product", "quantity": 1, "salePrice": 199.99, "totalPrice": 199.99, "planDetails": { "policyPurchaseDate": "2026-11-12T10:15:30Z", "quoteId": "{quoteId}", "quoteItemId": "{quoteItemId}" } } ], "customerDetails": { "firstName": "Test", "lastName": "Customer", "customerEmail": "test.customer@example.com", "addressLine1": "123 Main St", "city": "Austin", "state": "TX", "country": "US", "zipCode": "78701" }, "isTestOrder": true }' ``` What the request must carry: | Part | Required fields | |---|---| | Order | `storeId`, `orderId` (your own order id), `orderPurchaseDate`, a non-empty `orderLineItemList`, `customerDetails` | | Each line | `lineItemId`, `productId`, `productSKU`, `productTitle`, `quantity`, `salePrice` | | `planDetails` | `policyPurchaseDate`, plus `quoteId` and `quoteItemId` from step 2 | | `customerDetails` | `firstName`, `lastName`, `customerEmail`, `addressLine1`, `city`, `state`, `country`, and `zipCode` or `pinCode` | Dates are ISO 8601 with `Z` or a timezone offset. Put `planDetails` only on the lines that carry a plan; a line without it creates nothing. One contract is created per unit of `quantity`. In the response, `contractList[]` has one entry per contract (`lineItemId`, `contractId`, `isCancelled`). Store each `contractId` against your order line. `errorList[]` is present when something failed. `200` means no line failed. `207` means some contracts were created and some lines failed. `400` means nothing was created. SureBright emails the customer the plan confirmation; see [Emails your customers receive](/customer-emails/overview). [Set or revert fulfillment dates](/api-reference/endpoint/order/fulfillment): `POST /order/api/v1/contract/fulfillment` Skip this step unless your store is set up so that coverage starts when the product ships. The endpoint is enabled per store by SureBright and uses its own server-to-server token, not your API key. Ask your SureBright contact before you build it. ```bash curl -X POST 'https://{HOST_NAME}/order/api/v1/contract/fulfillment' \ -H 'Authorization: Bearer {SERVICE_TOKEN}' \ -H 'Content-Type: application/json' \ -d '{ "contractIds": ["{contractId}"], "action": "SET", "fulfillmentDate": "2026-11-14T09:00:00Z" }' ``` Check `results[]`: each entry carries the `contractId`, its `effectiveDate` and `expirationDate`, and `skipped: true` when the contract already had dates. `"action": "REVERT"` clears the dates after a cancelled shipment. [Cancel / Update contracts for Order](/api-reference/endpoint/order/update-contract): `PUT /partner/api/v1/order` Send the whole order again with the same `orderId`, changed to how it stands now. The body has the same shape and required fields as step 4; it is not a partial update. | Change in your order | What to send | Result | |---|---|---| | Fewer units of a covered product | The line with the lower `quantity` | The difference is cancelled | | The plan is removed or refunded | The line with `quantity` set to `0`, or without `planDetails` | Every contract on that line is cancelled | | More units of a covered product | The line with the higher `quantity` | Contracts are created for the extra units | To cancel a whole order, do this for every plan line. Keep `productId` and `optionId` the same as in step 4, because a line's existing contracts are found by them. Cancelled contracts come back in `contractList` with `isCancelled: true` and cannot be reactivated. The customer receives a cancellation email. [Get Contracts for Order](/api-reference/endpoint/order/get-contracts): `GET /partner/api/v1/order` ```bash curl -G 'https://{HOST_NAME}/partner/api/v1/order' \ --data-urlencode 'storeId={storeId}' \ --data-urlencode 'partnerOrderId=ORDER-1001' \ -H 'X-SureBright-Access-Token: sb_live_YOUR_API_KEY' ``` `partnerOrderId` is the `orderId` you sent in step 4. `data.order` is the order as SureBright stored it and `data.contracts` lists its active contracts; cancelled contracts are left out. A `404` with `errorCode: ORDER_NOT_FOUND` means there is no order with that id on that store. The lookup is one order per call. To see all contracts for a period, use the export on [Sales](/merchant-portal/sales). ## Where claims are filed There is no claims step to build: the API has no claim endpoints. Customers file a claim in the customer portal or by email, as described in [Filing a claim](/claims/filing-a-claim). ## Related Keys, the header and testing. Rules shared by every Order endpoint. How your systems learn about contract and claim changes. The codes each endpoint family returns. --- # SureBright API overview Source: https://docs.surebright.com/api-reference/introduction > What the SureBright REST API does, the production host, which endpoints need an API key, an endpoint map and your first request in curl. The SureBright API lets a storefront, app or back office that is not on one of SureBright's platform integrations sell protection plans: look up a product's SureBright category, get plan quotes to show the shopper, and create, update and cancel the plan contracts when the order is paid or changes. It is a JSON REST API served from **`api.surebright.com`** in production. ## Hosts and authentication Production is **`https://api.surebright.com`**. The staging host is shared by your SureBright contact or in your Integration Kit, and staging uses its own keys. Only the **Order** endpoints under `/partner/api/v1/order` need credentials: a merchant API key, prefixed `sb_live_`, in the `X-SureBright-Access-Token` header. Quote and store category endpoints are public and take no key. There is no sandbox mode: mark orders you send while building with `"isTestOrder": true`. See [Authentication](/api-reference/authentication). ## Your first request List the SureBright categories your store's products map to. No key is needed. ```bash curl 'https://api.surebright.com/quote/api/storeCategory/listStoreCategories?storeId={storeId}' ``` Then run the [Quickstart](/api-reference/quickstart), four requests that end with a recorded test order, and follow [Integrate with the API](/api-reference/integration-tutorial), which walks one order from the first quote to a cancelled plan. ## Endpoint map | Method | Path | Purpose | Key | |---|---|---|---| | GET | [`/quote/api/storeCategory/listStoreCategories`](/api-reference/endpoint/store-category/list-category) | List your store's SureBright categories | No | | GET | [`/quote/api/quote/category/listQuotes`](/api-reference/endpoint/quote/list-warranty-quotes-by-category) | Quote plans from a category and a price | No | | GET | [`/quote/api/quote/listWarrantyQuotes`](/api-reference/endpoint/quote/list-warranty-quotes-by-product) | Quote plans for a platform product and variant | No | | GET | [`/quote/api/quote/listWarrantyQuotes`](/api-reference/endpoint/quote/list-warranty-quotes-by-url) with `productUrl` | Quote plans from a product page URL | No | | POST | [`/quote/api/whole-system/listQuotes`](/api-reference/endpoint/quote/list-warranty-quotes-for-whole-system) | Quote whole-system plans | No | | POST | [`/partner/api/v1/order`](/api-reference/endpoint/order/create-contract) | Create contracts when an order is paid | Yes | | PUT | [`/partner/api/v1/order`](/api-reference/endpoint/order/update-contract) | Update or cancel an order's contracts | Yes | | GET | [`/partner/api/v1/order`](/api-reference/endpoint/order/get-contracts) | Look up an order's contracts | Yes | | POST | [`/partner/api/v1/order/whole-system`](/api-reference/endpoint/order/create-contract-whole-system-warranty) | Create whole-system contracts | Yes | | POST | [`/partner/api/v1/order/whole-system/cancel`](/api-reference/endpoint/order/cancel-contract-whole-system-warranty) | Cancel a whole-system contract | Yes | Those are the operations in the machine-readable spec, [`/api-reference/openapi.json`](/api-reference/openapi.json). Other documented endpoints, each with its own page: [cart quotes](/api-reference/endpoint/quote/list-cart-quotes), [product quotes in bulk](/api-reference/endpoint/quote/list-product-quotes), [shipping protection quotes](/api-reference/endpoint/quote/shipping-quote), [categorize a product](/api-reference/endpoint/product-category/categorize), [fulfillment dates](/api-reference/endpoint/order/fulfillment) (its own server-to-server token), [POS sale ingest](/api-reference/endpoint/partner/transaction-ingest) (enabled per merchant) and [partner sign-in (OIDC)](/api-reference/endpoint/partner/sso). ## Show the offer without building UI Most stores do not call the Quote API from their own code: the SureBright storefront SDK shows the offer on product and cart pages and adds the plan to the cart. See [SDK installation](/frontend-widget-integration/frontend-widget-kit/sdk-installation) and [Headless and custom storefronts](/frontend-widget-integration/frontend-widget-kit/headless-and-custom-storefronts). ## Before you go live - [Authentication](/api-reference/authentication): keys, the header and testing - [HTTP status codes](/api-reference/http-status-codes) and the error bodies each endpoint returns - [Limits, idempotency and versioning](/api-reference/limits-and-versioning) - [Notifications and webhooks](/api-reference/notifications-and-webhooks) --- # Limits, idempotency and versioning Source: https://docs.surebright.com/api-reference/limits-and-versioning > What is and is not fixed about the SureBright API: request limits, what happens when you send the same order twice, pagination, path versions and where to download the OpenAPI document. This page collects the operational facts an integrator asks about before going live: how fast you may call, whether a retry can create duplicates, how results are paged and how the API is versioned. Where SureBright has not published a figure or a policy, the page says so instead of guessing. ## Rate limits | Endpoints | Limit | Over the limit | |---|---|---| | Category, quote and Order endpoints | No fixed public limit is published | Not applicable | | [Invoice upload and line-item update](/api-reference/endpoint/quote/invoice-upload) | 50 requests per minute, shared across all callers | `429` with a `Retry-After` header in seconds | "No published limit" is not an invitation to send traffic without bound. Keep to the rate your shoppers and orders naturally produce. Before a bulk load, such as a backfill of past orders or quoting a whole catalogue, tell your SureBright contact what you plan to send and when. ## Idempotency The Order endpoints do not take an idempotency key. An order is identified by its `storeId` and `orderId`, and that pair is what makes a repeat safe. | You send | What happens | |---|---| | The same `POST` or `PUT /partner/api/v1/order` body again | Each plan line is compared with the active contracts already on the order, matched by `productId` and `optionId`. Units that already have a contract get no second one. The existing `contractId` values come back in `contractList` | | The same order with a higher `quantity` on a plan line | Contracts are created for the extra units only | | The same order with a lower `quantity`, `quantity` `0`, or no `planDetails` on a line | The difference is cancelled. A cancelled contract cannot be reactivated | | The same [fulfilment dates](/api-reference/endpoint/order/fulfillment) request again | Contracts that are already dated are reported with `skipped: true` and left alone | Two things follow from this: - A retry is only harmless when the body is unchanged. Because a later request with fewer units cancels contracts, always send the order as it stands now, not an older copy. - Use one stable `orderId` per order and keep each line's `productId` and `optionId` the same on every call. Changing them makes SureBright treat the line as a different product. `POST` and `PUT` on `/partner/api/v1/order` are handled the same way: either creates the order when it is new and updates it when it exists. Customer emails are sent at most once per order or per plan, so a replayed order does not email the customer twice; see [Emails your customers receive](/customer-emails/overview). The field-level rules are on [Create Contracts for Order](/api-reference/endpoint/order/create-contract) and [Cancel / Update contracts for Order](/api-reference/endpoint/order/update-contract). For the rules on headers and methods shared by every Order endpoint, see [Request conventions](/api-reference/endpoint/order/request-conventions). ## Pagination and sizes No endpoint in the API reference takes `page`, `limit` or cursor parameters. | Endpoint | How results are bounded | |---|---| | [List Category](/api-reference/endpoint/store-category/list-category) | One array with every active category. Stores on the category tree get one level per call, or every priced leaf with `view=leaves` | | [Quotes by Category](/api-reference/endpoint/quote/list-warranty-quotes-by-category) | One quote per `storeCategoryList` entry you send | | [Get Contracts for Order](/api-reference/endpoint/order/get-contracts) | One order per call, with its active contracts. There is no endpoint that lists contracts across orders | The OpenAPI document gives `orderId` and `lineItemId` a maximum length of 48 characters. Stay within it. To read contracts for a whole period, use **Download** on [Sales](/merchant-portal/sales). ## Versioning Versions are part of the path, and not every family has one: | Path family | Version segment | |---|---| | Order: `/partner/api/v1/order`, `/partner/api/v1/order/whole-system` | `v1` | | Fulfilment dates: `/order/api/v1/contract/fulfillment` | `v1` | | Partner sign-in: `/site-platform/api/v1/sso` | `v1` | | Quotes and categories: `/quote/api/quote/...`, `/quote/api/storeCategory/...`, `/quote/api/whole-system/...` | None | That is a description of the paths in use today. SureBright has not published a compatibility or deprecation policy for the API, and there is no public changelog, so these docs make no promise about either. Write your client to ignore response fields it does not recognise, and ask your SureBright contact how changes that affect your integration will reach you. ## The OpenAPI document The machine-readable description of the API is served from this docs site at `/api-reference/openapi.json`, in OpenAPI 3.0 format. Download it and import it into Postman or a similar tool to get a ready-made collection. - It covers the ten operations whose reference pages are generated from it: categories, quotes by category, by product and by URL, the Order create, update and lookup calls, and the whole system warranty calls. - Pages written by hand, such as [Get a quote](/api-reference/endpoint/quote/get-quote) and [Set or revert fulfillment dates](/api-reference/endpoint/order/fulfillment), are not in it. - Its server is the placeholder `https://{HOST_NAME}`. Set the host after you import; see [Authentication](/api-reference/authentication#required-credentials). - Three operations carry their query string inside the path. Check those requests after importing, because some tools read the query string as part of the path. ## Timeouts and retries The points below are general client advice, not SureBright commitments. SureBright does not publish response-time figures. - Set an explicit timeout on every call so a slow response cannot hold a checkout page or a worker open. - A quote that fails or times out should hide the offer, not block the product page or the checkout. - Retry `429`, `502`, `503` and network errors with a growing delay between attempts, and honour `Retry-After` when it is present. Do not retry `400` or `401` unchanged; fix the request or the key first. - Send one request per order at a time. Wait for the response, or for your timeout, before you send that order again. - After a create that timed out, read the order back with [Get Contracts for Order](/api-reference/endpoint/order/get-contracts) or resend the same body; both are safe for the reasons under [Idempotency](#idempotency). ## Related - [Integrate with the API](/api-reference/integration-tutorial) - [Authentication](/api-reference/authentication) - [Request conventions](/api-reference/endpoint/order/request-conventions) - [HTTP status codes](/api-reference/http-status-codes) - [Notifications and webhooks](/api-reference/notifications-and-webhooks) --- # Notifications and webhooks Source: https://docs.surebright.com/api-reference/notifications-and-webhooks > What SureBright can tell your systems when something happens, the mechanism for each kind of event today, and what it does not push. This page answers one question: when something happens in your protection programme, how do your own systems find out? Some events are pushed to you, some you read from an API response, and some you have to poll for. SureBright does not send contract or claim events to a merchant endpoint today. If you need contract or claim changes pushed to your systems, ask your SureBright contact. ## Find the mechanism | You want to know when | Mechanism today | Push or pull | |---|---|---| | A contract was created for an order you sent by API | The response to [Create Contracts for Order](/api-reference/endpoint/order/create-contract) lists every `contractId` in `contractList` | Pull (same request) | | A contract on one of your orders was cancelled or changed | Poll [Get Contracts for Order](/api-reference/endpoint/order/get-contracts) for that order | Pull | | A contract is on hold or needs something from you | The merchant portal. See [Why a contract is on hold](/contracts/holds) and [Order Resolution](/merchant-portal/order-resolution), which is available on request | Pull (portal) | | Contracts were sold over a period | **Download** on [Sales](/merchant-portal/sales) gives a CSV for a date range | Pull (portal) | | A claim was filed, approved, declined or settled | No API and no webhook. The customer is emailed at each stage; see [Claim communications](/claims/communications). Where your team sees claims is covered in [Merchant adjudication](/claims/merchant-adjudication) | Pull (portal) | | A shopper selects or removes a plan on your storefront | `window.SureBright.onSelectionChange` and the `sb-widget-event` DOM events from the storefront SDK. See the [JavaScript API Reference](/frontend-widget-integration/frontend-widget-kit/javascript-injection) | Push (in the browser) | | A cart is abandoned, an offer is prepared or sent, or a cart is recovered | The abandoned-cart **Webhook** connected tool, or Klaviyo or Omnisend events. See [Channels and connected tools](/abandoned-cart-guide/channels) | Push | | An order is eligible for a post-purchase offer, or a plan was bought from one | Klaviyo events **SureBright: Eligible Order** and **SureBright: Policy Purchased**. See [Email integrations](/klaviyo-integration/integration-guide) | Push (into Klaviyo) | | The customer was emailed about their plan | Not pushed to you. The list of emails and when each is sent is on [Emails your customers receive](/customer-emails/overview) | None | ## Polling for contract changes [Get Contracts for Order](/api-reference/endpoint/order/get-contracts) takes one `storeId` and one `partnerOrderId` per call and returns the order with its active contracts. Cancelled contracts are left out, so a `contractId` you stored that no longer appears in `data.contracts` has been cancelled. There is no endpoint that lists every contract changed since a point in time. In practice: - Store the `contractId` values from the create response against your order lines. - Re-read an order when something happens to it on your side, for example a refund or an edit, rather than on a timer across all orders. - If you do run a periodic check, keep it to recent orders and a modest request rate. See [Limits, idempotency and versioning](/api-reference/limits-and-versioning). ## The abandoned-cart Webhook This is the one place where SureBright posts events to a web address you own. It is set up in the merchant portal under **Abandoned Cart**, then **Messages → Connected tools**, on stores where Abandoned Cart is switched on. It carries abandoned-cart events only, not contract or claim events. | Aspect | Behaviour | |---|---| | Endpoint | An `https` URL. Connecting sends a signed ping and needs a `2xx` answer. Redirects are not followed | | Request | One JSON `POST` per event with `id`, `event`, `event_name`, `occurred_at`, `shop` and `data` | | Headers | `X-SureBright-Signature`, `X-SureBright-Event`, `X-SureBright-Delivery`, `X-SureBright-Timestamp` | | Signature | `sha256=` followed by the hex HMAC-SHA256 of the raw request body, keyed with the signing secret shown once when you connect | | Success | Any `2xx` answer within 10 seconds | | Retries | A failed delivery is tried up to 3 times in all, at least 10 minutes apart, within 24 hours. After that the event is not sent again | Compute the HMAC over the body exactly as received, before any JSON parsing, and compare it with the header. Use the `X-SureBright-Delivery` value to ignore a delivery you have already processed. The event names and what each one carries are listed on [Channels and connected tools](/abandoned-cart-guide/channels#events-your-tool-receives); the full field list is in the **Event catalog** on the Connected tools screen. ## Webhooks SureBright receives When your store runs on a supported platform, SureBright subscribes to that platform's order, refund, fulfilment and product events so that contracts follow your orders. Those are inbound to SureBright and you never call them. They are listed on [Platform webhooks SureBright receives](/api-reference/endpoint/webhooks/platform-receivers), which is useful when you audit the webhooks on your store. A custom integration has no such subscription. You tell SureBright about a new, changed or cancelled order yourself, with the calls in [Integrate with the API](/api-reference/integration-tutorial). ## Related The calls that create, update and look up contracts. The Webhook, Klaviyo and Omnisend for abandoned-cart events. Storefront callbacks and DOM events. What SureBright sends to customers and when. --- # API quickstart Source: https://docs.surebright.com/api-reference/quickstart > Four copy-paste curl requests: list your store's categories, quote plans for a product, record a test order with a plan, and look its contracts up. This page gets you from nothing to a recorded test order with a protection plan in four requests. Run them in a terminal in order: each one uses a value from the one before. For what each field means and the update and cancel calls, follow [Integrate with the API](/api-reference/integration-tutorial) afterwards. ## Before you start | You need | Where to get it | |---|---| | Your `storeId` and `storeParentId` | Your SureBright Integration Kit, or ask your SureBright contact | | An API key, prefixed `sb_live_` | Merchant Portal **Developers** page. Only steps 3 and 4 need it. See [Authentication](/api-reference/authentication) | | `curl` and `base64` | Any macOS or Linux terminal | Set them once: ```bash export SB_HOST='https://api.surebright.com' export SB_STORE_ID='{storeId}' export SB_STORE_PARENT_ID='{storeParentId}' export SB_API_KEY='sb_live_YOUR_API_KEY' ``` There is no sandbox. The order in step 3 is real, so keep `"isTestOrder": true` in it: SureBright records it as a test order with a **Test** badge on **Sales**. Make Order calls from your server in production, never from the browser. ## 1. List your store's categories No key needed. ```bash curl "$SB_HOST/quote/api/storeCategory/listStoreCategories?storeId=$SB_STORE_ID" ``` A successful response looks like this (example values from the [OpenAPI spec](/api-reference/openapi.json)): ```json [ { "storeCategoryId": "07b1dcb3-fbe5-46c6-b42f-66d82e89f2a7", "storeParentId": "13612f29-8ec5-49ad-bab1-5ab09b51367e", "sbCategoryId": "4c3103e4-38dc-4171-96e5-b4b77ab0e96f", "sbCategoryName": "Small Home Appliance", "labelList": [ "Ovens", "Microwaves", "Refrigerators" ] } ] ``` Pick an entry from the array and copy its `sbCategoryId`: ```bash export SB_CATEGORY_ID='{sbCategoryId}' ``` ## 2. Quote plans for a product No key needed. The inputs go in one JSON object, Base64-encoded as the `payload` parameter. `quoteSyncMode=SYNC` saves the quote before the response returns, so you can use it in step 3 straight away. ```bash PAYLOAD=$(printf '{"storeParentId":"%s","country":"US","visitId":"quickstart-1","platform":"OFFLINE_PORTAL","storeCategoryList":[{"sbCategoryId":"%s","productPrice":199.99}]}' \ "$SB_STORE_PARENT_ID" "$SB_CATEGORY_ID" | base64 | tr -d '\n') curl -G "$SB_HOST/quote/api/quote/category/listQuotes" \ --data-urlencode 'quoteSyncMode=SYNC' \ --data-urlencode "payload=$PAYLOAD" ``` A successful response looks like this (example values from the [OpenAPI spec](/api-reference/openapi.json)): ```json { "quoteList": [ { "storeCategoryId": "ecca4210-09a4-446c-ad87-5e65bd50df12", "sbCategoryId": "4c3103e4-38dc-4171-96e5-b4b77ab0e96f", "country": "US", "platform": "SHOPIFY", "sbProductId": "643bc477-0eec-4da1-946a-38ff7d1292c9", "storeParentId": "ecca4210-09a4-446c-ad87-5e65bd50df12", "allowDynamicPolicyPricing": true, "quoteId": "33f21a29-95ca-4150-b5df-afe36f5ef537", "quoteItemList": [ { "quoteId": "33f21a29-95ca-4150-b5df-afe36f5ef537", "quoteItemId": "33f21a29-95ca-4150-b5df-afe36f5ef537", "lowerPrice": 749.99, "upperPrice": 999.99, "coverageYears": "1", "policyPrice": "79", "storeProductVariantPrice": "899.99", "country": "US", "isActive": true } ], "coverageType": "AD", "coverageList": [ { "coverageItemType": "COVERAGE_OPTION", "coverageItemTitle": "Your warranty plan provides", "coverageItemList": [ "Protection against everyday spills (food, beverages, human or pet biological stains, cosmetics, etc)." ] } ], "policyId": "1234567890", "createdAt": "2021-01-01T00:00:00Z", "updatedAt": "2021-01-01T00:00:00Z" } ] } ``` From the first entry of `quoteList`, copy `quoteId`, and from its `quoteItemList` copy one `quoteItemId`. Each `quoteItemList` entry is one plan with its `coverageYears` and `policyPrice`. An empty `quoteList` means no plan matches that category and price: try another category or price. ```bash export SB_QUOTE_ID='{quoteId}' export SB_QUOTE_ITEM_ID='{quoteItemId}' ``` ## 3. Record a test order with the plan Needs your API key. ```bash NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ) curl -X POST "$SB_HOST/partner/api/v1/order" \ -H "X-SureBright-Access-Token: $SB_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "storeId": "'"$SB_STORE_ID"'", "orderId": "QUICKSTART-1", "orderPurchaseDate": "'"$NOW"'", "orderLineItemList": [{ "lineItemId": "LINE-1", "productId": "PROD-1", "productSKU": "SKU-1", "productTitle": "Quickstart test product", "quantity": 1, "salePrice": 199.99, "totalPrice": 199.99, "planDetails": { "policyPurchaseDate": "'"$NOW"'", "quoteId": "'"$SB_QUOTE_ID"'", "quoteItemId": "'"$SB_QUOTE_ITEM_ID"'" } }], "customerDetails": { "firstName": "Test", "lastName": "Customer", "customerEmail": "test.customer@example.com", "addressLine1": "123 Main St", "city": "Austin", "state": "TX", "country": "US", "zipCode": "78701" }, "isTestOrder": true }' ``` A successful response looks like this (example values from the [OpenAPI spec](/api-reference/openapi.json)): ```json { "storeId": "f4c059b2-5b74-4e4c-a3c5-85bc80cf8a09", "orderId": "83737121380", "contractList": [ { "lineItemId": "374dc3c3-94a3-4b85-a876-8651e461446d", "contractId": "abc12345-6789-4abc-bcde-ef1234567890", "isCancelled": false } ] } ``` A `200` with one entry in `contractList` means the contract was created. A `400` or an `errorList` in the response says which field to fix; see [HTTP status codes](/api-reference/http-status-codes). If the request timed out, send it again with the same `orderId`: SureBright does not create the contract twice. ## 4. Look the contracts up Needs your API key. ```bash curl -G "$SB_HOST/partner/api/v1/order" \ --data-urlencode "storeId=$SB_STORE_ID" \ --data-urlencode 'partnerOrderId=QUICKSTART-1' \ -H "X-SureBright-Access-Token: $SB_API_KEY" ``` A successful response looks like this. The spec describes `data.order` and each contract in `data.contracts` without listing their fields, so they are shown abridged here: ```text { "isError": false, "storeId": "f4c059b2-5b74-4e4c-a3c5-85bc80cf8a09", "partnerOrderId": "QUICKSTART-1", "data": { "order": { ...the order as SureBright stored it... }, "contracts": [ { ...one active contract... } ], "processedAt": "2026-11-05T10:15:30.000Z" } } ``` `data.contracts` lists the contract from step 3. The order also appears on **Sales** in the Merchant Portal with a **Test** badge. ## Next steps - [Integrate with the API](/api-reference/integration-tutorial): every step in detail, including fulfilment, updates and cancellations. - [Endpoint map](/api-reference/introduction#endpoint-map): every endpoint and whether it needs a key. - [Use these docs with AI assistants](/api-reference/ai-assistants): point a coding agent at `llms.txt` and the OpenAPI spec to write this integration for you. --- # Whole System Warranty API Source: https://docs.surebright.com/api-reference/whole-system-warranty > How a proposal platform or an installer's own system quotes, creates, changes and cancels a Whole System Warranty plan through the SureBright API. This guide shows how to add the Whole System Warranty to a proposal through the API: quote the plan from the proposal's line items, create it when the customer has bought, change it afterwards and cancel it. Each step names the endpoint and shows a minimal request. The linked reference pages carry the full field lists. ## Which reader you are | | You run a proposal or quoting platform used by many installers | You are an installer connecting your own system | |---|---|---| | Whose plans you create | Each installer's, with that installer's approval | Your own | | API key you send | Your platform's own key | Your own key | | `storeId` you send | Your platform's SureBright store id | Your own SureBright store id | | How SureBright knows the installer | `sbAccountId` and `sbStoreId`, which you receive when the installer connects | Not needed. Leave both out | | Extra work | Build the Connect to SureBright sign-in once, then connect each installer | None | | Where the plan is recorded | In the installer's account. They see it in the installer portal under **Sold plans** | In your own account | | Cancelling by API | While the plan is active, subject to the checks in step 5 | Within 30 days of creating the plan | | What to read | Every section | Skip [Acting for an installer](#acting-for-an-installer-connect-to-surebright) | If your platform creates a plan without `sbAccountId` and `sbStoreId`, the plan is recorded under your platform's own account, not the installer's. To record each sale under the installer who made it, connect the installer first. ## Before you start | You need | Where it comes from | |---|---| | The API host (`HOST_NAME`), your `storeId` and an API key | [Authentication](/api-reference/authentication). If you do not have them, ask your SureBright contact | | Whole System Warranty set up on your account | SureBright does this. Until it is done the quote call returns `512` or `514` | | For platforms: a `client_id` for Connect to SureBright | SureBright registers your application. See [Partner sign-in (OIDC)](/api-reference/endpoint/partner/sso) | The quote call takes no key. The create and cancel calls take your key in the `X-SureBright-Access-Token` header. Make every call from your server, never from the browser. The quote endpoint prices plans for the United States only. If you sell in Canada, ask your SureBright contact before you build. ## The model: one proposal, one plan A proposal is one installation job. SureBright keeps one proposal record for it and creates at most one plan from it. The plan covers every eligible line on the proposal as a whole. There are no per-product plans to track. | Identifier | Who issues it | What it is for | |---|---|---| | `sbProposalId` | SureBright, in the first quote response | Ties the job together. Send it on every re-quote and on every create or update | | `partnerProposalId` | You, on the quote request | Your own proposal reference. Optional. It must be unique to one proposal on your `storeId`, because a quote that reuses it updates that proposal instead of starting a new one | | `warrantyQuoteId` | SureBright, in each quote response | The quote you are buying from. Sent on create | | `warrantyQuoteItemId` | SureBright, one per plan term | The term the customer chose. Sent on create | | `contractId` | SureBright, in the create response | The plan. Send it to cancel, and quote it to SureBright support | Store `sbProposalId` and `contractId` against your own proposal. `sbSalesLeadId` in responses is an older name for `sbProposalId` and carries the same value. ## The flow, step by step [For Whole System Warranty](/api-reference/endpoint/quote/list-warranty-quotes-for-whole-system): `POST /quote/api/whole-system/listQuotes` Send every line on the proposal and the length of the installation warranty the installer gives, in months. Leave `sbProposalId` out of the first request. ```bash curl -X POST 'https://{HOST_NAME}/quote/api/whole-system/listQuotes' \ -H 'Content-Type: application/json' \ -d '{ "storeId": "{storeId}", "partnerProposalId": "{yourProposalReference}", "installerWarrantyDuration": 12, "lineItemList": [ { "title": "{productName}", "description": "{productDescription}", "unitPrice": 2400, "quantity": 2 }, { "title": "{productName}", "unitPrice": 180, "quantity": 6 } ] }' ``` `storeId`, `lineItemList` and `installerWarrantyDuration` are required. Each line needs `title`, `unitPrice` and `quantity`. `description` and `categoryTag` are optional and help SureBright recognise the product. From the response keep: | Field | Use | |---|---| | `sbProposalId` | The proposal. Store it. Sent in steps 2, 3 and 4 | | `warrantyQuoteId` | The quote. Sent in step 3 | | `warrantyQuoteItemList[]` | One entry per plan term. `warrantyQuoteItemId` and `coverageYears` are sent in step 3. `quotePrice` is the suggested customer price. `planCost`, when present, is what SureBright charges you for that plan | | `lineItemList[]` | Your lines back, each with `isCovered` and `sbCategoryName` | | `totalCoveredAmount` | The total of the covered lines. The plan is priced on this figure | | `coverageList`, `tncLink` | Coverage wording and a link to the plan's documents, to show the customer | Same endpoint. Send the proposal's current lines and installation warranty length again, this time with `sbProposalId`. ```bash curl -X POST 'https://{HOST_NAME}/quote/api/whole-system/listQuotes' \ -H 'Content-Type: application/json' \ -d '{ "storeId": "{storeId}", "sbProposalId": "{sbProposalId}", "installerWarrantyDuration": 12, "lineItemList": [ { "title": "{productName}", "description": "{productDescription}", "unitPrice": 2400, "quantity": 3 } ] }' ``` | What you sent | What comes back | |---|---| | The same lines and the same installation warranty length, and SureBright's pricing and coverage have not changed | The same `warrantyQuoteId` and `warrantyQuoteItemId` values as before | | Anything priced has changed: a line, a price, a quantity or the way a line is classified | New `warrantyQuoteId` and `warrantyQuoteItemId` values. Use these from now on. The earlier ids for that installation warranty length stop working | | A different installation warranty length | A new quote for that length. The proposal keeps one quote per length, and the `warrantyQuoteId` you send in step 3 decides which one applies | The response always carries the same `sbProposalId`. A re-quote changes the proposal only. A plan that already exists stays as it is until you send step 4. [Create / Update Contracts for Whole System Warranty](/api-reference/endpoint/order/create-contract-whole-system-warranty): `POST /partner/api/v1/order/whole-system` Call this once the customer has bought the plan and the installation is complete. The plan is dated from the day you create it, so do not create it for a proposal that is still open. ```bash curl -X POST 'https://{HOST_NAME}/partner/api/v1/order/whole-system' \ -H 'X-SureBright-Access-Token: sb_live_YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "storeId": "{storeId}", "sbProposalId": "{sbProposalId}", "warrantyQuoteId": "{warrantyQuoteId}", "warrantyQuoteItemId": "{warrantyQuoteItemId}", "warrantyCoverageYears": 3, "warrantyPrice": {priceChargedToTheCustomer}, "customerDetails": { "customerFirstName": "{firstName}", "customerLastName": "{lastName}", "customerEmail": "{email}", "customerAddress1": "{streetAddress}", "customerCity": "{city}", "customerState": "{state}", "customerZipCode": "{zipCode}", "customerCountry": "US" } }' ``` | Field | Required | Notes | |---|---|---| | `storeId` | Yes | The same `storeId` you quoted with | | `sbProposalId` | Yes | From step 1 | | `warrantyQuoteId` | Yes | From the latest quote for the installation warranty length the installer is giving | | `warrantyQuoteItemId` | Yes | The term the customer chose | | `warrantyCoverageYears` | Yes | Must equal that term's `coverageYears` | | `warrantyPrice` | Yes | What the customer was charged for the plan. A number, zero or more | | `customerDetails` | Yes | `customerFirstName`, `customerLastName` and `customerEmail` are required. Send the address fields too: without `customerAddress1` the plan waits for the customer's address | | `isTestOrder` | No | `true` while you test. See [Testing](#testing) | | `sbAccountId`, `sbStoreId` | Platforms only | Both are required when you create for a connected installer | You do not send line items. The covered lines, the covered total and the installation warranty length come from the proposal as it was last quoted. A `200` response carries `isError: false` and the plan's `contractId`. Store it. Cover begins on the day you create the plan and runs to the end of the term. For a breakdown, the manufacturer warranty and the installer's installation warranty apply first. See [When coverage starts](/contracts/effective-dates). This takes two calls. First re-quote as in step 2, with the same `sbProposalId` and the lines as they stand now. Then send step 3 again with the same `sbProposalId` and the new `warrantyQuoteId` and `warrantyQuoteItemId`. Because the proposal already has a plan, the call updates that plan and returns the same `contractId`. | Change | Allowed | |---|---| | The covered items | For 90 days from the day the plan was created. Updating the plan does not restart the 90 days | | The customer's details only | At any time | After the 90 days, a call that would change the covered items returns HTTP `400` with `errorType: 517` and the message `Line items cannot be updated after 90 days of purchase date`. Nothing on the plan changes. [Cancel Contracts for Whole System Warranty](/api-reference/endpoint/order/cancel-contract-whole-system-warranty): `POST /partner/api/v1/order/whole-system/cancel` ```bash curl -X POST 'https://{HOST_NAME}/partner/api/v1/order/whole-system/cancel?contractId={contractId}' \ -H 'X-SureBright-Access-Token: sb_live_YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "cancellationReason": "{reason}" }' ``` The request is the same for both readers. The rule that applies depends on how the plan was created: | The plan was created | You can cancel | A refused cancellation looks like | |---|---|---| | With your own key, under your own account | Within 30 days of the plan's order being created. The plan must belong to the account that owns the key | `505` with `errorCode: CANCELLATION_WINDOW_EXPIRED` after 30 days. `503` with `CONTRACT_ACCESS_DENIED` for another account's plan | | For a connected installer, with `sbAccountId` | While the plan is active and the installer's connection is active. There is no 30-day limit. The call is refused while the plan has an active claim, or when no refund is due on it | `400` with `isError: true` and a `message`. `403` with `Store integration is inactive` when the installer has disconnected | A successful response is `200` with `isError: false` and `cancelledContractId`. Check `isError` on every `200`, because a plan that was already cancelled is also answered with `200`. Cancelling ends cover for every line on the plan. You cannot cancel one product; change the covered items with step 4 instead. `cancellationReason` is optional and is recorded for plans created for a connected installer. After a cancellation, do not call create again for that proposal. If the customer buys again, quote the job as a new proposal. There is no call in this step. | Who | What they see | |---|---| | The customer | SureBright emails the customer at `customerEmail` to confirm the plan, and normally again if it is cancelled. Claims are filed by the customer with SureBright, or by the installer for them. See [What your customer gets](/installers/your-customer) | | A connected installer | The plan appears in their installer portal under **Sold plans**, like a sale they recorded themselves. From there they can open it and file a claim for the customer | | You, with your own key | The plan is recorded under the account that owns the key. Keep the `contractId`: there is no call that reads a plan back | ## How line items are judged SureBright assesses every line you send for eligibility. Only eligible lines are priced. | What happens | In the response | |---|---| | A line is recognised as an eligible product | `isCovered: true` and its `sbCategoryName` | | A line is not recognised, or is not eligible | `isCovered: false` and an empty `sbCategoryName` | | The covered lines are added up | `totalCoveredAmount`: `unitPrice` times `quantity` across the covered lines only | | No line is covered | No quote. Status `516` with `Category Not Found` | | The covered lines add up to zero | No quote. Status `515` with `Not Eligible` | Show the customer which lines are covered. A line that comes back with `isCovered: false` is not part of the plan and does not count towards its price. If a line you expected to be covered is not, check its `title` and `description`, add a `categoryTag`, and ask your SureBright contact if it still is not covered. **Labour lines.** This endpoint has no separate line type for installation labour. A labour line is assessed like any other line, from its `title`, `description` and `categoryTag`. Check its `isCovered` value to see whether it counted towards `totalCoveredAmount`. **Installation warranty length.** `installerWarrantyDuration` is a number of months. | You send | Result | |---|---| | `3`, `6` or `12` | Priced on that length | | Any other value above `3` | Priced on the nearest length below it. `9` is priced as `6`, and `24` as `12` | | Less than `3` | No quote. Status `513` with `No Quote Found` | | Nothing | Status `511` with `installerWarrantyDuration is required` | **Plan terms.** Plans are quoted for 2, 3 and 5 years. Each `warrantyQuoteItemList` entry is one term. **Country.** The endpoint prices for the United States only. An account with no United States Whole System Warranty set up gets status `512`. What makes a product eligible is described for installers on [What a plan can cover](/installers/eligibility). ## Acting for an installer: Connect to SureBright A platform never holds an installer's API key. Each installer connects their SureBright account to your platform once, and you then create plans for them with your own key. The reference pages call this SureBright Connect. Send the installer to SureBright with the flow on [Partner sign-in (OIDC)](/api-reference/endpoint/partner/sso). They sign in to SureBright and see a screen headed **Connect to** followed by your platform's name. Under **Select locations** they tick the locations you may act for. Under **Permissions** they see what you asked for. They finish with **Allow and continue**, or **Cancel** to decline. The person who approves must be an owner or administrator of the installer's SureBright account. To create and cancel plans you need the `sales.write` scope. The installer sees it as "Record warranty sales for the authorized locations". Without it every create and cancel for that installer is refused. | You receive | Format | Send it as | |---|---|---| | `sbAccountId` | `sb_int_` followed by a UUID, for example `sb_int_3f9d2c7b-1a4e-4b6d-9c0f-5e8a7d6b2c10` | `sbAccountId` | | `locations[]`, one entry per approved location, each with a `locationId`, `name` and `address` | `locationId` is an opaque string | The `locationId` of the location that made the sale, as `sbStoreId` | `sbAccountId` identifies the connection between that installer and your platform. It is not a credential and it does not expire with the tokens. Quote with your own `storeId` as in step 1 of the flow. On create, add the two ids: ```bash curl -X POST 'https://{HOST_NAME}/partner/api/v1/order/whole-system' \ -H 'X-SureBright-Access-Token: sb_live_YOUR_PLATFORM_KEY' \ -H 'Content-Type: application/json' \ -d '{ "storeId": "{yourPlatformStoreId}", "sbAccountId": "sb_int_{uuid}", "sbStoreId": "{locationId}", "sbProposalId": "{sbProposalId}", "warrantyQuoteId": "{warrantyQuoteId}", "warrantyQuoteItemId": "{warrantyQuoteItemId}", "warrantyCoverageYears": 3, "warrantyPrice": {priceChargedToTheCustomer}, "customerDetails": { "customerFirstName": "{firstName}", "customerLastName": "{lastName}", "customerEmail": "{email}" } }' ``` `sbStoreId` is always required on a connected create, including when the installer approved a single location. `storeId` stays your own store id. On a successful create, the proposal and its plan move into the installer's account, under the location you named. The plan appears in the installer's portal under **Sold plans**. After that: - Re-quote that proposal with `sbProposalId`. A re-quote that carries only `partnerProposalId` does not find it and starts a new proposal. - Keep sending the same `sbAccountId` and `sbStoreId` when you update the plan. A proposal stays with the connection and location it was first created under. - A proposal that already has a plan under your own account cannot be moved to an installer afterwards. Decide before the first create. ### What makes a connected create fail | Cause | Status and body | What to do | |---|---|---| | `sbStoreId` is missing | `400`, `sbStoreId is required` | Send the `locationId` of the location that made the sale | | The connection is not active, or it was not made with your application | `401`, `code: invalid_api_key`, `Partner authentication failed` | Ask the installer to connect again | | The installer did not grant `sales.write` | `403`, `code: insufficient_scope`, `The sales.write scope is required` | Request `sales.write` and ask the installer to approve again | | `sbStoreId` is not a location the installer approved | `403`, `code: access_denied`, `The selected location is not authorized` | Use a `locationId` from the `locations` you received, or ask the installer to approve the location | | The location has since been closed or deactivated | `403`, `code: access_denied`, `The selected location is not active` | Ask the installer which location to use | | The person who approved is no longer an active owner or administrator of the installer's account | `403`, `code: access_denied`, `The merchant authorization is no longer active` | Ask a current owner or administrator to connect again | | `storeId` is not your own store id | `403`, `code: access_denied`, `The supplied storeId does not belong to the authenticated partner` | Send your platform's `storeId` | | The proposal was not quoted with your `storeId` | `403`, `Proposal does not belong to the authenticated partner account` | Quote with your own `storeId` first | | The proposal already belongs to another connection or location | `403`, `Proposal is not available to this connection` | Send the `sbAccountId` and `sbStoreId` it was first created with | The full list is on the [create reference page](/api-reference/endpoint/order/create-contract-whole-system-warranty). ## Idempotency and duplicates **A repeat create is safe.** The create call takes no idempotency key. The proposal is what makes a repeat safe: if the proposal already has a plan, a second create with the same `sbProposalId` updates that plan with what you sent and returns the same `contractId`. It does not create a second plan. If a create times out, send it again unchanged. Send creates for one proposal one at a time, and wait for the response before you retry. **Keep `partnerProposalId` unique.** A quote that reuses a `partnerProposalId` on the same `storeId` re-quotes the existing proposal. Reusing one reference for two different jobs overwrites the first job's quote. If you send both `sbProposalId` and `partnerProposalId` they must point at the same proposal, or the quote returns `409` with `PROPOSAL_ID_MISMATCH`. SureBright does not match a plan you create through the API against a sale the installer records by hand. If the installer records a job in the installer portal and your platform also sends it, two plans are created for the same job and both are billed. Agree with each installer which route records the sale, and use only that route for a given job. See [Choose how you sell](/installers/ways-to-sell). ## Testing There is no separate test key. See [Live keys and testing](/api-reference/authentication#live-keys-and-testing). | You want to | What to do | |---|---| | Check your line items and see real prices without creating anything | Call the quote endpoint. It creates a proposal, not a plan | | Try create without recording a real sale | Send `"isTestOrder": true` in the create body | `isTestOrder` must be a boolean. Any other type is rejected with `400` and `isTestOrder must be a boolean`. A plan created with `isTestOrder: true` is flagged as a test plan and its charge is waived. The customer email can still be sent, so put an address you control in `customerEmail`. Send the same `isTestOrder` value each time you call create for that proposal. For a connected installer, the plan keeps the value from its first create. ## Errors These endpoints use their own codes. Read the body as well as the status: on create, most failures are HTTP `400` with the code in `errorType`. | Call | Status | Code in the body | Meaning | What to do | |---|---|---|---|---| | Quote | `511` | | `storeId`, `lineItemList` or `installerWarrantyDuration` is missing | Send all three | | Quote | `512` | | The account is not set up for Whole System Warranty in the United States | Ask your SureBright contact | | Quote | `513` | | No quote: `installerWarrantyDuration` is below `3`, a line has no `title`, or no plan matched | Check the installation warranty length and the lines | | Quote | `514` | | `storeId` is not known | Check the `storeId` | | Quote | `515`, `516` | | No covered line, or the covered lines total zero | See [How line items are judged](#how-line-items-are-judged) | | Quote | `404` | `SB_PROPOSAL_NOT_FOUND` | `sbProposalId` is not known | Quote without it to start a new proposal | | Quote | `409` | `PROPOSAL_ID_MISMATCH` | `sbProposalId` and `partnerProposalId` point at different proposals | Send the pair that belongs together | | Quote | `409` | `PARTNER_PROPOSAL_RESERVED` | A plan is being created from this proposal right now | Retry once the create has finished | | Quote | `403` | `PARTNER_PROPOSAL_ACCESS_DENIED` | The proposal has moved to a connected installer, and the `storeId` you sent is not the one it was created with | Quote with the `storeId` you created the plan with | | Quote | `502` | `QUOTE_PERSISTENCE_FAILED` | The quote could not be saved | Quote again before you create | | Create | `400` | `errorType: 512` | A required field is missing or malformed. `errors` lists each one | Fix the fields listed | | Create | `400` | `errorType: 515` | The proposal was not found on that `storeId` | Check `sbProposalId` and `storeId`. For a connected installer's proposal, send `sbAccountId` and `sbStoreId` | | Create | `400` | `errorType: 518`, `519`, `520` | The quote, the term or `warrantyCoverageYears` does not match the proposal's latest quote | Re-quote and send the ids from that response | | Create | `400` | `errorType: 517` | The covered items cannot change after 90 days | Nothing changed. Ask your SureBright contact | | Create | `401`, `403` | `invalid_api_key`, `insufficient_scope`, `access_denied` | A connected create was not authorised | See [What makes a connected create fail](#what-makes-a-connected-create-fail) | | Create | `409` | | `Proposal changed. Reload the quote before submitting.` or `Contract creation is still in progress` | Re-quote, or wait, then retry | | Cancel | `505` | `CANCELLATION_WINDOW_EXPIRED` | More than 30 days since the plan's order was created | Ask your SureBright contact | | Cancel | `503`, `504` | `CONTRACT_ACCESS_DENIED`, `CONTRACT_NOT_FOUND` | The plan is not yours, or the `contractId` is not known | Check the `contractId` and the key | | Cancel | `403` | | `Store integration is inactive`: the installer has disconnected | Ask the installer to connect again, or to cancel in their portal | | Cancel | `400` | | A connected plan could not be cancelled: an active claim, no refund due, or already cancelled. `message` says which | Read `message` | | Any | `401` | | `X-SureBright-Access-Token header is required`, or the key was not accepted | See [Authentication](/api-reference/authentication) | | Any | `500`, `502`, `503` | | SureBright could not complete the request | Retry. A repeated create is safe | On these endpoints `503`, `504` and `505` on cancel and `511` to `516` on quote are application codes, not gateway errors. Each reference page lists every code with its exact message. ## What the API does not do today | Not available | What to do instead | |---|---| | Filing or reading a claim | The API has no claim endpoints. The customer files with SureBright, or the installer files for them from the plan in the installer portal. See [Claims on a system you installed](/installers/claims) | | Push notifications | SureBright does not send plan or claim events to your systems. See [Notifications and webhooks](/api-reference/notifications-and-webhooks) | | Reading a plan back, or listing plans | There is no lookup call for whole-system plans. Store the `contractId` from the create response. A connected installer sees their plans under **Sold plans** | | Cancelling part of a plan | Cancel ends the whole plan. Change the covered items with step 4 | ## Related Every request and response field of the quote call. Fields and errors for create and update. The two cancellation rules and every error. The Connect to SureBright sign-in and consent flow. Keys, the header and testing. How installers sell the plan, with and without the API. --- # BigCommerce Source: https://docs.surebright.com/bigcommerce/overview > Connect your BigCommerce store with the SureBright app, see what shoppers get on your storefront, check that it works, and know what happens to plans when an order changes or you uninstall. SureBright for BigCommerce is a single-click app. Install it and your store is connected: offers appear on your storefront, and the plans shoppers buy become contracts with no further setup. This page follows the order you will work in: connect, see what appears on your storefront, check it works, manage orders and refunds, and uninstall. ## What you get on BigCommerce - Protection offers on product pages, on the cart page and in quick view on category pages. - A shipping protection checkbox in the cart, when shipping protection is enabled for your store. - A contract for every plan a shopper buys, kept in step when you cancel or refund the order. - Sign-in to the [merchant portal](/merchant-portal/overview) by opening the app from your BigCommerce control panel. - Your products and categories copied to SureBright and kept current as you add or change them. ## What you need to do | When | What you do | |---|---| | Once | Install the app and approve the access it asks for. | | Once | Go through the onboarding journey in the merchant portal and review any product that needs a category. | | Always | Leave the two SureBright scripts and the SureBright products in your catalogue as they are. | | If you want | Switch shipping protection off for individual products. | ## Connect your store Install **SureBright** from your BigCommerce control panel and approve the access it asks for. SureBright creates your SureBright store from your BigCommerce store details (domain, country and admin email). SureBright adds two scripts to your storefront, copies your catalogue (products and categories) and gives your store a default widget configuration. You do nothing in this step. When setup finishes you are signed in to the [merchant portal](/merchant-portal/overview) as the store owner. The first visit opens the onboarding journey. Opening the app from the BigCommerce control panel later signs you in again. Offers appear once SureBright has reviewed the store and your products carry a category. Check [Products](/merchant-portal/products) for anything marked as needing a category. Your **Email** and **Phone** in portal [Settings](/merchant-portal/settings#update-your-contact-details) are read-only on BigCommerce stores and come from BigCommerce. ## What shoppers see on your storefront You do not place anything by hand. Once the app is installed, shoppers see: | Where | What the shopper sees | |---|---| | Product pages | The protection offer with the available plan terms, a **Protect My Purchase** button in the detail popup, and a link to the plan's terms. When the shopper changes the product option, the offer updates for the selected variant. | | Cart page | An **Add Warranty** button next to each cart item that qualifies, plus the shipping protection checkbox when shipping protection is enabled for your store. | | Quick view on category pages | The product offer for the product they opened. | When a shopper changes the quantity of a covered product or removes it, the matching plan line is adjusted or removed, so the cart never carries a plan without its product. ## Scripts and products to leave in place The app adds two entries under **Storefront > Script Manager**. Both load in the page head on every storefront page, are marked **Essential** for consent purposes, and are not shown in checkout. | Script | What it is for | |---|---| | **SureBright SDK configuration** | Tells SureBright which store and country the page belongs to. | | **SureBright SDK** | Shows the offers on your storefront. | Do not delete or edit these scripts. Offers stop appearing if either one is missing. If one goes missing, ask your SureBright contact to recreate it. The app also adds digital products to your catalogue, because a plan is sold as a product: - Plans are named `Product Warranty Powered by SureBright - `, with one variant per price band and term and a **Quote Details** modifier. - Shipping protection is a digital product named **Shipping Protection Powered by SureBright**. Leave these products as they are, including their names. Offers and contracts depend on them. ## Check that it works Open **Storefront > Script Manager** and confirm **SureBright SDK configuration** and **SureBright SDK** are both listed. Once SureBright has reviewed your store, pick a product that carries a category on [Products](/merchant-portal/products). You should see the protection offer. Change the product option and check that the offer updates. Add the product to the cart. You should see the **Add Warranty** button next to it. Place an order that includes a plan, then look under **Recent Sales** on the [Sales](/merchant-portal/sales) page. A contract can appear a short while after the order. [Test your setup](/platforms/test-your-setup) describes the full test, from the offer to the cancellation. ## Choose which products get shipping protection On stores that sell shipping protection, the cart checkbox offers shipping protection for the cart's eligible products. You decide which products count on the merchant portal's [Products](/merchant-portal/products#choose-which-products-count-towards-shipping-protection) page: - The **Shipping protection** column is **On** by default for eligible products. - Set it to **Off** for any product you want to leave out. - Products whose category is not a shipping category show **Not eligible**. A change applies the next time a shopper's cart is priced. ## What happens when an order changes You manage orders in BigCommerce as usual. SureBright follows what you do there: | When this happens in BigCommerce | What happens to the plan | |---|---| | A shopper places an order with a plan | A contract is created for each plan unit, for the product it covers. | | You cancel the order, or remove a plan line from it | The contracts for those plans are cancelled. | | You refund plan units | The contracts for the refunded units are cancelled. | | You ship the order | On stores where coverage starts at fulfilment, coverage is dated from the shipment. Shipping protection contracts are created for the shipment. | | You add or change a product or category | SureBright's copy updates, including the product's categories and images, so the product can be offered a plan. | The app sets all of this up when you install it. Do not create BigCommerce webhooks for SureBright by hand: only the ones the app registers work. The customer on a contract comes from the order's first shipping address (name, email, phone, address). Orders with no shipping address fall back to the billing address. A missing email or address holds the contract; see [Why a contract is on hold](/contracts/holds). ## Find your contracts in the merchant portal Every contract shows under **Recent Sales** on the portal's [Sales](/merchant-portal/sales) page. Plans that could not be matched to a product, or sales whose details are incomplete, show in **Order Resolution**. The cases and what you can do about them are listed in [Why a contract is on hold](/contracts/holds#cases-you-see-in-order-resolution). ## Uninstall the app Uninstall the app from the BigCommerce control panel to disconnect your store. Existing contracts stay in force and remain visible to their holders. No new contracts are created after that. Reinstalling the app reconnects the same SureBright store. ## Related - [Products](/merchant-portal/products) - [Sales](/merchant-portal/sales) - [Why a contract is on hold](/contracts/holds) - [Pause or remove SureBright](/platforms/pause-or-remove) --- # Adjudicator Portal Source: https://docs.surebright.com/claims/adjudicator-portal > Find your way around the portal where claims are read and worked: sign in, the claims ledger, a single claim, filing for a customer, contracts, customers, your team and repairs. Early access. Ask your SureBright contact to enable this for your store. The Adjudicator Portal is where you read the claims against your contracts and, if your team decides its own claims, work them. Use this page to find the screen you need. What you can do on each screen depends on your role and on who decides your claims; see [Merchant adjudication](/claims/merchant-adjudication). ## Sign in Enter your **Work email** and click **Send me a code**. There is no password. Type the one-time code from the email and click **Sign in**. **Resend the code** sends another, and **Use a different email** starts again. If you are new, you arrive through an invitation link. The link expires and works once. Enter **Your name** if you like, click **Accept invitation**, then sign in as above. Access is granted per organisation, so if you cannot sign in, ask an org admin on your team. ## Find your way around the menu | Menu entry | Who sees it | What you do there | |---|---|---| | **Claims** | Everyone | Read and work the claims ledger | | **Repairs** | Everyone | Decide repair items waiting on an adjudicator | | **Contracts** | Org admins | Browse every contract your organisation holds | | **Customers** | Everyone | Look up the people behind the contracts | | **Team** | Org admins | Invite members and manage their access | | **Communication** | Org admins | Reword the emails your customers receive | The top bar has a search box for claims, contracts, customers or an email address, and the **File a claim** button, on every screen. Your name and role are at the foot of the menu, where you sign out. An organisation that decides its own claims is marked **Self-adjudicated** there. ## Work through the claims ledger **Claims** opens the ledger. The line under the title tells you how many claims are waiting on you and how long the oldest has waited. | You want to | Do this | |---|---| | See open, closed or all claims | Pick the **Open**, **Closed** or **All claims** tab. Each shows its count. | | Narrow to one stage | Under **Open**, click **New**, **In review** or **Awaiting fulfilment**. Under **Closed**, click **Fulfilled** or **Declined**. | | See only claims that need you | On the **Open** tab, set **Waiting on** to **You**. **Customer** shows claims waiting on a reply. | | See your own claims, or ones nobody holds | Set **Assigned to** to **Me** or **Unassigned**. | | Find one claim | Search by claim number, customer, email or words from the description. | | Change the order | Set **Sort** to **Waiting longest**, **Newest** or **Incident date**. The ledger starts on **Newest** and remembers the order you last chose. | | Take the list elsewhere | Click **Export CSV**. It exports the claims that match your filters. | The columns are **Claim**, **Customer**, **What happened**, **Stage**, **Waiting**, **Assigned to** and **Incident date**. **Stage** also says who the claim is waiting on, or **Agent assessing** while an assessment is running. **Waiting** shows how long the claim has been in its stage and adds **over** once it has waited too long. In the CSV export, the stage appears as a code: `NEW`, `REVIEW_IN_PROGRESS` (in review), `FULFILMENT_PENDING` (awaiting fulfilment) or `CLOSED`. A closed claim also has an outcome: `SETTLED` (fulfilled), `DECLINED`, `WITHDRAWN` or `LAPSED` (closed, no reply). ## Read and work a single claim Click a claim in the ledger to open it. Opening a **New** claim moves it to **In review**, unless you are a viewer. Press Esc to go back to the ledger. The top of the page shows the claim number, its stage, the progress bar, the product, the purchase price, the incident date and whether the incident falls inside the plan's cover dates. Markers such as **Reopened**, **Resembles an earlier claim**, **Agent paused** and **Customer barred** appear beside the claim number when they apply. | You want to | Do this | |---|---| | Take the claim, or hand it to a colleague | Set **Assigned to** to **Self-assign**, a team member or **Unassigned**. | | Say whose move it is | Set **Waiting on** to **Adjudicator** or **Customer**. | | Read what the customer said | See **Customer's account**. **Add additional information** records something you learned by phone or email. | | Look at the photographs and documents | See **Evidence**. Each file shows whether it has been scanned. **Add a file** uploads one yourself. | | See what the AI makes of the claim | See **Coverage assessment**. **Run it again** asks for a fresh answer, and **Write my own reading** records yours. | | Ask the customer for something | Click **Request info**. Edit the questions and click **Send message**. | | Chase a customer who has not replied | Click **Send a reminder** on the **Decision** card. | | Decide the claim | Click **Approve** or **Decline**, then confirm in the **Approve claim** or **Decline claim** dialog. The dialog lists what your choice does and what the customer will be told. The buttons appear once the claim has a coverage assessment. | | Finish an approved replacement | Click **Mark fulfilled** once the replacement has gone out. If the claim still reads **In review**, click **Move to awaiting fulfilment** first. You can add a note for your own record. | | Run an approved repair | Use the **Repair** card: the plan, estimates, spend requests, reviews, invoices and closing the plan. See [Resolutions and payouts](/claims/resolutions-and-payouts). | | Leave a note for your team | Add it under **Timeline**. Notes are private and never shown to the customer. | | Check the history | **Timeline** lists everything that happened, newest first. Filter it with **All**, **Notes**, **Decisions**, **Messages** or **Automated**. | | Open the contract or the customer | Use the links on the **Record** card, which also links to the plan's terms. | How to read the assessment and what each decision does is covered in [Merchant adjudication](/claims/merchant-adjudication). A fulfilled, declined or withdrawn claim is read-only apart from private notes. If your team decides its own claims, SureBright staff see the controls on your claims locked. If you are a viewer, you can read everything and change nothing. ## File a claim for a customer Use **File a claim** in the top bar for a claim taken by phone or email. Viewers do not have the button. The form walks through five steps: **Contract**, **What happened**, **When**, **Evidence** and **Review**. Search by customer name, email or contract reference, pick the contract and the product, say how the customer got in touch, enter the incident date and what happened, attach at least one photograph or document, and click **File the claim**. See [Filing a claim](/claims/filing-a-claim). ## Look up contracts and customers **Contracts** (org admins only) lists every contract your organisation holds: product, customer, coverage dates, purchase price, status and the date sold. Search by contract ID, customer, product or order number, and filter by **Status**. Open a contract to see its claims. Anyone working a claim can still open the one contract behind it from the claim. **Customers** lists the people behind the contracts with how many contracts and claims each has, how many claims are open and when they were last active. Search by name, email or a product they bought, and sort by **Most claims**, **Name** or **Last activity**. A customer's page lists their contracts and claims. To stop a customer filing new claims with you, open their page and click **Ban customer**, with a reason. Claims already open are unaffected. The ban shows on their page, where **Lift ban** removes it. A ban placed by SureBright across every merchant can only be lifted by SureBright. ## Manage your team and customer emails **Team** (org admins only) is where you invite people, choose each person's role and approval limit, and revoke access. Invitations you have raised are listed under **Awaiting SureBright approval** until SureBright approves them. See [Merchant adjudication](/claims/merchant-adjudication) for the roles and the steps. **Communication** (org admins only) is where you reword the emails your customers receive, preview them and go back to earlier wording. See [Claim communications](/claims/communications). Your claim settings, such as who decides your claims and which resolutions are offered, are managed by SureBright. Ask your SureBright contact if something needs changing. ## Decide repair requests in the Repairs queue **Repairs** lists the estimates, spend requests, reviews and plan closes waiting on an adjudicator, most urgent first. Each row shows what is waiting on you and when it is due or how long it has waited, with **Urgent** and **Overdue** markers. Search by claim number or job number. Filter by **Type**, by **Status** (**Open**, **Resolved** or **All**) and by **Due** (**Overdue only** or **Not overdue**). Click an item to open the work order it belongs to on the claim's **Repair** card, where you decide it. ## Related - [Merchant adjudication](/claims/merchant-adjudication): roles, approval limits and how to decide a claim. - [How a claim moves](/claims/overview): what each stage and outcome means. - [Resolutions and payouts](/claims/resolutions-and-payouts): replacement, repair and the money pool. - [Claim communications](/claims/communications): the emails sent from a claim. --- # Claim communications Source: https://docs.surebright.com/claims/communications > The emails a customer receives during a claim, when each one is sent and by whom, and how to put them in your own words. Your customer hears about a claim through a small set of emails, each tied to a moment in the claim. Read this page to know what your customer will be told and when, and how to rewrite the wording in your own voice. ## Emails your customer receives Every email carries the claim number in its subject, so a reply lands on the same claim. | Email | Listed in the editor as | Sent when | Sent by | |---|---|---|---| | Acknowledgement | **We've got your claim** | The claim is filed, from the portal or from a confirmed email. It confirms receipt and promises nothing else. | Automatic, once per claim | | Request for information | **We need something from you** | Review cannot go further without something only the customer can give (a clearer photograph, a missing detail, a product that does not match), or an adjudicator has a question of their own. One email lists everything outstanding. | A person | | First reminder | **A first nudge** | Day 3 after the request, with items still outstanding | A person | | Second reminder | **A second nudge, before we close** | Day 7. It names the date the claim will be closed if nothing arrives, and how long a reply will still reopen it. | A person | | Closed for no reply | **Closed for now** | A person closes the claim because the customer has not replied. The claim closes as **Closed, no reply**. | A person | | Approval | **Approved** | The claim is approved. The email names what the customer gets, for example a replacement or a repair. | A person | | Settled | **Settled** | The replacement or repair has been delivered and the claim is marked fulfilled | A person | | Decline | **Declined** | A person declines the claim and picks the reason. The wording for each reason is fixed. | A person, always | Only the acknowledgement goes out by itself. Every other email is prepared as a draft on the claim, and a person presses **Send message**. One person can prepare a draft and another can send it. Reminders count from the moment the request was actually sent. A reminder lists only what is still outstanding: if the customer has sent two of three items, it asks for one. If everything has arrived, there is nothing to send. The portal tells you when a reminder is due; a person decides to send it. Sending a request for information marks the claim as waiting on the customer. Preparing the draft does not. See [How a claim moves](/claims/overview). ## When your customer replies Customers reply to the address the email came from. The reply is matched by the claim number in the subject and added to the claim as a follow-up, and any attachments are kept as evidence on the claim. A reply on a claim closed for no reply, inside the window the customer was promised, reopens the same claim. ## Write the emails in your own words Your organisation can rewrite any customer email except the decline. Until you do, your customers receive SureBright's wording. In the Adjudicator Portal, open **Communication**. Only an org admin can change wording. Choose one under **Messages**. Each is tagged **Your wording**, **SureBright's** or **Fixed**. Change the **Subject** and the **Message**. Both are needed. **Compare with SureBright's** shows what you have changed. **Preview** shows the email as it would be sent, filled in with an example claim, along with any warnings about your text. Click **Save wording**. Every future email of that kind uses your wording. Emails already sent are unaffected. To go back to SureBright's wording, click **Load the default** and then **Save wording**. The decline cannot be rewritten by any organisation and is tagged **Fixed**. Its wording is set for each decline reason, and it is always sent by a person. You can read it in the editor. ### Insert claim details with merge fields You edit wording, never facts. A merge field is a placeholder that is filled in from the claim when the email is sent, for example `{{customerName}}`. - Each email has its own list of fields. The editor shows them beside the text and marks which are already in your wording. Click one to insert it. - Every claim email offers `{{claimNumber}}`, `{{customerName}}` and `{{productName}}`. - Anything that is a list or that differs from claim to claim comes as a ready-made block, for example the list of items still outstanding, or the sentence that differs between a replacement and a repair. Write around the block and it stays correct for every claim. - There are no conditions, loops or formulas. You cannot save wording that uses a field the email does not have. - Spaces inside the braces are fine: `{{ customerName }}` works. An optional detail that is missing leaves a gap, never the word "null". ### Go back to an earlier wording Every save keeps the wording it replaced. The editor lists them under **What this used to say**, each with the time it was saved and who saved it. From there you can: - **Edit this version** to load it back into the editor. Save to put it back in use. - **Use this version** to put it back in use straight away. - **Name this version** so you can find it again. - **Remove this version** to take it off the list. The wording your customers were sent under it stays on record. Early access. The **Communication** editor is in the Adjudicator Portal, which is enabled per organisation. Ask your SureBright contact. Once saved, your wording applies whichever team sends the email. ## Can your team be copied on claim emails Claim emails go to the customer at the email address on the order, and the customer's replies are added to the claim. To follow a claim: - Read it in the Adjudicator Portal, where every email sent and every reply is on the claim's **Timeline**. See [How a claim moves](/claims/overview#what-you-see-as-the-merchant). - Without the portal, email [support@surebright.com](mailto:support@surebright.com) with the claim number and ask for an update. If you would like a member of your customer service team copied on a customer's claim emails, ask your SureBright contact. ## What a customer email never contains Each email can only use the claim details listed for it. A customer email never carries an assessment, a confidence score, an internal note, a staff member's name or the contract's money figures. ## Related - [How a claim moves](/claims/overview): the stages behind each email. - [Filing a claim](/claims/filing-a-claim): how a claim starts and what the customer is asked for. - [Merchant adjudication](/claims/merchant-adjudication): who sends the emails for your organisation. - [Adjudicator Portal](/claims/adjudicator-portal): where drafts are sent and wording is edited. --- # Filing a claim Source: https://docs.surebright.com/claims/filing-a-claim > How a customer starts a claim in the customer portal or by email, what evidence is accepted, why a filing can be refused, and how your team can file for a customer. A claim is filed against one plan and one covered product. Customers can file it themselves in the customer portal or write to SureBright, and your team can file on a customer's behalf. Read this page when a customer asks you how to start a claim or why one was refused. ## How a customer files in the customer portal The customer signs in to the customer portal with the email address the plan was sold to, opens the product under **Protection plans** and clicks **File a claim**. The form asks for the details in the table below. Every one of them is required. The photographs upload first and the claim is filed only when every file has arrived, so a failed upload never leaves a claim with missing evidence. If a file fails, the customer is asked to try again. The customer sees the claim number and the next step, and receives an acknowledgement email. Review starts by itself once the photographs have been checked. | Field | Notes | |---|---| | **First name**, **Last name** | Pre-filled from the account | | **Email** | Read-only. The claim is filed by the address the plan was sold to. | | **Phone number** | | | **When did it happen?** | A calendar day, no later than today | | **Describe the issue** | At least 50 and up to 2,000 characters. The prompt asks when it started, what the product does or does not do, and what the customer has tried. | | Photos or videos | At least one. See the limits below. | ### What evidence is accepted | Rule | Limit | |---|---| | Files per claim | 10 | | Size per file | 25 MB | | Accepted types | JPG, JPEG, PNG, GIF, WebP, HEIC, HEIF, MP4 and MOV | HEIC and HEIF, the formats an iPhone produces by default, are accepted as they are. The customer does not need to convert them. If one file is too large, the form names that file and the limit; it does not refuse the whole selection. ### When a claim is already open on the product A plan can carry more than one claim. When a claim is already open for the product, the form shows **A claim is already open for this product** with the claim number, date filed, status and next step, and offers two choices: - **Same issue, track existing claim** takes the customer to the claim they already have. - **Different issue, file a new claim** opens a new form and keeps the earlier claim number in view. Both claims draw on the same contract money pool. See [Resolutions and payouts](/claims/resolutions-and-payouts). ## Why a filing is refused The portal tells the customer the reason in plain words. These are the reasons, and what you can do about each. | Reason | What it means | What you can do | |---|---|---| | The plan cannot be found | There is no such plan. | Check the customer is looking at the right order. | | The plan was cancelled | A cancelled plan no longer provides cover. | Nothing to file. Explain that the plan was cancelled. | | Cover has ended | The incident is dated after the plan ended, or the plan has already ended. A customer cannot file on an ended plan themselves. | If the incident happened while the plan was active, your claims team or SureBright can still file it for them. | | The email does not match | The signed-in address is not the plan holder's. | Ask the customer to sign in with the address on the order. | | The customer cannot file new claims | The customer has been barred from filing. | Ask your SureBright contact. | | No covered product | The plan names no covered product. | Ask your SureBright contact. | These do not stop a filing: an incident dated before cover began, cover that is already used up, or a product the form could not match. The claim is filed, and those facts are weighed when it is reviewed. ## When a customer emails instead Customers can also write to SureBright's claims address. An email is not a claim on its own: a person at SureBright reads it, checks the customer's details, the product and the incident date against the customer's plans, and opens the claim. The incident date must be known before the claim can be opened. From then on the claim appears in your organisation's ledger like any other. A reply about an existing claim is added to that claim and does not open a new one. ## File a claim for a customer When a customer rings or writes to you, your claims team can file for them in the Adjudicator Portal. Viewers cannot file. Click **File a claim** in the top bar. It is on every screen. From a customer's or a contract's page it starts with that customer or contract already found. Search by customer name, email or contract reference, pick the contract, and choose which product is being claimed. Choose how the customer got in touch (**Phone** or **Email**) and write what happened and what broke. The claimant's details are filled in from the contract. The date is checked against the plan's cover dates as soon as you enter it, and the form tells you if it falls outside them. Attach at least one photograph or document. Check the summary and click **File the claim**. The files upload before the claim is filed, as they do in the customer portal. The claim then appears in the ledger as **New**, and **Open the claim** takes you to it. Early access. Filing from the Adjudicator Portal is available where the portal is enabled for your organisation. Ask your SureBright contact. ## File a claim for a customer without the Adjudicator Portal If a customer cannot or will not use the customer portal, for example because they do not use a computer, prefer to write in French, or phoned your call centre, your team can send the claim to SureBright and SureBright files it for them. From the customer, get what happened, the date it happened, and at least one clear photograph or short video of the fault or damage. Send to [support@surebright.com](mailto:support@surebright.com): the order number, the customer's name and the email address on the order, the product, the incident date, the description and the photographs. Say that you are filing on the customer's behalf. SureBright checks the details against the customer's plan and files the claim. The customer then receives the claim emails at the email address on the order, and can reply to them. If the customer writes in a language other than English, send what they gave you as it is. SureBright can still file the claim. ### Send customers to your team first Some merchants want customers to contact their own team before SureBright, for example through a call centre. You can tell customers to do that on your store and in your own emails, and your team then files the claim using the steps above or in the Adjudicator Portal. Where the portal is enabled, you can also rewrite the claim emails your customers receive. See [Claim communications](/claims/communications#write-the-emails-in-your-own-words). ## How you can help a customer - Point them to the customer portal and the plan's **File a claim** button. The claim must be filed from the email address the plan was sold to. - Ask for clear photographs or a short video of the damage before they start. One good photograph of the fault beats ten of the box. - If the customer's address or phone on the order was wrong, fix it on the order first. The claim is filed by the plan holder's address. - If they filed by email and heard nothing, their message may still be waiting to be read. Ask your SureBright contact before filing a second claim; a duplicate is flagged and takes longer. - Do not ask a customer to file a second claim for the same incident. **Different issue, file a new claim** is only for a different incident. ## Related - [How a claim moves](/claims/overview): the stages a claim passes through after it is filed. - [Claim communications](/claims/communications): the emails your customer receives. - [Customer portal](/customer-portal/overview): what your shoppers see when they sign in. - [Adjudicator Portal](/claims/adjudicator-portal): where your claims team reads and works claims. --- # Merchant adjudication Source: https://docs.surebright.com/claims/merchant-adjudication > Choose who decides your claims, set up your claims team and its approval limits, and use the AI coverage assessment to reach a decision. Either SureBright decides your claims or your own team does. Read this page before you ask SureBright to let your team decide its own claims, and when you set up the people who will work them. ## Who decides your claims | Set-up | What it means for you | |---|---| | SureBright decides (the default) | SureBright's team opens, assesses, decides, writes to the customer and settles. Where the Adjudicator Portal is enabled, you can read every claim against your contracts. Your team acts only when SureBright asks for something: order details, an inspection of a returned unit, or a replacement or repair you supply. | | Your team decides | Your team works claims from start to finish. SureBright staff can read a claim, but the controls that act on it are locked for them unless they deliberately take over. Anything they then do is recorded in your organisation's name and visible to you. | Only SureBright can switch you from one to the other, so ask your SureBright contact. Before you switch to deciding your own claims, your team needs at least one org admin, because only an org admin can invite the rest of the team. In both set-ups one decision settles the claim. There is no second review after it: approving moves the claim to **Awaiting fulfilment**, and marking it fulfilled closes it. See [How a claim moves](/claims/overview). ## Settings SureBright keeps for your organisation How claims are handled is set per organisation by SureBright. To change a setting, ask your SureBright contact. A change applies to claims filed from then on; claims already open keep the settings they were filed under. | Setting | Choices | Default | What it changes | |---|---|---|---| | **Resolutions offered** | **Replacement**, **Repair** | **Replacement** | What an approval in the portal can give the customer. **Repair** is switched on by SureBright where its service network covers your products. Other settlements, such as a reimbursement, are arranged by SureBright. See [Resolutions and payouts](/claims/resolutions-and-payouts). | | **Automation** | **Off**, **Suggest** or **Auto**, chosen separately for each of the three tasks below | **Suggest** | How much the AI does before a person steps in. | | **Money ceiling for automated decisions** | An amount | 0 | The most an automatic coverage decision may commit on a single claim without a person. At zero, the AI can still read, classify and draft, but anything that commits money waits for a person. | | Time before a claim counts as late | Hours | 72 | How long a claim can wait in a stage before the ledger marks it as over. | Every claim is visible to SureBright as well as to your team. ### What automation does at each level | Task | **Off** | **Suggest** | **Auto** | |---|---|---|---| | Reading inbound email into a claim | An email waits for a person to open a claim from it | The email is read into a draft claim for a person to confirm | The email is read into a claim automatically | | Deciding whether the plan covers the incident | A person decides with no AI input | The AI proposes a coverage decision and a person approves it | The AI's decision counts straight away, within the money ceiling | | Drafting customer messages | No drafts are prepared | Drafts are prepared; a person edits and sends | Drafts are prepared; sending still needs a person | At every level, the only customer email that goes out by itself is the acknowledgement when a claim is filed. See [Claim communications](/claims/communications). ## Set up your claims team Access to claims comes from a person's role on the claims team, which you manage under **Team** in the Adjudicator Portal. A Merchant Portal role (owner, admin or sales associate) gives no access to claims: an owner who is not on the claims team cannot read a claim. | Role | Can | |---|---| | **Org admin** | Everything an ops member can, plus invite and remove members, set each member's approval limit, change the customer email wording, browse the full contract list and override a recorded decision | | **Ops** | Work claims from start to finish: open, assign, assess, decide, draft and send messages, mark a claim fulfilled, write notes, compose a repair plan and decide repair estimates | | **Viewer** | Read claims, their evidence, decisions and messages, and the repair plan, estimates, invoices and service record. Change nothing. | Each member also has: - **Scope**: which claims they see. Your members see your own organisation. - **Approval limit**: the most they may approve on a single claim. When a claim is worth more than a member's limit, the portal says so and someone with a higher limit has to approve it. The member can still decline it. Leave the limit blank for no limit. ### Invite a team member In the Adjudicator Portal, open **Team**. Only an org admin sees it. Under **Invite someone**, enter the person's **Email**, choose a **Role** and, if you want one, an **Approval limit**. Click **Send invitation**. SureBright reviews each invitation. Until then it is listed under **Awaiting SureBright approval** and nothing is sent to the person. You can withdraw it with **Revoke invitation**. Once approved, the person is emailed a sign-in link and appears under **Members**. Someone who already has a SureBright account is granted access straight away and can work claims the next time they sign in. To change someone later, find them in the **Members** table: pick a new role and confirm with **Change role**, edit their approval limit, or click **Revoke access**. Their decisions on past claims stay on record. ## How the AI coverage assessment helps you decide When a claim is filed, and again whenever new evidence or a corrected description arrives, the AI reads the customer's account and the photographs against the plan's coverage for that product and proposes an answer. You see it on the claim under **Coverage assessment**, with its reasoning, the parts of the plan it rests on and the words it quoted from the customer. | The assessment says | What it means | What you can do | |---|---|---| | **Covered** | The plan covers this incident. It may rest on a condition you should check first, listed under **What this answer assumes** (for example, that the customer has really lost use of the product). | Approve, or decline if you disagree | | **Not covered** | The plan excludes this incident. | Decline with a reason, or approve anyway and say why | | An answer with a caution | The AI reached an answer, but something is worth reading first, such as a photograph already used on an earlier claim. | Read the caution, then decide | | **Agent could not assess this claim** | No answer. The assessment says what would unblock it: clearer photographs, more detail, more than one incident in the account, a product that does not match, or a gap SureBright has to fix. | Click **Request info** to ask the customer, or decide by hand | | **A service matter** | The request is about a service or benefit, not a claim on the product. | Read the assessment, then decide | Cautions, such as a photograph that contradicts the account, no evidence supplied or no incident date, travel with the answer. They never change it by themselves. The AI's quotes are checked against what the customer actually wrote, and an answer that rests on words the customer did not write is flagged for you to read yourself. ### The assessment proposes, you decide With automation on **Suggest**, the default, an assessment changes nothing about a claim until a person acts on it. - To act on it, click **Approve** or **Decline** on the claim. - To ask the customer for what is missing, click **Request info**. The questions the assessment raised are filled in for you to edit and send. - To get a fresh answer after new evidence arrives, click **Run it again**. - If you disagree, click **Write my own reading** and record your own answer and why. Both readings stay on the claim, and SureBright uses your corrections to improve later assessments. ### Record the decision | You click | What happens | |---|---| | **Approve**, then **Approve claim** | You choose **Replacement** or **Repair** where both are offered. The claim moves to **Awaiting fulfilment** and the approval email is prepared for the customer. | | **Decline**, then **Decline claim** | You must pick a **Reason**, from **Never qualified** or **Not covered by the terms**. The claim closes as **Declined**, the customer is told the reason in fixed wording, and a 30-day appeal window opens. An appeal brings the claim back to a person. | You can add a **Rationale** to either. It is saved on the claim and is not sent to the customer. A recorded decision is never edited or deleted. An org admin can override one, which records a new decision beside the old one, and both stay visible. Overriding is limited to org admins because it changes an outcome the customer has already been told about. Early access. The team, the assessment and the decision are worked in the Adjudicator Portal, which is enabled per organisation. Ask your SureBright contact. The claim settings apply to every organisation at their defaults. ## When SureBright asks you to inspect a returned unit For some products SureBright asks you, the seller, to inspect the claimed unit before the claim is decided. You do the inspection; SureBright still makes the decision. SureBright tells you which claim the unit belongs to. If you need a return label for the customer, ask support on that claim before the customer ships. Reply to support with the claim number and what you found: the fault, its likely cause, whether it can be repaired, and photographs. Say plainly if you think the fault is damage rather than a breakdown, or if it matches an earlier claim on the same unit. SureBright passes your findings into the claim review. SureBright then contacts the customer with the outcome or the next step. If the customer disputes your diagnosis, do not argue the claim with them. Send the claim number and the customer's objection to support. A declined customer can also appeal within 30 days, and the appeal is reviewed by a person. See [How a claim moves](/claims/overview#reopened-appealed-duplicate-and-split-claims). ## Related - [Adjudicator Portal](/claims/adjudicator-portal): find your way around the portal your team works in. - [How a claim moves](/claims/overview): stages, who a claim is waiting on and how it closes. - [Resolutions and payouts](/claims/resolutions-and-payouts): replacement, repair and the contract's money pool. - [Claim communications](/claims/communications): the emails your customer receives and how to reword them. --- # How a claim moves Source: https://docs.surebright.com/claims/overview > Find out where a claim is, who it is waiting on, how it can end, and what you and your customer see along the way. A claim is a customer's request to use the protection plan on a product they bought from you. Use this page to tell where a claim is, whose move it is, and what happens next for you and for your customer. ## The four stages of a claim Every claim passes through the same stages. You see them on the progress bar at the top of a claim and in the **Stage** column of the claims ledger in the Adjudicator Portal. | Stage | What it means | Who is usually working | |---|---|---| | **New** | Filed. Nobody has picked it up yet. An automatic coverage assessment may already be on its way. | Nobody | | **In review** | Being worked. The evidence is read, the customer's account is checked against the plan, and a decision is recorded. | The adjudicator, or the customer if something was asked of them | | **Awaiting fulfilment** | Approved, not yet delivered. A replacement is being arranged or a repair is under way. | Whoever ships the replacement or does the repair | | **Closed** | Finished. The stage shows how it ended, for example **Fulfilled** or **Declined**. | Nobody | A claim moves from **New** to **In review** when a person opens it or asks for a coverage assessment, on to **Awaiting fulfilment** when it is approved, and to **Closed** when it is fulfilled, declined, withdrawn or closed because the customer did not reply. A claim that is awaiting fulfilment can go back to **In review** if a reply from the customer reopens the question. ## Who a claim is waiting on Whose move it is sits beside the stage, not inside it. A claim in review can be waiting on the adjudicator or on the customer and still read **In review**. Nothing is waiting once a claim is closed. | Waiting on | What it means | |---|---| | **Adjudicator** | The person deciding the claim owes the next move. If that is you, the ledger says **Waiting on you**, and the time the claim has waited counts against you. | | **Customer** | Something was asked of the customer (a clearer photograph, a date, a description) and nothing has come back yet. | | **Merchant** | You are shipping a replacement from your own stock. | | **SureBright engineering** | SureBright is arranging a dispatch or a repair. | | **Internal** | An internal approval is pending. | | **Third party** | A service provider, a retailer or a payout platform owes the next step. | Sending the customer a request for information hands the claim to the customer without changing its stage. In the ledger, use the **Waiting on** filter (**Anyone**, **You** or **Customer**) to see only the claims that need you. ## How a claim closes | Closed as | What happened | |---|---| | **Fulfilled** | The approved replacement or repair was delivered and the claim was marked fulfilled. | | **Declined** | A person recorded a decline, with a reason. | | **Withdrawn** | The customer withdrew the claim, or the team working it cancelled it. Any cover it had set aside goes back to the contract. | | **Closed, no reply** | The customer went quiet after a request for information. The claim was closed with a promise that a reply still reopens it. | Only a claim closed for no reply reopens. If the customer writes back inside the window they were promised, the same claim returns to **In review** and no new claim is opened. A claim that was fulfilled, declined or withdrawn never reopens. ## Why a claim is declined A decline always carries a reason, and the customer is told it in the decline email. If a customer asks you why their claim was declined, these are the usual reasons. | Usual reason | What it means | What to tell the customer | |---|---|---| | The plan does not cover what happened | For example, the product was dropped or damaged, but the plan covers breakdowns only. Damage is covered only by an accidental damage plan. | The claim was assessed against the plan they bought. They can check their plan in the [customer portal](/customer-portal/overview). | | The manufacturer's warranty, or the store's own warranty, still applies | A breakdown plan that begins after the first warranty on the product does not cover a fault while that warranty runs. | Contact the manufacturer first, or the store when it gave its own warranty, for example on used or refurbished stock. See [Your own store warranty](/contracts/effective-dates#your-own-store-warranty-on-used-or-refurbished-stock). | | The product arrived faulty or damaged | A plan covers a product that was delivered working. A fault or damage on arrival is a matter for your store's returns, or for shipping protection if they bought it. | Handle it as a return or exchange with your store. See [Claims and your role](/learn/claims-and-your-role#a-product-arrived-faulty-or-damaged). | | The incident was outside the plan's dates | The problem happened before cover started or after it ended. | Show them their cover dates in the customer portal. | If the customer disagrees, they can appeal within 30 days of the decline, and a person reviews it again (see below). If you think a decline is wrong, send the claim number and your reasons to [support@surebright.com](mailto:support@surebright.com). ## Reopened, appealed, duplicate and split claims Some claims continue an earlier one. The link shows on the claim, so you can follow the history. | Situation | What happens | Effect on cover | |---|---|---| | The customer comes back on a claim closed for no reply, inside the reopen window | The same claim reopens, marked **Reopened**. The new photograph or note is attached to it. | Uses nothing new | | The customer disputes a decline | Declining opens a 30-day appeal window. An appeal brings the question back to a person, and nothing already recorded is erased. | A new claim, linked to the declined one | | A new claim looks like an earlier one that can no longer reopen | The claim is marked **Resembles an earlier claim** as a possible duplicate. Filing is never blocked. | Counts as a claim of its own | | One claim describes more than one incident | The coverage assessment points this out and proposes the separate claims it should become. | Each part is its own claim | ## What you see as the merchant Where you see claims depends on who decides them. See [Merchant adjudication](/claims/merchant-adjudication) for the two set-ups. - **SureBright decides for you** (the default). SureBright's team works each claim. Where the Adjudicator Portal is enabled for you, you can read every claim filed against your contracts there: its stage, who it is waiting on, the evidence, the messages sent to the customer and the decisions. Without the portal, ask support for a claim's status. You act only when SureBright asks you for something, such as order details or a replacement you supply. - **Your team decides.** Your team opens, assesses, decides, writes to the customer and settles. SureBright staff can still read the claim. The controls that act on it are locked for them unless they deliberately take over, and anything they then do is recorded and visible to you. Either way, a claim page carries a **Timeline** of every stage change, assessment, decision and message, newest first, with your team's private notes, which are never shown to the customer. A claim being repaired also shows the contract's money pool: the most the contract can pay out across all its claims, what is reserved and what is still available. See [Resolutions and payouts](/claims/resolutions-and-payouts). Early access. The Adjudicator Portal is being enabled store by store. Ask your SureBright contact to enable it for your organisation. See [Adjudicator Portal](/claims/adjudicator-portal). ## How long a claim takes The customer gets an acknowledgement by email as soon as the claim is filed. After that, how long a claim takes depends on the product, the evidence, whether the unit needs an inspection and how quickly the customer replies. For the expected timing on a particular claim, ask SureBright support or your SureBright contact. A claim waiting on the customer, for example for a clearer photograph, does not move until they reply. See [Claim communications](/claims/communications). ## When a claim seems stuck If the Adjudicator Portal is enabled for you, open the claim and read **Waiting on**. If it is waiting on the customer, ask the customer to answer SureBright's last email. Email [support@surebright.com](mailto:support@surebright.com) with the claim number, the order number and the email address on the order. Say how long the claim has waited and what the customer was last told. SureBright follows up with the claims team. If you have had no answer, or the customer has not been contacted when they were told they would be, reply on the same support email and ask for it to be escalated, or ask your SureBright contact. ## Who works on a repair Repairs through SureBright's service network are arranged by SureBright. The servicer deals with your customer and with SureBright, and in the Adjudicator Portal the servicer is shown as a SureBright provider. If a servicer needs to reach your team about a product, or you want to know what details are shared with them, ask your SureBright contact. See [Service network](/service-network/overview). ## What your customer sees The customer portal lists a customer's claims under **Claims**, each with one of four statuses and one sentence about what happens next. | Customer sees | When | |---|---| | **In progress** | The claim is new, in review or awaiting fulfilment | | **Completed** | The claim was fulfilled | | **Declined** | The claim was declined | | **Closed** | The claim was withdrawn, or closed because the customer did not reply. It is not shown as a deadline the customer missed. | The customer sees the claim number, the product, the date they filed, the status and the next step. They never see an assessment, a confidence score, an internal note, a staff member's name or any money figure. The emails they receive at each step are described in [Claim communications](/claims/communications). ## How a claim reaches SureBright - **The customer portal.** The customer files it themselves, with photographs. - **Email.** The customer writes to SureBright, and a person confirms the details before a claim is opened. - **Your team or SureBright.** An adjudicator files it by hand after a phone call or an email. All three are described in [Filing a claim](/claims/filing-a-claim). ## Related - [Filing a claim](/claims/filing-a-claim): how a customer starts a claim and what evidence is accepted. - [Claim communications](/claims/communications): the emails your customer receives at each step. - [Merchant adjudication](/claims/merchant-adjudication): who decides your claims and how your claims team is set up. - [Resolutions and payouts](/claims/resolutions-and-payouts): what an approved claim settles with. - [Claims and your role](/learn/claims-and-your-role): what you do and what SureBright handles. --- # Resolutions and payouts Source: https://docs.surebright.com/claims/resolutions-and-payouts > What an approved claim can give the customer, how repairs and replacements reach them, how you are paid back when you supply the replacement or repair, and how to read the contract's money pool. When a claim is approved, SureBright decides how it is settled. Read this page to know what a customer can get, what each outcome asks of you, and how you are paid back when your team supplies the replacement, parts or repair. ## What an approved claim can settle with SureBright decides how each approved claim is settled. It is usually a replacement or a repair. It can also be settled another way when that suits the claim better. | Outcome | When it is used | |---|---| | **Replacement** | The usual outcome. SureBright arranges the replacement unit, or asks you to supply it and pays you back. See [When you supply the replacement, parts or repair](#when-you-supply-the-replacement-parts-or-repair). | | **Repair** | Where SureBright's service network covers your products, or where you or a local servicer repair the product and SureBright pays for the work. | | Reimbursement | SureBright has settled claims by paying the customer instead, for example by cheque or with a gift card. This is SureBright's decision on each claim. | You do not need to promise the customer a particular outcome. Tell them SureBright will confirm what the claim settles with when it is approved. The approval email names it. See [Claim communications](/claims/communications). ### If the replacement is out of stock or a repair would cost too much Tell SureBright on the claim. Send the claim number to [support@surebright.com](mailto:support@surebright.com) and say what is unavailable, or what the repair would cost. SureBright then decides another way to settle the claim, such as a different replacement or a reimbursement. ### How a repair reaches your customer How a product is repaired depends on the product and where the customer is. SureBright decides this for each claim. | How | What the customer does | |---|---| | On-site repair | A technician comes to the customer. | | Mail-in repair | The customer ships the product in for repair and it is shipped back. Shipping both ways is usually covered on the claim, so the customer is not asked to pay it. | | Replacement or reimbursement | Used when a repair is not practical, for example when no servicer covers the customer's area. | If a customer asks who will repair their product, or whether they must pay shipping, send the claim number to support and SureBright will confirm. ### In the Adjudicator Portal In the Adjudicator Portal, an approval records **Replacement** or, where SureBright has switched it on for your organisation, **Repair**. Where both are offered, the adjudicator chooses when approving. A claim keeps the resolutions that were on offer when it was filed, so enabling repair changes only claims filed afterwards. Any other settlement is arranged by SureBright with you and the customer. See [Merchant adjudication](/claims/merchant-adjudication). ## When you supply the replacement, parts or repair SureBright may ask your team to ship a replacement, send parts or repair the product, for example because you hold the stock or the know-how. SureBright then pays you back for it. Wait until SureBright has approved the claim and asked you to supply the replacement or repair. If you replace a product before the claim is approved, tell support straight away with the claim number, so the settlement is not paid twice. Reply with the claim number and the costs: | You supply | Send | |---|---| | A replacement unit | What the unit cost you to get in (its landed cost) and the cost of shipping it to the customer. SureBright may also ask you to confirm whether the product is still under the manufacturer's warranty. | | Parts | A parts estimate or invoice | | A repair by your team or a local servicer | The repair estimate before the work, then the invoice | Ship the replacement or finish the repair and tell SureBright, with tracking where there is any. If your team decides its own claims in the Adjudicator Portal, click **Mark fulfilled** on the claim instead. SureBright pays you back at the agreed cost. If you have a question about a payment, send the claim number to support. To get the order details you need to ship a replacement, look the order up in your store admin or in [Sales](/merchant-portal/sales) by the order number on the claim. ## What happens to the claimed unit SureBright decides on each claim whether the faulty unit is returned, and to whom. If you would like the unit back after a replacement or a reimbursement, ask on the claim before it is settled. SureBright tells you whether it will be returned and how the return label is arranged. A unit that a repair provider still holds when its job ends is shipped back with a label SureBright provides. See [Service network](/service-network/overview). ## When a claim is approved for replacement in the Adjudicator Portal The claim moves to **Awaiting fulfilment** and a replacement is what it settles with. The amount is the replacement unit's price, which is looked up, not typed in. | Who decides your claims | Who ships | What you do | |---|---|---| | SureBright | SureBright arranges the replacement. The claim shows as waiting on **SureBright engineering**. | Nothing, unless SureBright asks you to supply it. See [When you supply the replacement, parts or repair](#when-you-supply-the-replacement-parts-or-repair). | | Your team | You ship from your own stock. The claim shows as waiting on **Merchant**. | Once it has gone out, click **Mark fulfilled** on the claim. The claim closes as **Fulfilled**, the payout is recorded against the contract's money pool and the customer is told it is done. | If a claim has an approval on record but still reads **In review**, click **Move to awaiting fulfilment** first. A member cannot approve a claim worth more than their approval limit. Someone with a higher limit has to approve it. ## When a claim is approved for repair in the Adjudicator Portal The claim moves to **Awaiting fulfilment** and the adjudicator composes a repair plan. SureBright's service network then matches each piece of work to a provider. See [Service network](/service-network/overview). ### Compose the repair plan Click **Compose repair plan** on the claim. A plan is one or more work orders. For each you choose the items it covers, the type of work, and whether the provider quotes first. | Work order type | How the work is done | |---|---| | **On-site repair** | On site | | **Mail-in repair** | Mail in | | **Detach and ship** | On site | | **Reinstall** | On site | | **Deliver** | On site | | **Pick up and return** | On site | Each work order is one of two kinds: - **Diagnostic**: the provider inspects and sends an estimate, which you approve before the repair goes ahead. - **Mechanical**: known work. You can pre-authorise it with an envelope of **Labour hours**, **People** and a **Parts allowance**, and the provider asks only if the job would go over. Only a mechanical work order can have an envelope. A plan holds up to 10 work orders and needs a service address with a two-letter country code. A work order can wait for another one to finish (**Waits for**), but work orders cannot wait on each other in a circle. ### Decide what a provider sends back Everything a provider raises appears on the claim's **Repair** card and in the **Repairs** queue, most urgent first. | You receive | What you decide | |---|---| | An estimate | **Approve**, **Adjust** or **Deny** the provider's quote. A denied estimate can be revised once. | | A spend request | **Approve**, **Adjust** or **Deny** spending beyond a pre-authorised envelope. | | A review | The unit does not match, is not as described or cannot be repaired. **Resume** the job, or **Close** it as not completed. | | An additional fault | The provider found another fault. **Acknowledge** it, and add a work order if one is needed. | | A plan ready to close | Once every work order has ended, close the plan as **Resolved** or **Exhausted**. | An org admin can click **Convert to replacement** at any point. The repair approval is overridden, the plan is withdrawn and the claim carries on as a replacement. A claim with an open repair plan cannot be marked fulfilled. Close the plan first, and make sure every repair invoice is approved. ### Who pays the repair invoices The provider invoices once the work is complete. The invoice is checked and approved or flagged, and the approved amount counts against the contract's money pool. You can read every invoice under **Invoices** on the claim's **Repair** card. SureBright pays the provider. You do not. When your own team or a local servicer does the repair instead, see [When you supply the replacement, parts or repair](#when-you-supply-the-replacement-parts-or-repair). ## How to read the contract's money pool Every contract has one lifetime pool, and every claim on that contract draws from it. The pool belongs to the contract, not to the claim in front of you, so the available figure is what is left for all of the contract's claims together. On a repair claim, the **Money pool** summary on the **Repair** card shows: | Figure | What it means | |---|---| | **Ceiling** | The most the contract can ever pay out, across all its claims | | **Reserved** | Money set aside by approvals that are not yet paid, so a second claim cannot promise what the first has committed | | **Repair spend, this claim** | What repairs on this claim have cost so far | | **Available** | The ceiling, less what is reserved, less what has been spent | | **Pool** reads **Void** | The ceiling has been reached. Nothing more can be paid from this contract. | Money is reserved when an approval commits an amount, released if the approval is overridden or the claim is withdrawn, and spent when a replacement, shipping or a repair is paid for. You cannot settle a claim for more than what is available; the portal shows the available and requested amounts. Once the pool is void, nothing more can be settled. Used-up cover does not stop a customer filing a claim. It shows on the claim and governs what can be paid. ## How payouts are recorded A payout records money leaving the pool for a claim. It is **Pending** when recorded but not yet issued, **Issued** once it has gone out, **Failed** if it could not be issued (the reason is kept with it), and **Reversed** if it was taken back afterwards. In the Adjudicator Portal, the payouts recorded on a claim are replacements. A repair is paid to the provider against its approved invoice and shows as repair spend, not as a payout. A reimbursement to the customer, or a payment back to you, is arranged by SureBright outside the portal. Early access. The **Repair** card, the **Repairs** queue and the **Money pool** summary are in the Adjudicator Portal, which is enabled per organisation. Ask your SureBright contact. ## Related - [Merchant adjudication](/claims/merchant-adjudication): who decides your claims and what your team can approve. - [Service network](/service-network/overview): how repair work reaches a provider. - [How a claim moves](/claims/overview): the stages before and after an approval. - [Adjudicator Portal](/claims/adjudicator-portal): where the Repair card and the Repairs queue live. - [Contact support](/help/contact-support): what to send about a claim. --- # When coverage starts Source: https://docs.surebright.com/contracts/effective-dates > When a customer's cover starts and ends for an ordinary order, a pre-order and a plan bought after the product, how your own store warranty fits in, and how to correct a wrong manufacturer warranty length. Use this page to tell a customer when their cover starts and when it ends. SureBright sets both dates. The end date is always the start date plus the plan's term. ## When cover starts, by situation | Situation | Cover starts | |---|---| | An ordinary order, on a store whose plans are dated at purchase (most stores) | From the purchase, adjusted for the plan type. See [Ordinary orders](#ordinary-orders-cover-dated-from-the-purchase). | | A pre-order, on a store whose plans are dated at shipment | From the day the product ships. See [Pre-orders](#pre-orders-cover-dated-from-the-shipment). | | A plan bought after the product, through a post-purchase offer, a registration page or at the point of sale | Measured from when the customer got the product, not from the day the plan was bought. See [Plans bought after the product](#plans-bought-after-the-product-post-purchase). | | A point-of-sale sale recorded with the wrong manufacturer warranty | You can correct it for 45 days. See [Correcting a point-of-sale sale](#correct-the-manufacturer-warranty-on-a-pos-sale). | | A plan sold with the wrong manufacturer warranty length, online | Send support the correct length. See [Correct a manufacturer warranty length](#correct-a-manufacturer-warranty-length). | | A used or refurbished product with your own store warranty | A breakdown plan starts after your store warranty ends. See [Your own store warranty](#your-own-store-warranty-on-used-or-refurbished-stock). | Whether your store dates plans at purchase or at shipment is set by SureBright for the whole store. Ask your SureBright contact to change it. [Fulfillment](/merchant-portal/fulfillment) compares the two. ## Ordinary orders: cover dated from the purchase On most stores the start date is worked out from the day the plan was bought, by plan type: | Plan type | Cover starts | |---|---| | Accidental damage | The day the plan was bought. Cover starts immediately. | | Breakdown (extended warranty) that begins after the manufacturer's warranty | The day the manufacturer's warranty ends, or the day the plan was bought if that is later. | | Breakdown (extended warranty) that includes the manufacturer's warranty period in its term | The day the plan was bought. | A small number of stores have a different start agreed with SureBright, with cover starting one year after purchase for certain categories. SureBright sets that up per store. **Example.** A customer buys a product on 1 March 2026 with a 12-month manufacturer's warranty, and adds a 2-year breakdown plan that begins after it. The manufacturer's warranty ends on 1 March 2027, so SureBright cover starts on 1 March 2027 and ends on 1 March 2029. An accidental damage plan on the same order would start on 1 March 2026. ### Which manufacturer warranty length is used For breakdown plans that begin after the manufacturer's warranty, the two never overlap: SureBright cover begins when the manufacturer's warranty ends. The manufacturer's warranty is counted from the product's purchase date, and its length is taken from the first of these that applies: 1. the length given for the product when the plan was quoted, when it is a positive number of months; 2. the length set for your store, which can be 0; 3. otherwise **12 months**. A store that is set to 0 months keeps 0. Any other missing or zero value falls back to 12 months. ## Correct a manufacturer warranty length The length SureBright uses decides when a breakdown plan starts, so a wrong length moves the customer's cover. Fix it the way that matches your case: | Situation | Do this | | --- | --- | | The product shows a **Mfr warranty** chip in [Products](/merchant-portal/products) | Click the chip and set the length. New quotes use it. See [Set the manufacturer warranty length](/merchant-portal/products#set-the-manufacturer-warranty-length) | | The product has no chip, and its manufacturer's warranty is not 12 months | Tell your SureBright contact. If your listings or catalogue already record the warranty length per product, say where, so it can be used for all of them and for products you add later | | A plan is already sold with the wrong length | Write to support with the order number, the product and the correct length. SureBright corrects the plan so cover starts when the real manufacturer's warranty ends, and corrects the product for future sales | | The customer got a longer manufacturer's warranty by registering the product with the manufacturer | The same: write to support with the order number and the new length | | A point-of-sale sale | Correct it yourself within 45 days. See [Correct the manufacturer warranty on a POS sale](#correct-the-manufacturer-warranty-on-a-pos-sale) | The widget may also show the manufacturer's warranty next to the plan. If the plan length on your product page and in the portal look different, see [Plan lengths on your product page](/merchant-portal/products#plan-lengths-on-your-product-page-look-different). ## Your own store warranty on used or refurbished stock For used and refurbished products, the warranty you give as the seller, for example 90 days, plays the part of the manufacturer's warranty: - Claims during your store warranty are yours to handle, as they would be the manufacturer's on a new product. A customer who files with SureBright during that period is sent back to you. - A breakdown plan starts when your store warranty ends. - Tell SureBright how long your store warranty is. On the POS portal, set it as the product's **Manufacturer / Seller Warranty** duration. See [Recording a sale](/pos/recording-a-sale). For your online store, tell your SureBright contact. See [Used, refurbished and open-box products](/contracts/what-can-be-covered#used-refurbished-and-open-box-products). ## Pre-orders: cover dated from the shipment If your products ship weeks or months after payment, your store can be set up so cover is dated when the product ships. On those stores: 1. When the order is paid, the plan is created without a start or end date. The customer's confirmation email waits, so it never shows blank dates. Billing does not wait. 2. When the product ships, the start and end dates are worked out from the shipment date and the confirmation email is sent. 3. Each unit is dated by the shipment it is in. If a customer buys three plans and one product ships first, one plan is dated then, and the other two are dated by the later shipment, with that shipment's date. A plan that already has dates is never re-dated. 4. If a shipment is cancelled, the dates are cleared and the plan waits again. The plan is not cancelled, because a cancelled shipment is usually re-shipped. Shipping again dates it again. A plan whose product had already shipped when the plan was created, for example a plan bought after the product shipped, is dated straight away from that shipment and does not wait. **Example.** An order is paid on 1 June and ships on 20 July. The customer's cover is worked out from 20 July, and the confirmation email arrives then. How SureBright learns about the shipment depends on your platform: - **On Shopify**, this happens by itself when you fulfil the order, or cancel a fulfillment. - **On BigCommerce**, cover is dated from the shipment when you ship the order. - **If you integrate directly** and date plans at shipment, SureBright can enable the [fulfillment endpoint](/api-reference/endpoint/order/fulfillment) so your system reports shipments and cancelled shipments. - **On other platforms**, ask your SureBright contact. ## Plans bought after the product (post-purchase) When a plan is sold after the product, through a post-purchase offer, a registration page or at the point of sale, the plan and the product have different purchase dates. Cover is measured from the **product's** purchase date, so the manufacturer's warranty is counted from when the customer actually got the product. **On stores dated at purchase**, the ordinary rules apply with that starting point: - A breakdown plan that begins after the manufacturer's warranty starts when that warranty ends, counted from the product's purchase, or on the day the plan was bought if that is later. - An accidental damage plan starts on the day the plan was bought. **Example.** A customer buys a product on 1 January 2026 with a 12-month manufacturer's warranty, then buys a breakdown plan on 1 March 2026. Cover starts on 1 January 2027, when the manufacturer's warranty ends, not 12 months after the plan was bought. **On stores dated at shipment**, the shipment date of the original product is the starting point: | Plan type | Cover starts | Cover ends | |---|---|---| | Breakdown that begins after the manufacturer's warranty | Shipment date plus the manufacturer's warranty | Start date plus the term | | Breakdown that includes the manufacturer's warranty period | The later of the shipment date and the day the plan was bought | Start date plus the term | | Accidental damage | The later of the shipment date and the day the plan was bought | The later of the product's purchase date and the shipment date, plus the term | For accidental damage the term runs from when the product's own cover would have started, so buying the plan late shortens the window instead of pushing the end date out. If the product is so old that the end date would fall before the start date, SureBright reviews the plan instead of giving it a fresh window. Two cases on stores dated at shipment: - A plan offered on your store for a product in an earlier order uses that product's real shipment date. - A plan bought through registration for a product that was not ordered on your store has no shipment to wait for. It is dated from the day the plan was bought. ## Whole-system plans: cover begins on the plan purchase date A Whole System Warranty plan is dated from the day the plan is bought, not from the end of another warranty. | Date | How it is set | |---|---| | Cover begins | On the plan purchase date | | Cover ends | On the last day of the plan's term, counted from the plan purchase date: 2, 3 or 5 years | The plan purchase date is the **Purchase date** you enter when you record the sale in the installer portal. For a plan created through the API, it is the day the plan is created. Your installation warranty and the manufacturer warranty still come first for the problems they cover: | Kind of problem | Who covers it | |---|---| | A breakdown your installation warranty or the manufacturer warranty covers | That warranty applies first. The plan covers the problem once that warranty has ended. | | Accidental damage to the portable devices in the system, or a power surge | The plan, from the plan purchase date | | Labour, once your installation warranty has ended | The plan, even while the manufacturer still covers the part | **Example.** You record a sale with a purchase date of 10 March 2026, a 12-month installation warranty and a 3-year plan. Cover begins on 10 March 2026 and runs to 10 March 2029. A breakdown in the first 12 months is handled under your installation warranty or the manufacturer warranty. A power surge in that time is covered by the plan. Who covers a problem at each stage is set out on [What your customer gets](/installers/your-customer). ## Correct the manufacturer warranty on a POS sale For plans sold through the SureBright POS extension, you can correct the manufacturer's warranty recorded at the sale from the POS sales history. The cover dates are then worked out again with the same rules as above. POS shows the cover dates before and after the change before you confirm. See [Sales history](/pos/sales-history). The correction is allowed only when all of these are true: - it is within **45 days** of recording the sale, counted in whole calendar days. A sale with no recorded purchase time cannot be corrected; - the plan is one that allows the change. For other plans the dialog says so and points you to support; - the plan covers a single product. Plans covering several products or a whole system are edited through their own flow; - the new length is at most **120 months**; - the plan has not failed or been cancelled. ## How dates affect activation and refunds - A plan cannot become active until its start date has been reached. See [Contract statuses](/contracts/lifecycle). - A plan that should have dates but does not is on hold until SureBright repairs them. A plan waiting for its shipment is simply waiting. See [Why a contract is on hold](/contracts/holds). - Pro-rata refunds use the plan's start and end dates. While the dates are blank, a refund is 100%. ## Related See which orders are still waiting on a shipment, and compare dating at sale with dating at shipment. What is stopping a plan from going active, and who clears it. - The start and end dates on this page are the contract's effective date and expiration date. - When you create contracts through the API, send the manufacturer's warranty length in months as `manufacturerWarrantyDuration`. See [Create contract](/api-reference/endpoint/order/create-contract). - On a store dated at shipment, a contract waiting for its shipment carries the `AWAITING_FULFILLMENT` hold, and one that should have dates but does not carries `COVERAGE_DATES_MISSING`. The [fulfillment endpoint](/api-reference/endpoint/order/fulfillment) dates a contract with `SET` and clears the dates with `REVERT`. --- # Why a contract is on hold Source: https://docs.surebright.com/contracts/holds > Find out why a plan you sold is not active, billed or confirmed to the customer yet, what you can do about it, and who clears it. A hold is the reason a plan (contract) cannot move forward yet. Use this page to find the hold, see what you can do about it, and know who clears it: the customer, you, or SureBright. Many holds clear by themselves once an expected event arrives, such as a shipment or a captured payment. ## What a hold stops A hold stops one or more of three things: - **Billing.** SureBright does not charge you for the plan until billing holds clear. - **Activation.** The plan stays not active until SureBright has finished setting it up. - **The customer's confirmation email.** The email waits while a detail that is printed on the plan is missing: customer and product details, the product category, or the coverage dates. Details the customer never sees, such as costs, margins and SKUs, never delay the email. ## Where you see a hold | Where | What you see | |---|---| | **Order Resolution** in the Merchant Portal | Anything that needs a decision from you: naming or associating a product, refunding a plan, or confirming which product a plan covers. See [Order Resolution](/merchant-portal/order-resolution). | | **Fulfillment** tab, on stores whose coverage starts at shipment | Plans waiting for a shipment count under **Pending fulfillment**. | | **Sales → Warranties pending**, on Lightspeed R Series stores | Plans that are not active yet, grouped as **No warranty created** or **Not activated**, each with what stopped it. | | The customer portal | Your customer sees the hold on their plan's card, for example **Address needed to activate warranty**, **Awaiting fulfillment** or **Setting up your protection**. See [Customer portal](/customer-portal/overview). | On Shopify, changes you make on the order itself, such as adding an email or address or capturing payment, reach the plan automatically. On WooCommerce, customer details you change on the order reach the plan too. On other platforms, ask your SureBright contact. ## Holds and what to do about them | What is holding the plan | What it means | What you do | Who clears it | |---|---|---|---| | Customer details missing | The customer's name, email, street address, city, state or ZIP is missing. A complete address is needed to issue the plan. | On Shopify and WooCommerce, add the details to the order; the plan picks them up. On any platform, the customer can add a missing address in the customer portal, and where the order shows in Order Resolution you can enter the detail in the case. For Shopify orders SureBright may also email the customer to ask. | The customer | | Order reference missing | The plan has no order reference. | Nothing. SureBright repairs it. | SureBright | | Product has no category | The product has no SureBright category, so the plan cannot be set up. | Nothing, unless SureBright asks you about the product. | SureBright | | Product has no coverage code | The product has no coverage code yet. | Nothing. | SureBright | | Product details missing | Model name, model number, manufacturer, condition, product ID or purchase price is missing, or the covered quantity could not be read. | Name the product in Order Resolution when the case asks **Which product did the customer buy?**, or complete the product in your catalogue. | You. A quantity that could not be read clears by itself. | | Store set-up incomplete | Your store's programme set-up with SureBright is not finished. | Ask your SureBright contact to complete your store set-up. | You, by asking SureBright | | Country not covered | The customer's country is not one where plans are sold (United States and Canada only), or it does not match the country the plan was priced for. Billing is held too. | This cannot be fixed. The plan is refunded through Order Resolution. | Nobody; the plan is refunded | | Sold below cost | The plan was sold for less than its cost. Billing is held. | Nothing. SureBright reviews the pricing. | SureBright | | Pricing detail missing | A pricing detail is missing, such as your margin, the plan's cost or price, or its price band. Billing is held. | Nothing. | SureBright | | Plan term missing | The plan's term in months is missing. | Nothing. | SureBright | | Plan not matched to its quote | The plan could not be tied back to the quote it was sold under. | Usually nothing; it clears when the quote is recovered. If the plan was sold outside the SureBright widget, answer the matching case in Order Resolution. | Clears by itself | | Waiting for shipment | Your store's coverage starts when the product ships, so activation and the confirmation email wait for the shipment. Billing is not held. | Ship the product. | Clears by itself when the order ships | | Waiting for payment | The order's payment has not been captured, so billing waits. | Capture the payment in your store admin. | Clears by itself when payment is captured | | Coverage dates missing | The start or end date is missing on a plan that should have them. The plan cannot become active until they are set. | Nothing. SureBright repairs the dates. | SureBright | | Currency mismatch | The plan was quoted in one country's currency but paid in another, for example a US quote paid in CAD through Shopify Markets. Billing is held until SureBright reconciles the amounts. | Nothing. | SureBright | ## Cases you see in Order Resolution Some problems are not a missing detail on an existing plan but a question nobody can answer automatically. These become **cases** in [Order Resolution](/merchant-portal/order-resolution). The first party to answer a case resolves it for everyone. Where the kind of case allows it, a case that nobody answers is resolved automatically after 48 hours. **I'll handle it** takes the order off that clock, and **or give me until** pushes the deadline out. | What the case says | What it means | What you can do | |---|---|---| | *We couldn't work out which product on this order this plan was sold against.* | No contract exists until the case is resolved. The reason is shown when known: the covered product was refunded or removed, more plan units were bought than products, the plan was priced for another country or province, the covered order was cancelled, or the plan details could not be found. | **Associate product** when the plan has nothing to attach to, refund the plan, or acknowledge the case without a change. When a correct product already exists (excess units, a region mismatch), only refund or acknowledge is offered. | | *More than one product on this order could be the one this plan covers.* | Several products fit the plan, so SureBright does not guess. | Pick the product the customer meant. The contract is created against it. | | *We couldn't work out what this shipping protection was covering.* | Shipping protection could not be matched to a shipment. | Refund it or acknowledge the case. | | **Missing required details** | The order is missing a detail the plan needs, for example the customer's email. | Enter the missing detail in the case. | | **Tracking details missing** or **Shipping carrier not recognized** | A shipping-protection shipment has no tracking number, or its carrier was not recognised. | Provide the tracking number or pick the carrier. | The quick filters in Order Resolution group cases as **Product refunded**, **Quantity mismatch**, **Region not covered**, **Product not identified**, **Missing details** and **Shipping**. ## Problems SureBright fixes for you These go to SureBright's team, not to you, but you may notice their effect on a plan. | Situation | What you may notice | |---|---| | No contract was created for a paid plan | SureBright repairs it. On Lightspeed R Series stores the sale shows under **No warranty created** with the reason **Warranty creation failed**. | | A plan was sold below its cost | Billing waits for SureBright's review. | | A plan was paid in a different currency from its quote | Billing is held until SureBright reconciles the amounts to the order currency. | | The plan documents are missing | The customer's confirmation email is still sent, without the plan documents attached. SureBright sends them to the customer separately. The plan itself is not held. | | The customer has no email address | The confirmation email cannot be sent, and the portal shows **No customer email**. The plan goes ahead if everything else is present. On Shopify, adding the email to the order sends the waiting email. On other platforms, ask your SureBright contact. | | A shipment is cancelled on a store whose coverage starts at shipment | The coverage dates are cleared and the plan goes back to waiting for shipment. The plan is **not** cancelled; shipping again dates it again. | ## How a hold clears Holds are checked again every time the plan's details change: the customer's details are updated on the order, a case is answered in Order Resolution, the order ships, or SureBright makes a repair. When the last missing detail is in place the plan becomes ready to bill, and it goes active once SureBright has finished setting it up and its start date is reached. See [Contract statuses](/contracts/lifecycle). A plan that is cancelled, expired or fully settled keeps its hold history for the record but no longer needs a fix. ## Related Answer the cases that are waiting on you. Whether a plan is active and whether it has been billed. API responses that return a contract's holds list them in `holdReasonList`, for example the [fulfillment endpoint](/api-reference/endpoint/order/fulfillment). | Value in `holdReasonList` | On this page | |---|---| | `ADDRESS_MISSING` | Customer details missing | | `INVOICE_MISSING` | Order reference missing | | `CATEGORY_MISSING` | Product has no category | | `PRODUCT_UNTAGGED` | Product has no coverage code | | `PRODUCT_DETAILS_MISSING` | Product details missing | | `STORE_MAPPING_MISSING` | Store set-up incomplete, or Country not covered | | `NEGATIVE_MARGIN` | Sold below cost | | `PRICE_MISMATCH` | Pricing detail missing | | `TENURE_UNKNOWN` | Plan term missing | | `QUOTE_MISSING` | Plan not matched to its quote | | `AWAITING_FULFILLMENT` | Waiting for shipment | | `AWAITING_PAYMENT` | Waiting for payment | | `COVERAGE_DATES_MISSING` | Coverage dates missing | | `CURRENCY_MISMATCH` | Currency mismatch | `PAYMENT_METHOD_MISSING`, `AMBIGUOUS_ASSOCIATION` and `CONTRACT_CREATION_FAILED` are also defined, but are not placed on contracts today. The matching problems are raised as cases instead. --- # Contract statuses Source: https://docs.surebright.com/contracts/lifecycle > How to tell whether a customer's plan is active and whether you have been billed for it, what each status means, and what moves a plan from one status to the next. Use this page to answer two questions about any plan (contract) you have sold: is the customer covered right now, and has SureBright billed you for it. The two are tracked separately, so a plan can be ready to bill before it is active, or be cancelled before it is ever billed. ## Where you see a plan's status | Where | What it shows | |---|---| | **Sales → Recent sales** in the Merchant Portal | The **Warranty status** column reads **Active** or **Cancelled**. The CSV from **Download** carries the same value in its **Warranty Status** column. See [Sales](/merchant-portal/sales). | | **Fulfillment** tab, on stores whose coverage starts at shipment | Per order, how many plans are **Fulfilled**, **Pending fulfillment** or **Cancelled**. See [Fulfillment](/merchant-portal/fulfillment). | | **Sales → Warranties pending**, on Lightspeed R Series stores | Plans that are not active yet, grouped as **No warranty created** or **Not activated**. | | **Order Resolution** | Orders where a plan is waiting for a decision from you. See [Order Resolution](/merchant-portal/order-resolution). | | The customer portal | What your customer sees on their plan, for example **Protected until** a date or **Setting up your protection**. See [Customer portal](/customer-portal/overview). | The sections below explain what sits behind those labels. ## Is the customer covered? | Status | What it means | What you do | |---|---|---| | Not active yet | The plan exists but cover has not begun. Something is still pending: billing, a hold, SureBright's set-up of the plan, or the start date has not arrived. | See [Why a contract is on hold](/contracts/holds). | | Active | The customer is covered. Payment has settled, SureBright has finished setting up the plan, and the coverage start date has been reached. | Nothing. | | Cancelled | The order was cancelled, the plan was refunded, or the plan was cancelled from the portal or a claim. This is final. | Nothing. | | Expired | The coverage term ended. This is final. | Nothing. | How a plan moves between them: - A plan becomes active once its payment has settled (charged to you, waived, or charged and later refunded), SureBright has finished setting it up, and its start date is today or earlier. - An active plan expires when its end date passes. - A plan can be cancelled from any status. - Once active, a plan stays active until it is cancelled or expires. A refund that settles later does not, by itself, undo the activation. - Nothing moves a plan out of cancelled or expired. - Test plans, which are never charged, read as active. A change that depends on the calendar (the start date arriving, the term ending) can take a short while to show, so a plan can still read as not active just after its start date. It catches up by itself. A plan that stays not active always has at least one hold explaining why. See [Why a contract is on hold](/contracts/holds). ## Have you been billed for the plan? | Billing status | What it means | |---|---| | Not ready to bill | SureBright cannot bill this plan yet. A detail needed to work out the charge is missing, or the plan is on a pricing hold: it was sold below cost, paid in a different currency from the one it was quoted in, or sold to a country that is not covered. | | Ready to bill | The plan will be billed. The amount you owe, the plan price minus your margin, is fixed at this point. | | Waiting for payment | Billing is waiting for the order's payment to be captured. | | Charged | SureBright has billed you for this plan. | | Waived | No charge: a test store or a test plan. | | Cancelled | The plan was cancelled before it was charged. Nothing is billed. | | Refunded | The plan was charged and later refunded. A refund on its own does not end an active plan. | How billing moves: - A plan becomes ready to bill when the missing details are in place and no pricing hold applies. This is checked again whenever the plan's details change. - Cancelling a plan that has not been charged means nothing is billed. - A charged plan reads as refunded only once the refund has actually gone through. Cancelling it is not enough. - Charged, waived, cancelled and refunded are final for billing. Later changes to the plan do not recalculate them. You cannot change a plan's billing status from the Merchant Portal. It moves only when SureBright's billing actually charges or refunds the plan. To see what an invoice charged you for, use [Invoice analysis](/merchant-portal/invoice-analysis). ## How a plan goes from sale to active The plan is created. It is not active yet, and billing starts as not ready or ready to bill. Once nothing is holding it, the plan moves from ready to bill to charged. When the start date is reached the plan becomes active. See [When coverage starts](/contracts/effective-dates). The plan expires when its term ends. It is cancelled instead if the order is cancelled, the plan is refunded, or it is cancelled from the portal. ## Related Every hold, who clears it, and what you can do. When a customer's cover starts and ends, by situation. API responses that return a contract's status use these values. | Value in `lifecycleState` | On this page | |---|---| | `CREATED` | Not active yet | | `ACTIVE` | Active | | `CANCELLED` | Cancelled | | `EXPIRED` | Expired | | Payment state | On this page | |---|---| | `PENDING_QUALIFICATION` | Not ready to bill | | `QUALIFIED` | Ready to bill | | `DEFERRED` | Waiting for payment | | `CHARGED` | Charged | | `WAIVED` | Waived | | `CANCELLED` | Cancelled | | `REFUNDED` | Refunded | The [fulfillment endpoint](/api-reference/endpoint/order/fulfillment) returns `lifecycleState` for the contracts it dates. **See also:** [What happens if an invoice is not paid](/merchant-portal/payment-questions#what-happens-if-we-do-not-pay-an-invoice), [Why plan length differs between your product page and the Merchant Portal](/merchant-portal/widget-options#why-the-length-differs-between-your-product-page-and-the-merchant-portal). --- # Plans bought in a later order Source: https://docs.surebright.com/contracts/plans-bought-later > When a customer buys protection in a separate, later order: how SureBright links the plan to the product they bought earlier, when you are asked to pick the product, and where you see these plans. A customer who skipped protection at checkout can come back and buy it later, through a [post-purchase offer link](/post-purchase/offer-links), a [registration page](/shopify/product-registration) or a follow-up campaign. That later purchase is an order of its own, with a plan in it and no product to cover. SureBright finds the product on the customer's earlier order and links the plan to it, so the plan covers what the customer actually bought. You may see this called **cross-order association**. It happens by itself on Shopify stores. There is nothing to set up. | You want to know | Go to | |---|---| | How SureBright finds the right product | [How the plan is matched to the product](#how-the-plan-is-matched-to-the-product) | | What to do when SureBright asks you | [When you need to pick the product](#when-you-need-to-pick-the-product) | | When the customer's coverage starts | [When coverage starts](#when-coverage-starts) | | What the customer is told | [What the customer receives](#what-the-customer-receives) | | Where to find these sales | [Where to see these plans](#where-to-see-these-plans) | ## How the plan is matched to the product When an order arrives with a plan and nothing in it the plan could cover, SureBright looks through that customer's recent orders on your store for the product the plan was bought for, and links the two. - **Only the customer's own recent orders are searched.** That means orders with the same customer email, up to their ten most recent, with cancelled orders left out. - **Products that already have protection are passed over.** A product that is fully protected, or that carries a different plan, is not matched again. - **Quantities are respected.** A plan for two units covers two units. If the earlier order listed the same product on several lines, the plan is spread across them with one contract per line. - **Units that cannot be placed are not linked.** They are raised for you to decide; see [When you need to pick the product](#when-you-need-to-pick-the-product). ### Example: a plan bought two weeks later A customer orders two speakers in order 1001 and declines protection at checkout. Two weeks later they follow an offer link and buy a 3-year plan for two units. That is order 1042, containing only the plan. SureBright finds the two unprotected speakers in order 1001 and links the plan to them. Two contracts are created, one per speaker, dated from the 1001 purchase. The customer gets one plan confirmation email listing both contract numbers. In the Merchant Portal the plan shows under order 1042 as **Post Purchase**, and Order Resolution reads it as **Covers a product on another order**. ## When you need to pick the product Most later plans are linked without you. When SureBright cannot be sure, the order appears in [Order Resolution](/merchant-portal/order-resolution), which is available on request. | What happened | What you see | What to do | |---|---|---| | More than one product in the customer's recent orders fits the plan | **More than one product on this order could be the one this plan covers** | Pick the one the customer meant | | No product in the customer's recent orders fits | The order is listed under **Unassociated warranties** | Use **Associate product** to name the product, from the order or from your catalogue, or refund the plan | | The earlier product is later refunded or removed | The plan loses its product and returns as an unassociated warranty with the reason *Covered product was refunded* or *removed* | Answer it. If nobody answers within 48 hours, SureBright refunds the plan | Other reasons a plan can wait on you are described on [Why a contract is on hold](/contracts/holds). ## When coverage starts Coverage is counted from the **product's** purchase, not from the day the plan was bought, so the manufacturer's warranty is measured from when the customer actually got the product. On stores whose coverage starts at shipment, it is counted from the earlier product's shipment date. A plan bought before the product ships waits for the shipment like any other. The exact rules are on [When coverage starts](/contracts/effective-dates#plans-bought-after-the-product-post-purchase). ## What the customer receives The customer receives the ordinary [plan confirmation email](/customer-emails/purchase-confirmation) once the plan is complete, naming the covered product from their earlier order and the coverage dates. If the product's details are still missing, the confirmation waits as it would for any plan. ## Where to see these plans | Screen | What you see | |---|---| | **Sales → Recent sales** | The contract is listed under the plan's own order. The **Platform** filter offers **Post Purchase** and **Registration Post Purchase** to show only these sales | | **Order Resolution** | On the plan's order, the plan line reads **Covers a product on another order**. A plan that could not be linked reads *Nothing recorded yet* until you resolve it | | **Warranty Intelligence** | The **When people buy** tab counts these plans in the post-checkout buckets, and the **Bought at checkout** tile shows how many days late buyers typically take. See [Warranty Intelligence](/merchant-portal/warranty-intelligence) | ## What stays the same on the earlier order - Your earlier order is left exactly as it was. The product line keeps its price and its fulfillment. - A plan is never linked to another customer's order, or to a cancelled order. - A plan you link by hand in Order Resolution is not matched again later. Your answer stands. On platforms other than Shopify, a plan bought on its own covers the product it was offered for, and past orders are not searched. Ask your SureBright contact if your store needs cross-order linking on another platform. ## Related - [Post-purchase offer links](/post-purchase/offer-links) - [Order Resolution](/merchant-portal/order-resolution) - [When coverage starts](/contracts/effective-dates) --- # What can be covered Source: https://docs.surebright.com/contracts/what-can-be-covered > Which shoppers and products get a protection offer: countries, categories and plan lengths, the manufacturer warranty a product needs, used and refurbished stock, business buyers, price bands and the window for buying a plan after the product. This page tells you which products and shoppers are offered a SureBright plan, and what you can do when one is not. It covers the rules that apply to every store. The plans and prices for your own categories are shown in the Merchant Portal under [Products](/merchant-portal/products). ## A product shows no offer: what to do | What you see | Why | Do this | |---|---|---| | No offer on any product | The storefront widget is not switched on, or your store is still **In review** | On Shopify, check **Settings → Storefront setup**. See [Storefront setup](/shopify/storefront-setup). On other platforms, work through [Offer not showing?](/help/offer-not-showing) | | The product has no category | A product needs a SureBright category before protection can be offered | In **Products**, pick one from the **Product category** dropdown. This also turns protection on | | **Warranty status** is **Inactive** | Protection is switched off for this product | Set **Warranty status** to **Active** | | **Warranty status** is **Under Review** | SureBright is checking the category | Wait for the review to finish | | The **Mfr warranty** chip reads **Add** | Plans in this category depend on how long the manufacturer covers the product | Click the chip and set the length | | The product cannot be turned on | Its category is one SureBright does not support | Ask your SureBright contact whether coverage can be added | | The price is zero, or outside the range its category covers | No plan exists for that price | See [Price bands](#price-bands) | | The shopper is outside the United States and Canada | Plans are not sold there | Nothing to change | | A bundle shows no offer, its parts do | The parts fall into different categories | Custom handling is available to stores that meet a minimum order volume. See [Bundles](/shopify/bundles) | | The product has no manufacturer warranty, or only a short one | Plans are offered on products that come with a warranty | See [Products need a manufacturer or seller warranty](#products-need-a-manufacturer-or-seller-warranty) | | The product is used or refurbished | Whether these are covered is set per store | See [Used, refurbished and open-box products](#used-refurbished-and-open-box-products) | [Coverage Intelligence](/merchant-portal/coverage-intelligence), available on request, lists every product without an offer, the reason for each and the one action that clears it. In the POS portal, ask [Ray](/pos/ray-assistant) **Is this product eligible for a plan?** ## Countries where plans are sold Plans are sold to shoppers in the **United States** and **Canada** only. The shopper's country decides, not where your business is based. - You sell in a country once SureBright has set up plans for your categories there. **Warranty Prices** on a product, and the **Country** tabs in [Warranty Pricing](/merchant-portal/warranty-pricing), show **US** and **CA** when you have both. - In Canada, plan prices can differ by province. The POS portal asks for the **Province** on Canadian sales and updates the prices. - Shipping protection is offered to shoppers in the United States. - A shopper elsewhere sees no offer. If an order with a plan still arrives from an unsupported country, the plan is held and refunded through **Order Resolution**. See [Why a contract is on hold](/contracts/holds). For languages and currencies, read [Languages and regions](/platforms/languages-and-regions). If your Shopify store uses Shopify Markets, also read [Shopify Markets pricing](/shopify/markets). ## Which categories and plan lengths are covered Every offer starts from the product's SureBright category. SureBright categorises your catalogue for you, and you can correct a product from the **Product category** dropdown. There is no single list that applies to every store. The categories and plan lengths you can offer are the ones set up for your store: | You want to know | Where to look | | --- | --- | | Which categories your store can offer | The **Product category** dropdown in [Products](/merchant-portal/products). A category that is not in the list is not set up for your store | | Which plan lengths a product gets, and at what price | **View Pricing** on the product. There is one column per plan length, for example **1Y**, **2Y** and **3Y** | | Whether a category has both an accidental damage and a breakdown plan | **Warranty Pricing**, or the **-AD** and **-B** categories in **Sales**, on stores that sell both | | What a plan covers and does not cover | The **What's covered?** link in the offer on your product page, and the plan's terms linked from it | A product in a category SureBright does not support cannot be turned on. Accessories and spare parts are often not covered on their own. ### Ask for a category or plan length you do not have You can ask for coverage on a product type you sell that has no offer, or for a plan length your store does not have yet. SureBright reviews each request and tells you whether it can be offered and at what price. Email your SureBright contact, or [support@surebright.com](mailto:support@surebright.com), with: - links to two or three of the products; - their selling prices; - the manufacturer's warranty on them, and how long it lasts; - whether they are new, used or refurbished; - roughly how many you sell a month. ## Products need a manufacturer or seller warranty SureBright plans are offered on products that come with a warranty from the manufacturer, or, for used and refurbished stock, from you as the seller. Breakdown plans begin when that warranty ends, so the length matters. See [When coverage starts](/contracts/effective-dates#which-manufacturer-warranty-length-is-used). | The product | What it usually means | | --- | --- | | Has a manufacturer's warranty of a year or more | Plans can be offered as normal | | Has a short manufacturer's warranty, or none | It may not be eligible. Ask your SureBright contact about your products | | Has a lifetime manufacturer's warranty | A breakdown plan adds little. Ask your SureBright contact whether an accidental damage plan is available for it | | Was bought from an unauthorised seller and carries no manufacturer's warranty | The extended plan needs a valid manufacturer's warranty behind it. Do not sell a plan on it | | Is used or refurbished with your own store warranty | Your store warranty takes the place of the manufacturer's. See [Used, refurbished and open-box products](#used-refurbished-and-open-box-products) | If a product's page states a manufacturer's warranty that differs from what SureBright assumes, see [Correct a manufacturer warranty length](/contracts/effective-dates#correct-a-manufacturer-warranty-length). ## Products sold for business use A business can buy a plan for a product just like any other customer. Whether the plan covers the product when it is used commercially, for example in a gym, salon, clinic, lab, hotel or on a farm, depends on the category. Some categories have a separate plan for commercial use. If you sell to business buyers, or sell products made for commercial use, tell your SureBright contact before you offer plans on them. Say which products, and how your customers use them. ## Used, refurbished and open-box products SureBright records whether a product is new, used or refurbished, and the condition travels with the plan. | Where you sell | How the condition is set | |---|---| | POS portal | The **Condition** field on each catalogue product: **New**, **Used**, **Refurbished** or **Certified Refurbished**. The **Warranty eligibility** column then shows **Eligible** or **Not eligible** for the product as entered | | Online store | Read from your product listing when SureBright categorises the catalogue | What you can do: - Enter the true condition for every product, and do not leave it blank. - If your used or refurbished products show no offer, or **Not eligible**, ask your SureBright contact whether your programme includes them. Whether they are covered, and at what price, is set per store and category. - Open-box is not a condition you can pick in the POS catalogue. Ask your SureBright contact how to list open-box stock. - Used and refurbished products need a warranty from you as the seller. Ask your SureBright contact what length is needed for your products. Your store warranty then plays the part of the manufacturer's warranty: claims during it are yours to handle, and the SureBright plan follows it. See [Your own store warranty](/contracts/effective-dates#your-own-store-warranty-on-used-or-refurbished-stock). ### Keep plans off your used or refurbished stock | Situation | Do this | | --- | --- | | Online, a few products | In [Products](/merchant-portal/products), set **Warranty status** to **Inactive** on each one | | Online, many products, or all your refurbished stock | Tell your SureBright contact how your listings mark the condition, for example a condition field, tag or product type, so those products are excluded together, including new ones you add later | | Your used products show an offer, and new ones do not | The condition is being read wrongly from your listings. Send support two or three product links | | Plans were already sold on products that turn out to be ineligible | Write to support with the order numbers. SureBright decides what happens to each plan. Plans sold this way have been cancelled with a full refund to the customer | [Warranty Intelligence](/merchant-portal/warranty-intelligence) reports attach rate by condition, so you can see how plans sell on each. ## Price bands Plans are priced in **price bands**: ranges of product price within a category. A product's price picks its band, and the band sets the plan price for each term. - A product priced at zero gets no offer. - A product priced below the lowest band or above the highest band of its category gets no offer. - The lowest and highest prices covered differ by category and by store, so there is no single figure. To see your own, open the grid in [Warranty Pricing](/merchant-portal/warranty-pricing), where each row is a band, or **View Pricing** on a product for its plan prices. - In [Coverage Intelligence](/merchant-portal/coverage-intelligence), these products carry the reason **Price outside band** and the action **Extend price band**. Ask your SureBright contact to extend a band. On a Shopify store using Shopify Markets, the band is picked from the price the shopper sees in their market. ## Buying a plan after the product A shopper who skipped protection at checkout can still buy it for a limited time. | How the plan is bought | Works on | Window | |---|---|---| | [Post-purchase offer links](/post-purchase/offer-links) | Shopify | 30 days from the order date, unless SureBright has set a different window for your store | | [Product registration pages](/shopify/product-registration) | Shopify. On other platforms, ask your SureBright contact | 30 days from the product purchase date by default. Stores whose contracts are created on fulfilment use the delivery date, with a 37-day window | | [AI purchase connectors](/ai-agents/purchase-connectors) | See the linked page | 90 days from the product's purchase date, 30 days for accidental damage plans. The product must have a manufacturer warranty | After the window closes the offer is no longer shown. To change the window for your store, ask your SureBright contact. ### A customer is just outside the window | Situation | Do this | | --- | --- | | The purchase date on the order is wrong | In [Leads](/merchant-portal/leads), enter the **Corrected purchase date** on the item, or the **Product purchase date** on a manual order | | The product's category allows a longer window | In Leads, pick that category for the item and click **Check plans with this category** | | You want an exception for one order | Write to support with the order number, the product, the purchase date and why. SureBright decides case by case and has made one-off exceptions. If it agrees, record the sale with the [Shopify draft order extension](/draft-order-guide/shopify-draft-order) or Leads as you would any later sale | | A plan sold outside the window as an agreed exception later meets a claim | SureBright honours a plan it accepted. The customer files the claim as usual | Sell after-the-fact plans only through these tools. A plan typed into an order by hand is not checked against the window and cannot be set up. See [Phone, draft and later sales](/learn/phone-and-later-sales). ## Bundle products A bundle is offered a plan when its protectable components share one category. Components that cannot be protected are left out of the plan. See [Bundles](/shopify/bundles). ## Related Categories, protection on or off, manufacturer warranty and plan prices per product. Which products have no offer, why, and what unblocks each one. What happens when an order with a plan cannot be completed. How plans are offered and split on bundle products. Developers: the quote endpoints return a status for each case above. See the [Quote API](/api-reference/endpoint/quote/index). --- # Cancellation emails Source: https://docs.surebright.com/customer-emails/cancellation > The emails a customer receives when a protection plan or shipping protection is cancelled or refunded. When a plan is cancelled or refunded, SureBright tells the customer so they know they are no longer covered. ## Cancellation confirmation email **Subject:** `Surebright Extended Protection cancellation confirmation for `. When several plans are cancelled together the subject reads `... for protection plans`. Programmes with a differently branded confirmation use a matching subject. **When it is sent** - When the plan is cancelled or refunded, including cancellations SureBright carries out on your behalf. - One email per customer and store, even when several plans are cancelled at once. - Not sent for some automatic cancellations that the customer did not ask for, on some platforms. **What it contains:** the cancelled plan(s). ## Shipping protection cancellation email **Subject:** `Your SureBright shipping insurance has been cancelled` **When it is sent:** when shipping protection on an order is cancelled. **What it contains:** the order, the plan number and the cancellation date. ## Related - [Emails your customers receive](/customer-emails/overview) - [Plan lifecycle](/contracts/lifecycle) - [Refunds and credits](/learn/refunds-and-credits) --- # Fulfillment and shipping emails Source: https://docs.surebright.com/customer-emails/fulfillment > The emails tied to your order shipping: the order received email for stores whose coverage starts at shipment, and the shipping protection confirmation. Two emails depend on when your store ships the order. Which ones your customers get depends on how your store is set up and whether the order has shipping protection. | Email | Who gets it | |---|---| | [Order received](#order-received-email) | Customers of stores whose plan coverage starts when the order ships | | [Shipping protection confirmation](#shipping-protection-confirmation-email) | Customers whose order includes SureBright shipping protection | To see and update what SureBright knows about your shipments, see [Fulfillment](/merchant-portal/fulfillment). ## Order received email Sent only on stores where the plan is bought at checkout but coverage begins when the order ships (pre-order and made-to-order stores set up this way by SureBright). **Subject:** `Your SureBright Protection Plan for order #` **When it is sent** - Once per order, straight after the order is placed, when the customer's email is present and shipping is the only thing the plan confirmation is waiting for. - Not sent if the plan confirmation is also waiting for something else, for example a missing customer name. In that case the customer hears nothing until the plan is complete. - Not sent on stores whose coverage starts at purchase. Their plan confirmation already arrives at checkout. **What it contains** - A table of the plans purchased: plan description, covered product (or `Not assigned` when the product is not yet linked), coverage period, quantity and plan price. - The statement that coverage begins on the day your store ships the order, and that the plan confirmation with full details follows once it does. The customer is not asked to do anything. **When the order ships**, the customer receives the [plan confirmation](/customer-emails/purchase-confirmation) with the coverage dates counted from the shipment. ## Shipping protection confirmation email Sent for orders that include SureBright shipping protection. **Subject:** `SureBright shipping insurance details of your recent purchase` **When it is sent** - When your store marks the order as fulfilled with tracking from a carrier SureBright recognises. If the carrier is not recognised, shipping protection is not activated and no email is sent. Stores with auto-refund enabled have the shipping-protection line refunded instead. - The order needs the customer's email and name, the order number, a shipping or billing address and the covered line items. **What it contains** - The customer's details and the covered line items. - What is covered (lost, damaged, misrouted or stolen packages in transit) and what is not, with a link to the full shipping protection details. - The order number and a link to the customer portal to file a claim. ## Related - [Emails your customers receive](/customer-emails/overview) - [When coverage starts](/contracts/effective-dates) - [Shipping protection](/shipping-protection/overview) --- # Missing customer details Source: https://docs.surebright.com/customer-emails/missing-details > The emails that ask a customer to complete their details so a plan can be activated: the action needed email and the address request for in-store and phone sales. A plan cannot be activated until SureBright has the customer's name and address. When those are missing and only the customer can supply them, SureBright emails the customer and sends them to the customer portal to fill them in. Once they do, coverage starts and they receive the [plan confirmation](/customer-emails/purchase-confirmation). | Email | Sent when | |---|---| | [Action needed](#action-needed-email) | An order reaches SureBright without the customer's name, address or phone number | | [Address request](#address-request-email) | A sale recorded in the POS portal leaves the address for the customer to add | ## Action needed email This is rare for online stores, because checkout normally captures a complete address. **Subject:** `Action needed to activate your plan` (or `plans` when the order has several) **When it is sent** - Only for details the customer can fix in the customer portal: first name, last name, address line, city, state or province, ZIP or postal code, country and phone number. The customer is never asked about anything else. - One email per order. A missing detail is asked for once even when it affects several plans. - Sent again only when the list of missing items changes. - Not sent when the order has no customer email, or when the plan has been cancelled. **What it contains** - The plan(s) waiting to be activated, with your store name, order number and plan number. - The list of pending items, each marked "Needed to issue your contract and activate coverage." - A "Complete this in the customer portal" button. - What happens once it is done: coverage starts, and the customer receives the plan confirmation by email. ## Address request email Sent for in-store and phone sales recorded in the [POS portal](/pos/overview) when the seller leaves the address for the customer to add. **Subject:** `Action required: Update your address to activate your warranty` **When it is sent:** once the sale is recorded, if the address was left out at the time of sale. **What it contains** - One block per plan: product name, plan description, order number, purchase date and quantity. - An "Update Your Address" button that opens the customer portal directly on the customer's plan. - The note that once the address is submitted the warranty is activated and the plan confirmation with full details follows. ## If the customer does not respond The plan stays on hold until the details arrive. You can see it, and the reason, in the Merchant Portal. See [Why a contract is on hold](/contracts/holds). ## Related - [Emails your customers receive](/customer-emails/overview) - [Customer portal](/customer-portal/overview) - [Recording a sale](/pos/recording-a-sale) --- # Emails your customers receive Source: https://docs.surebright.com/customer-emails/overview > Every email SureBright sends your customers about a protection plan they bought, from purchase to shipment to cancellation: when each one goes out and what you can change. SureBright emails your customers directly about the plans they buy, so you do not need to send anything yourself. Use this section to answer "what did my customer receive, and when?" and to see what you can change. Every email comes from `support@surebright.com`, names your store by its display name (never a raw store domain), and tells the customer to reply to that address or call SureBright customer service with questions. Each email is sent at most once per order or per plan. Editing an order later never sends a duplicate. ## Every email and when it is sent | Stage | Email | When the customer gets it | Details | |---|---|---|---| | Purchase | **Plan confirmation** | As soon as SureBright has everything the plan needs: who the customer is, which product is covered and the coverage dates. For most online stores this is at checkout. It is the customer's proof of coverage. | [Purchase confirmation](/customer-emails/purchase-confirmation) | | Fulfillment | **Order received** | Only on stores whose coverage starts when the order ships. Sent at checkout, while the plan confirmation waits for the shipment. | [Fulfillment and shipping](/customer-emails/fulfillment#order-received-email) | | Fulfillment | **Shipping protection confirmation** | When an order with shipping protection ships with tracking from a carrier SureBright recognises. | [Fulfillment and shipping](/customer-emails/fulfillment#shipping-protection-confirmation-email) | | Missing details | **Action needed** | When a plan cannot be activated because the customer's name, address or phone number is missing from the order. | [Missing customer details](/customer-emails/missing-details#action-needed-email) | | Missing details | **Address request** | When an in-store or phone sale is recorded in the POS portal and the address is left for the customer to add. | [Missing customer details](/customer-emails/missing-details#address-request-email) | | Cancellation | **Cancellation confirmation** | When a plan is cancelled or refunded. Some automatic cancellations the customer did not ask for are not emailed. | [Cancellation](/customer-emails/cancellation) | | Cancellation | **Shipping protection cancellation** | When shipping protection on an order is cancelled. | [Cancellation](/customer-emails/cancellation#shipping-protection-cancellation-email) | These are the emails about a plan the customer already bought. Two other sets of emails are covered elsewhere: - Emails that offer protection to customers who did not buy it at checkout. See [Post-purchase offer emails](/post-purchase/offer-emails). - Emails sent during a claim. See [Claim communications](/claims/communications). ## What you can change SureBright runs these emails. You cannot edit them from your store or the Merchant Portal, but you can do the following. | You want to | Do this | |---|---| | Show the right store name | Keep your store name accurate in your store's own settings (on Shopify, the shop name). Every email uses it. | | Use your own branding or subject lines | Ask SureBright. Branded templates and subjects are set up per store. | | Change the plan description, or the manufacturer-warranty period shown in the coverage wording | Ask SureBright. | | Have a plan confirmation sent again | Ask SureBright support, naming the contract. | Everything else (timing, wording, which template applies) follows the plan sold and cannot be changed per order. ## Where the emails send your customers The emails point customers to the SureBright customer portal at `https://customer.surebright.com`. - **Sign in without a password.** The customer enters their email and receives a one-time code (`OTP Verification Code for logging in to Surebright`). They can instead ask for a sign-in link (`Sign in to SureBright`), which expires after 15 minutes and works once. Any email address can sign in. - **See their protection plans**, each with the covered product, coverage start and end dates, the contract number and a status such as "Protected until …", "Expired on …", "Cancelled", "Awaiting payment", "Awaiting fulfillment", "Action required", "Under review" or "Setting up your protection". - **Update their address** when a plan is waiting on it. This is where the Action needed and Address request emails lead. - **File a claim** on an eligible plan, and follow the status of a filed claim. - **Open the coverage document** attached to the plan. - **Shipping protection** plans and shipping claims appear alongside product protection. ## Related - [Why a contract is on hold](/contracts/holds) - [Customer portal](/customer-portal/overview) - [Helping a customer](/help/helping-a-customer) --- # Purchase confirmation Source: https://docs.surebright.com/customer-emails/purchase-confirmation > The plan confirmation email, the customer's proof of coverage: when it is sent, what it contains, what to check when it has not arrived, and where customers read the coverage terms. The plan confirmation is the main email a customer gets about their protection plan, and their proof of coverage. **Subject:** `SureBright warranty policy details of your recent purchase`. Some programmes use a differently branded confirmation with its own subject line. ## When it is sent - At checkout for most online stores, as soon as the plan is created with everything in place: the customer's name and email, the covered product and its price, and the coverage dates. - If something is missing at first, the email goes out by itself as soon as the gap is filled, for example when the order ships, when the customer adds their details, or when a missing product detail is resolved. - On stores whose coverage starts at shipment, the confirmation is held until the order ships. Those customers get the [Order received email](/customer-emails/fulfillment#order-received-email) at checkout instead. - Several units or plans on the same order line are confirmed in one email with one row per contract number. - In-store and phone sales recorded in the [POS portal](/pos/overview) get the same confirmation when the sale is recorded. If the coverage document is not available at that moment, no email is sent for that sale. - A plan bought in a later order, for a product the customer bought earlier, gets the same confirmation, naming the product from the earlier order. See [Plans bought in a later order](/contracts/plans-bought-later). ## What it contains - Customer name, address, phone number and email. - Plan number (the plan SKU), plan description (for example `Extended Warranty 36 Months` or `Extended Warranty + Accidental Damage`), customer account number, purchase date, coverage period, product name and product retail price, and the deductible when one applies. - A table of order and contract numbers, one row per contract. - The plan's coverage document, attached to the email. If it cannot be attached, the email carries a link to read it online and SureBright sends the document separately. - A link to the customer portal to file a claim. ### How the coverage period reads The wording follows the plan type. Breakdown plans that start after the manufacturer's warranty read, for example, `12 months manufacturer warranty + 36 months extended warranty`. Other plans read as a plain month count. Some stores have a custom description set up by SureBright. ## If your customer has not received it The confirmation goes to the email address on the order. Most missing confirmations trace back to that order: phone sales, in-store sales and orders created by hand are the usual cases, where the order was saved without the customer's email address. The email also comes from SureBright, not from your store, so customers sometimes miss it because they expect a message from you, or it lands in a spam folder. | Check | What it means | |---|---| | The order has no customer email, or a wrong one | Nothing can be sent. Add the correct address to the order, then ask SureBright support to send the confirmation. SureBright also follows up to capture the customer's contact. | | The customer's first or last name, the product name or the product price is missing | The confirmation waits until the detail is filled in. When it is something only the customer can supply, they get the [Action needed email](/customer-emails/missing-details#action-needed-email). | | Your store's coverage starts at shipment and the order has not shipped | The confirmation goes out when the order ships. | | The plan's coverage document is not ready yet | The confirmation waits and goes out as soon as the document is ready. SureBright handles this; there is nothing for you to do. | | The plan was cancelled | No confirmation is sent for a cancelled plan. | | None of the above, or the customer needs it again | Ask SureBright support to resend the confirmation, with the order number or contract. | **Get ahead of it.** Make the customer's email address a required field wherever your team creates orders by hand. Tell customers at the point of sale that their plan confirmation comes from SureBright. Until September 2026 every store's customers received a separate "purchase confirmation" at checkout. It was retired because for most stores the plan confirmation arrived first. An interim "your plan is confirmed, documents follow" email has also been retired. ## Where customers read the coverage terms Customers, and your team, can read exactly what a plan covers before and after buying. The coverage document is the customer's proof of what they bought. | Who, and when | Where to find the terms | |---|---| | A shopper on your online store, before buying | **What's covered?** on the protection offer opens the coverage popup, which lists what the plan covers and links to the plan's detailed terms. | | A shopper choosing shipping protection | The **view coverage** / **see complete coverage** link opens a popup with what is covered and a link to the full plan documents. See [Shipping protection](/shipping-protection/overview#coverage-popup). | | A customer at your counter (POS portal) | **What's covered** in the plan picker shows the coverage and a **See detailed T&C** link. **Order Documents** at the customer step opens the documents for the sale. Open either and use your browser's print option to hand the customer a copy. See [Recording a sale](/pos/recording-a-sale#give-the-customer-a-printed-copy-of-the-terms). | | A customer at a Shopify POS till | The plan screen has a button that opens the plan's documents. See [POS extension](/shopify/pos-extension). | | A customer after buying | The coverage document is attached to the plan confirmation, and stays on the plan in the [customer portal](/customer-portal/overview). The shipping protection confirmation links to the full shipping protection details. | ### Terms to share with a customer before they buy, or to put on your site Ask your SureBright contact, or email [support@surebright.com](mailto:support@surebright.com), naming the products or categories you sell. SureBright can send a coverage summary for them and the link to the shipping protection details. ### A customer asks whether something specific is covered The plan's coverage document is the answer, and it differs by plan and category. Point the customer to it. If you or the customer cannot tell from the document, email [support@surebright.com](mailto:support@surebright.com) with the product and the question. SureBright answers coverage questions; do not promise cover your team cannot confirm. ## Related - [Emails your customers receive](/customer-emails/overview) - [Why a contract is on hold](/contracts/holds) --- # Customer portal Source: https://docs.surebright.com/customer-portal/overview > What your shoppers can do at customer.surebright.com, so you can guide them: sign in without a password, check their plans and coverage dates, file a claim, and protect other products they own. The customer portal at **https://customer.surebright.com** is where a shopper who bought a SureBright plan through your store sees that plan, checks its coverage dates and files a claim. The link is in the confirmation email SureBright sends after the sale. There is nothing for you to set up. When a shopper asks where their warranty is, point them to the portal. Use this page to answer a shopper's questions: how to sign in, what a plan's status means, and how to file a claim. ## How a shopper signs in Sign-in is passwordless. There is no registration, no password and no "forgot password". The shopper enters the email address used on the order and submits it. Any address can sign in; the portal shows whatever plans belong to it. SureBright emails a code. The shopper types it in to sign in. **Sign in with a magic link** emails a link instead. The link expires after 15 minutes and works once. **Sign in with a one-time code instead** is offered on every step, and **Use a different email** goes back to the start. A shopper whose order used a different email address (a spouse's, a work address) must sign in with that address. Plans are listed by the email on the order. ### When the portal asks for an address An extended warranty cannot be activated without a full shipping address. When the shopper signs in and one of their plans is waiting on an address, the portal opens the address form straight away. The street address autocompletes as the shopper types, and they confirm apartment, city, state or province, ZIP or postal code and phone. The address must be in the country the plan was bought in, and only United States and Canada addresses are accepted. Once the address is saved, the plan moves on to activation. The shopper can open the same form later from the plan's card with **Update address**. ## Plans and what each status means The home page, **Protection plans**, greets the shopper by first name and lists every plan on one page, as cards. Each card is tagged **Extended warranty** or **Shipping protection**, and the filter chips **All**, **Extended warranty** and **Shipping** narrow the list. Plans that need the shopper to do something come first, then the rest by purchase date. The status line on a card tells the shopper where the plan stands. | Status on the card | What it means | |---|---| | **Protected until** a date | The plan is active; coverage ends on that date. | | **Protected · shipped** a date | Shipping protection on a shipped order. | | **Setting up your protection** | SureBright received the plan and is still processing it. | | **Awaiting payment** | The order has not been paid yet. | | **Awaiting fulfillment** | Coverage starts when the product ships. | | **Address needed to activate warranty** | The shopper must add an address, as described above. | | **Details needed to activate warranty** | The shopper must fill in specific missing details; **Resolve details** asks only for those fields. | | **Action required** | Something else is needed from the shopper. | | **Under review** | SureBright is checking the plan. | | **Claim in review** | A claim has been filed on this plan. | | **Expired on** a date | Coverage has ended. | | **Cancelled** | The plan was cancelled. | | **Coverage ended** | Shipping protection that is no longer active. | Clicking a card opens the plan details: a **Plan summary** with the product purchase date, the manufacturer warranty, **SureBright coverage starts** (or **started**) and **SureBright coverage ends** (or **ended**), the term, and the store the product was bought from; and a **References** section with the order number. The shopper can also open their plan documents from here. A plan that is not active yet shows **After activation** in place of dates it does not have. The portal has no self-serve cancellation or ownership transfer. A shopper who wants either should contact SureBright support or you; refunds you grant go through **Order Resolution** in the merchant portal. ## How a shopper files a claim On an active extended warranty the shopper clicks **File a claim**. If a claim is already open on the plan the form says so first and lets the shopper open it instead of filing another. | Field | Notes | |---|---| | **First name**, **Last name** | Pre-filled from the account. | | **Email** | Read-only; the claim is filed under the signed-in address. | | **Phone number** | Required. | | **Incident date** | Required; cannot be in the future. | | **Describe the issue** | Required; at least 50 characters. | | **Serial number** | Optional. | | **Photos or videos** | At least one file showing the problem, up to 10 files, 25 MB each. | If an upload fails, nothing is filed, and **Try again** resubmits the claim. When a claim cannot be accepted, the form shows the reason, for example that coverage has not started yet or has ended. See [Filing a claim](/claims/filing-a-claim) for what happens after submission. **Claims** in the top navigation lists every claim with its number, product, submission date and status: **Pending**, **In progress**, **Active**, **Approved**, **Completed**, **Declined**, **Rejected** or **Closed**. Clicking a claim shows its details and the next step when there is one. ## File a shipping protection claim Shoppers who hold shipping protection also see **Shipping Warranties** and **Shipping Claims** in the menu. A shipping claim is filed from the shipment's card in two steps: select the affected items, then give the reason (**Loss**, **Damage** or **Shortage**), the date the problem was discovered and a description. A shipment can have one claim at a time; a second attempt is pointed back to **Shipping Claims**. See [Shipping claims](/shipping-protection/claims) for the full flow and statuses. ## Protect other products from a receipt When a shopper uploads a receipt in the portal (for example to activate a plan bought on SureBright Anywhere), every other eligible product on that receipt is kept as an offer in **My List**. It shows those products with the retailer badge, how long ago they were bought, and how many days are left to protect them: 90 days from purchase for an extended warranty, 30 days for accidental damage. Each row has an inline term picker (typically 1, 2 and 3 years, the middle one marked **Popular**), **What's covered?**, and two actions: - **Purchase now** starts a checkout for that one product. - **+ Add to cart** collects several products into the **Cart**, which checks out as one order. Checkout is a SureBright-hosted payment page. The shopper returns to **Protection plans** with a payment-received message; the plan appears in the list once SureBright has created it. A cancelled checkout keeps the cart. A cart can only check out products bought in one country at a time, because one checkout is charged in one currency. Offers disappear from My List when the product is protected or its window closes. The cart icon only shows when the cart has something in it. ## Activate a plan bought elsewhere A plan bought on SureBright Anywhere, or through an AI assistant, is paid for before SureBright has the receipt. It shows on **Protection plans** as a card reading **Finish setup to activate your warranty** with the outstanding steps as chips (**Upload invoice**, **Verify contact**) and an **Activate** button. The shopper uploads the receipt (PDF, PNG, JPEG or WebP, up to 20 MB), confirms the purchase country when the receipt does not show one, and activates. If the receipt cannot be matched to what was bought, the portal explains why in plain terms and offers **Contact support**, which asks SureBright to finish the activation by hand. ## Get help or change account details **Help** has the FAQ and a contact form. SureBright customer support is support@surebright.com and +1 855-306-4874. **Account settings** (under the account menu) holds the shopper's name and phone number. **Sign out** ends the session on that device. ## Related Answers to the questions shoppers ask you most. How a shopper claims for a lost, damaged or short shipment. --- # Confirming which product a plan covers Source: https://docs.surebright.com/customer-portal/warranty-link > What to tell a shopper who receives a SureBright email asking which product their protection plan covers, what the confirmation page shows, and what happens after they confirm. Sometimes an order carries protection plans but nothing says which product each plan was bought for. SureBright then emails the shopper a link to a short confirmation page. The shopper picks the product for each plan and the plan is activated. You do not need to do anything. Use this page when a shopper asks what the email is, or says the link does not work. ## What the shopper sees on the confirmation page The page is titled **Confirm your protection plan** and shows your store name and, when there is a deadline, **Please confirm by** followed by the date. Below it is one card per plan on the order, headed **Protection plan** with the plan's reference. Each card asks **Which product does this plan cover?** and lists the products on the order with their price and quantity. - When SureBright can tell which product a plan most likely belongs to, that product is pre-selected and marked **recommended**, and the card carries a **suggested match** chip. - A product already chosen for another plan is greyed out as **already paired with another plan**. One plan covers one product. - **I'm not sure, I'll link this later** leaves a plan unlinked without blocking the others. **Confirm & activate** submits the choices. The page then reads **Your protection plan is confirmed**, says how many plans were activated and how many are left to link later, and tells the shopper a confirmation email is on its way. ## If the link does not work | The shopper sees | Why | What to tell them | |---|---|---| | **Activation link required** | The page was opened without the link from the email. | Open the page from the link in the email. A shopper is never asked to type a code or reference. | | **We couldn't open this activation** | The link is invalid, has expired, or the order has already been confirmed. | Open the most recent email, or reply to it to have the link re-sent. | Once the shopper has confirmed, the link no longer opens, even if they left some plans to link later. A shopper who wants to pair the remaining plans should contact SureBright support. ## Related Answers to the questions shoppers ask you most. Where you pick the product for a plan yourself. Two endpoints sit behind the page. Use them only if you are building your own confirmation page for shoppers; otherwise the SureBright page handles everything. Every request carries the `order_key` and `customer_key` from the emailed link, which are specific to one order and one customer. Replace `{HOST_NAME}` with the API host SureBright gives you. **Read the order** ``` GET https://{HOST_NAME}/site-platform/api/warranty-link/order?order_key=...&customer_key=... ``` The order identifier from the emailed link. The customer identifier from the emailed link. Your store name, shown as the page heading. SureBright's order identifier. One of the statuses below. When the link stops working, if a deadline is set. The products on the order: `lineKey`, `title`, `imageUrl`, `price`, `quantity`. The plans on the order: `lineKey`, `policySKU`, `title`, `price`, and `linkedProductOrderLineKey` when already linked. SureBright's suggested pairing: `warrantyLineKey`, `productLineKey`, `confidence` (`high`, `medium` or `low`) and `reasons`. Plans SureBright could not suggest a product for. **Submit the pairing** ```bash curl -X POST "https://{HOST_NAME}/site-platform/api/warranty-link/submit" \ -H "Content-Type: application/json" \ -d '{ "order_key": "ORDER_KEY", "customer_key": "CUSTOMER_KEY", "links": [ { "warrantyLineKey": "w-1", "productLineKey": "p-2" } ] }' ``` From the emailed link. From the emailed link. One entry per plan the shopper paired, each with `warrantyLineKey` and `productLineKey`. At least one entry. Every key must belong to this order, a plan may appear once, and a product may appear once. `LINKED` when every plan was paired, `PARTIALLY_LINKED` when some were left for later. Plans paired in this submission. Plans still waiting for a product. **Order statuses** | `orderStatus` | Meaning | |---|---| | `AWAITING_CUSTOMER_LINK` | SureBright has the order and is about to email the shopper. | | `LINK_EMAILED` | The email was sent; the page can be opened and submitted. | | `PARTIALLY_LINKED` | The shopper paired some plans and left others for later. The link no longer opens. | | `LINKED` | Every plan is paired. The link no longer opens. | **Errors** Both endpoints answer with the HTTP status and a JSON body carrying `isError: true` and a `message`. | Status | When | |---|---| | `400` | A key is missing, or `links` is empty or names a key that is not on the order, or pairs a plan or product twice. | | `403` | `customer_key` does not match the order. | | `404` | No order for `order_key`. | | `409` | The order is already `LINKED` or `PARTIALLY_LINKED`; the body includes `orderStatus`. | | `410` | The link has expired. | --- # Over the Phone Sales using Draft Order Extension Source: https://docs.surebright.com/draft-order-guide/shopify-draft-order > Sell a protection plan over the phone from Shopify draft orders: with the product, for a product the customer already bought from you, or for one bought elsewhere. Use the SureBright Draft Order extension to sell a protection plan from inside Shopify's own draft orders, for example when a customer orders by phone or wants a plan for something they already own. You add the plan to the order in Shopify admin and take payment there as you would for any draft order. ## Pick your situation | The customer | Go to | | --- | --- | | Is buying the product and the plan together | [Sell a product and a plan in one draft order](#sell-a-product-and-a-plan-in-one-draft-order) | | Already bought the product on your Shopify store | [Sell a plan for a product bought on your Shopify store](#sell-a-plan-for-a-product-bought-on-your-shopify-store) | | Bought the product somewhere else, and you list it on your Shopify store | [Sell a plan for a product bought elsewhere that you list](#sell-a-plan-for-a-product-bought-elsewhere-that-you-list) | | Bought the product somewhere else, and you do not list it on your Shopify store | [Sell a plan for a product you do not list yet](#sell-a-plan-for-a-product-you-do-not-list-yet) | ## Before you start ### Open the SureBright draft order extension **Note:** The SureBright Draft Order extension for Shopify requires permission to create draft orders. Follow these steps to open the SureBright Draft Order extension for the first time: 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 does 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, Shopify shows a screen asking you to grant the extension its permissions. Approve it. 6. The SureBright popup then opens and you can begin adding warranty plans to your line items. ### Use the Add warranty card instead Besides the **More actions** dropdown, the SureBright app adds a card to the page itself, on both **order** pages and **draft order** pages. The card reads **Protect your customer's purchase with a warranty plan.** and has a single **Add warranty** button. Clicking **Add warranty** opens the same SureBright popup as **More actions → SureBright - Product Protection Draft Order**, so every use case below works the same way whichever entry point you start from. Use whichever you find faster; the card is handy because it stays visible while you scroll the order. The card and the **More actions** item belong to the same SureBright extension, so the one-time Shopify permission screen described above applies whichever one you use first. ## Sell a product and a plan in one draft order You can create a draft order that sells both a product and its warranty plan in a single transaction. - In your Shopify admin, go to Orders \> Drafts \> Create Order. ![Draft Order1 Pn](/images/draft_order1.png) - Search for the product by clicking “Browse” button and add it to the draft order. ![Draft Order3 Pn](/images/draft_order3.png) - Click Save on the top. ![Draft Order4 Pn](/images/draft_order4.png) - 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) - 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. ## Sell a plan for a product bought on your Shopify store If a customer previously purchased a product from your Shopify store and now wants to buy a warranty: - Open the order that contains the product the customer wants to cover. - 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) - 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) - Set the payment terms or send an invoice. ## Sell a plan for a product bought elsewhere that you list 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. - In your Shopify admin, go to Orders \> Drafts \> Create Order. ![Draft Order1 Pn](/images/draft_order1.png) - 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) - Click Save on the top. ![Draft Order4 Pn](/images/draft_order4.png) - 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 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) - 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) - 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) - 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.) - 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 ## Sell a plan for a product you do not list yet In cases where the product is not listed on your Shopify store, but a customer wants to buy a warranty for it: - If the product SKU selected is not present in your Shopify store, then add it in your Shopify store. After adding the SKU, allow a few hours for the product to be categorised. Only then do the policy options appear. For immediate assistance, feel free to contact us at [support@surebright.com](mailto:support@surebright.com). - Navigate to Orders \> Drafts \> Create Order ![Draft Order1 Pn](/images/draft_order1.png) - 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. - Click Save on the top. ![Draft Order4 Pn](/images/draft_order4.png) - 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 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) - 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) - The warranty options dropdown shows **"No Extended Warranty Options Available"**. ![No Warranty Options Available](/images/draft-order-popup-no-options.png) - 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) - 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) - 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) - 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.) - Set the payment terms or send an invoice. Finalize and fulfill the order once the warranty payment is processed. ## Selling through other channels If you also sell through other channels, tell us and we will help you set up each one: - **E-commerce platform apps**: Shopify, WooCommerce, BigCommerce, Shift4Shop. - **Brick and mortar stores and over the phone sales**: Shopify POS, Lightspeed POS, the dedicated POS portal. - **Missed point of sale and marketplace sales**: a dedicated online portal, QR code-based warranty cross-selling, 1-click checkout web links for your post-purchase campaigns, follow-up email campaigns. - **Independent websites**: integration through two simple APIs, or the website widget. ## Related Every way to sell a plan outside your storefront checkout. Add a plan to a past order from the Merchant Portal instead. The card is an admin block extension rendered at `admin.order-details.block.render` (handle `sb-policy-draft-order-create`) and `admin.draft-order-details.block.render` (handle `sb-policy-draft-order-update`). It contains no policy logic: its **Add warranty** button calls `shopify.navigation.navigate("extension://sb-draft-order-action-create")` on order pages and `extension://sb-draft-order-action-update` on draft-order pages, handing off to the action extension (`admin.order-details.action.render` / `admin.draft-order-details.action.render`) that owns the popup. All three extensions share the merchant-facing name **SureBright - Product Protection Draft Order**. --- # Acumatica warranty SKUs Source: https://docs.surebright.com/erp/acumatica-warranty-skus > Add the SureBright warranty catalog to Acumatica Cloud ERP as non-stock items from the plan SKU CSV in the Merchant Portal, then let your existing Acumatica to Shopify connector publish them. Use this page when you run Acumatica Cloud ERP and sell SureBright plans through a Shopify store connected to it. You download the warranty products and their prices from the Merchant Portal as a CSV (see [Download your plan SKUs](/erp/download-plan-skus)), or SureBright sends you a ready-to-import sheet. You load that file into Acumatica once. From then on the warranty SKUs live in your catalog and publish to Shopify like any other product, and online warranty sales flow back into Acumatica automatically. This procedure was validated against **Acumatica Cloud ERP 2026 R1** (build 26.100.0175). Screen IDs are stable across versions and can be typed into the search box; field labels and layouts vary slightly. ## Who does what | Step | Who | What happens | |---|---|---| | 1. Gets the SKU CSV | You, or SureBright | **Products > Download plan SKUs** in the Merchant Portal, then add an `ItemClass` column holding your class ID on every row. Or ask SureBright for the ready-to-import sheet, which already has it. | | 2. Prepares the instance | You, once | Raise the inventory ID length, then create the item class `SB-PRODUCT`. | | 3. Imports the CSV | You | The SKUs become non-stock items in Acumatica. | | 4. Publishes to Shopify | Automatic | Through your existing Acumatica commerce connector. | Everything you add is standard: non-stock items and one item class, created with Acumatica's built-in import tools. No existing configuration, workflow, chart of accounts or data is changed, and any SKU can be deactivated at any time. The one exception is the segmented key length in the first action, which is tenant-wide; route that change through whoever owns your Acumatica configuration. ## Agree two values with SureBright first | Value | Default | Why it matters | |---|---|---| | **Item class name** | `SB-PRODUCT` | It is the value in the CSV's `ItemClass` column, and it must match the class you create character for character, including the hyphen. If your organisation requires a different name, agree it before the sheet is issued rather than editing the file. | | **Inventory ID (SKU) format** | `SBW-1U-CEAD-49999` | `SBW` (SureBright Warranty), term and region (`1U` = 1 year, USA), coverage code (`CEAD` = Consumer Electronics, Accidental Damage), and the upper price of the band in cents with no decimal. 17 characters. The same SKU must appear in Acumatica, in Shopify and on the warranty line of each online order, or online sales will not reconcile. A shorter convention is possible; tell SureBright and the sheet is adjusted. | By default the sheet comes in the minimal format (`InventoryID`, `Description`, `ItemClass`, `BasePrice`) and relies on the item class for everything else. A full-details sheet with every Acumatica field spelled out is available on request once you have confirmed UOM, tax, posting class and GL codes with SureBright. ```csv InventoryID,Description,ItemClass,BasePrice SBW-1U-CEAD-04999,"CE Accidental Damage · 1yr · ≤ $49.99",SB-PRODUCT,4.99 SBW-1U-CEAD-09999,"CE Accidental Damage · 1yr · $50–$99.99",SB-PRODUCT,8.99 SBW-1U-CEAD-24999,"CE Accidental Damage · 1yr · $100–$249.99",SB-PRODUCT,14.99 SBW-1U-CEAD-49999,"CE Accidental Damage · 1yr · $250–$499.99",SB-PRODUCT,24.99 ``` The descriptions contain characters that US-ASCII cannot represent, so the data provider's encoding must be set to UTF-8 (see Action 2). ## Set up Acumatica in three actions Do them in this order. The first two are hard dependencies of the third. ### Action 0: raise the segmented key length (CS202000) Acumatica builds inventory IDs from a segmented key named `INVENTORY`, which ships with a length of **10** characters. A warranty SKU is 17. Acumatica does not reject the longer value; it **truncates it silently** and the import still reports success. Distinct SKUs collapse onto a handful of surviving codes, each overwritten by the next row that truncates to the same string. This is the only failure in the procedure that raises no error, and re-importing afterwards does not repair the damaged records. If an import has already run under the old limit, remove or deactivate the truncated items before re-running. In **Segmented Key ID** select `INVENTORY`. In the segment grid change **Length** from `10` to `20`. Leave **Validate**, **Align** and **Editable** alone; `30` is the maximum Acumatica allows. The length is a maximum, not a fixed width: shorter codes are stored exactly as entered. Acumatica caches the key definition per session. Until you sign in again the field keeps truncating at 10 characters without notice. Open **IN202000** and type a full 17-character SKU into **Inventory ID**. If the whole string stays in the field the change is active; if it stops accepting characters part-way, sign out and in again. Raising the length is additive and leaves existing items untouched. Lowering it later is not safe: it can orphan codes that no longer fit. ### Action 1: create the warranty item class (IN201000) The class sets item type, unit, GL accounts and tax once, so every warranty SKU inherits them. Create it before importing or every row fails with no accounting treatment. Two prerequisites on a new tenant: a **tax category** must exist (**TX205500**), because Acumatica will not save any non-stock item without one and a new tenant has none; and TX205500 itself needs company and branch setup (**CS101500** / **CS102000**) to open. | Field (IN201000) | Set to | Notes | |---|---|---| | **Class ID** | `SB-PRODUCT` | Must match the CSV's `ItemClass` value exactly. | | **Description** | `SureBright Product Protection` | Free text. | | **Item Type** | `Non-Stock Item` | A warranty has no inventory to track. | | **Stock Item** | cleared | | | **Base / Sales / Purchase Unit** | `EA` | Verify the unit exists in your Units of Measure list; the field accepting input is not confirmation. | | **Require Shipment**, **Require Receipt** | cleared | Nothing to pick, pack or receive. | | **Kit** | `No` | | | **Export to External Application** (eCommerce) | enabled | Puts every imported SKU into the Shopify sync. Makes **Description** mandatory on each item; SureBright's sheet carries one for every row. Labelled **Export to External System** in some builds. | | **Posting Class** | your choice, for example `NONSTOCK` | Set with your accountant. | | **Sales / Income Account** | your choice, for example a dedicated `Warranty Income` account | Keeps warranty revenue separately reportable. | | **Deferral Code** | your choice, usually `None` | | | **Accrue Cost**, **Expense / COGS Account** | your choice, usually off | Only needed if you book a per-sale payable at point of sale. | | **Tax Category** | your choice, must exist | The category your tax configuration applies to service and warranty lines. | Create a dedicated class rather than reusing an existing one: an existing class may carry a different base unit, which then propagates silently to every warranty SKU. ### If these instructions do not match your system Your Acumatica may already have its own item-class scheme, a naming rule for classes, or a class name in an older SureBright sheet that differs from the one here (for example `SB_PRODUCT_PROTECTION`). You do not have to follow the default name. | Your situation | What to do | |---|---| | Your organisation names item classes its own way | Create the warranty class under your name, with the settings in the table above. Tell SureBright the exact Class ID, and the sheet is reissued with that value in the `ItemClass` column. | | You want to use a non-stock class you already have | Check it against every row of the table above, especially **Item Type**, **Base / Sales / Purchase Unit**, **Require Shipment** and **Export to External Application**. If they all match, tell SureBright its Class ID. If any differ, create a dedicated class instead. | | Your sheet names a class that does not exist in your system | Do not edit the file. Ask SureBright to reissue the sheet with the class you created. | | A screen or field in this guide looks different in your build | Send SureBright the screen ID, a screenshot and your Acumatica version. | Whatever the class is called, the `ItemClass` value in the sheet must match its Class ID character for character. ### Action 2: import the CSV Enter a **Name** (for example `Warranty SKU Import`) and set **Provider Type** to **CSV Provider**, then **Save**. Only after saving does the **FILES** link in the top-right corner become available: use it to upload the CSV; the `FileName` parameter fills in on its own. On the **PARAMETERS** tab change **Encoding** from `US-ASCII` to **Unicode (UTF-8)** and save again. On the **SCHEMA** tab click **Fill Schema Fields** in the **Source Fields** panel; the four columns appear, all typed `String`. Change `BasePrice` to **Decimal** (re-running Fill Schema Fields resets it). Tick **Active** on the source object in the **Source Objects** panel; it is clear by default and the import scenario will not list the object until it is ticked. Save. Set **Screen Name** to **Non-Stock Items** (IN202000), **Data Provider** to the one you created, and **Provider Object** to your CSV object. If Provider Object is empty and outlined red, go back and tick **Active** on the schema tab. Toggle **Show All Commands** to see the service rows Acumatica writes for you; they cannot be deleted. Pick each target from the magnifier lookup rather than typing it; typed text sets only half the value and Save fails with *'Target Object' cannot be empty*. Type the plain column name (`InventoryID`), not the `=[InventoryID]` formula form. | Field on IN202000 | Target | Source field | |---|---|---| | Inventory ID | `Item.InventoryCD` | `InventoryID` | | Item Class | `ItemSettings.ItemClassID` | `ItemClass` | | Default Price | `ItemCurySettings.BasePrice` | `BasePrice` | | Description | `Item.Descr` | `Description` | To confirm a target, open the form with **View Screen**, hold **Ctrl + Alt** and click the field; the **Element Properties** dialog shows the data view and field name. The object names `ItemSummary` and `PriceGL` found in some older notes do not exist. Add `` as the last row with **Execute Action** set to **Once, for Last Detail**. Without it every row stages and nothing commits; the run fails with *12 items have not been processed successfully. View name: Item.* and the history shows *Processed: 0 records*. Select the scenario, tick **Discard Previous Result**, click **Prepare** and scan for red error rows, then click **Process**. Tick **Discard Previous Result** on every re-run or Prepare reuses the previously staged rows. ## Verify the import (IN202000) Open **Non-Stock Items** and search the prefix `SBW`. Each item should show the correct item class, price and **Active** status, and the Inventory ID should carry all 17 characters. Then count: the number of records must equal the number of rows in the sheet. *Processing completed successfully* is also what a truncated import reports, so the record count is the only reliable check. Three records where there should be twelve, with IDs like `SBW-1U-CEA`, means Action 0 was skipped: complete it, remove the affected items and re-import. ## Check the SKUs publish to Shopify Publishing is automatic through your existing Acumatica commerce connector; there is nothing to set up or schedule. Because the item class enables **Export to External Application**, every imported SKU is already in the sync. Confirm two things once: | Where | Setting | Expected | |---|---|---| | Item, **eCommerce** tab (IN202000) | Export to External Application / Availability / Visibility | Enabled / Available / **Invisible (Unlisted)**. Warranties must not be browsable: shoppers add them through the SureBright offer, not from your catalog pages. | | Your connector | Non-stock items in sync scope; SKU mapping | Included; Inventory ID maps to the Shopify SKU. | After the first sync, open one warranty product in Shopify and compare its SKU to the Inventory ID character by character. A product published as `SBW-1U-CEA` instead of `SBW-1U-CEAD-04999` will never reconcile, and fixing it later means unpicking records on both platforms. ## Troubleshooting | Symptom | Cause and fix | |---|---| | Import reports success but far fewer items than rows; codes cut short | `INVENTORY` key still 10 characters. Raise to 20, sign out and in, remove the affected items, re-import. | | *12 items have not been processed successfully. View name: Item.* | No `` row. Add it as the last row, Once for Last Detail. | | *Can't write CLR type System.String with handler type NumericHandler* | `BasePrice` still typed String on the data provider. Set Decimal and save. | | *'Tax Category' cannot be empty* | No tax category exists. Create one at TX205500. | | *The required configuration data is not entered on the Branch form* | Finish CS101500 and CS102000 before opening Tax Categories. | | `File '' is not found` | The provider was not saved before upload. Save, then upload through FILES. | | Provider Object empty and outlined red | Source object not **Active** on the SCHEMA tab. | | Descriptions show mangled characters | Encoding left at US-ASCII. Set UTF-8 and re-prepare. | | Items import but carry no accounting treatment | `ItemClass` in the CSV does not match the class ID exactly. | | Item will not save, Description required | Export to External Application makes Description mandatory; every row needs one. | If an issue persists, send SureBright the screen ID, the exact error text and the record count from IN202000. ## Related - [Shopify admin housekeeping](/shopify/admin-housekeeping): Shopify settings that keep plan products working. - [Storefront setup](/shopify/storefront-setup): turn the SureBright offer on in your Shopify theme. --- # Download your plan SKUs Source: https://docs.surebright.com/erp/download-plan-skus > Download the SureBright plan SKUs for your store from the Merchant Portal as a CSV, ready to load into your ERP, 3PL or accounting tool. Every SureBright plan you sell is a product in your store catalogue, with one SKU per plan length, region, coverage type and price band. Your ERP, 3PL or accounting tool needs those SKUs so that plan lines on your orders match an item and plan revenue is reported on its own. You can download them yourself from the Merchant Portal at any time. ## Download the CSV Sign in to the [Merchant Portal](/merchant-portal/onboarding) and open **Products**. The button is in the row with the search box and **Filters**. Your browser saves a file named like `SureBright-Plan-SKUs--.csv`. Follow the guide for your ERP below, or import the file into your 3PL or accounting tool as non-stock, non-shipping items. Download again whenever your plans change, for example after new price bands are added, and import the new rows. ## What is in the file One row per plan SKU, UTF-8, with a header row. | Column | What it holds | |---|---| | `InventoryID` | The plan SKU, for example `SBW-1U-CEAD-49999`. This is the value your ERP item number must match exactly. | | `Description` | A readable name for the plan, with its term and coverage, for example `SureBright Protection Plan - 1 Year - Accidental Damage`. | | `BasePrice` | The plan's current price. When several prices use the same SKU, this is the most recent one. | | `Currency` | The currency of the prices. | | `TermYears` | The plan length in years. | | `CoverageType` | The kind of cover the plan gives. | | `Region` | The country or region the plan is sold in. | | `AllPrices` | Every live price that uses this SKU, when there is more than one. | The ERP guides only map the first three columns. Leave the others unmapped, or use them for reporting. ## If something looks wrong | What you see | What to do | |---|---| | A message that you have no plan SKUs yet | Your plan products have not been set up in your store yet. Finish onboarding, or ask your SureBright contact. | | A message that some older plans were left out | A few plans created before the current SKU format have no SKU in the file. Ask your SureBright contact for those rows. | | You do not see **Download plan SKUs** | Ask your SureBright contact to send you the SKU sheet instead. It has the same columns. | ## Guides for your ERP - [Acumatica warranty SKUs](/erp/acumatica-warranty-skus) - [NetSuite warranty SKUs](/erp/netsuite-warranty-skus) - [Dynamics 365 Business Central warranty SKUs](/erp/dynamics-365-warranty-skus) - [SAP Business One warranty SKUs](/erp/sap-business-one-warranty-skus) - [Odoo warranty SKUs](/erp/odoo-warranty-skus) On another ERP, 3PL or accounting tool, see [Plan SKUs for your ERP or 3PL](/learn/plans-in-your-order-tools#plan-skus-for-your-erp-or-3pl). --- # Dynamics 365 Business Central warranty SKUs Source: https://docs.surebright.com/erp/dynamics-365-warranty-skus > Add the SureBright warranty SKUs to Microsoft Dynamics 365 Business Central as non-inventory items from the plan SKU CSV you download from the Merchant Portal, so plan sales from your store reconcile in Business Central. Use this page when you run Microsoft Dynamics 365 Business Central and sell SureBright plans through an online store or point of sale that syncs orders into it. You download the warranty SKUs and their prices from the Merchant Portal as a CSV (see [Download your plan SKUs](/erp/download-plan-skus)). You load it into Business Central once. From then on every plan line on an order that reaches Business Central matches an item you already have. Page names below are from current Business Central releases. Use the search (the magnifier, or **Alt+Q**) to find a page by name. If a page does not match, send SureBright a screenshot. ## Who does what | Step | Who | What happens | |---|---|---| | 1. Downloads the SKU CSV | You | **Products > Download plan SKUs** in the Merchant Portal. One row per SKU, UTF-8. | | 2. Agrees the accounting | You, once | Pick the posting group and tax group plan sales use. | | 3. Imports the sheet | You | The SKUs become non-inventory items in Business Central. | | 4. Matches orders | Your order connector | Plan lines on incoming orders map to these items by SKU. | Everything you add is standard: non-inventory items, created with Business Central's own Excel tools. No existing item, setup or posting configuration is changed, and any SKU can be blocked at any time. ## Before you import | Check | Why it matters | |---|---| | **The SKU format** | Each plan SKU encodes the plan length, region, coverage type and price band, for example `SBW-1U-CEAD-49999`. It is 17 characters, inside Business Central's 20-character limit for an item **No.** The same SKU must appear on your store's plan products, on each order's plan line and in Business Central. | | **Item number series** | If your item **No.** comes from a number series without **Manual Nos.**, allow manual numbers for the import, or the SKUs are replaced with generated numbers. | | **Posting groups** | Pick a **Gen. Prod. Posting Group** that posts to a dedicated income account, for example `Warranty Income`. Agree it with your accountant. | | **Tax** | Pick the **Tax Group Code** (or VAT product posting group) your setup applies to service and warranty lines. | | **How your connector matches items** | The Shopify connector and most other store connectors match order lines to items by SKU or item number. Confirm which field yours reads. | ## Import the SKUs Open **Items**, then **Edit in Excel**. Business Central opens the list in Excel with its add-in, so rows you add are published back as new items. | Sheet column | Business Central field | |---|---| | `InventoryID` | **No.** | | `Description` | **Description** | | `BasePrice` | **Unit Price** | On every row also set **Type** to **Non-Inventory**, **Base Unit of Measure** to `PCS` or the unit you use for services, your **Gen. Prod. Posting Group** and your **Tax Group Code**. Click **Publish** in the Excel add-in. Rows with an error stay highlighted with the reason; fix them and publish again. For a large catalogue, or if your administrator prefers it, a **Configuration Package** on the **Item** table does the same job. ## Verify the import Filter **Items** on **No.** `SBW*`. Each one should be a non-inventory item with the full SKU, the right price and your posting group. Count them: the number of items must equal the number of rows in the sheet. Then place a test order with a plan in your store and check that the plan line lands on the Business Central sales order against the matching item. ## Troubleshooting | Symptom | Cause and fix | |---|---| | Items were created with generated numbers instead of SKUs | The item number series does not allow manual numbers. Turn on **Manual Nos.**, delete the generated items and publish again. | | A row will not publish because of posting setup | No **Gen. Prod. Posting Group** or tax group on the row. Set them and publish again. | | Orders with a plan fail to import | The connector cannot find an item with the plan line's SKU. Compare the SKU on the order to the item **No.** character for character. | If an issue persists, send SureBright the error text, the SKU involved and a screenshot of the item card. ## Related - [Plans in your order tools](/learn/plans-in-your-order-tools#plan-skus-for-your-erp-or-3pl): what plan SKUs are and what to ask SureBright for. - [Supported platforms](/platforms/overview#erp): every ERP SureBright works with. --- # NetSuite warranty SKUs Source: https://docs.surebright.com/erp/netsuite-warranty-skus > Add the SureBright warranty SKUs to Oracle NetSuite as non-inventory items for sale from the plan SKU CSV you download from the Merchant Portal, so plan sales from your store reconcile in NetSuite. Use this page when you run Oracle NetSuite and sell SureBright plans through an online store or point of sale that syncs orders into it. You download the warranty SKUs and their prices from the Merchant Portal as a CSV (see [Download your plan SKUs](/erp/download-plan-skus)). You load that file into NetSuite once. From then on every plan line on an order that reaches NetSuite matches an item you already have, so orders import cleanly and plan revenue is reported on its own. Menu paths below are from current NetSuite releases. Labels vary slightly by edition and by the roles and features enabled in your account. If a screen does not match, send SureBright a screenshot. ## Who does what | Step | Who | What happens | |---|---|---| | 1. Downloads the SKU CSV | You | **Products > Download plan SKUs** in the Merchant Portal. One row per SKU, UTF-8. | | 2. Agrees the accounting | You, once | Pick the income account and tax schedule plan sales post to. | | 3. Imports the CSV | You | The SKUs become non-inventory items for sale in NetSuite. | | 4. Matches orders | Your order connector | Plan lines on incoming orders map to these items by SKU. | Everything you add is standard: non-inventory items, created with NetSuite's own CSV import. No existing item, workflow, chart of accounts or saved search is changed, and any SKU can be made inactive at any time. ## Before you import | Check | Why it matters | |---|---| | **The SKU format** | Each plan SKU encodes the plan length, region, coverage type and price band, for example `SBW-1U-CEAD-49999`. The same SKU must appear on your store's plan products, on the plan line of each order and in NetSuite, or orders will not reconcile. | | **The income account** | Use a dedicated account, for example `Warranty Income`, so plan revenue stays separately reportable. Agree it with your accountant. | | **Tax** | If you use tax schedules, pick the one your tax setup applies to service and warranty lines. | | **How your connector matches items** | Most Shopify, BigCommerce and other store connectors match order lines to NetSuite items by SKU (Item Name/Number). Confirm yours does, and which field it reads. | ## Import the SKUs Go to **Setup > Import/Export > Import CSV Records**. Set **Import Type** to **Items** and **Record Type** to **Non-inventory Item for Sale**. Choose the CSV SureBright sent and set the character encoding to **Unicode (UTF-8)**. On **Import Options** select **Add**. Running it again later with **Update** changes prices without creating duplicates. | CSV column | NetSuite field | |---|---| | `InventoryID` | **Item Name/Number** | | `Description` | **Display Name/Code** and **Sales Description** | | `BasePrice` | **Base Price** (Pricing) | Then set default values for every row: your **Income Account**, your **Tax Schedule** if you use one, and **Subsidiary** in OneWorld accounts. Save the mapping so it can be reused, then click **Run**. Watch the job under **Setup > Import/Export > View CSV Import Status** and open the response file if any row failed. Keep the plan items out of your web store and catalogue browsing. Shoppers add plans through the SureBright offer, not from a product page. If your account has web store fields on items, leave **Display in Web Store** cleared. ## Verify the import Search items for the prefix `SBW`. Each one should be a non-inventory item for sale with the full SKU, the right price and your income account. Count them: the number of items must equal the number of rows in the sheet. Then place a test order with a plan in your store and check that the plan line lands on the NetSuite sales order against the matching item. ## Troubleshooting | Symptom | Cause and fix | |---|---| | A row fails with an account or tax error | No default **Income Account** or **Tax Schedule** was set in the mapping. Add them and re-run that row. | | Descriptions show mangled characters | The import ran with a non-UTF-8 encoding. Re-run with **Unicode (UTF-8)**. | | Orders with a plan fail to import into NetSuite | The connector cannot find an item with the plan line's SKU. Compare the SKU on the order to the Item Name/Number character for character. | | Duplicate plan items appear | The import was re-run with **Add** instead of **Update**. Make the duplicates inactive. | If an issue persists, send SureBright the error text, the SKU involved and a screenshot of the item. ## Related - [Plans in your order tools](/learn/plans-in-your-order-tools#plan-skus-for-your-erp-or-3pl): what plan SKUs are and what to ask SureBright for. - [Supported platforms](/platforms/overview#erp): every ERP SureBright works with. --- # Odoo warranty SKUs Source: https://docs.surebright.com/erp/odoo-warranty-skus > Add the SureBright warranty SKUs to Odoo as service products from the plan SKU CSV you download from the Merchant Portal, so plan sales from your store reconcile in Odoo. Use this page when you run Odoo and sell SureBright plans through an online store or point of sale that syncs orders into it. You download the warranty SKUs and their prices from the Merchant Portal as a CSV (see [Download your plan SKUs](/erp/download-plan-skus)). You load it into Odoo once. From then on every plan line on an order that reaches Odoo matches a product you already have, and nothing is reserved or delivered for it. Field names below are from current Odoo versions. Some changed between versions; for example, the product type choices differ between Odoo 17 and later versions. If a screen does not match, send SureBright a screenshot. ## Who does what | Step | Who | What happens | |---|---|---| | 1. Downloads the SKU CSV | You | **Products > Download plan SKUs** in the Merchant Portal. One row per SKU, UTF-8. | | 2. Agrees the accounting | You, once | Pick the product category, income account and tax plan sales use. | | 3. Imports the CSV | You | The SKUs become service products in Odoo. | | 4. Matches orders | Your order connector | Plan lines on incoming orders map to these products by SKU. | Everything you add is standard products, created with Odoo's own import. No existing product, category or account is changed, and any SKU can be archived at any time. ## Before you import | Check | Why it matters | |---|---| | **The SKU format** | Each plan SKU encodes the plan length, region, coverage type and price band, for example `SBW-1U-CEAD-49999`. The same SKU must appear on your store's plan products, on each order's plan line and as the **Internal Reference** in Odoo. | | **Product category** | Create a category for plans, for example `SureBright Plans`, whose income account is a dedicated one, for example `Warranty Income`. Agree it with your accountant. | | **Tax** | Pick the customer tax your setup applies to service and warranty lines. | | **How your connector matches products** | Most store connectors match order lines to products by **Internal Reference**. Confirm yours does. | ## Import the SKUs In **Sales** (or **Inventory**), open **Products > Products** and switch to the list view. Open the **gear** menu (or **Favorites** in older versions) and choose **Import records**. Upload the CSV and set the encoding to **UTF-8**. | CSV column | Odoo field | |---|---| | `InventoryID` | **Internal Reference** | | `Description` | **Name** | | `BasePrice` | **Sales Price** | Add columns to the CSV for the fields every plan shares, or set them afterwards in bulk from the list: **Product Type** = **Service**, **Product Category** = your plan category, **Customer Taxes** = your service tax, **Can be Sold** ticked, **Can be Purchased** cleared. Click **Test** first. Odoo lists any row it cannot read without saving anything. When the test is clean, click **Import**. If you run Odoo eCommerce, keep the plan products unpublished on the website. Shoppers add plans through the SureBright offer, not from a product page. ## Verify the import Search products for `SBW` in **Internal Reference**. Each one should be a service product with the full SKU, the right price and your plan category. Count them: the number of products must equal the number of rows in the sheet. Then place a test order with a plan in your store and check that the plan line lands on the Odoo sales order against the matching product, with no delivery created for it. ## Troubleshooting | Symptom | Cause and fix | |---|---| | A delivery order is created for the plan line | The product type is not **Service**. Change it on the plan products. | | Revenue posts to the wrong account | The product category's income account points elsewhere. Fix it on the category. | | Descriptions show mangled characters | The import ran with a non-UTF-8 encoding. Re-import with **UTF-8**. | | Orders with a plan fail to import | The connector cannot find a product with the plan line's SKU. Compare the SKU on the order to the **Internal Reference** character for character. | If an issue persists, send SureBright the error text, the SKU involved and a screenshot of the product. ## Related - [Plans in your order tools](/learn/plans-in-your-order-tools#plan-skus-for-your-erp-or-3pl): what plan SKUs are and what to ask SureBright for. - [Supported platforms](/platforms/overview#erp): every ERP SureBright works with. --- # SAP Business One warranty SKUs Source: https://docs.surebright.com/erp/sap-business-one-warranty-skus > Add the SureBright warranty SKUs to SAP Business One as non-inventory sales items from the plan SKU CSV you download from the Merchant Portal, so plan sales from your store reconcile in SAP Business One. Use this page when you run SAP Business One and sell SureBright plans through an online store or point of sale that syncs orders into it. You download the warranty SKUs and their prices from the Merchant Portal as a CSV (see [Download your plan SKUs](/erp/download-plan-skus)). You load it into SAP Business One once. From then on every plan line on an order that reaches SAP Business One matches an item you already have. Menu paths below are from current SAP Business One releases. They vary slightly between the SQL and HANA versions and by localisation. If a screen does not match, send SureBright a screenshot. ## Who does what | Step | Who | What happens | |---|---|---| | 1. Downloads the SKU CSV | You | **Products > Download plan SKUs** in the Merchant Portal. One row per SKU, UTF-8. | | 2. Agrees the accounting | You, once | Pick the item group and G/L accounts plan sales post to. | | 3. Imports the sheet | You | The SKUs become sales items that are not inventory items. | | 4. Matches orders | Your order connector | Plan lines on incoming orders map to these items by SKU. | Everything you add is standard item master data, created with SAP Business One's own import tools. No existing item, price list or account is changed, and any SKU can be made inactive at any time. ## Before you import | Check | Why it matters | |---|---| | **The SKU format** | Each plan SKU encodes the plan length, region, coverage type and price band, for example `SBW-1U-CEAD-49999`. The same SKU must appear on your store's plan products, on each order's plan line and as the **Item No.** in SAP Business One. | | **Item group** | Create or pick an item group for plans, for example `SureBright Plans`, whose G/L accounts post to a dedicated revenue account. Agree it with your accountant. | | **Price list** | Decide which price list carries the plan prices, usually your base sales price list. | | **How your connector matches items** | Most store connectors match order lines to items by **Item No.** Confirm yours does. | ## Import the SKUs Keep one row per SKU with three columns: **Item No.** (`InventoryID`), **Item Description** (`Description`) and the price (`BasePrice`). Save it as a text file, tab separated, which is what the import expects. Go to **Administration > Data Import/Export > Data Import > Import from Excel**. Set **Business Object** to **Items**. Map the columns to **Item No.**, **Item Description** and the price list price, then choose the file. For the imported items, clear **Inventory Item**, keep **Sales Item** ticked and clear **Purchase Item**, and assign your plan **Item Group**. A plan has no stock to count, pick or receive. Your administrator can do this in the same import with the matching columns, or afterwards in **Item Master Data**. For large catalogues your partner may prefer the **Data Transfer Workbench (DTW)**, using the **Items** template with the same fields. ## Verify the import Open **Item Master Data** and search **Item No.** `SBW*`. Each item should have the full SKU, the right price, **Inventory Item** cleared and your plan item group. Count them: the number of items must equal the number of rows in the sheet. Then place a test order with a plan in your store and check that the plan line lands on the sales order against the matching item. ## Troubleshooting | Symptom | Cause and fix | |---|---| | Plan lines ask for stock or a warehouse | **Inventory Item** is still ticked on the item. Clear it. | | Revenue posts to the wrong account | The item group's G/L accounts point elsewhere. Fix them on the item group. | | Orders with a plan fail to import | The connector cannot find an item with the plan line's SKU. Compare the SKU on the order to the **Item No.** character for character. | If an issue persists, send SureBright the error text, the SKU involved and a screenshot of the item. ## Related - [Plans in your order tools](/learn/plans-in-your-order-tools#plan-skus-for-your-erp-or-3pl): what plan SKUs are and what to ask SureBright for. - [Supported platforms](/platforms/overview#erp): every ERP SureBright works with. --- # Spreadsheet order intake Source: https://docs.surebright.com/erp/spreadsheet-order-intake > Email SureBright a spreadsheet of your orders and have the protection plans set up for you, with no storefront integration: what to send, what your customers receive and where the plans appear. Available on request. Ask your SureBright contact to enable this for your store. Use spreadsheet order intake when your orders do not come from a connected storefront or POS. You email an Excel workbook of orders to the mailbox SureBright gives you. SureBright finds the plans in it, asks a customer to confirm which product their plan covers where that is not obvious, and sets up the plans. Read this page when you are setting it up, or when you want to know what happens after you send a file. ## What happens after you send a file 1. **You send the file.** Attach the `.xlsx` to an email from a sender address you registered with SureBright and send it to the intake mailbox. Mail from any other sender is ignored. 2. **SureBright reads it.** Within a few minutes SureBright reads the workbook and works out which lines are products and which are plans. A line counts as a plan when its product ID is one of the plan SKUs you agreed at setup. 3. **Customers confirm the covered product.** For an order with exactly one product and one plan, the plan is matched to the product automatically. For anything else the customer receives an email with a link to confirm which product each plan covers. 4. **Plans start.** Once every plan on the order is matched to a product, SureBright creates the contract and emails the customer their coverage confirmation. Sending the same file twice does nothing: a file with the same contents is handled only once. Send a new file with new orders instead. ## What the workbook must contain The workbook has two sheets, **Orders** and **Product**, joined by the product ID. Your column headers can differ from the names below. SureBright matches your headers to these fields once at setup (capital letters do not matter) and uses the same matching for every file you send after that. Fields marked **required** must be present and filled on every row, or the order cannot be handled. ### Columns on the Orders sheet One row per order line. Rows that share the same order number form one order. | Field | Required | Notes | |---|---|---| | Order number | yes | Groups rows into an order and becomes the order reference on the contract. | | Order date | | Purchase date of the order. | | Customer first name, last name | | | | Customer email | yes | Where the confirmation link and the coverage email are sent. | | Customer phone | | | | Address line 1, line 2, city, state, ZIP, country | | Printed on the contract. If address details are missing, the contract is put on hold; see [Why a contract is on hold](/contracts/holds). | | Product ID | yes | Identifies the product or plan on the line and joins to the Product sheet. | | Order line key | | Your line identifier, kept on the contract. | | Sale price | | Price paid for the line. | | Quantity | | Units on the line. | | Discount amount | | | ### Columns on the Product sheet One row per product ID referenced by the Orders sheet. | Field | Notes | |---|---| | Product title | Shown to the customer on the confirmation page; a second column can be named as a fallback when the first is blank. | | Product SKU | | | List price | The product's list price, distinct from the sale price. | | Product description | | | Product URL | | | Product condition | | If you want an extra column kept with the order, ask for it at setup. Do not include credentials or other sensitive columns in the file; SureBright uses only the columns above. ## What the customer receives **Confirmation email.** Subject *Complete your warranty registration*. It thanks the customer for buying a warranty with your store, says how many warranties they have to link to how many products, and has a **Link my warranty** button. The link is specific to the order and expires after the number of days stated in the email; if they did not buy the warranty they can ignore it. Customers can reply to the email with questions. **Confirmation page.** Titled **Confirm your protection plan** with the line *Tell us which product each protection plan covers so we can activate it.* For each plan the page asks **Which product does this plan cover?** and lists the order's products; a product already matched to another plan is marked as such. The customer can choose **I'm not sure** and come back later. **Confirm & activate** submits the choices and shows **Your protection plan is confirmed**. An expired or already used link shows *We couldn't open this activation* with instructions to use the most recent email or reply to it for a new one. **Coverage email.** Once the contract exists the customer receives the standard SureBright coverage confirmation for your store. Orders with one product and one plan skip the confirmation step entirely; the customer only receives the coverage email. Keeping one order per product in your export therefore gets customers covered fastest. ## Where the plans appear Contracts show under **Recent Sales** on the portal's [Sales](/merchant-portal/sales) page like any other sale, with your order number as the reference. Until a customer confirms, the order has no contract; SureBright can re-send the confirmation link on request. If a plan cannot be matched to a product, or a contract cannot be created after the customer confirms, SureBright reviews the order and it may appear in **Order Resolution**. ## What SureBright needs from you at setup - The sender address (or addresses) your files will come from. - The sheet names and column headers you use, so they can be matched to the fields above. - The SKUs or product IDs of the plans you sell, so plan lines can be recognised. - Your store's country and the name you want customers to see in the emails. ## Related Other ways to sell a plan outside your storefront checkout. Where an order appears when it needs a decision from you. **See also:** [Report sales made outside an integrated checkout](/platforms/other-platforms#report-sales-made-outside-an-integrated-checkout). --- # Analytics and consent Source: https://docs.surebright.com/frontend-widget-integration/frontend-widget-kit/analytics-and-consent > What the SureBright SDK records about shopper interactions with the protection offer, how it honours Shopify customer privacy consent, and what is never recorded. The SDK records how shoppers interact with the protection offer so the merchant portal can show offer views, plan clicks, add-to-cart with and without protection, and experiment results under **Sales**. This page is for merchants and developers who want to know exactly what is sent, when, and how consent is respected. The raw endpoint and payload are documented in [Event Collector](/frontend-widget-integration/frontend-widget-kit/event-collector). ## What is recorded Each row is one event sent to SureBright. The wire names are the `et` values in the collector reference. | Shopper moment | Event | | --- | --- | | Plans were fetched for the product on the page | `SB_FETCHED_POLICY`, once per product and variant per page view. Counts as a product view with an offer. | | The offer rendered on the page, or a plan pop-up opened | `SB_VIEWED_POLICY`, once per surface per view. | | The offer was actually seen: at least 50% of it on screen for one continuous second | `SB_VIEWED_POLICY_IMPRESSION`, once per surface per view. Opening the cart drawer starts a new view. | | A plan card was selected or deselected | `SB_CLICKED_POLICY`, `SB_UNCLICKED_POLICY`. Choosing the decline card is a deselect; a selection the SDK made itself to mirror the cart is not recorded. | | "What's covered" opened | `SB_CLICKED_LEARN_MORE`, followed by `SB_VIEWED_POLICY` for the pop-up. | | A pop-up was closed | `SB_CLICKED_PROTECT_MY_PURCHASE`, `SB_CLICKED_NO_THANKS` or `SB_CLICKED_CLOSE_POPUP_ICON`, by how it was closed. | | The add-protection call-to-action in the cart was used | `SB_CLICKED_ADD_WARRANTY_BUTTON`. | | The cart page or drawer was viewed | `SB_VIEWED_CART`. | | The shopper added a product to the cart | `ADD_TO_CART`, with the plan that went with it, or empty plan fields when none did. Sent immediately. For a bundle, one per component. | | The cart confirmed the add | `SB_CONFIRMED_ADD_TO_CART`, when a cart read within 10 seconds shows the product quantity went up. | | A plan was added from the product-registration page | `SB_CLICKED_ADD_TO_CART`. | | The shopper was exposed to an experiment | `SB_VIEWED_EXPERIMENT`, on the first impression, once per experiment and treatment per browser session. | | The SDK hit an error | `SB_ERROR`. | Every event carries the store id, a visit id (one per browser session), platform and storefront runtime (`SHOPIFY` with `LIQUID`, `HYDROGEN` or `SHOPYFLOW`), store country, the page it came from, the time, the Shopify theme id, the cart token when known, and the configuration version that rendered the offer. Where they apply it adds the quote and plan ids, product id, variant, price and quantity, plan price and term, display currency, which term was pre-selected and which wore the ribbon, and experiment and treatment ids. Events are tagged with the SDK build (`sim-x`) and an `isBot` flag. ### What is never recorded No customer name, email, phone, address, order number or payment detail is ever part of an event. The SDK reads none of these. The cart token and visit id are the only identifiers, and neither is tied to a person. The following is also dropped before it is sent: - Anything from a Shopify theme-editor preview (`Shopify.designMode`) or a SureBright design preview. These are not shoppers. - Errors raised by crawlers. A client whose user agent names a bot, crawler or spider, or that runs under browser automation, is tagged `isBot: true`; its other events are kept, tagged, so they can be filtered. - Events with no store id. A headless storefront that omits `data-sb-store-id` produces none; see [Headless and custom storefronts](/frontend-widget-integration/frontend-widget-kit/headless-and-custom-storefronts). ## Where events go Events are buffered in the page and posted to SureBright's event collector in batches of up to 10, every 5 seconds, when a batch fills, or when the page is hidden or unloaded. `ADD_TO_CART` is sent at once. Events that could not be sent are kept in `sessionStorage` under `sb_analytics_pending_event_list` (at most 100) and retried on the next page in the session. From the collector they feed the **Sales** analytics in the merchant portal. The SDK sends events to SureBright only; it does not load or call any third-party analytics script. ## Consent on Shopify On a Shopify Online Store theme the SDK follows the shopper's choice in Shopify's Customer Privacy API, the same source your cookie banner writes to. When the page has `Shopify.loadFeatures`, the SDK loads `consent-tracking-api` and listens for the `visitorConsentCollected` document event. Events are recorded into the buffer but no request leaves the page. The buffer is also saved to `sessionStorage`, so a shopper who answers the banner on a later page still gets their earlier interactions counted. If `analyticsProcessingAllowed()` is true, or the visitor's analytics consent is anything other than an explicit `no`, the buffer is flushed and recording continues normally. The buffer is discarded, the saved copy is cleared, and the SDK records nothing further on that page. A store that does not use Shopify's consent banner (no `Shopify.loadFeatures` on the page) is treated as allowed, which matches Shopify's own behaviour for stores with no privacy settings. On Hydrogen, Shopyflow and non-Shopify platforms the SDK has no consent source and records as soon as the shopper interacts; if your storefront runs its own consent manager and must gate SureBright, tell SureBright, since there is no public switch in the SDK today. Consent gates reporting only. The offer still renders, plans are still added to the cart, and cart sync still runs whatever the shopper chose. None of those depend on analytics. ## Checking what is sent Add `?sb_debug` to a product URL and watch for `[SB] [ANALYTICS]` lines in the console; each `track` and `flush` is logged. In the Network tab, filter on `/events/api/event` to see the batches and their `eventList` bodies. If you see `track` lines but no requests on a Shopify store, the consent API has not yet reported a choice; answer the banner and the batch will leave. If your storefront renders the offer with its own UI, or runs where the SDK cannot see the interaction, you have to send these events yourself; the field list, the minimum set that makes a store visible in Sales, and a worked example are in [Event Collector](/frontend-widget-integration/frontend-widget-kit/event-collector). --- # Client-side cart sync Source: https://docs.surebright.com/frontend-widget-integration/frontend-widget-kit/cart-sync > How the SDK keeps protection lines in step with the products they cover, how it works alongside cart apps and accelerated checkout, and what a theme must not do. Once a shopper has a protection plan in the cart, the SureBright SDK keeps that line honest: the same quantity as the product it covers, one plan per product, and gone when the product is gone. It does this in the browser, on every page the SDK runs on, without any code from the theme. The server-side [Cart Validator](/shopify/enable-surebright-cart-validator) is the backstop at checkout; cart sync is what stops most problems reaching it. ## When sync runs A sync cycle is scheduled on page load, whenever the cart changes (the SDK watches cart requests and cart DOM re-renders), after the SDK adds a plan, after a shopper add-to-cart, and, on platforms that expose it, when checkout starts. Cycles are debounced by 600 ms so a burst of cart writes produces one read. Before reading the cart the SDK waits for any add-to-cart it has seen start to land, up to a cap. A read taken while a write is in flight is never trusted for a deletion. A circuit breaker stops sync after 5 cycles in 10 seconds so a theme that re-renders the cart on every write cannot put the SDK in a loop. ## How protection lines are recognised and matched A cart line is a SureBright protection line when its title contains `Protection Powered by SureBright`, `Product Warranty Powered by SureBright` or `SureBright Protection Plan`, its handle matches `surebright-*` or `sb-protection-*`, or it carries the `_sbQuoteId` property. SureBright can add store-specific titles to this list. A protection line is matched to the product it covers through its `_variantId` property, which holds the covered product's variant id. Lines that cover a cart line rather than a variant use `_lineItemKey`. Shipping-protection lines (`_sbQuotePlatform = PLATFORM_SHIPPING_INSURANCE`) and registration-page plans (`REGISTRATION_POST_PURCHASE`) are left out of sync entirely. ## What sync corrects | Situation | What the SDK does | | --- | --- | | Product quantity changed | Raises or lowers the protection line so the covered units equal the product units, counted across every cart line of that variant. A store can cap units per product. | | Two different plans for the same product | Keeps the most recently added (by `_sbAddedAt`) and removes the other. Two lines of the same plan are not treated as duplicates. | | Protection with no `_variantId` or `_lineItemKey` | Removed. There is nothing to match it to. | | Covered product removed from the cart | The protection line is removed. | | More protection units than product units | Trimmed to the product quantity. | | Bundle component plans | Kept at bundle quantity times component quantity, one line per component; see [Bundles](/shopify/bundles). | | Post-purchase plan (`PLATFORM_POST_PURCHASE`) | Not matched to a cart product. Collapsed to one line per covered product and locked to `_sbPurchasedQuantity`. | The orphan rules (no key, product gone) can be set per store to keep the line instead of removing it. In that case the SDK logs a warning and leaves the Cart Validator to block checkout. ## Removing orphans before checkout On Shopify Online Store themes a cart read is reliable, so an orphaned plan is removed on the first sync pass. On Hydrogen and Shopyflow the cart can briefly under-report its lines mid-mutation, so any removal justified by a missing product has to appear in two consecutive reads, about 2.5 seconds apart, before it is executed. Duplicate removals are never deferred, because a transient read cannot invent a second line. After writing, the SDK re-reads the cart 300 ms later and verifies each operation landed. Failed writes are retried up to 3 times with back-off. A write the store keeps refusing (for example an HTTP 422 because the cart caps units of a variant) is given up after 2 attempts, logged as `Coverage left mismatched`, and not re-issued until the target quantity changes. When at least one write succeeded the SDK refreshes the cart page or drawer so the shopper sees the result; on themes without section rendering this is a full reload, and the SDK waits for its own pending writes to finish before navigating. ## How add-to-cart is intercepted Sync fixes the cart after the fact; interception is how the plan gets in at the moment of the add. Per store, SureBright configures an ordered pipeline of hooks, each with a trigger, an extractor for the variant and quantity, and a matcher: | Hook | What it catches | | --- | --- | | `FORM_SUBMIT` | The product form posting to `/cart/add`. | | `BUTTON_CLICK` | The add-to-cart button itself, used when a store owns `window.fetch` (Shopyflow) so the SDK writes the plan after the native add instead of rewriting the request. | | `FETCH`, `XHR` | AJAX adds to `/cart/add.js`, JSON, form-encoded or `FormData`. A request carrying several items (an add-on app bundling extras with the product) counts as the product's add when one item is the product on offer. | | `GRAPHQL` | Storefront API `cartCreate` and `cartLinesAdd` mutations, used by accelerated checkout and headless carts. | The SDK's own cart requests carry an `X-SB-Internal: 1` header so they are never re-intercepted. In the quick-view surface every hook is forced to act before the base add completes, because themes often navigate right after it. ## Third-party cart apps If an app renders your cart instead of the theme, the SDK has to ask that app to repaint after it writes, and it has to recognise the app's rows. Two apps are supported today: | App | How the SDK works with it | | --- | --- | | Rebuy Smart Cart | Rows are found by `.rebuy-cart__flyout-item` (or the drawer line selector configured for your store). After a write the SDK waits for `window.Rebuy.Cart` (the `rebuy:cart.ready` event, up to 8 s) and calls `fetchShopifyCart` so the flyout re-reads the cart. | | UpCart | Rows are `.upcart-product-item`. The SDK waits for UpCart's React app to mount (up to 3 s) and calls `upcartRefreshCart()`. Its own `/cart/add` requests carry `upcart=1&opens_cart=never` so the drawer re-reads without popping open. | SureBright declares the cart app for your store; the presence of the app's script is not enough, since many stores install Rebuy for upsells while the theme cart stays in charge. If you switch cart apps, tell SureBright. ## Accelerated checkout (Shop Pay, Buy with Shop) Dynamic checkout buttons create the cart with a `cartCreate` mutation and leave for checkout in the same instant, so there is no cart page for sync to fix. When Shop Pay support is enabled for your store, the SDK adds a `GRAPHQL` step that holds that mutation, adds the selected plan as a line with the usual properties, and lets it go. If no plan is selected and the store nudges, the offer pop-up opens and the request waits for the shopper's answer. The quick-view surface gets the same step. Without this flag, a "Buy with Shop" purchase carries no plan. ## What a theme developer must not do - Do not rename, strip or re-key `_sb*`, `_variantId`, `_lineItemKey` or `_bundle*` line properties anywhere between the cart and the order. They are how the order is matched to the quote; see [Cart line-item properties](/frontend-widget-integration/frontend-widget-kit/javascript-injection#cart-line-item-properties). - Do not replace `window.fetch` or `XMLHttpRequest` after the SDK has loaded without calling through to the original. The SDK observes cart responses to know when to sync; a wrapper that swallows them blinds it. If you must wrap, load your wrapper first. - Do not change the quantity of a SureBright line yourself. Protection quantity follows the product it covers, and the next cycle puts it back. On shipping-protection and post-purchase rows the SDK disables the theme's quantity stepper outright and keeps only the remove control. - Do not merge cart lines client-side. Each add carries a distinct `_sbAddedAt` so plans stay separate; merging hides changes. - Do not block or rewrite `/cart/change.js` and `/cart/update.js`. Sync writes through them. - Do not load the SDK twice. The second load is ignored, but a theme and an app embed both loading different builds is a common source of confusion. - Cart re-renders need no signal from you; the SDK observes them. If your theme re-renders collection grids client-side, dispatch `document.dispatchEvent(new CustomEvent("sb:cart-sections-refreshed"))` afterwards so the SDK re-hides SureBright's protection products in the new markup. ## Debugging Add `?sb_debug` to the cart URL. Sync logs under `[SB] [SYNC]`: `Cart read` with the item count, `SyncResolver: plan assembled` with the operation count, `Deferred warranty removal pending second-read confirmation` when a removal is waiting, and `Executing sync plan` when writes go out. `[SB] [INTERCEPTOR]` lines show which hooks were installed and whether a request matched. `window.__SUREBRIGHT_DESTROY__()` removes the interceptors and observers if you need to compare against the theme alone. --- # Event Collector Source: https://docs.surebright.com/frontend-widget-integration/frontend-widget-kit/event-collector > The storefront analytics endpoint the SureBright SDK reports to (POST /events/api/event): payload fields, required values, event names, and when a custom storefront has to call it directly. The SDK reports shopper interactions with the protection offer to SureBright's event collector. Those events feed the **Sales** analytics in the merchant portal: how many product views had an offer, how many shoppers looked at a plan, how many added to cart with and without protection, and attach-rate experiments. If the SDK runs on your pages, it does this for you and you can stop reading. Call the collector yourself only when the SDK cannot see the interaction: a native app, a server-rendered checkout the script cannot run in, or a storefront where you render the offer with your own UI from SureBright quote data. Without these events, that traffic is invisible in Sales analytics. ## Endpoint ```text POST https://api-external.surebright.com/events/api/event Content-Type: application/json ``` - **Authentication: none.** The route is deliberately unauthenticated so browsers can post to it; CORS allows any origin. Do not send anything you would not put in a public page. - The body is always a batch: `{ "eventList": [ ... ] }`. A single event still goes in a one-element array. - Events are buffered server-side and written asynchronously; the response tells you how many were accepted, not that they were stored. ### Response ```json { "isError": false, "acceptedCount": 2, "rejectedCount": 0, "webhookEventsPushedCount": 0 } ``` | Status | Meaning | | --- | --- | | `200` with `acceptedCount` / `rejectedCount` | Rejected events failed validation (see below) and were dropped silently. | | `200` with `{"isError": true, "message": "No events to push"}` | `eventList` was missing or empty. | | `503` | The server could not buffer the batch. Retry later with the same events. | ## Event fields Field names are short wire keys. The server maps them to full names; unknown keys are stored as-is under their wire name. Keys the server owns (`_id`, `userAgent`, `receivedAt`, `timestamp`, `metadata`, `productDetailMap`) are ignored if you send them. Event type. One of the names under [Event types](#event-types). Store id, as SureBright knows your store (for Shopify, the `*.myshopify.com` domain). When the event happened, as a strict ISO 8601 timestamp with a `Z` or `±hh:mm` offset, for example `2026-11-09T14:03:21.512Z`. Anything else (including a missing offset, or an impossible date such as `2026-02-30`) rejects the event. Visit id: a UUID you generate once per browser session and reuse on every event in it. Strongly recommended; if omitted the server stores `INVALID_VISIT` and the event cannot be joined into a funnel. Page source. One of `PRODUCT_PAGE`, `CART_PAGE`, `COLLECTION_PAGE`, `CHECKOUT_PAGE`, `THANK_YOU_PAGE`, `OTHER_PAGE`, `QUICK_VIEW_POPUP`, `CART_POPUP`, or, for events raised from a popup, the popup name (`NUDGE_POPUP`, `ADD_WARRANTY_POPUP`, `LEARN_MORE_POPUP`, `ADD_TO_CART_POPUP`, `REGISTRATION_POST_PURCHASE`). May be prefixed with the control that triggered it, separated by `#`, for example `ATC_BUTTON#PRODUCT_PAGE`; the server splits the prefix into `eventSource`. Sales analytics counts product-page funnel events by `ps = PRODUCT_PAGE`. Platform: `SHOPIFY`, `BIGCOMMERCE`, `WOOCOMMERCE`, or `CUSTOM`. Store country code, for example `US` or `CA`. Province/state the quote was priced for, when applicable. SureBright quote id the event relates to. SureBright quote item id (the specific plan). Platform cart id / token, when known. SureBright cart analytics id, when the SDK has stamped the cart with one. Omit if you do not have it. Theme id. Session treatment id, only when the store runs a SureBright experiment. Error message, for `SB_ERROR` events. Error code, for `SB_ERROR` events. Product and plan details for the event. An empty string for any value is stored as `null` (that is how "no plan" is expressed). Product id. Variant id. Product price. Product quantity. Protection (policy) product id. Sales analytics treats an add-to-cart with `p_plpid` empty/null as "added without protection". Protection product variant id. Protection quantity. Plan price. Plan tenure, e.g. `2Y`; `0Y` when no plan. Default-selected plan tenure shown in the offer, e.g. `2Y`. Ribbon-highlighted plan tenure shown in the offer. Price version id, for versioned pricing. Display currency. Shopify category id. SureBright category id. Whether quotes were available for the product. The server adds `eventId` (if you did not send one), `receivedAt`, and a parsed `userAgent` from the request header. Events containing a `wt` (webhook topic) field are treated as webhook events, not shopper events, and are discarded. Do not use that key. ## Event types These are the `et` values the storefront SDK emits. Use the same names so your traffic lands in the same reports. | `et` | When | | --- | --- | | `SB_FETCHED_POLICY` | Quotes were fetched for a product the shopper is viewing. Sales analytics counts this as a product view with an offer. | | `SB_VIEWED_POLICY` | The offer became visible, or a plan popup opened (with `ps` set to the popup name). | | `SB_VIEWED_POLICY_IMPRESSION` | A widget surface was rendered and seen. | | `SB_VIEWED_CART` | The cart page or cart drawer was viewed. | | `SB_CLICKED_POLICY` | The shopper selected a plan. | | `SB_UNCLICKED_POLICY` | The shopper deselected a plan. | | `SB_CLICKED_LEARN_MORE` | The shopper opened "what's covered". | | `SB_CLICKED_PROTECT_MY_PURCHASE` | The shopper confirmed protection in a popup. | | `SB_CLICKED_NO_THANKS` | The shopper declined protection in a popup. | | `SB_CLICKED_CLOSE_POPUP_ICON` | The shopper closed a popup without choosing. | | `SB_CLICKED_ADD_WARRANTY_BUTTON` | The shopper used an "add protection" call-to-action (cart). | | `ADD_TO_CART` | The shopper added a product to the cart, with or without a plan. `ps` carries the triggering control (e.g. `ATC_BUTTON#PRODUCT_PAGE`) and `pd.p_plpid` says whether protection went with it. Sent immediately, not batched. | | `SB_CLICKED_ADD_TO_CART` | Protection was added from the product-registration flow. Older SDK builds also sent it for product-page adds, and the legacy product-page funnel chart still counts it. | | `SB_CONFIRMED_ADD_TO_CART` | The cart confirmed the add (quantities verified after the write). | | `SB_VIEWED_EXPERIMENT` | The shopper was exposed to an experiment treatment (`stid`). | | `SB_ERROR` | The SDK hit an error (`em`, `ec`). | Which events the merchant portal reads: the design/experiment analytics count `SB_FETCHED_POLICY`, `SB_VIEWED_POLICY_IMPRESSION`, `SB_CLICKED_POLICY`, `ADD_TO_CART` and `SB_VIEWED_CART` per visit; the legacy product-page funnel chart counts `SB_FETCHED_POLICY`, `SB_VIEWED_POLICY` and `SB_CLICKED_ADD_TO_CART` with `ps` = `PRODUCT_PAGE`. The minimum set that makes a custom storefront visible is `SB_FETCHED_POLICY`, `SB_VIEWED_POLICY_IMPRESSION`, `SB_CLICKED_POLICY` and `ADD_TO_CART`, each with a shared `vi`. ## Example A shopper on a product page adds a product together with a 2-year plan: ```javascript fetch const visitId = sessionStorage.getItem("sb_visit") ?? crypto.randomUUID(); sessionStorage.setItem("sb_visit", visitId); await fetch("https://api-external.surebright.com/events/api/event", { method: "POST", headers: { "Content-Type": "application/json", "Accept": "application/json" }, keepalive: true, body: JSON.stringify({ eventList: [ { et: "ADD_TO_CART", sid: "your-store.myshopify.com", vi: visitId, pf: "SHOPIFY", ct: "US", ps: "ATC_BUTTON#PRODUCT_PAGE", etime: new Date().toISOString(), sqid: "7b9a6c31-f6c5-4110-a1f4-c69dca10ab06", sqiid: "047cd751-8737-45cd-b113-227312a88d51", pd: { p_pid: "6673746231399", p_vid: "39876543210987", p_pp: "649.99", p_pq: 1, p_plpid: "7080029454439", p_plvid: "40937702359143", p_plq: 1, p_plp: "69.00", p_pt: "2Y", p_dc: "USD", isqa: true } } ] }) }); ``` ```bash curl curl -X POST https://api-external.surebright.com/events/api/event \ -H "Content-Type: application/json" \ -d '{ "eventList": [{ "et": "ADD_TO_CART", "sid": "your-store.myshopify.com", "vi": "3f1c9e0a-2d5b-4c7e-9a1f-0b6d8e4c2a71", "pf": "SHOPIFY", "ct": "US", "ps": "ATC_BUTTON#PRODUCT_PAGE", "etime": "2026-11-09T14:03:21.512Z", "sqid": "7b9a6c31-f6c5-4110-a1f4-c69dca10ab06", "sqiid": "047cd751-8737-45cd-b113-227312a88d51", "pd": { "p_pid": "6673746231399", "p_vid": "39876543210987", "p_pp": "649.99", "p_pq": 1, "p_plpid": "7080029454439", "p_plvid": "40937702359143", "p_plq": 1, "p_plp": "69.00", "p_pt": "2Y", "p_dc": "USD", "isqa": true } }] }' ``` For an add-to-cart **without** protection, send the same `ADD_TO_CART` event with `p_plpid`, `p_plvid`, `p_plp`, `sqid` and `sqiid` as empty strings, `p_plq: 0` and `p_pt: "0Y"`. That is exactly what the SDK sends, and the empty `p_plpid` is what analytics uses to tell the two apart. ## Behaviour to copy from the SDK - Batch up to 10 events per request; send immediately on add-to-cart, otherwise when the batch fills or the page unloads (`keepalive: true`). - Keep events you could not send and retry them on the next page load. - On Shopify, send nothing until the shopper's analytics consent allows it (see [Consent gating](/frontend-widget-integration/frontend-widget-kit/placements#analytics-events-and-consent)). - Do not send events from crawlers or your own test tooling; they count as shoppers. --- # Headless and custom storefronts Source: https://docs.surebright.com/frontend-widget-integration/frontend-widget-kit/headless-and-custom-storefronts > A guide to running the SureBright SDK outside the Shopify theme app embed: declaring your store and platform, giving the SDK page context, keeping cart line properties intact, and what fails when a step is skipped. On a Shopify Online Store theme the SureBright app embed loads the SDK, tells it which store it is on, and hands it a cart it already knows how to read. On a headless build (Hydrogen, Shopyflow on Webflow, or your own front end) none of that is given. You own the script tag, the cart, and the page, so you have to supply what the embed would have supplied. This guide walks through those pieces in order and ends with what breaks when one is missing. The exact attributes, globals and line-item properties are specified in the [JavaScript API Reference](/frontend-widget-integration/frontend-widget-kit/javascript-injection); this page explains how they fit together and does not repeat the field tables. ## Which path are you on | Storefront | Adapter the SDK uses | What you need to do | | --- | --- | --- | | Shopify Online Store theme | `shopify` | Nothing here. Turn on the app embed; see [Storefront setup](/shopify/storefront-setup). | | Shopify Hydrogen / Remix | `shopify-hydrogen` | Everything on this page, plus the Hydrogen loader and cart-action requirements in [SDK Installation](/frontend-widget-integration/frontend-widget-kit/sdk-installation#shopify-hydrogen-and-other-headless-shopify-builds). | | Shopyflow (Shopify on Webflow) | `shopify-shopyflow` | Steps 1, 2 and 4 below. The SDK reads Shopyflow's own globals for the rest. | | Another headless Shopify front end | none yet | Talk to SureBright before building. The SDK can only drive carts it has an adapter for. | | BigCommerce, WooCommerce | `bigcommerce`, `woocommerce` | Wired by the SureBright integration for that platform. | `custom` is also accepted as a platform name, but that adapter reads no product data and has no cart, so no offer renders and nothing can be added. Use it only when SureBright asks you to. ## Step 1: declare the store and platform on the script tag Load the script once per page and tell it who you are: ```html ``` - `data-sb-store-id` is the store identifier SureBright gave you. For Shopify-backed storefronts that is the `*.myshopify.com` domain, not your public hostname. The SDK does not keep a list of customer domains, so it cannot work this out from the URL. - `data-sb-platform` is matched case-insensitively against `SHOPIFY`, `HYDROGEN`, `SHOPYFLOW`, `BIGCOMMERCE`, `WOOCOMMERCE` and `CUSTOM`. Setting `window.__SUREBRIGHT_PLATFORM__` before the script (lower-case names such as `shopify-hydrogen`) does the same thing and is checked next. The SDK reads these from `document.currentScript` while it executes, then falls back to the first ` ``` Accepted values: `shopify`, `shopify-hydrogen`, `shopify-shopyflow`, `bigcommerce`, `woocommerce`, `custom`. Detection order: a `data-sb-platform` attribute on the SDK ` ``` Both fields are optional strings (trimmed, truncated to 120 characters). Fallbacks: `themeId` from `window.Shopify.theme.id`, `templateSuffix` from ``. Only set these if SureBright has configured a theme- or template-specific design for your store; otherwise the default configuration is used. ## Debugging | Switch | Effect | | --- | --- | | `?sb_debug` in the URL | Turns on console logging for this page load. | | `localStorage.setItem("sb_debug", "true")` | Turns on console logging for every page load until removed. | | `window.__SUREBRIGHT_DESTROY__()` | Tears down widgets, interceptors, and listeners created by the SDK. Reload the page to get them back. | Log lines are prefixed `[SB] [CATEGORY]` (categories include `INIT`, `CONFIG`, `PLATFORM`, `QUOTES`, `INTERCEPTOR`, `WIDGET`, `CART`, `SYNC`, `ANALYTICS`, `VARIANT`). In the shipped bundle all levels, including warnings and errors, are silent unless debug mode is on. The SDK also keeps the last 100 log entries in memory for SureBright's own tooling; there is no public accessor. `window.__SB_DIAG__` is **not** created by the storefront SDK. It is populated by a separate diagnostic script that SureBright engineers paste into the console; you can ignore it. ## Custom elements The SDK renders its UI as custom elements, each with an open shadow root, so your theme CSS does not leak in and the widget CSS does not leak out. Styling is controlled through the store's design configuration in SureBright, not by overriding these elements. | Element | Where | | --- | --- | | `sb-product-widget` | Product page and quick view offering | | `sb-warranty-offering-modal` | "What's covered" / plan selection modal | | `sb-cart-cta`, `sb-bottom-cart-cta` | Cart page and cart drawer calls-to-action | | `sb-line-item-badge`, `sb-warranty-details`, `sb-si-details` | Cart line decorations | | `sb-checkout-widget` | Checkout offering (platforms that render SDK UI in checkout) | | `sb-shipping-insurance`, `sb-shipping-insurance-popup`, `sb-shipping-insurance-cart-popup` | Shipping protection | | `sb-post-purchase-modal` | Post-purchase / thank-you offering | | `sb-registration-page` | Product registration page | Elements the SDK inserts carry a `data-sb-widget-surface` attribute (for example `quickview`) and, for inline product offerings, `data-sb-surface="embedded"`. Use these to detect the widget in your own scripts; do not move or restyle them. --- # Placements Source: https://docs.surebright.com/frontend-widget-integration/frontend-widget-kit/placements > Where the SureBright widget can appear on a storefront, how each surface is anchored, and how analytics and consent work across them. The SDK can render the protection offer on several surfaces. Each one is switched on per store and anchored to your theme with CSS selectors that SureBright keeps in the store's widget configuration, not in your code. When the SDK starts it fetches that configuration, works out which page it is on, and mounts only the surfaces that are enabled for that page. Nothing on this page needs code from you. If a surface is missing, mis-anchored, or appears where it should not, tell SureBright which page and element it should attach to and we change the selector on our side. On stores that use Studio, these selectors are worked out by SureBright's **store onboarding agent**. It drives a real browser through the storefront, finds the anchor for each surface, and checks it against the live page before the design is saved. See [The storefront scan](/merchant-portal/onboarding#the-storefront-scan). ## How anchoring works For each surface the configuration carries one or more CSS selectors (the **anchor**) plus, where it matters, an insertion position relative to the anchor (`beforebegin`, `afterbegin`, `beforeend`, `afterend`; the default is `beforeend`). If none of the configured selectors match, the SDK tries a per-platform list of fallback selectors (`fallbackAnchorSelectorsList`) and, failing that, logs the miss in debug mode and renders nothing. Selectors are grouped by surface: | Configuration section | Selector keys | | --- | --- | | `pdp` | `offeringWidgetAnchor`, `addToCartButton`, `addToCartForm` | | `quickView` | `addToCartButton` | | `cart` | `lineItemContainer`, `lineItemProductImage`, `lineItemWarrantyCTAAnchor` | | `cartDrawer` | `container` | | `cartNotification` | (enabled flag; selectors resolved from the theme) | | `checkout` | `offeringWidgetAnchor` | | `shippingInsurance` | `offeringWidgetAnchor` | | `collectionPage` | `policyProductCardSelectorList` | | `policyProductPage` | elements to hide on the protection product's own page | | `warrantyRegistration` | registration form and search selectors | Rendered elements are custom elements with shadow DOM (listed in the [JavaScript API Reference](/frontend-widget-integration/frontend-widget-kit/javascript-injection#custom-elements)), so theme CSS does not affect them. Appearance is controlled by the design configuration SureBright holds for the store. ## Surfaces The main offering: plan cards (grid, stacked, dropdown, or checkbox layouts, as configured) rendered as `sb-product-widget` at the `pdp.offeringWidgetAnchor`, normally next to the add-to-cart button. The SDK follows variant changes (URL, form inputs, or theme globals) and refreshes quotes. Depending on configuration, adding to cart without a selection can open a plan modal (`sb-warranty-offering-modal`) before the item is added; the SDK intercepts the theme's add-to-cart request (form submit, fetch, XHR, or GraphQL) to add the protection line alongside the product. Shop Pay / dynamic checkout buttons are handled when the store enables it. When the theme opens a product in a quick-view modal, the SDK detects it (`quickView.enabled`), renders the same offering inside the modal with `data-sb-widget-surface="quickview"`, and intercepts the modal's add-to-cart button (`quickView.addToCartButton`). Selection-change callbacks from here report `source: "quickview"`. Three things can appear on the cart page, each enabled separately: - **Add-protection call-to-action** (`sb-cart-cta`) next to an unprotected product line, anchored at `cart.lineItemWarrantyCTAAnchor` inside each `cart.lineItemContainer`. Clicking it opens the plan modal; selection callbacks report `source: "cart"`. - **Line decorations** on protection lines: a badge (`sb-line-item-badge`) and a coverage summary (`sb-warranty-details`), with a "change plan" action where enabled. - **Bottom cart call-to-action** (`sb-bottom-cart-cta`), a single toggle for the whole cart. The SDK also runs **cart sync** here: it keeps each protection line's quantity equal to the product line it covers, removes protection whose product was removed (orphans), and de-duplicates protection lines, using the `_sbQuoteId`, `_variantId` and `_sbAddedAt` line-item properties. The same cart surfaces inside a slide-out cart (`cartDrawer.container`). The SDK observes the drawer for open/close state and DOM re-renders and re-mounts its elements after the theme refreshes the drawer's sections. When enabled (`cartNotification.enabled`), the SDK places an offer for the just-added item inside the theme's "added to cart" notification/popup so shoppers can add protection without leaving the page. No offer is shown on collection pages. The SDK's job there is housekeeping: it hides SureBright's own protection products from product grids using `collectionPage.policyProductCardSelectorList`, so shoppers do not see "Extended Protection Plan" as a buyable product. The suppression re-runs on `popstate`, on `load`, and whenever a `sb:cart-sections-refreshed` event is dispatched on `document`, so themes that re-render grids client-side can trigger it. (The same applies on the protection product's own page, where the add-to-cart form is hidden via the `policyProductPage` selectors.) On platforms where the SDK can run inside checkout, a compact offer (`sb-checkout-widget`: checkbox, toggle, button, or link style) is mounted at `checkout.offeringWidgetAnchor`. Shopify's checkout does not run storefront scripts; there, the offer is delivered by SureBright's checkout UI extension that ships with the Shopify app, not by this SDK. Selection callbacks from either report `source: "checkout"`. A separate opt-in (`sb-shipping-insurance`) for shipping-related loss or damage, rendered on the cart page or drawer at `shippingInsurance.offeringWidgetAnchor`, with its own explainer popup. When the shopper opts in the SDK adds a shipping-protection line carrying `_sbQuotePlatform = PLATFORM_SHIPPING_INSURANCE`, re-quotes it as the cart changes, and removes it when the cart no longer qualifies. Selection callbacks report `source: "shippingInsurance"`. On the order confirmation page (`/thank_you`, `/thank-you`, `/orders/…`, or `/order-confirmation`, by platform) the SDK can open `sb-post-purchase-modal`, offering protection for eligible items the shopper just bought. Accepting adds the plan to the cart for the shopper to check out; that line carries `_quotePlatform = PLATFORM_POST_PURCHASE` and `_sbPurchasedQuantity`. Selection callbacks report `source: "postPurchase"`. A standalone page (`sb-registration-page`) where a shopper finds a product they already own, enters the purchase date, and buys protection for it. The SDK mounts it when the URL matches the store's registration paths; by default `/pages/extended-product-protection` and `/pages/product-registration`. The Shopify app embed always injects the SDK on these paths. Selection callbacks report `source: "registration"`. For bundle products the SDK can quote each component separately and add one protection line per component. Those lines carry `_isBundleComponentPolicy="true"`, `_bundleParentVariantId`, `_bundleParentProductId` and `_componentQuantity`, and cart sync keeps them aligned with the bundle's quantity. Bundle handling depends on the store's bundle app and is enabled per store. ## Analytics events and consent Every surface reports shopper interactions to SureBright's event collector so the merchant portal can show offer impressions, plan clicks, add-to-cart with and without protection, and experiment exposure. The event names and payload are documented in [Event Collector](/frontend-widget-integration/frontend-widget-kit/event-collector). Events are buffered and sent in batches of up to 10; add-to-cart events are sent at once. Events that could not be sent are kept in `sessionStorage` (`sb_analytics_pending_event_list`) and retried on the next page load. ### Consent gating on Shopify On Shopify storefronts the SDK honours the shopper's privacy choices through Shopify's Customer Privacy API: - It loads `consent-tracking-api` via `Shopify.loadFeatures` and listens for the `visitorConsentCollected` document event. - Analytics are sent only when `analyticsProcessingAllowed()` is true, or the current visitor consent for analytics is not `"no"`. Until consent is known, events stay buffered; once consent is granted the buffer is flushed, and if it is refused nothing is sent. - Stores that do not use Shopify's consent banner (so `Shopify.loadFeatures` is absent) are treated as allowed. On non-Shopify platforms the SDK has no consent integration and always reports. If your storefront has its own consent manager and must block SureBright analytics, tell SureBright; there is currently no public switch for it in the SDK. Widget rendering and cart behaviour are never gated by consent; only analytics reporting is. **See also:** [What merchants can change on the widget](/merchant-portal/widget-options), [Building your own offer](/merchant-portal/widget-options#building-your-own-offer). --- # SDK Installation Source: https://docs.surebright.com/frontend-widget-integration/frontend-widget-kit/sdk-installation > How the SureBright storefront SDK gets onto a page: the Shopify theme app embed, the manual script tag for custom storefronts, and what Hydrogen and other headless builds must provide. The SureBright widget is one script, `sbsimxsdk*.js`, served from `https://cdn.surebright.com/`. It starts itself when it loads and reads everything it needs (which widgets to show, where, in what design) from the configuration SureBright keeps for your store. There are no keys to paste and no init call to make. How the script reaches the page depends on your platform. ## Shopify (Online Store themes) Nothing to code. When the SureBright app is installed, its theme app extension adds an app embed block named **SureBright Offering** to the theme. Make sure it is switched on under **Online Store → Themes → Customize → App embeds**. The block decides which SDK file to load from a per-store app metafield, `config.sb_sdk_version`, that SureBright sets for you: | `config.sb_sdk_version` | Script loaded | | --- | --- | | `v0` | `https://cdn.surebright.com/sbsimxsdkv0.js` | | `v1` | `https://cdn.surebright.com/sbsimxsdk.js` | | `v2` | `https://cdn.surebright.com/sbsimxsdkv2.js` | | `dynamic_pricing_v0` | `https://cdn.surebright.com/sbsimsdk_dynamic_pricing_v0.js` | | not set | The legacy script bundled with the app extension (`sbsimsdk.js`) | The only accepted values are the four above; SureBright's install endpoint rejects anything else. A second metafield, `config.sb_sdk_page_type_list`, can limit the Shopify page types the script is injected on. Product, cart, collection and index pages, plus `/pages/extended-product-protection` and `/pages/product-registration`, are always included when a `v0`/`v1`/`v2` version is set. Do not add the manual script tag below to a Shopify theme that already has the app embed enabled. The SDK guards against running twice, but the extra request is wasted and makes debugging confusing. Magento and Salesforce Commerce Cloud stores are also wired up by the SureBright integration for that platform; there is nothing to do here. ## Custom storefronts: add the script tag If you built your own front end (Hydrogen, Next.js, or any custom stack), add the script once, in the place that applies to every page, so it runs on product, collection, cart, and checkout pages. ```html Static tag ``` ```html Dynamic injection ``` Keep the `id` as `sbsimxsdk` and include the tag only once per page. SureBright will tell you if your store should load a different file name (for example `sbsimxsdkv2.js`); the tag is otherwise identical. Two optional attributes on the tag are read by the SDK: | Attribute | Purpose | | --- | --- | | `data-sb-store-id` | The store identifier SureBright gave you. **Required for Hydrogen**, where there is no `window.Shopify.shop` to read it from. | | `data-sb-platform` | Forces the platform adapter (`shopify`, `shopify-hydrogen`, `shopify-shopyflow`, `bigcommerce`, `woocommerce`, `custom`, any case). Equivalent to setting `window.__SUREBRIGHT_PLATFORM__` before the script. | ## Shopify Hydrogen and other headless Shopify builds The SDK has a dedicated Hydrogen adapter. It can usually detect Hydrogen on its own, but declaring it is cheaper and avoids a wrong guess on pages without the usual markers: ```html ``` The adapter works with the conventions of the Hydrogen skeleton template. Your app must keep the following in place: The SDK reads the hidden `input[name="cartFormInput"]` that Hydrogen's `CartForm` renders inside the product form to learn the selected variant (`inputs.lines[0].merchandiseId` as a `gid://shopify/ProductVariant/...` id) and, when present, `selectedVariant.price.currencyCode`. Keep that input in the DOM and keep its value up to date when the shopper changes variants. The SDK reads the cart by fetching `/cart.data` and the product route's `.data` loader (`/products/{handle}.data`). The cart loader must return the cart with `lines` and each line's `attributes { key value }`, which the SDK treats as the line's properties. To add, change, or remove protection the SDK `POST`s to `/cart.data` with a form-encoded `cartFormInput` such as `{"action":"LinesAdd","inputs":{"lines":[{"merchandiseId":"gid://shopify/ProductVariant/…","quantity":1,"attributes":[{"key":"_sbQuoteId","value":"…"}]}]}}`. It also sends `LinesUpdate` and `LinesRemove`. These requests include `credentials: "include"` and an `X-SB-Internal: 1` header. Your cart action must pass `attributes` through to the Storefront API unchanged; dropping them breaks order attribution (see [Cart line-item properties](/frontend-widget-integration/frontend-widget-kit/javascript-injection#cart-line-item-properties)). The SDK watches `fetch` responses for `/cart.data` and observes DOM changes to keep its view of the cart current and to reconcile protection quantities with product quantities (cart sync). If you use a custom fetch wrapper, make sure the real `fetch` responses still flow through `window.fetch`. Page type on Hydrogen is derived from the path: `/products/` is a product page, `/cart` the cart, `/collections/` a collection, `/checkout` checkout, and `/thank-you` or `/orders/` the post-purchase page. Keep these conventional paths if you want the matching surfaces to render. ## Verify Open a product page and confirm the SDK file loads in the browser's Network tab. Then add `?sb_debug` to the URL and watch the console for `[SB]` lines: you should see the platform being detected and the configuration being loaded. If detection times out after 15 seconds, the platform override above is the first thing to add. More switches are listed under [Debugging](/frontend-widget-integration/frontend-widget-kit/javascript-injection#debugging). Once the script is on your storefront, tell the SureBright team. We finish configuration on our side (placements, design, which surfaces are on) and test with you before enabling the widget for shoppers. If your own code needs to react when a shopper adds or removes protection, see the [JavaScript API Reference](/frontend-widget-integration/frontend-widget-kit/javascript-injection). If your storefront does not let the SDK observe shopper behaviour, see [Event Collector](/frontend-widget-integration/frontend-widget-kit/event-collector). --- # Shipping protection widgets Source: https://docs.surebright.com/frontend-widget-integration/frontend-widget-kit/shipping-protection-widgets > The storefront surfaces that offer shipping protection: the cart widget and its layouts, the coverage pop-ups, the in-cart line treatment, and the checkout block, with how each is enabled. Shipping protection is a separate opt-in from product protection: one small fee that covers the whole shipment against loss, damage and theft in transit. What it covers, how it is priced and what happens when an order ships is described in [Shipping protection](/shipping-protection/overview). This page is about what the shopper sees on the storefront and how those surfaces are switched on. Shipping protection is enabled per store by SureBright. Once it is on, the SDK quotes the cart, shows the offer in the cart, and keeps exactly one shipping-protection line in step with what is in the cart. Nothing is needed from the theme beyond an anchor SureBright configures. ## The cart widget The widget (`sb-shipping-insurance`) is mounted on the cart page and in the cart drawer at the anchor configured for your store, usually just above the **Checkout** button. It appears only when SureBright returns a shipping quote for the eligible items in the cart; a cart with nothing eligible shows nothing. Two interaction modes are available: | Mode | What the shopper sees | | --- | --- | | Checkbox (default) | A checkbox row reading **Add Shipping Protection for $X**, with the description **Protection against package damage, loss, theft, missing items and much more** and a **see complete coverage** link. Variants of this row exist with your logo inline, as a compact card, or as a table row for themes that render the cart as a table. | | Button | A card with the shipping-protection icon, the title **Shipping Protection**, the same description and coverage link, a **powered by** SureBright line, and an **Add Shipping Protection for $X** button. | Ticking the box or pressing the button adds the shipping-protection line; doing it again removes it. The price is recalculated whenever the cart changes. The texts above are SureBright's defaults and can be changed per store, as can the icon colour theme and whether co-branding is shown. Stores still on SureBright's earlier widget build see one of three equivalent templates: a card with a shipping illustration, checkbox and info icon; a compact checkbox row; or the compact row placed inside a cart table row. Which one a store uses is set by SureBright. ## The coverage pop-up **see complete coverage** opens a pop-up with the coverage list for the quote. Two layouts exist, chosen per store: | Layout | Contents | | --- | --- | | Standard coverage (`sb-shipping-insurance-popup`) | The coverage rows with their icons, a **Why SureBright** strip, a shipping illustration, and **Protect my purchase** and **No, thanks** buttons. | | Cart eligible items (`sb-shipping-insurance-cart-popup`) | A headline **Protect your $X worth of items for just $Y** (the amounts are the eligible cart value and the fee), the coverage rows, a trust rating with your logo and SureBright's, a list of the eligible items in the cart, and the same two buttons. | Choosing **Protect my purchase** in the pop-up adds the line exactly as the widget does. The headline, headings, button labels and footer text are configurable per store by SureBright. ## The line in the cart When shipping protection is in the cart it is a line item named **Shipping Protection Powered by SureBright**, a product SureBright created in your catalogue. The SDK relabels that row with a branded card (`sb-si-details`) showing the title, description and coverage link, and locks the row's quantity controls while leaving the remove control working. The line always has quantity 1; if a theme or app changes it, the SDK sets it back. The SDK re-evaluates the line whenever the cart changes: | Cart state | Result | | --- | --- | | Eligible items changed, new quote returned | The fee on the widget updates; if the quote now points to a different protection variant, the line is swapped. | | No eligible items left | The line is removed. On headless storefronts this waits for a second confirming read about 2.5 seconds later. | | SureBright declined to quote the cart (for example the shipping value is above the limit) | The line is removed, so the shopper is not charged for cover that does not exist. | | Quote request failed for a technical reason | The line is left alone until the next successful quote. | | More than one shipping-protection line | Collapsed to one. | The line carries `_sbQuotePlatform = PLATFORM_SHIPPING_INSURANCE`, `_sbQuoteId` and `_sbAddedAt`; these must reach the order unchanged. See [Cart line-item properties](/frontend-widget-integration/frontend-widget-kit/javascript-injection#cart-line-item-properties). When the cart line badges are enabled for your store, products covered by shipping protection also get a shipping-protected badge on their own cart rows. ## In checkout Shopify's checkout does not run storefront scripts. On Shopify Plus the offer continues inside checkout through the **SureBright Protection Block**, a checkout UI extension that ships with the app: a checkbox below the cart lines reading **Add Shipping Protection for $X**, re-quoted when the shipping address changes. It is placed from the checkout editor and documented in [Checkout extensions](/shopify/checkout-extensions). On other plans the cart widget is the last place the shopper can opt in. ## Enabling it Shipping protection is a store-level setting SureBright enables. It needs the shipping-protection product in your catalogue, which SureBright creates. Shipments are covered to United States addresses only; see [Orders that cannot be covered](/shipping-protection/overview#orders-that-cannot-be-covered). Tell SureBright where in your cart page and drawer the widget should sit. The anchor is a CSS selector kept in your store's configuration, not in your theme code. Checkbox or button, standard or cart-items pop-up, and any copy changes. All of this is configured by SureBright. Follow [Checkout extensions](/shopify/checkout-extensions) to place the Protection Block. ## For developers The widget dispatches `sb-widget-event` with `SHIPPING_INSURANCE_TOGGLED`, `SHIPPING_INSURANCE_DIALOG_OPEN`, `SI_COVERAGE_LINK_CLICKED`, `SI_PROTECT_CLICKED` and `SI_DECLINE_CLICKED`, and `window.SureBright.onSelectionChange` reports changes with `source: "shippingInsurance"` and a `null` product. Both are described in the [JavaScript API Reference](/frontend-widget-integration/frontend-widget-kit/javascript-injection). With `?sb_debug` the orchestrator logs under `[SB] [SHIPPING]`. --- # Contact SureBright support Source: https://docs.surebright.com/help/contact-support > How you and your customers reach SureBright, where to ask from inside the Merchant Portal, and what to include so a request can be answered in one reply. This page lists every way to reach SureBright, for you and for your customers, and what to put in a request so the team does not have to write back for details. ## How you reach SureBright Email [support@surebright.com](mailto:support@surebright.com) or call **+1 855-306-4874**. Inside the Merchant Portal you can also start from these places: | Where | What it gives you | | --- | --- | | **Help**, at the bottom of the sidebar | **Common questions** by topic with a search box, **Tour the portal** walkthroughs, and under **Still need help?** the support email and phone number. | | [Ray](/merchant-portal/ray), the launcher at the bottom right of every page | An assistant you can ask about your sales, billing, products and orders, and about how the portal works. For anything else it points you to support. Available on request. | | **Comments** on an [Order Resolution](/merchant-portal/order-resolution#leave-a-comment-for-surebright) case | A thread on that order which SureBright's team reads. A comment does not resolve the case. | | **Contact support** in a payment status dialog | Shown when adding or changing a payment method fails, with a reference you can quote. See [Billing](/merchant-portal/billing#payment-methods). | | **Need help? Contact support**, at the foot of the sign-in page | Opens an email to support when you cannot sign in. | | The **book a call** prompt in the page header | Shown while your store is in review. | Ray is the only chat in the portal. ## How your customers reach SureBright Customers can contact SureBright directly. You do not need to relay their messages. - **Customer portal.** At **https://customer.surebright.com** the customer signs in with the email address used on the order. **Help** there has the FAQ and a contact form. See [Customer portal](/customer-portal/overview). - **Email and phone.** [support@surebright.com](mailto:support@surebright.com) and **+1 855-306-4874**. The plan emails SureBright sends a customer come from that address and tell the customer to reply to it or call. - **Claims.** Claims are filed in the customer portal, from the plan's card. A reply to any claim email is threaded onto that claim. See [Filing a claim](/claims/filing-a-claim). - **Shipping protection.** Shipping claims are filed in the customer portal too. See [Shipping claims](/shipping-protection/claims). ## What to include Start every request with your **store URL**, as shown on the **Store details** card in the portal's **Settings**. Then add what fits the request. | Request about | Include | | --- | --- | | The widget or your storefront | The URL of the product or cart page where the problem shows. What you see and what you expected. A screenshot. Whether you changed your storefront's design, theme or apps recently. On Shopify, also the status of your live theme in [Settings → Storefront setup](/merchant-portal/settings#check-your-shopify-storefront-setup). | | An order or a contract | The order number as your store admin shows it. The **Policy ID** from the contract's **Contract Details** in [Sales](/merchant-portal/sales). What looks wrong: the status, the covered product or the customer details. If the order has an Order Resolution case, comment on the case instead. | | A claim | The claim number, which the customer sees when the claim is filed and under **Claims** in the customer portal. The email address on the order, and the order number. For a claim that has stalled, how long it has waited and what the customer was last told; see [When a claim seems stuck](/claims/overview#when-a-claim-seems-stuck). To file for a customer, see [Filing a claim](/claims/filing-a-claim#file-a-claim-for-a-customer-without-the-adjudicator-portal). | | A shipping claim | The order number and the shipment's tracking number. Anything the carrier told you, such as a signed proof of delivery. | | Being paid back on a claim | The claim number, and the invoice or estimate for the replacement, parts, repair or shipping you supplied. See [When you supply the replacement, parts or repair](/claims/resolutions-and-payouts#when-you-supply-the-replacement-parts-or-repair). | | Billing | Which invoice, from **Billing → Billing History**, and the figure you cannot trace. Run **Analyse →** on the invoice first: timing differences are explained there and never need a ticket. See [Invoice analysis](/merchant-portal/invoice-analysis). For a failed payment method, quote the reference from the status dialog. | | The API | Which API call you made and when, what you sent, and the full error you got back. If a contract was created, its contract ID. Do not send your API key. | | Who can sign in | The name and email address of the person to add or remove. See [Team and access](/merchant-portal/team-and-access). | | A customer's data | On Shopify, the Shopify customer id or order number, and the date you sent the request from Shopify. See [customer data requests](/shopify/gdpr). On other platforms, ask your SureBright contact how to send the request. | | A feature available on request | The name of the feature. | Send one request per subject, and write order numbers exactly as your store admin shows them. For your developers: endpoints, keys and error responses are described in the [API reference](/api-reference/introduction). ## Related Short answers to the most common questions, each linked to its page. What to do when a customer asks about cancelling, returns, emails or a claim. What the portal assistant can look up and change. The Help page, your store card and the header prompts. --- # Merchant FAQ Source: https://docs.surebright.com/help/faq > Short answers to the questions store owners, operations and support staff ask most about running a SureBright protection-plan program, each linked to the page that covers it in depth. Each answer below is short and ends with a link to the page that covers the topic fully. If your question is not here, write to [support@surebright.com](mailto:support@surebright.com) or call **+1 855-306-4874**. For the concerns that come up most, with what to do about each, see [Common concerns](/learn/overview). For charges, credits and invoices, see [Payment questions](/merchant-portal/payment-questions). ## Getting started and going live ### How do I sign in to the Merchant Portal? It depends on your platform. Whichever way you come in, you land on **Sales**. | Platform | How you sign in | | --- | --- | | Shopify | Enter your **Store URL** (for example `mystore.myshopify.com`) and click **Sign in**. Shopify asks you to approve access and sends you back to the portal. | | BigCommerce | Open the SureBright app from your BigCommerce control panel. | | WooCommerce | Open the plugin's **Merchant Portal** page in your WordPress admin and click **Login**. | | Magento | Click **Login Now** on the SureBright page in your Magento admin, then use the credentials SureBright shared with you. | | Other platforms | Use the Store ID and password SureBright shared with you. | There are no role settings to manage; see [Team and access](/merchant-portal/team-and-access) for giving a colleague access. See [Merchant Portal overview](/merchant-portal/overview). ### What do the store statuses on my account card mean? **Live** means the store is approved and protection is offered on your storefront. **In review** means SureBright is still reviewing the store, and the header carries a **book a call** prompt meanwhile. **Not installed** means no storefront is connected yet, and **Not approved** means the store was not approved; contact support. See [Your store card](/merchant-portal/overview#check-your-stores-status). ### Why is there no protection offer on my product pages? The offer appears only on products whose category is eligible, and only once your store card reads **Live**, so test on a product that qualifies first. If that product shows nothing, check that SureBright is switched on in your storefront: - **On Shopify**, the **SureBright Offering** app embed must be on in your live theme. Open **Settings → Storefront setup** and check the badge next to your **Live theme**; if it reads **Not turned on**, click **Turn on in Shopify ↗**, switch the embed on and **Save**. See [Storefront setup](/shopify/storefront-setup). - **On Magento**, confirm the integration reads **Authorized** and purge caches from the SureBright page in your Magento admin. See [Storefront widget](/magento/storefront-widget). - **On BigCommerce and Shift4Shop**, check that the two SureBright scripts are still listed in your store admin. See [BigCommerce](/bigcommerce/overview) and [Shift4Shop](/shift4shop/overview). - **On other platforms**, ask your SureBright contact. For a step-by-step check, see [Offer not showing?](/help/offer-not-showing). ### Why do some products show an offer and others do not? A product needs a SureBright category before protection can be turned on, and one marked **Under Review** cannot be changed until the review finishes. Some categories are priced on the manufacturer's warranty length; until you set it from the **Mfr warranty** chip, that product shows no offer. A bundle whose components fall into different categories is not offered a plan. See [Products](/merchant-portal/products). ### What does the storefront scan do, and does it change my storefront? It looks at your storefront the way a shopper would. It reads one product page for your colours, fonts and corner style, and works out where the widget should sit on the product page and in the cart, so your first design already matches your store. Nothing is added to your storefront's code, and nothing goes live until you publish. Studio, where the scan runs, is available on request. See [Onboarding](/merchant-portal/onboarding#the-storefront-scan). ### I installed SureBright. What happens next, and when will we be live? SureBright reviews your store, sets up your categories and plans with you, and switches the offer on once you have approved how it looks and added a payment method. See [After you install](/merchant-portal/onboarding#after-you-install-the-path-to-going-live). ### Which permissions does the Shopify app need, and why must they stay granted? The app reads products and orders to price and record plans, and manages the plan products in your catalogue. If you remove or refuse a permission, offers or contracts stop. See [Store access and permissions](/platforms/store-access#shopify-app-permissions). ### Is a collaborator request from SureBright genuine, and should I share a login? See how to check a request and why you should never share passwords in [Store access](/platforms/store-access#collaborator-requests-from-surebright). ### Can we try SureBright on a few products before a full launch? Yes. See [Start with a few products](/platforms/test-your-setup#start-with-a-few-products). ### Our platform is not listed. What would we need to build? See [If your platform is not listed](/platforms/other-platforms#what-an-integration-needs). ### Which products and plan lengths can SureBright cover? See [Which categories and plan lengths are covered](/contracts/what-can-be-covered#which-categories-and-plan-lengths-are-covered), including [used and refurbished stock](/contracts/what-can-be-covered#used-refurbished-and-open-box-products) and [products sold for business use](/contracts/what-can-be-covered#products-sold-for-business-use). ## Pricing, margins and billing ### Who collects the money when a shopper buys a plan? You do. The plan is a line item in your own checkout, so you collect the plan price with the rest of the order. SureBright then invoices you the net: the plan price less your margin. SureBright does not send you payouts or commission payments: your share stays with you from the moment the shopper pays. Any billed order shows **Total Warranty Price**, **Your Margin** and **Net to SureBright** side by side. See [Billing](/merchant-portal/billing). ### How does SureBright bill me? Once a month, at the start of the month, for the plans that became billable since your last invoice. The invoice is charged to your default payment method, and the PDF is emailed to you once the payment is confirmed. **Billing Status** reads **Processed** (paid) or **Pending** (issued, not yet paid). The **Net Amount Calculation** shows charges, carryover, refunds for cancellations and credits, and **Download Billed Orders** exports every order billed to you. See [Invoices and charges](/merchant-portal/invoices-and-charges) and [Payment questions](/merchant-portal/payment-questions). ### Which payment methods can I use, and why is my bank account pending? You can add a credit card, debit card or bank account through a secure form provided by Stripe. Cards are usable at once. A bank account may show **Your bank account is being verified**, or ask you to enter the amounts of small deposits the bank sends before it can be used. See [Payment Methods](/merchant-portal/billing#payment-methods). ### Why does my invoice not match the Sales page for the same period? Almost always timing, not an error. Open the invoice and click **Analyse →** to run the **Reconciliation Check**. Contracts that completed after the invoice was issued are **pending invoicing** and roll on to your next invoice; contracts cancelled after billing are listed under **Late Cancellations** and credited on your next invoice. See [Payment reconciliation](/merchant-portal/payment-reconciliation). ### What happens if an order was charged for more plans than it bought? The Reconciliation Check raises a red alert, **N duplicate contracts across N orders**. SureBright cancels the extra contracts and the amount you paid for them is refunded as a credit on next month's invoice. You do not need to request anything, and the customer's coverage is unaffected. See [The duplicate contracts alert](/merchant-portal/payment-reconciliation#if-you-see-a-duplicate-contracts-alert). ### Can I set my own plan prices? Yes, with **Warranty Pricing**, available on request. Reprice cells in the category grid or give one product its own price, then **Review & publish**. Every publish is kept as a version with its own attach figures, so you can see what a price change did. Each price has a minimum the page will not let you go below, and only the store owner or an admin can publish. See [Warranty Pricing](/merchant-portal/warranty-pricing). ### How is shipping protection priced? By price bands on the eligible value of the cart. The default is $2.50 for every $100 of eligible value, up to $5,000, and your margin is a percentage of the band fee agreed when the store was configured. Bands and margins differ between stores. See [Shipping protection](/shipping-protection/overview#how-shipping-protection-is-priced). ### Are there setup or monthly fees? No. For standard integrations there is no setup fee, no monthly or subscription fee and no minimum commitment. SureBright invoices you only for its share of the plans you sold, less refunds and credits. On some accounts a card payment to SureBright carries a card processing fee, which you avoid by paying from a bank account, and a custom implementation is priced with you before work starts. See [What SureBright charges you](/merchant-portal/how-billing-works#what-surebright-charges-you). ### Why is there a card processing fee on my invoice, and how do I avoid it? See [The card processing fee](/merchant-portal/payment-methods#the-card-processing-fee). ### Can we pay by wire, EFT or another method instead of a card? See [Pay by invoice instead](/merchant-portal/payment-methods#pay-by-invoice-instead). ### When am I invoiced and charged, and is this a bill or a payment to us? See [The billing cycle](/merchant-portal/invoices-and-charges#the-billing-cycle) and [Is this a bill or a payment to us](/merchant-portal/invoices-and-charges#is-this-a-bill-or-a-payment-to-us). ### How do I confirm SureBright received our payment? See [Check that a payment was received](/merchant-portal/invoices-and-charges#check-that-a-payment-was-received). ### What happens if we do not pay an invoice? See [What happens if we do not pay an invoice](/merchant-portal/payment-questions#what-happens-if-we-do-not-pay-an-invoice). ### Can we deduct cancellations from a payment? See [Can we deduct cancellations from this payment](/merchant-portal/payment-questions#can-we-deduct-cancellations-from-this-payment). ### Who pays for a discounted or free plan? See [Discounted and free plans](/merchant-portal/how-billing-works#discounted-and-free-plans). ### Why is the plan price on my site different from what I expected? See [Warranty Pricing](/merchant-portal/warranty-pricing#why-is-the-plan-price-on-my-site-different-from-what-i-expected). ## Orders and contracts ### When is a contract created after an order? You get one contract per plan unit, linked to the product unit it covers. When it is created depends on your platform: | Platform | The contract is created | | --- | --- | | Shopify | Once the order is paid. An unpaid order gets no contract until it is paid. | | Magento, BigCommerce, Shift4Shop | When the order that includes the plan is placed. | | WooCommerce | When the order is placed, once the four order webhooks are set up. See [WooCommerce](/woocommerce/overview). | | Salesforce Commerce Cloud | When the order job you schedule in Business Manager next runs. See [Jobs](/salesforce-commerce-cloud/jobs). | | Lightspeed, the POS portal and API integrations | See [What works on each platform](/platforms/overview#what-works-on-each-platform). | On stores whose coverage starts at shipment, the contract is created with the order and its coverage dates are set when the product ships. See [Contract statuses](/contracts/lifecycle). ### What do the contract statuses mean? Every contract has two statuses. One says whether the customer is covered: not active yet, active, cancelled or expired. The other says whether SureBright has billed you: not ready to bill, ready to bill, then charged. The portal's **Warranty status** column sums both up in one label. See [Contract statuses](/contracts/lifecycle). ### Why is a contract still pending or on hold? A contract that is not active yet always has at least one hold: a missing customer address, a product without a category, a plan waiting on fulfillment, or payment not yet captured, among others. The holds page says who clears each one (the customer, you or SureBright) and what you can do. Anything needing your decision appears in **Order Resolution**. See [Why a contract is on hold](/contracts/holds). ### When does coverage start and end? Coverage always ends one plan term after the day it starts. On most stores, accidental damage coverage starts on the plan purchase date, and breakdown plans that begin after the manufacturer's warranty start when that warranty ends. On fulfillment-based stores coverage starts the day the product ships. A plan bought after the product is dated from the product's purchase. See [When coverage starts](/contracts/effective-dates). ### What is Order Resolution, and what happens if nobody answers a case? **Order Resolution** queues orders where SureBright could not finish a plan on its own: which product a plan covers, whether to refund an extra unit, or a customer detail the order never carried. Cases SureBright can safely resolve itself are resolved 48 hours after they are raised if nobody answers, and the default outcome is a refund of the customer's plan. **I'll handle it** stops the clock; **or give me until** pushes the deadline out by 3, 7 or 14 days. See [Order Resolution](/merchant-portal/order-resolution). ### A customer bought a plan in a later order. Which product does it cover? On any platform, when SureBright cannot tell which product a plan covers, the order appears in Order Resolution for you to pick or associate the product. - **On Shopify**, SureBright first looks through the customer's recent orders, finds the product the plan was priced for and attaches the plan to that earlier purchase. Products already covered are skipped and quantities are respected. See [Plans bought in a later order](/contracts/plans-bought-later). - **On Shift4Shop**, a plan bought after the original order is matched to the product on that order. - **On other platforms**, ask your SureBright contact. ### How do I sell a plan over the phone or add one to a past order? It depends on your platform. - **On Shopify and Magento**, open **Leads** to add a plan to an order a customer already placed or to **Record manual order**; the draft order is created on your platform, where you collect payment, and the contract activates once it is paid. - **On Shopify**, you can also use the SureBright draft order extension inside Shopify admin. - **On any platform**, orders held in another system can be sent as a spreadsheet, on request, and sales made at a counter can be recorded in the SureBright POS portal. See [Manual and draft orders](/manual-orders/overview). ### A customer paid for a plan but it is not in Sales. What do I check? See [A paid plan is missing from Sales](/merchant-portal/sales#a-paid-plan-is-missing-from-sales). ### Why is the plan line unfulfilled in my order or shipping tools? See [How the plan line is fulfilled](/learn/plans-in-your-order-tools#how-the-plan-line-is-fulfilled). ### A customer is just outside the window to buy a plan. Can you make an exception? See [A customer is just outside the window](/contracts/what-can-be-covered#a-customer-is-just-outside-the-window). ### The manufacturer warranty length SureBright uses is wrong. How do I fix it? See [Correct a manufacturer warranty length](/contracts/effective-dates#correct-a-manufacturer-warranty-length). ### Why does a draft order plan not activate, or get duplicated? See [Draft orders, invoices, duplicates and cancellations](/learn/phone-and-later-sales#draft-orders-invoices-duplicates-and-cancellations). ## Cancellations, returns and refunds ### What happens to a plan when the order is cancelled or refunded? On most platforms the plan follows the order: cancel or refund in your store admin and the matching contracts are cancelled for you. The customer receives a cancellation confirmation email, and a plan already billed to you comes back as a credit on your next invoice. | Platform | What cancels a plan | | --- | --- | | Shopify | Cancelling the order cancels every contract on it. So does a full refund, or one that is effectively full. Refunding only some of the order's plans cancels only the contracts for those units. | | Magento | A credit memo or a cancellation on the order reaches the contract. See [Storefront widget](/magento/storefront-widget). | | BigCommerce | Cancelling the order, removing a plan line from it, or refunding plan units. See [BigCommerce](/bigcommerce/overview#what-happens-when-an-order-changes). | | WooCommerce | Refunding a plan line, or deleting the order. See [WooCommerce](/woocommerce/overview#refund-delete-or-restore-an-order). | | Shift4Shop | Reducing the warranty quantity on the order, or fully refunding or cancelling it. See [Shift4Shop](/shift4shop/overview#what-happens-when-an-order-changes). | | Salesforce Commerce Cloud | Ask your SureBright contact. | | Lightspeed, the POS portal and API integrations | See [What works on each platform](/platforms/overview#what-works-on-each-platform). | See [Contract statuses](/contracts/lifecycle). ### The customer returned the product but kept the plan. What now? Nothing is cancelled automatically. A case with the reason *Covered product was refunded* appears in Order Resolution, where you can associate the plan with another product, refund it, or acknowledge and keep it. If nobody answers within 48 hours, SureBright refunds the customer's plan. See [Order Resolution](/merchant-portal/order-resolution#what-happens-after-48-hours). ### How is a plan refund calculated? This applies to refunds SureBright issues for you, which are available on Shopify stores only. When you choose a refund in Order Resolution, the default is pro-rata by remaining coverage time: plan price multiplied by remaining days over total days. If the coverage dates are not set yet, the refund is 100%. A 10% administration fee applies only when the person resolving the case chooses it and more than 30 days have passed since coverage started. See [Order Resolution](/merchant-portal/order-resolution) and, for cancellations later in the plan, [When a customer cancels later on](/learn/refunds-and-credits#when-a-customer-cancels-later-on). ### My store is not on Shopify. Can SureBright refund the plan? Refunds through SureBright are available on Shopify only. On other platforms a case whose only outcomes are refunds is shown read-only; refund the plan line in your store admin, then press **Tell us what you did**. Where a non-refund answer exists you can still submit it, including **End cover on the N extra warranty unit(s)**, which ends the cover while the refund stays yours to make. See [Order Resolution](/merchant-portal/order-resolution#if-surebright-cannot-refund-on-your-platform). ### Can a customer cancel or transfer a plan themselves? No. The customer portal has no self-serve cancellation or ownership transfer. A customer who wants either should contact SureBright support or you, and refunds you grant go through **Order Resolution**. For what to do when a customer asks, see [Helping a customer](/help/helping-a-customer). See [Customer portal](/customer-portal/overview#plans-and-what-each-status-means). ### How do I cancel or refund a plan? See [Cancel or refund a plan](/learn/changing-a-plan#cancel-or-refund-a-plan). ### A customer exchanged the product. What happens to the plan, and what if the price differs? See [The customer exchanged the product](/learn/changing-a-plan#the-customer-exchanged-the-product). ### How do I correct the customer's name, email or purchase date on a plan? See [Correct the customer's name, email or purchase date](/learn/changing-a-plan#correct-the-customers-name-email-or-purchase-date). ### The customer sold or gave the product away. Can the plan move to the new owner? See [The customer sold or gave the product away](/learn/changing-a-plan#the-customer-sold-or-gave-the-product-away). ## Claims ### How does a customer file a claim? The customer signs in to **customer.surebright.com**, opens the product under **Warranties** and chooses **File a claim**. The claim must come from the email address the plan was sold to, with the incident date, a description and at least one photo or video (up to 10 files of 25 MB each). Customers can also write to SureBright's claims address, where a person confirms the claim from the email. See [Filing a claim](/claims/filing-a-claim). ### Do I have to handle claims myself? By default, no. SureBright's team opens, assesses, decides, writes to the customer and settles every claim; your team acts only when a replacement ships from your own stock. You can read every claim against your contracts in the Adjudicator Portal, which is being enabled store by store, and organisations that want to work their own claims can ask SureBright for self-adjudication. See [Merchant adjudication](/claims/merchant-adjudication). ### How does a claim move from filed to closed? Every claim passes through **New**, **In review**, **Awaiting fulfilment** and **Closed**, and closes as **Fulfilled**, **Declined**, **Withdrawn** or **Closed, no reply**. Only a claim closed for no reply reopens, if the customer writes back inside the promised window. Each claim also records whose move it is: the adjudicator, the customer, you, or SureBright fulfilment. See [How a claim moves](/claims/overview). ### What does an approved claim settle with? SureBright decides how each approved claim is settled. It is usually a replacement unit or a repair through SureBright's service network, and it can be a reimbursement, for example by cheque or gift card, when a replacement or repair is not practical. Repair invoices are paid to the provider by SureBright, not by you. See [Resolutions and payouts](/claims/resolutions-and-payouts). ### What does shipping protection cover? A shipment to a United States address that is lost (including misrouted and never delivered), damaged in shipping, stolen, or arrives with items missing. Those are the reasons a shopper can claim; a delivery that arrives late but intact is not one of them. Cover is created when you fulfil the order with a carrier and tracking number. See [Shipping claims](/shipping-protection/claims) and [Shipping protection](/shipping-protection/overview). ### What do I do about a shipping protection claim? Usually nothing. The customer files it at **customer.surebright.com** from the shipment's card, SureBright checks it against the shipping contract and settles it, and payment of an approved claim goes to the customer directly. Shipping claims are not listed in the Merchant Portal and do not change the order, the contract or your margin. Now and then SureBright asks for your help, for example to dispute a delivery with the parcel carrier or get signed proof of delivery. See [Shipping claims](/shipping-protection/claims#when-surebright-asks-for-your-help). ### Do plans have a deductible? Some do. Whether a plan has one depends on the plan, so check the plan's terms before you tell a customer there is none. See [Where to read a plan's coverage terms](/customer-emails/purchase-confirmation#where-customers-read-the-coverage-terms). ### How long does a claim take, and how do I follow one up? See [How long a claim takes](/claims/overview#how-long-a-claim-takes) and [When a claim seems stuck](/claims/overview#when-a-claim-seems-stuck). ### Why was my customer's claim declined? See [Why a claim is declined](/claims/overview#why-a-claim-is-declined). ### A product arrived broken. Is that a claim? See [A product arrived faulty or damaged](/learn/claims-and-your-role#a-product-arrived-faulty-or-damaged). ### Can we file a claim for a customer? See [File a claim for a customer](/claims/filing-a-claim#file-a-claim-for-a-customer-without-the-adjudicator-portal). ### SureBright asked us to inspect a returned unit. What do we send? See [When SureBright asks you to inspect a returned unit](/claims/merchant-adjudication#when-surebright-asks-you-to-inspect-a-returned-unit). ### How do we get paid back for a replacement, parts or a repair we supplied? See [When you supply the replacement, parts or repair](/claims/resolutions-and-payouts#when-you-supply-the-replacement-parts-or-repair). ## Customers and emails ### Which emails does SureBright send my customers? SureBright emails customers directly from `support@surebright.com`, naming your store. The main one is the **Plan confirmation**, the customer's proof of coverage with the contract number. Depending on the order they may also receive **Order received** (stores whose coverage starts at shipment), **Action needed** (missing customer details), a **Shipping protection confirmation** and a **Cancellation confirmation**, each at most once per order or plan. See [Emails your customers receive](/customer-emails/overview). ### Can I change the wording or branding of those emails? Not from the portal. SureBright sends the customer emails, and their timing, wording and layout depend on the plan sold. Your store name is taken from your store's own settings, so keep it accurate there. Branded templates and resending a confirmation for a given contract are handled by SureBright on request. See [What you can change](/customer-emails/overview#what-you-can-change). ### A customer says they never received a confirmation. Why? The plan confirmation is sent only once the contract has every detail it prints: customer name and email, covered product and price, plan category and coverage dates. If the order has no customer email, nothing can be sent. On stores whose coverage starts at shipment, the confirmation waits for the shipment and the customer gets **Order received** at checkout instead. See [Plan confirmation](/customer-emails/purchase-confirmation). ### Where does a customer see their plan? At **https://customer.surebright.com**, linked from the confirmation email. Sign-in is passwordless: the customer enters the email address used on the order and receives a one-time code or a magic link. Each plan is a card with a status such as **Protected until** a date or **Address needed to activate warranty**, and claims are filed from there. See [Customer portal](/customer-portal/overview). ### A customer asked for their data or its erasure. What do I do? How you send the request depends on your platform. - **On Shopify**, use Shopify's own flow: open the customer, choose **Request customer data** or **Erase personal data**, and include SureBright. Shopify passes the request to SureBright, and the data or the confirmation of erasure comes from SureBright separately. Email support with the Shopify customer id or order number and the date you sent the request. See [GDPR webhooks](/shopify/gdpr). - **On other platforms**, ask your SureBright contact. ### Can I offer protection to customers who skipped it at checkout? On Shopify, yes. A post-purchase offer link (`https://yourstore.com/?quoteLeadId=`) opens a popup on your storefront with the plans still available for that order, and the plan order is linked back to the original product. The SureBright Klaviyo events carry this link ready made, and your own tools can build it from the order ID. See [Post-purchase offer links](/post-purchase/offer-links). On other platforms, ask your SureBright contact. ### Does SureBright email my customers offers after they buy? Where SureBright has switched them on for your store, yes. See [Offer emails](/post-purchase/offer-emails), including [which orders get an offer](/post-purchase/offer-emails#which-orders-get-an-offer). ### Is there a plan overview I can give my support team or publish for customers? See [Plan overview for your team](/help/plan-overview). ### Where can customers read a plan's coverage terms? See [Where to read a plan's coverage terms](/customer-emails/purchase-confirmation#where-customers-read-the-coverage-terms). ## Widget and storefront ### Can I change how the widget looks? Yes, in **Studio**, available on request. You edit the design on a capture of your own product page: templates, colours, layout, text sizes, the plans row and the coverage popup. The wording itself is set by SureBright. Nothing changes on your store until you click **Publish changes**, and **Restore previous design** brings back the version that was live before. See [Studio](/merchant-portal/studio). ### Are there ready-made widget designs I can start from? Yes. Studio has a gallery of published templates across card, stacked-row and dropdown layouts. Each one is shown in your store's colours on a capture of your own product page, and you can change colours, corners, text size, the badge and the popup without code. Any template can be tested against your live design before it goes live. See [Template gallery](/merchant-portal/template-gallery). ### Can I test two widget designs against each other? On Shopify stores, yes. In Studio's **A/B Testing** tab, pick a draft or previously live design as the challenger, set the traffic split (the challenger can take 10 to 90 percent) and start the test. The two designs are compared on attach rate, and a winner is called only when the lead is too wide to be chance. One test runs at a time, until you stop it or promote a winner. Design tests are not available on other platforms, because attach rate is measured on Shopify only. See [Design tests](/merchant-portal/design-tests). ### Which plan is pre-selected when the widget opens? The **Default Selected Plan** in Studio's **Plans** row: **None**, **1st**, **2nd** or **3rd** paid plan. Until you choose one, the 2nd plan is selected. Shoppers can always change or remove the selection, and the **"No coverage"** card can be shown so they can decline on purpose. See [Default plan selection](/merchant-portal/default-plan-selection). ### Why can shoppers see or buy the protection product on its own? The plan is a real product in your catalogue. SureBright hides it from your collection pages and hides the add-to-cart form on the plan's own page. If it still shows somewhere, tell SureBright which page and which part of it. Shopify stores can also block standalone plan purchases at checkout: see [Questions for Shopify stores](#questions-for-shopify-stores). ### Can I turn the add-to-cart pop-up on or off? See [Turn the add-to-cart pop-up on or off](/merchant-portal/widget-options#turn-the-add-to-cart-pop-up-on-or-off). ### Can you move the widget, or change it on phones? See [Move the widget on the product page](/merchant-portal/widget-options#move-the-widget-on-the-product-page). ### Can you remove the offer from my cart page but keep it on product pages? See [Where the offer can appear](/merchant-portal/widget-options#where-the-offer-can-appear). ### The plan stopped reaching the cart after a theme change. Why? See [What commonly gets in the way](/help/offer-not-showing#what-commonly-gets-in-the-way) and [After a theme or platform change](/platforms/after-a-theme-or-platform-change). ### Why does my product page show a longer term than the Merchant Portal? See [How plan length is shown](/merchant-portal/widget-options#how-plan-length-is-shown). ### Can you remove or relink the SureBright logo? See [Remove or relink the SureBright logo](/merchant-portal/widget-options#remove-or-relink-the-surebright-logo). ### SureBright's script is slowing my pages. What can I do? See [If SureBright's script is slowing your pages](/merchant-portal/analytics-and-page-speed#if-surebrights-script-is-slowing-your-pages). ## Platforms ### Which platforms does SureBright work with? Shopify (on a theme, or headless on Hydrogen), Magento, Salesforce Commerce Cloud, BigCommerce, WooCommerce and Shift4Shop for online stores; Lightspeed X-Series, Lightspeed R-Series, Shopify POS and the SureBright POS portal for the counter; and Acumatica, Oracle NetSuite, Microsoft Dynamics 365 Business Central, SAP Business One and Odoo for ERP. Custom and headless storefronts can run the storefront SDK and the API directly. See [Supported platforms](/platforms/overview). ### Is the WooCommerce plugin self-install? Not yet. The WooCommerce plugin is in limited release: it is installed with help from your SureBright contact, not from the WordPress plugin directory. Talk to SureBright before you plan a launch on WooCommerce. See [WooCommerce](/woocommerce/overview). ### Can I sell plans in my physical store? Yes. Shopify POS stores add the SureBright tile to the smart grid and sell the plan on the same receipt as the product. Lightspeed X-Series and R-Series stores are connected directly. Any other register can use the SureBright POS portal, where staff record sales by hand or in bulk with their own logins and roles. See [POS portal overview](/pos/overview). ### Which countries are plans sold in? Plans are sold to shoppers in the United States (priced in USD) and Canada (priced in CAD) only. They are not sold in other countries, including the United Kingdom, Australia and Mexico. The shopper's country decides what they are offered, not where your business is based. In Canada, ask your SureBright contact to confirm your plans cover a province, Quebec included, before you launch there. Shipping protection covers shipments to United States addresses only. See [Languages and regions](/platforms/languages-and-regions). ### Which languages are the widget and plans available in? English and French. No other language is available: a storefront in Spanish or German shows the widget in English. See [Languages and regions](/platforms/languages-and-regions). ### Is there an API, and how do I get a key? Yes. Quote and category endpoints are public; only the Order endpoints need a key, sent in the `X-SureBright-Access-Token` header. Keys are created on the portal's **Developers** page, enabled on request: label the key, click **Generate new key** and copy it, because the full key is shown once. There is no sandbox mode and no separate test key: every key starts with `sb_live_`. Integration partners that act for a merchant connect through SureBright Connect instead of a key. See [Authentication](/api-reference/authentication) and [Partner sign-in](/api-reference/endpoint/partner/sso). ### My till is not Lightspeed or Shopify POS. Can I still sell plans in store? See [Already have a register or POS system](/pos/overview#already-have-a-register-or-pos-system). ### Do you have security or accessibility documentation? See [Security and compliance](/help/security-and-compliance). ## Questions for Shopify stores ### Can I offer protection inside Shopify checkout? Only on Shopify Plus, because Shopify shows checkout blocks on Plus plans alone. The **SureBright Protection Block** offers shipping protection below the cart lines and the **SureBright Protection Badge** lets shoppers add a product warranty in checkout. Add both from **Settings → Storefront setup → Open checkout editor ↗** and turn on **Include app in Shop Pay**. Magento, BigCommerce, WooCommerce and Shift4Shop have no in-checkout offer; on Salesforce Commerce Cloud, ask your SureBright contact. See [Checkout extensions](/shopify/checkout-extensions). ### Do plans follow my Shopify Markets prices? On Shopify stores with Markets enabled for SureBright, the plan is priced against the price the shopper sees in their market rather than your base price. A plan quoted in one currency and paid in another is put on hold until SureBright has matched the amounts. See [Shopify Markets pricing](/shopify/markets). ### How do I keep my Shopify discounts off SureBright products? In Shopify, create a smart collection with the condition **Product vendor** is not equal to **Surebright**, then create your discount as **Amount off products** applied to that collection. The plans are left out and the discount applies to everything else. See [Discounts that exclude SureBright products](/shopify/admin-housekeeping#discounts-that-exclude-surebright-products). On other platforms, ask your SureBright contact. ### How do I stop a plan being bought without its product on Shopify? You can block standalone plan purchases at checkout with the **sb-cart-validator** checkout rule, which stops a plan being bought without the product it covers. See [Cart Validator](/shopify/enable-surebright-cart-validator). ## Getting help ### How do I contact SureBright support? Click **Help** at the bottom of the portal sidebar for common questions, a search box and guided tours. Under **Still need help?** you can reach the team at [support@surebright.com](mailto:support@surebright.com) or **+1 855-306-4874**. Features marked available on request (**Studio**, **Warranty Pricing**, **Order Resolution**, **Abandoned Cart**, **Fulfillment**) are switched on by the same team. For what to include in a request, see [Contact SureBright support](/help/contact-support). See [Getting help](/merchant-portal/overview#getting-help). ### What is Ray? Ray is the assistant inside the Merchant Portal, available on request. It answers questions about your sales, billing, products, leads, Order Resolution cases and abandoned carts from the portal's own data, and can make a defined set of changes for you. Every change is previewed first and made only after you click **Confirm**. See [Ray](/merchant-portal/ray). --- # Helping a customer Source: https://docs.surebright.com/help/helping-a-customer > A task-first guide for your support team: what to do when a customer asks about cancelling, a return, an email, their plan or a claim. Use this page when a customer writes to your support team about a SureBright plan. Each section is one request: what you do, what the customer can expect, and where the detail is. Start with the order number and the email address on the order. Customers can also contact SureBright directly at [support@surebright.com](mailto:support@surebright.com) or **+1 855-306-4874**. ## Your helpdesk and SureBright There is no helpdesk integration to set up. SureBright works alongside whatever tool your team already uses: | Who | What they do | |---|---| | Your customers | See their plans, add a missing address and file claims themselves in the [customer portal](/customer-portal/overview). The link is in their confirmation email. | | Your support team | Answer common questions with this page and the [plan overview](/help/plan-overview), and look up a customer's plan under **Sales** in the [Merchant Portal](/merchant-portal/sales). Give them their own logins; see [Team and access](/merchant-portal/team-and-access). | | SureBright | Handles claims and anything your team cannot resolve. Forward the customer's question to [support@surebright.com](mailto:support@surebright.com) with the order number, or give the customer that address. | ## Cancellations, returns and refunds ### "I want to cancel my plan" - **What you do:** Refund the plan line on the order in your store admin, or send the request to SureBright support with the order number. Customers cannot cancel a plan themselves in the customer portal. - **What to expect:** Refunding the plan cancels it for the units you refunded. The customer receives a **Cancellation confirmation** email, and a plan you were already billed for comes back as a credit on your next invoice. - **How the refund reaches SureBright:** On Shopify, BigCommerce and WooCommerce, refund the plan line. On Magento, issue a credit memo for the plan. On Shift4Shop, reduce the warranty quantity on the order. On Salesforce Commerce Cloud and other platforms, send the request to SureBright support so the plan is cancelled. - **Refund amount, when SureBright issues the refund (Shopify only):** When you choose a refund in Order Resolution, the default is the unused share of the plan: the plan price in proportion to the coverage time left. A plan with no coverage dates yet is refunded in full. A 10% administration fee applies only when the person resolving the case chooses it and more than 30 days have passed since coverage started. - **On other platforms:** SureBright cannot issue the refund. You refund the plan line in your store admin. See [Order Resolution](/merchant-portal/order-resolution). #### Check for claims before you cancel A cancelled plan no longer provides cover, so before you refund a plan, check that the customer has not filed a claim on it: - **If your store has the Adjudicator Portal**, search for the customer's email address or the contract and look at its claims. See [Adjudicator Portal](/claims/adjudicator-portal). - **Otherwise**, email [support@surebright.com](mailto:support@surebright.com) with the order number and the customer's email address, and ask SureBright to confirm whether any claim has been filed on the plan. ### "I returned or exchanged the product" - **What you do:** Open the order in **Order Resolution**, where it appears with the reason *Covered product was refunded*. Choose to refund the plan, keep it, or move it to another product. If the customer took a different product instead, choose **Associate product** and pick it. **I'll handle it** gives you time to check with the customer. - **What to expect:** The plan is not cancelled just because the product was refunded. If nobody answers within 48 hours, SureBright refunds the customer's plan. Order Resolution is available on request. See [What happens after 48 hours](/merchant-portal/order-resolution#what-happens-after-48-hours). ### "My order was cancelled or refunded. Is the plan cancelled too?" - **What you do:** On most platforms, nothing more. - **What to expect:** On Shopify, Magento, BigCommerce and Shift4Shop, cancelling the order or refunding it in full cancels every plan on it. On WooCommerce, refund the plan line or delete the order. On Salesforce Commerce Cloud, ask your SureBright contact. The customer receives a **Cancellation confirmation** email, and a plan you were already billed for is credited on your next invoice. See [Contract statuses](/contracts/lifecycle). ### "I bought the wrong plan" or "the plan is on the wrong product" - **Wrong product:** If the order is waiting in **Order Resolution**, choose **Associate product** there. On Shopify you can also open the sale in [Sales](/merchant-portal/sales#find-a-sale) and use **Edit Product Details**, offered on eligible active plans. On other platforms, ask your SureBright contact. - **Wrong plan:** The Merchant Portal cannot swap one plan for another. Refund the plan to cancel it, as described in the first section of this page, then sell the right plan: with a [post-purchase offer link](/post-purchase/offer-links) on Shopify, or from [Leads](/merchant-portal/leads) on Shopify and Magento. On other platforms, ask your SureBright contact. ### "I bought the plan later, in a separate order" - **What you do:** Usually nothing. If the order appears in **Order Resolution**, pick the product the customer meant. - **What to expect:** On Shopify and Shift4Shop, SureBright links the plan to the matching product from the customer's earlier order on its own. On other platforms, ask your SureBright contact. On any platform, when SureBright cannot tell which product is meant, the order goes to Order Resolution, and the customer may get an email asking them to [confirm which product the plan covers](/customer-portal/warranty-link). For Shopify, see [Plans bought in a later order](/contracts/plans-bought-later). ## Customer details and emails ### "My email, phone or address has changed" - **What you do:** On Shopify and WooCommerce, correct the details on the order; the plan picks them up. On other platforms, ask your SureBright contact. To move a plan to a different email address, write to SureBright support with the order number. - **What the customer can do:** Add a missing address from the plan's card in the customer portal (**Update address**), and edit their name and phone number under **Account settings**. - **What to expect:** A plan cannot be activated while the customer's name, email or address is missing, and its confirmation email waits. In the customer portal, plans are listed under the email address on the order, and a claim must be filed from that address. See [Why a contract is on hold](/contracts/holds). ### "The plan is in the wrong name" This happens when a plan was bought as a gift, when you bought the plan for a customer, or when staff typed the store's own name or email on the order. - **What you do, for a POS portal sale:** open the sale in [Sales History](/pos/sales-history#fix-change-or-cancel-a-sale) and choose **Update customer details**. The confirmation goes to the corrected address. - **What you do, for any other sale:** email [support@surebright.com](mailto:support@surebright.com) with the order number, the contract number if you have it, the email address on the plan now, and the correct name, email address, phone and address of the person who should hold the plan. SureBright updates the plan. - **What to expect:** once the email address is changed, the plan is listed under the new address in the customer portal, and claims are filed from that address. Ask SureBright to resend the plan confirmation to the new address if the customer needs it. ### "The purchase date on my plan is wrong" - **What you do, for a POS portal sale with the wrong manufacturer warranty:** correct it yourself within 45 days with **Update product details**. See [Update product details](/pos/sales-history#update-product-details). - **What you do, for a wrong purchase or sale date:** email [support@surebright.com](mailto:support@surebright.com) with the order number, the contract number and the correct date, and attach the receipt or invoice if you have it. SureBright reviews the request and corrects the dates. - **What to expect:** coverage dates are worked out from the product's purchase date, so a corrected date can move the start and end of cover. See [When coverage starts](/contracts/effective-dates). ### "I never got a confirmation email" - **What you do:** Check the sale's **Warranty status** in **Sales** and complete any missing customer details on the order. Ask SureBright support to resend the confirmation. Meanwhile, point the customer to the customer portal, where they can see the plan. - **What to expect:** The **Plan confirmation** comes from support@surebright.com once the plan has everything it needs. An order with no customer email cannot receive one. On stores whose coverage starts at shipment, the customer gets **Order received** at checkout and the confirmation when the product ships. See [Purchase confirmation](/customer-emails/purchase-confirmation). ### "Where can I see my plan?" - **What you do:** Send them to **https://customer.surebright.com**. If no plans show, ask which email address the order used. - **What to expect:** The customer enters the email address used on the order and signs in with a one-time code or a magic link. Each plan is a card with a status, such as **Protected until** a date. See [Customer portal](/customer-portal/overview). ## Claims and delivery problems ### "I need to file a claim" - **What you do:** Point them to the customer portal and ask them to have clear photos or a short video ready. - **What to expect:** The customer signs in, opens the product and chooses **File a claim**, using the email address the plan was sold to. They give the incident date, a description and at least one photo or video. SureBright's team handles the claim by default; your team acts only when a replacement ships from your own stock. See [Filing a claim](/claims/filing-a-claim) and [How a claim moves](/claims/overview). ### "My parcel was lost, damaged or arrived short" - **What you do:** Point them to the customer portal. There is nothing else for you to do. - **What to expect:** With shipping protection, the customer files the claim from the shipment's card, choosing **Loss**, **Damage** or **Shortage**. SureBright reviews and settles it, and an approved claim is paid to the customer directly. Shipping claims are not listed in the Merchant Portal and do not change the order. See [Shipping claims](/shipping-protection/claims). ## Privacy requests ### "Send me my data" or "erase my data" - **What you do, on Shopify:** Open the customer in Shopify admin, choose **Request customer data** or **Erase personal data**, and include SureBright. Then email SureBright support with the Shopify customer id or order number and the date you sent the request. - **What to expect, on Shopify:** SureBright receives the request from Shopify and replies to you separately with the data or a confirmation of erasure. See [customer data requests](/shopify/gdpr). - **On other platforms:** Ask your SureBright contact. ## Related The same topics, question first. A one-page briefing and FAQ copy for your customers. How to reach the team and what to include. The queue of orders that need a decision from you. What your customers see when they sign in. **See also:** [The customer sold or gave the product away](/learn/changing-a-plan#the-customer-sold-or-gave-the-product-away). --- # Offer not showing? Source: https://docs.surebright.com/help/offer-not-showing > A step-by-step check for a missing or broken protection offer on any platform, the apps and storefront changes that commonly cause it, and what to send SureBright when you need help. Use this page when the protection offer is missing from a product page, shows on some products only, or shows but the plan never reaches the cart. Work down the checks in order. Most take a minute in the Merchant Portal or on your own storefront. ## Check in this order In the Merchant Portal open **Products** and find the product. It needs a **Product category** and a **Warranty status** of **Active**. | You see | Do this | | --- | --- | | No category, or **Inactive** | Pick a category (this also turns protection on), or set the status to **Active**. | | **Under Review** | Wait. The status cannot be changed until SureBright finishes the review. | | A **Mfr warranty** chip reading **Add** | Click the chip and set the length. No offer shows until you do. | | The product is a bundle | As standard, a bundle whose components sit in different categories is not offered a plan. Custom handling is available to stores that meet a minimum order volume. See [Bundles](/shopify/bundles). | | Everything looks right, on Shopify | Check the product is on the **Online Store** sales channel. See [Shopify admin housekeeping](/shopify/admin-housekeeping#online-store-sales-channel). | Test on a second product you know is **Active** before moving on. If that one shows the offer, the problem is this product. See [Products](/merchant-portal/products). Look at the store card at the foot of the portal sidebar. It must read **Live**. **In review** means nothing is offered yet, **Not installed** means no storefront is connected, and **Not approved** means contact support. See [Your store card](/merchant-portal/overview#check-your-stores-status). Where you check depends on your platform. | Platform | Check | | --- | --- | | Shopify | The **SureBright Offering** app embed is on in your live theme. See the Shopify steps below. | | Magento | The integration reads **Authorized**. Then purge caches from the SureBright page in your Magento admin. See [Storefront widget](/magento/storefront-widget). | | BigCommerce | **SureBright SDK configuration** and **SureBright SDK** are both listed in **Storefront > Script Manager**. See [BigCommerce](/bigcommerce/overview#check-that-it-works). | | Shift4Shop | The two SureBright entries are listed under **Frontend Scripts**. See [Shift4Shop](/shift4shop/overview). | | Custom storefront | Ask your developer to confirm the SureBright script is on the page. See [SDK Installation](/frontend-widget-integration/frontend-widget-kit/sdk-installation). | | Other platforms | Ask your SureBright contact. | **On Shopify**, open **Settings → Storefront setup** and read the badge next to your **Live theme**. - **Not turned on**: click **Turn on in Shopify ↗**, switch **SureBright Offering** on, click **Save** in Shopify, then come back and click **Check again**. - **Turned on**, but only against a theme marked **Not published** or **Development theme**: shoppers do not see that theme. Turn it on for the live theme too. - **Can't check right now**: click **Open in Shopify ↗** and look at the App embeds panel yourself. See [Storefront setup](/shopify/storefront-setup). The offer is placed next to your product page's **Add to cart** button, at a spot SureBright matched to your storefront. If the product page was rebuilt, for example by a new theme, a page builder or a redesigned buy box, that spot may no longer exist and nothing is drawn. There is nothing for you to change in your storefront's code. Send SureBright the product URL and say where the offer should sit. The placement is updated on SureBright's side. See [Move the widget](/merchant-portal/widget-options#move-the-widget-on-the-product-page). If the offer shows on some devices only, is covered by something else, or no longer pops up when a shopper adds to cart, find the change in the table in the next section. Pick a plan, add the product and open your cart. You should see a separate line, titled **Product Warranty Powered by SureBright** unless your store uses its own title, with **Product** and **Term** under it. | You see | Likely cause | Do this | | --- | --- | --- | | No plan line | A cart app or an express checkout button took the shopper past the offer. | See the table below. | | The plan line appears, then goes | A plan is removed when the product it covers leaves the cart. | Add the product and plan together again. If it still disappears, contact SureBright. | | The plan shows in the cart drawer only after a page reload | Your cart drawer is not refreshed after the plan is added. | Send SureBright your store URL. SureBright can set your drawer to refresh. | | The plan never reaches the cart, after a theme or product page change | The way your theme adds to cart changed. | See the next section. | | The offer looks normal but plans stopped selling | A plan product SureBright created in your catalogue was renamed, repriced, deleted or unpublished. Plans stop working when that happens, even though the offer still shows. | Do not edit these products. Ask SureBright to restore them. | | Checkout is blocked, on Shopify | The Cart Validator stops a plan being bought without the product it covers. | Add the covered product, or remove the plan. See [Cart Validator](/shopify/enable-surebright-cart-validator). | ## What commonly gets in the way | What you changed | What happens | What to do | | --- | --- | --- | | A new cart drawer or side cart | The offer and plan details inside the cart can stop appearing, because they were matched to the old drawer. | Send SureBright your store URL so the cart placement can be matched again. | | A change to how **Add to cart** works, for example a redesigned product page or a theme update | SureBright adds the plan alongside the product by following the way your theme adds to cart. If that changes, the plan can stop reaching the cart even though the offer still shows and the product is added. | Tell SureBright before you change your product page or theme. Afterwards, add a product with a plan and check the cart. If the plan is missing, send SureBright the product URL. | | A cart app that replaces your storefront's own cart | SureBright has to be told which app draws your cart. On Shopify, Rebuy Smart Cart and UpCart are supported. Installing the app is not enough on its own. | Tell SureBright before you add, switch or remove a cart app. | | An upsell or add-to-cart app | The offer pop-up is tied to the shopper adding the product they are viewing. An app that adds products its own way can skip it. | Test add to cart after installing or changing such an app. If the pop-up stopped, send SureBright a product URL and the app's name. | | Quick view or quick-buy buttons | The offer appears in a quick-view window only when SureBright has switched that on for your store. Collection pages never show the offer. | Ask your SureBright contact to enable quick view. Shoppers can still add a plan from the cart where your cart offer is on. | | Buy-now and express checkout buttons | These send the shopper straight to checkout. The plan is carried along only when SureBright has enabled this for your store. | Ask your SureBright contact to enable it. Shopify Plus stores can also offer protection inside checkout: see [Checkout extensions](/shopify/checkout-extensions). | | A chat or support widget | The plan pop-up is built to open on top of everything else on the page, a floating chat button included. The offer on the product page and the buttons in the cart are part of the page, so a chat button pinned to the corner of a phone screen can sit on top of them. | Move the chat button in that app's settings, or ask SureBright to move the offer. | | A page builder | A product page or landing page built in a page builder may have no spot for the offer, and SureBright may not be loaded on that kind of page at all. | Send SureBright the page URL. | | Publishing a new theme, on Shopify | SureBright is switched on per theme, so a new theme starts with it off. The offer's placement was matched to the old theme. A design you [targeted](/merchant-portal/design-targeting) at the old theme does not carry over. | Before you publish, turn SureBright on for the new theme in **Storefront setup**, preview a product page, and tell SureBright about the switch. | | A new theme, redesign or domain on another platform | The offer's placement was matched to the old pages, and on some platforms the offer is tied to your store's domain. | See [After a theme or platform change](/platforms/after-a-theme-or-platform-change#other-platforms-theme-and-domain-changes) for what to check on your platform. | | You cannot see a change you just made | A browser that visited your store recently can keep showing the earlier offer for up to two hours. | Check again in a private window. On Magento, also purge the full-page cache. | ## A plan was sold but is missing from Sales A customer paid for a plan, but it is not in **Sales**, or the customer says they have no plan. Check these first. | Check | If so | | --- | --- | | The order's payment has not been captured, or the order is still a draft | A plan is set up only once it is paid for. Capture the payment, then check again. | | The order is in **Order Resolution** | SureBright needs an answer from you before the plan can be completed. See [Order Resolution](/merchant-portal/order-resolution). | | The plan was added to the order by hand, by editing the order or typing in a line | A hand-added line carries none of the plan's details, so no plan is set up. Use SureBright's tools instead: see [Phone and later sales](/learn/phone-and-later-sales). | | The order was a test order | Test orders carry a **Test** tag in **Sales**. | | None of these | SureBright sets up missing plans for you. Email [support@surebright.com](mailto:support@surebright.com) with the order number, the customer's email and the plan they bought. See [Problems SureBright fixes for you](/contracts/holds#problems-surebright-fixes-for-you). | ## Store monitoring by SureBright SureBright runs an automated check on live storefronts. It opens a sample of your product pages, looks for the offer and confirms that a plan reaches the cart. If it finds a problem, SureBright may contact you. The usual causes are the ones on this page, so the checks above are the place to start. The check cannot test a storefront that blocks automated visitors, or a sample product that is sold out. ## What to send SureBright Write to [support@surebright.com](mailto:support@surebright.com) with: - Your store URL. - A product URL where the offer is missing or broken. - The device and browser, and whether it happens on phone, desktop or both. - When it last worked. - Any theme, app or checkout change since then, including a newly published theme. - A screenshot of what you see. For developers: the script's debug switch, the elements it renders and how each placement is anchored are covered in the [JavaScript API Reference](/frontend-widget-integration/frontend-widget-kit/javascript-injection#debugging), [Placements](/frontend-widget-integration/frontend-widget-kit/placements) and [Client-side cart sync](/frontend-widget-integration/frontend-widget-kit/cart-sync). ## Related - [Storefront setup](/shopify/storefront-setup): on Shopify, switching SureBright on per theme and reading the badges. - [After a theme or platform change](/platforms/after-a-theme-or-platform-change): what to check on each platform after a redesign. - [Products](/merchant-portal/products): categories, protection status and manufacturer warranty length. - [What you can change on your widget](/merchant-portal/widget-options): moving the widget, the add-to-cart pop-up and where the offer appears. - [Merchant FAQ](/help/faq): short answers to other common questions. --- # Plan overview for your team Source: https://docs.surebright.com/help/plan-overview > A one-page summary of SureBright protection plans to hand to your customer service and store staff, plus FAQ copy you can publish for your customers. This page is written to be shared. Give the first part to your customer service and store staff as a one-page briefing, and copy the second part onto your own FAQ or warranty page. For step-by-step answers to individual requests, your team uses [Helping a customer](/help/helping-a-customer). ## What you can do | You want to | Use | |---|---| | Brief your customer service or store team | [The one-page overview](#the-one-page-overview) | | Publish answers for your customers | [FAQ copy for your customers](#faq-copy-for-your-customers) | | Handle one customer's request | [Helping a customer](/help/helping-a-customer) | | Get promotional material, training or extra FAQs | [Promotional material and training](#promotional-material-and-training) | | Connect SureBright to your helpdesk | There is nothing to connect. See [Your helpdesk and SureBright](/help/helping-a-customer#your-helpdesk-and-surebright) | ## The one-page overview **What the customer buys.** A protection plan provided by SureBright for a product they bought from you. You sell it; SureBright looks after it, including every claim. **Types of cover.** | Plan | What it is for | When cover starts | |---|---|---| | Extended warranty (breakdown) | The product breaks down | Usually when the first warranty on the product ends. That is the manufacturer's warranty, or your own store warranty when you give one in its place, for example on used or refurbished stock. While it runs, a breakdown goes to whoever gives it: the manufacturer, or your store. See [Your own store warranty](/contracts/effective-dates#your-own-store-warranty-on-used-or-refurbished-stock) | | Accidental damage | Accidental damage to the product. Some plans combine it with breakdown cover, shown as **Extended Warranty + Accidental Damage** | Usually the day the plan was bought | | Shipping protection | A parcel that is lost, damaged, misrouted or stolen in transit | When the order ships | Cover ends one plan term after it starts. Some stores date cover from the day the product ships instead. The customer's confirmation email shows the exact dates. See [When coverage starts](/contracts/effective-dates). **What is and is not covered.** It depends on the plan and the product's category. The coverage document attached to the customer's confirmation email is the answer for that customer. Do not promise cover you cannot see in the document; send the question to SureBright. See [Where to read a plan's coverage terms](/customer-emails/purchase-confirmation#where-customers-read-the-coverage-terms). **What the customer receives.** A confirmation email from `support@surebright.com` with the plan details, the contract number and the coverage document. It is the customer's proof of coverage. See [Emails your customers receive](/customer-emails/overview). **Where the customer sees the plan.** At **https://customer.surebright.com**, signing in with the email address used on the order. There is no password: SureBright emails a one-time code or a sign-in link. See [Customer portal](/customer-portal/overview). **How a claim is made.** The customer signs in to the customer portal, opens the product and chooses **File a claim**. They need the date it happened, a short description, and at least one photo or video. SureBright reviews the claim and keeps the customer informed by email. Your team is asked only when SureBright needs your input. See [Claims and your role](/learn/claims-and-your-role). **A product that arrives broken.** A product that arrives faulty or damaged is a return to your store, not a claim on the plan. With shipping protection, the customer can instead file a shipping claim in the customer portal. **Cancelling.** Customers cannot cancel a plan themselves. They ask you, and you refund the plan line on the order or send the request to SureBright. See [Helping a customer](/help/helping-a-customer#i-want-to-cancel-my-plan). **Who to contact.** Customers can reach SureBright at `support@surebright.com` or **+1 855-306-4874**. Your team uses the same address, with the order number. See [Contact support](/help/contact-support). ## FAQ copy for your customers Copy these answers onto your own FAQ, warranty or support page. Replace `YOUR STORE` with your store name. Each answer holds for every store; anything specific to a plan, such as dates and what is covered, sends the customer to their own documents. ```text Who provides my protection plan? Protection plans sold by YOUR STORE are provided by SureBright. SureBright looks after your plan for its whole term, including any claim. Where can I find my plan? After you buy, SureBright emails your plan details from support@surebright.com, with your coverage document attached. Keep this email: it is your proof of coverage. You can also see your plan at https://customer.surebright.com. Sign in with the email address you used on your order. There is no password: SureBright emails you a one-time code or a sign-in link. I can't find my confirmation email. Check your spam or promotions folder for an email from support@surebright.com. You can also sign in at https://customer.surebright.com with the email address on your order to see your plan. If it is still missing, contact us with your order number. When does my coverage start and end? Your confirmation email and the customer portal show your exact coverage dates. For a breakdown, your product's manufacturer warranty usually comes first, and your plan takes over when it ends. Accidental damage cover usually starts the day you buy the plan. What does my plan cover? Your coverage document, attached to your confirmation email and available in the customer portal, lists exactly what your plan covers. How do I make a claim? Sign in at https://customer.surebright.com with the email address used on your order, open the product and choose File a claim. Tell SureBright when it happened, describe the problem and add at least one photo or video. SureBright will keep you updated by email. My order arrived damaged or didn't arrive. Contact us first about a product that arrived faulty or damaged. If you bought shipping protection, you can file a shipping claim from the customer portal for a parcel that was lost, damaged or stolen in transit. How do I cancel my plan? Contact us with your order number and we will arrange the cancellation. Who do I contact with questions about my plan? SureBright: support@surebright.com or +1 855-306-4874. ``` If your store offers plans after purchase, for example through a [product registration page](/shopify/product-registration) or [offer emails](/post-purchase/offer-emails), add a line telling customers where to go. Only add what your store actually offers. ## Promotional material and training Ask your SureBright contact, or email [support@surebright.com](mailto:support@surebright.com), for any of these. Say what you want to use it for. | You want | Ask for | |---|---| | Material to promote plans by email, on social media or on your site | SureBright's promotional material for merchants | | Counter cards or signage for your stores | In-store material. See [POS portal](/pos/overview#counter-cards-signage-and-staff-training) | | A session or guide for your customer service team | Training for your team | | A coverage summary for the products you sell | A coverage summary for your categories | For promotion that runs inside your store, you can also use what you already have: the [offer on your product pages](/merchant-portal/studio), [offer emails](/post-purchase/offer-emails) and [abandoned cart recovery](/abandoned-cart-guide/abandoned-cart). ## Related What your team does for each kind of request. Every email SureBright sends, and when. What customers can do when they sign in. What SureBright handles and when your team is asked. --- # Security, compliance and accessibility requests Source: https://docs.surebright.com/help/security-and-compliance > What you can tell your own security, finance or legal reviewers about how SureBright handles payment and customer data, and how to request compliance reports, a security questionnaire or an accessibility review. Use this page when your security, procurement or accessibility team asks about SureBright before or after you go live. It lists what you can check yourself in these docs, and how to ask SureBright for anything else. ## What you can do | Your reviewer asks for | Do this | |---|---| | A compliance report or certification | [Request security documentation](#request-security-documentation) | | A completed security or vendor questionnaire | [Request security documentation](#request-security-documentation) | | What customer data SureBright holds and why | Read [What SureBright holds about a customer](/shopify/gdpr#what-surebright-holds-about-a-customer) | | How a customer's data request or erasure is handled | Read [Customer data requests](/shopify/gdpr), and the privacy section of [Helping a customer](/help/helping-a-customer#privacy-requests) | | How you pay SureBright, and whether SureBright sees card numbers | Read [Payment details](#payment-details) | | Who on your team can access SureBright | Read [Access for your team](#access-for-your-team) | | Whether the protection offer on your store is accessible to keyboard and screen-reader users | [Request an accessibility review](#request-an-accessibility-review) | ## What you can tell a reviewer today ### Payment details - **Your payment to SureBright.** Card and bank details you add for SureBright's invoices are entered in a secure form provided by Stripe. SureBright does not see or store the full numbers. See [Payment methods](/merchant-portal/payment-methods) and [POS billing](/pos/billing). - **Your customers' payments.** Plans sold on your online store are paid for through your own checkout, and plans sold in store are paid to you at the counter. SureBright does not hold your customers' payment details. See [How the money works](/merchant-portal/how-billing-works). ### Customer data SureBright holds the customer details a plan needs: name, contact details, address, the product covered and the coverage dates. [What SureBright holds about a customer](/shopify/gdpr#what-surebright-holds-about-a-customer) lists each item and why it is held. Customers sign in to the [customer portal](/customer-portal/overview) without a password, using a one-time code or a single-use sign-in link sent to the email address on their order. They see only the plans sold to that address. ### Access for your team | Where | How access works | |---|---| | Merchant Portal | On Shopify, each colleague signs in with their own Shopify staff login. See [Team and access](/merchant-portal/team-and-access). | | POS portal | Each team member has their own login and a role per store, which an owner or admin grants and can remove. See [Locations and team](/pos/locations-and-team). | | API | Keys are created, rotated and revoked by you on the **Developers** page. See [Developers](/merchant-portal/developers). | ## Request security documentation Email [support@surebright.com](mailto:support@surebright.com), or ask your SureBright contact, with: - your store name; - what you need: a specific report or certification by name, your own questionnaire (attach it), or a call with your security team; - who should receive it, and any deadline your review has. SureBright replies with what can be shared and how. ## Request an accessibility review If your team, or a customer, finds that the SureBright offer on your store is hard to use with a keyboard or a screen reader, email [support@surebright.com](mailto:support@surebright.com) with: - the page address and the widget affected (product page offer, cart, coverage popup, shipping protection); - what the person tried to do, the browser and the assistive technology used; - a screenshot or short recording, if you have one. SureBright looks into each report. The offer's wording, colours and layout on your store can also be adjusted in [Studio](/merchant-portal/studio), for example to raise contrast. ## Related - [Customer data requests (Shopify)](/shopify/gdpr) - [Contact SureBright support](/help/contact-support) - [Payment methods](/merchant-portal/payment-methods) --- # What's new in the docs Source: https://docs.surebright.com/help/whats-new > Dated list of changes to docs.surebright.com: new and rewritten pages, renamed addresses and corrected answers. The most recent changes come first. Old addresses keep working: a page that moved redirects to its new address. ## 19 November 2026 - **New platform:** [Wix](/wix/install-guide). Install the SureBright app for Wix, switch your products on and publish your site. Also new: [uninstall and reinstall](/wix/uninstall-and-reinstall) and [Wix FAQs](/wix/faq). Wix is added to [Supported platforms](/platforms/overview) and the platform picker. - **New:** [API quickstart](/api-reference/quickstart), four copy-paste requests from your first quote to a recorded test order. - The [OpenAPI spec](/api-reference/openapi.json) now names the production host and marks which endpoints need an API key. - **Quickstart responses:** each [quickstart](/api-reference/quickstart) step now shows a sample response. - **API overview:** the [endpoint map](/api-reference/introduction#endpoint-map) now lists the method and path of every endpoint in the OpenAPI spec, and says how to get the staging host. - **New page:** [Enable the SureBright Cart Validator](/shopify/enable-surebright-cart-validator) has its own page again, with a troubleshooting table. - **Retired endpoint:** the old **By Product Details** quote endpoint is gone. Its address now opens [By Category](/api-reference/endpoint/quote/list-warranty-quotes-by-category), and the [Quote API overview](/api-reference/endpoint/quote/index#if-you-only-have-a-products-title-and-price) shows the two calls that replace it. - **Salesforce Commerce Cloud:** the [testing checklist](/salesforce-commerce-cloud/testing) now gives the expected result of each check. - **Clearer page titles** in search results, naming the task and the platform or screen. ## 18 November 2026 - **New:** [What is SureBright?](/learn/what-is-surebright), a one-page summary of what SureBright does, where it works and what it costs, and [Ways to offer product protection](/learn/compare-protection-options), which compares the options and lists the questions to ask any provider. - **New:** [Use these docs with AI assistants](/api-reference/ai-assistants). - **Rewritten:** the [API overview](/api-reference/introduction) now gives the production host, which endpoints need a key, a first request and a map of every endpoint. - **Clearer answers** in the [Merchant FAQ](/help/faq) on the countries plans are sold in, languages, fees and payouts, deductibles, what shipping protection covers, the API sandbox and the WooCommerce plugin. - **Switching providers:** [Switching to SureBright](/platforms/switching-to-surebright) now covers leaving Extend, Mulberry, Clyde or Route. - **Moved:** the Salesforce Commerce Cloud pages now use lower-case addresses, for example [/salesforce-commerce-cloud/integration-guide](/salesforce-commerce-cloud/integration-guide). The old addresses redirect. - **Redirects** for every address of the previous docs site that no longer exists. - The [Abandoned Cart Recovery](/abandoned-cart-guide/abandoned-cart) guide was reorganised into task pages. ## 17 November 2026 - **New docs site.** The docs are now organised by who is reading: Merchants, Store Staff, Installers and Developers. Pick your online store and point of sale once, and the guides show only the pages that apply to you. - New guides for every supported platform, the Merchant Portal, claims, billing, the POS portal, Whole System Warranty for installers, AI agents, and a [Merchant FAQ](/help/faq). --- # Change or cancel a plan Source: https://docs.surebright.com/installers/changes-and-cancellations > Change the products or term on a recorded plan, correct customer details, and cancel a plan in the installer portal, with what you can do yourself and until when. Use this page when a job changes after you recorded the sale: a change order, a wrong detail, or a customer who wants to cancel. Everything starts from the plan. Open **Sales** > **Sold plans**, select the plan, and open the three-dot menu at the top of **Order details**. ## What you can change | You want to | Use | Until when | | --- | --- | --- | | Add, remove or correct products, for example after a change order | **Edit sale** | The 90th day after the installation completion date. | | Change the plan term | **Update warranty plan**, or **Edit sale** | The 90th day after the installation completion date. | | Correct the customer's name, email, phone or address | **Update customer details** | Until the plan is cancelled. | | End the plan | **Cancel sale** | While no claim is open on it. | The plan shows the reminder "Products can be added, removed, or updated within 90 days of the sale." ## Handle a change order From the three-dot menu, select **Edit sale**. Add, remove or correct items. Check both tabs, **Covered items** and **Not covered**. The purchase date stays as it was. On **Warranty plan**, the prices update to match the items you added or removed. Change the term here if you need to. **Order summary** shows the **Old warranty plan**, the **New warranty plan** and the difference, as **Balance due** or **Refund to original payment**. Tick the box and select **Confirm**. Check the customer details and select **Submit**. The portal shows "Sale updated successfully". To change only the term, select **Update warranty plan**, pick from **Available plans**, check **Order summary** and select **Submit**. ### After the 90th day The portal no longer lets you edit the products or the term. Some limited changes are still possible. Email support@surebright.com with the order number and the change you need. ### A later job or phase for the same customer - If you finish the extra work while the plan can still be edited, add the products with **Edit sale**. - Otherwise, record a new plan for the later job, within 90 days of completing it. See [Quote and record a sale](/installers/quote-and-record-a-sale). ## Fix wrong details | What is wrong | Do this | | --- | --- | | The customer's name, email, phone or address | Select **Update customer details**, correct it and select **Save**. | | A product, a price or a quantity | Use **Edit sale** within the 90 days. After that, email support@surebright.com with the order number and the correction. | | The term | Use **Update warranty plan** within the 90 days. | | The same job was recorded twice | Cancel the duplicate and choose **Duplicate sale** as the reason. | ## Cancel a plan Your customer can cancel at any time. When they ask you, you cancel the plan in the portal. From the three-dot menu on the plan, select **Cancel sale**. Before you confirm anything, the portal shows **Refund to customer**. If the plan has been running for a while, it also shows how many days of coverage were used and the **Amount billed to you**. Choose a **Reason for cancellation**: **Customer changed mind**, **Duplicate sale**, **Wrong product details**, **Price adjustment** or **Other**. Tick "I understand the refund amount and the billing changes." and select **Confirm cancellation**. The plan then shows **Cancelled**. A plan cannot be cancelled while a claim is open on it. The portal shows "Refund not available. An active claim exists for this contract." in place of the refund, and **Confirm cancellation** stays unavailable. The same applies to **Edit sale** and **Update warranty plan**. Wait until the claim is closed, or contact SureBright support. A cancelled plan cannot be edited, and you cannot file a claim on it. ## Plans that came through an integrated platform If a platform such as Specifi created the plan, change or cancel it where it was created, so the platform and SureBright stay in step. - **To cancel:** cancel the plan from inside the platform. Then check that it shows **Cancelled** under **Sold plans** in your portal. - **To change:** make the change in the platform if it offers one. If it does not, contact SureBright with the proposal reference. - **If the platform cannot do it:** contact SureBright with the proposal reference. Do not record the job again in the portal. ## Fix common problems | You see | What to do | | --- | --- | | "Products can be changed within 90 days of the sale. Contact support@surebright.com for later changes." | The edit window has ended. Email support with the order number and the change. | | "Refund not available. An active claim exists for this contract." | A claim is open on the plan. Try again when it is closed. | | "This sale changed. Reopen it before editing." | Someone else changed the plan while you had it open. Close it, open it again and redo your change. | | "No alternative plans are available for this sale." | There is no other term to move to. Ask SureBright if you expected one. | | A price is refused when you edit it | You cannot set a price below your cost for that plan. | | "Couldn't calculate the refund. Please try again." | Close the window and open **Cancel sale** again. If it repeats, contact SureBright support with the customer's name. | | There is no three-dot menu on the plan | The plan is already **Cancelled**. | ## Related - [Quote and record a sale](/installers/quote-and-record-a-sale) - [Choose how you sell](/installers/ways-to-sell) - [Claims on a system you installed](/installers/claims) - [What your customer gets](/installers/your-customer) --- # Claims on a system you installed Source: https://docs.surebright.com/installers/claims > How a claim is filed on a Whole System Warranty plan you sold, how you file one for your customer, where you follow it, and what you must wait for before you repair anything. Use this page when a customer tells you something in their system has failed. You can file the claim for them, follow it in the portal, and see why a claim was denied. SureBright reviews and approves every claim. When a claim is approved, the repair job comes to you first. ## Three ways a claim is filed | Who files | How | | --- | --- | | Your customer, online | At **customer.surebright.com**. | | Your customer, through SureBright support | By email at [support@surebright.com](mailto:support@surebright.com) or by phone on **+1 855-306-4874**. | | You, for your customer | From the customer's plan in the installer portal. | The claim button on the SureBright website is for customers and opens the customer portal. As the installer, file from the plan. A failure must be reported within 30 days of when it first happened. A failure reported later is not eligible, so file as soon as your customer calls. ## File a claim for your customer Filing always starts from the customer's plan, so the claim is tied to the right order and products. The **Claims** screen lists claims that have been filed. Go to **Sales** > **Sold plans**, search by the customer's name, phone number or email, and open the plan. **File claim** is at the top of **Order details**. Use **Add item** and select the products that have the problem. Say what failed and when, in at least 50 characters. Upload MP4, PNG or JPEG files, up to 50 MB each and up to 10 files per claim. Select **File claim**. The claim now appears under **Claims** > **Open claims**. Your customer does not need a receipt or proof of purchase. The order and its products are already on file. ## What happens after a claim is filed 1. SureBright checks the claim against the plan and against the manufacturer warranty and your installation warranty on the product. 2. SureBright reviews the claim and approves or denies it. 3. If it is approved, a service request comes to you first, as the original installer. See [Service requests: doing the repair](/installers/service-requests). ### If the product is still under another warranty That warranty applies first. | The failure falls under | What happens | | --- | --- | | Your installation warranty | SureBright closes the claim, and you handle the repair under your own warranty. | | The manufacturer warranty, after your installation warranty has ended | The manufacturer supplies the part. The plan pays the labour, and the job comes to you. | ## Wait for authorisation before you repair Do not start a repair before SureBright has authorised it. Repairs done without authorisation are not paid. If you find that more work is needed once the job is under way, ask for additional authorisation before you do the extra work. Open the job, select **Extend timeline**, pick a reason, answer **Yes** to **Will this bump up the repair cost?**, enter the extra cost and why it changed, and attach photos or documents of what you found. SureBright may approve all, part or none of the extra work. The decision comes by email, with a note on the claim. ## Collect the deductible from your customer A deductible can apply to an approved claim. The customer guide explains when. - You collect it from your customer once the claim is approved and before the repair. - You do not take it off your invoice. Bill the approved labour and parts in full, and SureBright settles the deductible against your invoice when the invoice is cleared. - The deductible is not income for you. ## Follow a claim Open **Claims**. **Open claims** holds claims in progress, and **Resolved claims** holds claims that are finished or were denied. Search by the customer's name, phone number or email. Open a claim to see: - the **Activity feed**, with every step and decision and its date - the estimate, once you have sent one - the expected completion date and the time remaining on the job - the customer's details and the plan's dates. ## Why a claim can be denied A denied claim shows as **Rejected**, and the reason is in its **Activity feed**. The common ones are: - the failure was reported more than 30 days after it happened - the product is not on the plan - the problem is not something the plan covers, such as cosmetic damage or a configuration problem - the repair was done before it was authorised. If you think a decision is wrong, open the denied claim, select **Appeal** and explain why. ## Fix common problems | What you see | What to do | | --- | --- | | Your customer filed with SureBright, but the claim is not in your list | Check **Open claims** and the store switcher. If it is still missing, contact SureBright support with the customer's name and the order number. | | **File claim** is greyed out | The plan has expired, or every product on it already has an open claim. | | There is no **File claim** button | The plan was cancelled, or your role does not include claims. Ask your Owner or Admin to check your role under **Team management**. | | The claim was denied | Read the reason in the **Activity feed**. Use **Appeal** if you have more to add. | | You were sent to the customer portal | That button is for customers. File from the customer's plan in the installer portal. | | You already did the repair | Repairs done before authorisation are not paid. Contact SureBright support and explain what happened. | ## Related Respond to the job, estimate it, do the work and close it. Invoice the finished job and see your payout. What to tell a customer about cover and claims. Where each screen is. --- # Common questions Source: https://docs.surebright.com/installers/common-questions > Short answers to the questions you are most likely to have about selling the Whole System Warranty, pricing and billing, your customer's cover, changes, claims and service work. Each answer here is short and links to the page with the detail. If your question is not here, email [support@surebright.com](mailto:support@surebright.com) or call **+1 855-306-4874**. ## Getting set up and selling ### I could not finish signing up. What now? Sign in again with the same email address and carry on from where you stopped. The last step is adding a bank account, which has to be verified before it can be used, so look for **Resume bank verification** if you started one. After you submit, SureBright reviews the account and emails you when it is approved. If you are stuck, contact SureBright. See [Getting started](/installers/getting-started). ### Is a plan line item in my proposal enough? No. A line item in D-Tools SI or Portal.io is only a line on the proposal. Those tools send nothing to SureBright, so nothing is covered until you record the sale in the installer portal. Record it once the customer has bought and the installation is complete, within 90 days of completing the installation. See [Proposal tools](/installers/proposal-tools). ### I use two tools, or a job is outside my proposal tool Record each job once, through one channel. If Specifi already created the plan from your proposal, do not record the same job in the portal as well, or your customer ends up with two plans. For a job outside your proposal tool, use **Quick quote** for the price and **Record sale** to upload the invoice or proposal or to enter the items by hand. See [Ways to sell](/installers/ways-to-sell). ### Can I sell the plan on commercial projects? The plan is sold to homeowners. Ask SureBright before you quote a commercial project. ### I also sell single products. Is that the same plan? No. A per-product plan is a different product, sold in the POS portal or an online store. The POS portal has a **Sell System Warranties** menu link into the installer portal, and access and roles are set separately in each. See [POS portal overview](/pos/overview) and [Ways to sell](/installers/ways-to-sell). ## What is eligible and what it costs ### What counts as eligible? Are cables, racks and mounts covered? A product is eligible when it is part of the system you professionally installed, is listed on your installation invoice and was sold with a manufacturer warranty of at least 1 year. Cables installed as part of the system are eligible. Racks, mounts, brackets, wall plates, structural hardware and connectors are not, and neither are consumables such as batteries and lightbulbs. You also need to give an installation warranty of at least 90 days. See [What is eligible](/installers/eligibility). ### How is the price set, and what do I keep? The price is worked out on the total eligible project cost, which is the eligible products plus your installation labour, without taxes, and on the plan term. The portal shows your cost, which is SureBright's share, and a suggested customer price. Whatever you charge above your cost is your margin, and charging above the suggested price is an Owner action. See [Quote and record a sale](/installers/quote-and-record-a-sale). ### When am I charged, and how do I get an invoice? SureBright charges you its share of each plan in the month after the sale is recorded. The amount shows as **Warranty Cost to You** on the Dashboard. Download past bills from **Settings** > **Billing** > **Billing history**, or open a plan and select **Download Invoice**. See [Getting paid, and what you are charged](/installers/invoices-and-payouts). ### Is the plan taxed? Enter project cost without taxes when you quote. How tax applies to the plan line on your own invoice depends on where your customer is, so check with your tax advisor, and ask SureBright if you are unsure how to show it. See [Tax on protection plans](/learn/tax). ## Cover and your customer ### When does cover start, given my installation warranty? Cover begins on the plan purchase date and runs to the end of the plan's term. Your installation warranty and the manufacturer warranty apply first for the problems they cover, and the plan picks up those problems when they end. Accidental damage to portable devices and power surge are covered from the plan purchase date. Labour is covered during the manufacturer warranty once your installation warranty has ended. See [What your customer gets](/installers/your-customer). ### What does my customer receive? When you record the sale, SureBright sends your customer a confirmation of the plan, what it covers and how to file a claim. They do not register products or keep receipts. There is also a plain-language customer guide for you to hand over. See [What your customer gets](/installers/your-customer). ## After the sale ### My job changed after I sold the plan. Can I update it? Yes. Until the 90th day after the installation was completed, open the plan under **Sales** and edit it to change the term or add or remove products. After that, email SureBright support with the order number and the change. A later installation job for the same customer can get its own plan within 90 days of its completion. See [Changes and cancellations](/installers/changes-and-cancellations). ### My customer wants to cancel. What do I do? Your customer can cancel at any time. Open the plan under **Sales** > **Sold plans** and select **Cancel sale**. The portal shows the refund amount before you confirm. See [Changes and cancellations](/installers/changes-and-cancellations). ## Claims and service work ### Who handles a claim, and do I do the repair? SureBright reviews and approves the claim. Your customer files it online or through SureBright support, or you file it for them from their plan. When a claim is approved, you get the repair job first as the original installer, and you are paid for the work. Do not repair anything before it is authorised. See [Claims on a system you installed](/installers/claims). ### What if I cannot take a service request? Reject it with a reason, within 24 hours. The job then goes to a qualified technician in SureBright's network, or to an installer you refer. If you do not respond in time, the request is rejected automatically. See [Service requests: doing the repair](/installers/service-requests). ## Related What the plan is and how you earn from it. Where to go for each task. For your own system or a platform you build. What decides the tax on a plan. --- # What a plan can cover Source: https://docs.surebright.com/installers/eligibility > Check who can buy a Whole System Warranty, what you must provide, which items in a project are eligible, and by when the sale must be recorded. Use this page before you quote, to check that the customer, the system and each item on your proposal can go on a plan. It covers eligibility only. For what the plan does when something fails, give your customer the customer guide and see [What your customer gets](/installers/your-customer). ## Who can buy a plan Homeowners whose system you installed, in the United States or Canada. Ask SureBright before you quote a commercial project. ## What you must provide An installation warranty of at least 90 days. The system is eligible only if you give one. You choose its length when you quote, under **Select Installer Warranty Duration**. Your installation warranty applies first, which is why the portal asks for it. ## What makes an item eligible An item can go on the plan when all three are true: 1. It is part of the professionally installed system. 2. It is listed on your installation invoice. 3. It was sold with a manufacturer warranty of at least 1 year. You do not enter the manufacturer warranty for each product. SureBright looks it up when a claim is reviewed. | Eligible | Not eligible | | --- | --- | | Home theatre and audio/video | Products sold as-is | | Smart home automation and control | Products without a qualifying manufacturer warranty | | Security and surveillance | Products that are not on your installation invoice | | Lighting and shade control | Separately purchased or non-integrated items | | Home networking | Consumables, such as batteries and lightbulbs | | HVAC control | Racks, mounts, brackets and wall plates | | Power management and protection | Structural hardware and connectors | | Accessories integrated at installation, such as the cables installed as part of the system | Energy generation and storage products | ## How your labour counts Your installation labour is part of the project, so it is part of the eligible project cost. The price of the plan is worked out on the total eligible project cost and the term you pick. - Enter the project cost with your installation cost included and taxes excluded. - A plan needs at least one eligible product. Labour on its own cannot be covered. For tax on the plan itself, see [Tax on protection plans](/learn/tax). ## What happens to items that are not eligible Nothing you need to remove by hand. When you record the sale, the portal sorts your items into two tabs, **Eligible items** and **Not eligible items**. - Items on **Not eligible items** are taken out before the plan is priced, so your customer pays only for what the plan covers. - The portal shows **Total project cost** and **Total eligible project cost** side by side, so you can see the difference. - If an eligible item was sorted wrongly, move it back with **Move to Eligible** and pick its product category. - Items that are not eligible are not part of the plan. After the sale, the plan lists them under **Not covered**. See [Quote and record a sale](/installers/quote-and-record-a-sale) for the steps. ## When the sale must be recorded | Situation | What applies | | --- | --- | | You finished the installation | Record the sale within 90 days of completing the job. After that the system is no longer eligible. | | You finished a job in the last 90 days and the customer has only now decided | It is still eligible today. Record it before the 90 days run out. | | The customer wants the plan more than 90 days after the installation | That system can no longer be covered. The next installation job you complete for them can be, within 90 days of its completion. | | You do a later job or phase for the same customer | Add the products to the existing plan while it can still be edited, or record a new plan for the later job within 90 days of completing it. See [Change or cancel a plan](/installers/changes-and-cancellations). | ## Check before you quote | You are quoting | Can it go on the plan? | | --- | --- | | **Cables** | Yes, when they are installed as part of the system and listed on your installation invoice. Connectors are not eligible. | | **Racks and mounts** | No. Racks, mounts, brackets, wall plates and structural hardware are not eligible. | | **Lighting** | Lighting and shade control are eligible. Lightbulbs are consumables and are not. | | **A product without a manufacturer warranty** | No. It needs a manufacturer warranty of at least 1 year. | | **As-is stock** | No. Products sold as-is are not eligible. | | **Refurbished stock** | Only if it meets all three rules: part of the installed system, on your installation invoice, and sold with a manufacturer warranty of at least 1 year, not as-is. If you are unsure, ask SureBright. | | **Equipment the customer supplied** | The same three rules apply. An item that is not on your installation invoice, or that the customer bought separately, is not eligible. If you are unsure, ask SureBright. | | **Batteries** | No. They are consumables. | | **Energy generation or storage products** | No. They are not eligible. | | **A commercial project** | Ask SureBright before you quote. | Something not listed here? Ask SureBright before it goes on the proposal. ## Related - [Quote and record a sale](/installers/quote-and-record-a-sale) - [Choose how you sell](/installers/ways-to-sell) - [Change or cancel a plan](/installers/changes-and-cancellations) - [Common questions](/installers/common-questions) --- # Get set up Source: https://docs.surebright.com/installers/getting-started > Create your installer portal account, add your stores, service locations and bank account, invite your team, and run your first quote. Use this page to go from the sign-in link SureBright sent you to your first quote. The business owner, or someone authorised to decide for the business, creates the account. Everyone else joins by invitation. ## Create your account and your first store Open the sign-in link SureBright sent you and choose **Sign up**. Enter your work **Email address**. The portal asks "Are you the business owner or authorized decision-maker?". Choose **Yes**. If you are not, ask the owner to sign up and invite you afterwards. Enter the code SureBright emails you, then select **Verify**. On "Let's get your owner account ready", enter **Your full name**, **Business name**, **Years of experience** and **Business phone number**, and choose a password. A store is one business location, with its own service locations, team and records. Enter the **Store name** and its address in the United States or Canada. A store phone number is optional. On "Pick all service locations you cover", choose one: - **Nationwide (US)** or **Nationwide (Canada)** if you take service work anywhere in the country. - **Select Specific States** or **Select Specific Provinces** if you work in certain states or provinces. - **Select Specific Cities** if you work in certain cities. - **Select specific locations on map** if you work within a set distance of a point on the map. SureBright sends you service requests inside these locations, so set them to where you really work. The last step asks for a bank account for two things: - **We pay you via**: where SureBright deposits your payouts for approved service invoices. - **We bill you via**: the account SureBright bills for its share of each plan you sell. It is billed monthly, and it is SureBright's share only, not your retail price. You can use the same bank account for both. If a bank account shows **Verification pending**, select **Resume bank verification** to finish it. The next screen lists your stores. Select **Add new store** if you have another location, and **Invite** to add a team member to a store. When every store is complete, select **Next**. ## While your account is reviewed After you submit, the portal shows "Congratulations! Your account setup is complete." and tells you SureBright is reviewing your details. You are emailed when you are approved. Until then: - The Dashboard shows "Your account is currently under review." - Under **Settings** > **Manage stores**, the store shows **In review** and **Awaiting approval**. It changes to **Active** once approved. - New sales and service activity become available after approval. A store that shows **Setup incomplete** is missing details. Select **Continue setup** to finish it. ## Invite your team Open **Team management** and select **Add team member**. Enter the person's name and email, choose a role, and pick one store or **All stores**. The invitation stays under **Pending invitations** until they accept. If the email does not arrive, select **Reinvite**, or use **Copy link** and send the link yourself. The money side, such as billing and payouts, is the **Owner**'s responsibility. See [Team, roles and stores](/installers/team-and-stores) for what each role can do. Roles here are separate from the POS portal. Someone who already has a POS portal login still needs an invitation to the installer portal. ## Learn the portal Open **Training** in the menu. The **Onboarding & Training** page has three sections: - **FAQs**: answers to common questions, grouped by topic. - **Tours**: short walkthroughs of the portal. - **Product Demos**: short sales training videos. On a desktop, the Dashboard also has a **Getting started** panel with the training videos and quick links. ## Run your first Quick quote On the **Dashboard**, select **Quick quote**. Type the **Total Project Cost**, including your installation cost and excluding taxes. Choose your installation warranty length under **Select Installer Warranty Duration**. The portal lists the plan terms with the suggested price, your cost and your margin for each. A quote is an estimate. Nothing is covered until you record the sale. See [Quote and record a sale](/installers/quote-and-record-a-sale). ## Before your first sale - Your store shows **Active** under **Settings** > **Manage stores**. - A bank account is in place for both **We pay you via** and **We bill you via**. - Your service locations match where you install and service. - You give your customers an installation warranty of at least 90 days. - You know which route each job will take. See [Choose how you sell](/installers/ways-to-sell). - If you use a proposal tool, you have the Dealer Setup Sheet from SureBright. If you use Specifi, your SureBright Store ID is entered there and your Specifi account is synced with SureBright. If it is not synced yet, reach out to us at [support@surebright.com](mailto:support@surebright.com). - Everyone who will quote or record sales has accepted their invitation. - You have the customer guide ready to hand over with your proposals. See [What your customer gets](/installers/your-customer). ## Related - [Find your way around the portal](/installers/portal-tour) - [What a plan can cover](/installers/eligibility) - [D-Tools SI, Portal.io and Specifi](/installers/proposal-tools) - [Whole System Warranty overview](/installers/overview) --- # Getting paid, and what you are charged Source: https://docs.surebright.com/installers/invoices-and-payouts > The two money flows in the installer portal: what SureBright pays you for service work, and what SureBright charges you for the plans you sold, with where to see and download each. Use this page to invoice a finished repair, track your payout, and understand what SureBright charges you for plans. These are two separate flows, so keep them apart when you read your numbers. | Flow | Direction | Where you see it | | --- | --- | --- | | Service work | SureBright pays you | **Invoices** | | Plans you sold | SureBright charges you its share | **Warranty Cost to You** on the Dashboard, and **Billing history** | The money side of the portal is the Owner's responsibility. If you cannot see earnings, costs, invoices or **Billing**, your role does not include them: ask your Owner. ## What SureBright pays you for service work ### Submit an invoice for a finished job You can invoice a job once you have closed it and SureBright has approved your closing report. The job then appears under **Invoices** > **Unpaid invoices** as **Pending**. Go to **Invoices** > **Unpaid invoices**. Use **View job details** if you want to see the repair behind it. The invoice is built for you from the approved report. It lists **Labor time**, **Team size**, **Hourly rate**, **Service total**, **Parts total** and **Total invoice amount**. One click sends it to SureBright. If an amount looks wrong, contact SureBright support with the request number before you submit. ### What the invoice is made of - **Labour**: the labour time approved for the job, at the fixed hourly rate the portal shows. - **Parts**: the parts you replaced, as listed in your approved report. If the manufacturer supplied the part under its warranty, or SureBright arranged the part, the invoice carries labour only. - **Only authorised work**: the invoice follows the approved estimate and any additional authorisation you were given during the job. Work that was not authorised is not paid, and neither is a visit where no problem was found. - **The deductible**: if one applied, you collected it from your customer before the repair. Do not take it off your invoice. Bill the approved labour and parts in full, and SureBright settles the deductible against the invoice when the invoice is cleared. The ledger on the Dashboard has a **Deductibles remitted** line. ### Follow the invoice to payment | Status | What it means | | --- | --- | | **Pending** | The job is ready to be invoiced, or the invoice is waiting to be processed. | | **Under review** | SureBright is reviewing the invoice you submitted. | | **Processing payment** | The invoice is approved and the payout is on its way. | | **Paid** | The payout has been sent. The invoice moves to **Paid Invoices**. | Open any invoice to see its activity and to select **Download invoice**. If SureBright sends an invoice back, the portal shows the reason and you get an email. Correct it in the portal and submit it again. ### Where your payout goes Payouts go to the bank account set under **Settings** > **Billing** as **We pay you via**. Add a payout method before you submit your first invoice. A bank account has to be verified before it can be used, so do this early. ## What SureBright charges you for plans you sold You collect the plan price from your customer. SureBright then charges you its share of each plan. The rest is your margin. - **Where you see it**: **Warranty Cost to You** on the Dashboard is SureBright's share of the plans you sold in the selected date range. On each plan, **Order details** shows **Total warranty price**, **Your cost** and **Your Margin**. - **The ledger**: select **Show full ledger** on the Dashboard for the lines behind the total, including refunds for cancelled plans. - **When you are billed**: once a month, in the month after the sale is recorded. Cancellations and refunds are adjusted on the bill automatically. - **How you pay**: SureBright collects from the bank account set under **Settings** > **Billing** as **We bill you via**. It can be the same account your payouts go to. ### Download a bill Open **Settings** > **Billing** > **Billing history**. Each row shows the date, store, amount, status (**Processed** or **Awaiting payment**) and payment method, with **Download invoice** at the end of the row. For one plan, open it under **Sales** > **Sold plans** and select **Download Invoice**. ### Set or change the bank account Under **Settings** > **Billing** > **Payment method**, select **Add payment method**. Use **Make default** to choose the account used across your stores. If you run several stores, the **Stores** list lets you set **We pay you via** and **We bill you via** for each one. For how tax applies to a plan, see [Tax on protection plans](/learn/tax). Project cost is entered without taxes when you quote. ## Where you see your earnings The **Your earnings** card on the Dashboard shows what the Whole System Warranty earned you in the date range you select. **Revenue Breakdown** splits your revenue two ways: - **Plans sold**: revenue from the plans you sold. - **Service revenue**: what you were paid for service work. Change the date range or the store switcher to see a different period or store. ## Fix common problems | What you see | What to do | | --- | --- | | There is no **Submit Invoice** button | The job has to be closed and its report approved first. If the job is closed and approved and you still do not see it, ask your Owner to submit it. | | Your earnings look lower than expected | Widen the date range or switch to **All stores**. Service revenue counts only once an invoice is paid. | | A payout is late | Check that a payout method is set, and verified, under **Settings** > **Billing**. If it is, contact SureBright support with the invoice number. | | You cannot see **Billing**, earnings or margins | Your role does not include them. Ask your Owner. | | You were billed for a plan you cancelled | Cancellations and refunds are adjusted automatically. Check **Show full ledger** for the **Refunds / Cancellations** line, and contact support if it is missing. | ## Related Close the job so it can be invoiced. How the plan price, your cost and your margin are set. Who can see the money views. What decides the tax on a plan. --- # Whole System Warranty Source: https://docs.surebright.com/installers/overview > What the Whole System Warranty is, who it is for, how you earn from it, and the steps from your proposal to being paid for a repair. The Whole System Warranty is one plan that protects a professionally installed, connected system as a whole, parts and labour, for 2, 3 or 5 years. Your customer gets a single plan for the home theatre, automation, security, networking, lighting and other eligible products you installed, instead of a warranty for each product. Use this page to see how the programme works and where each step is explained. ## Who it is for It is for you if you install connected systems for homeowners in the United States or Canada and give your own installation warranty of at least 90 days. You are the seller: you quote the plan, collect the price from your customer and keep your margin. SureBright runs the plan. Planning a commercial project? Ask SureBright before you quote it. ## Two ways you earn | You earn | How | | --- | --- | | **Margin on every plan** | The portal shows your cost and a suggested customer price. What you charge above your cost is yours. | | **Paid service work** | When a covered product needs repair, you have the first right to do the work on your own installs, and SureBright pays you for it. | ## Who does what | | You | SureBright | | --- | --- | --- | | **Selling** | Quote the plan, collect the price from your customer, record the sale. | Works out the price from the eligible project cost and the term. | | **What is covered** | List what you installed. | Checks which items the plan can cover. | | **Your customer** | Hand over the customer guide with your proposal. | Sends the plan confirmation and handles customer support. | | **Claims** | File a claim for your customer if they come to you. | Reviews and approves every claim. Replaces or reimburses when a product cannot be repaired. | | **Repairs** | Accept the service request, send an estimate, do the authorised work. | Authorises service before any repair. Sends the job to its own network if you cannot take it. | | **Money** | Pay SureBright's share of each plan you sell. Invoice for your service work. | Pays you for approved service work. | ## From proposal to payout Create your account, add your stores and service locations, and add a bank account. See [Get set up](/installers/getting-started). Get a price with **Quick quote**, or add the plan as a line item in your proposal tool. [Choose how you sell](/installers/ways-to-sell) shows which route fits you, and [What a plan can cover](/installers/eligibility) tells you what to include. Once your customer has bought the plan and the installation is complete, record the sale within 90 days of completing the job. A line item in a proposal is not coverage until the sale is recorded. See [Quote and record a sale](/installers/quote-and-record-a-sale). SureBright sends your customer a confirmation of the plan, what it covers and how to file a claim. See [What your customer gets](/installers/your-customer). Your customer files a claim with SureBright, or you file it for them from the plan with **File claim**. A failure must be reported within 30 days. SureBright reviews and approves the claim. See [Claims on a system you installed](/installers/claims). The service request comes to you first. Respond within 24 hours with **Accept**, **Extend timeline** or **Reject**, send your estimate, and start work only after it is approved. See [Service requests](/installers/service-requests). Close the job with **Mark job as done** and a closing report. Once the report is approved, the invoice can be submitted. See [Invoices and payouts](/installers/invoices-and-payouts). Do not start a repair before SureBright authorises it. Unauthorised repairs are not paid. ## Where to go next Proposal tools, the installer portal, or your own system: pick one route per job. From sign-up to your first quote. Check items before you quote. Quick quote, Record sale and saved proposals. What to do in each proposal tool, and afterwards. Change orders, corrections and cancellations. ## Related - [Find your way around the portal](/installers/portal-tour) - [Team, roles and stores](/installers/team-and-stores) - [Common questions](/installers/common-questions) --- # Find your way around the portal Source: https://docs.surebright.com/installers/portal-tour > Where everything lives in the installer portal: the Dashboard, the menu, the store switcher, and the screen to open for each thing you need to do. Use this page to learn what each part of the installer portal is for and where to go for a given task. Sign in with the link SureBright sent you. You land on the **Dashboard**. ## What each menu item opens | Menu item | What you do there | | --- | --- | | **Home** | The **Dashboard**: start a quote or a sale, check your earnings, and see what needs attention. | | **Sales** | Every plan and proposal, in three tabs: **Sold plans**, **Draft Proposals** and **Expired Proposals**. | | **Service** | Repair jobs SureBright sends you, in four tabs: **New Request**, **Ongoing**, **Completed** and **Rejected**. | | **Claims** | Claims on the plans you sold, under **Open claims** and **Resolved claims**. | | **Invoices** | What you are paid for service work, under **Unpaid invoices** and **Paid Invoices**. | | **Team management** | Invite people, set their role and store, and remove them. | | **Training** | The **Onboarding & Training** page: videos, portal tours and the FAQ. | | **Settings** | **Account details**, **Manage stores**, **Billing** and **Contact us**. | What you see depends on your role. See [Team, roles and stores](/installers/team-and-stores). ## Start a quote or a sale from the Dashboard Two buttons sit at the top of the Dashboard. | Button | Use it when | | --- | --- | | **Quick quote** | You need a price for a proposal or a conversation, before the customer has decided. You enter the project cost, your installation warranty length and the plan term. | | **Record sale** | The customer has bought the plan and the installation is complete. | A quote is an estimate. Nothing is covered until you record the sale. See [Quote and record a sale](/installers/quote-and-record-a-sale). If both buttons are greyed out, the store you have selected is not **Active** yet. Pick another store, or finish the store's setup under **Settings** > **Manage stores**. ## See what you earned and what you owe The **Your earnings** card shows what the Whole System Warranty earned you in the date range you pick: **Last 7 days**, **Last 30 days**, **Last 3 months** or **Custom range**. - **Warranty Cost to You** is SureBright's share of the plans you sold in that period. It is what SureBright charges you, and it shows a due date once a bill has been raised. - **Show full ledger** opens the lines behind the totals, including your margin, service revenue and refunds for cancellations. - **Revenue Breakdown** splits your revenue into **Plans sold** and **Service revenue**. Whether you see the earnings and cost cards depends on your role. If you do not, ask your Owner. For how the money works, see [Getting paid, and what you are charged](/installers/invoices-and-payouts). ## See what needs your attention Below the earnings, four columns show your latest work: **Plans sold**, **Claims**, **Service Request** and **Invoices**. Each card is one record: one plan, one claim, one service request or one invoice. A card shows its status, and the status changes as the work moves on, so the columns tell you what to deal with next. Select a card to open the record. **Recent activities** lists the latest changes on your account. Select **View all** to see the full list, and filter it by **Plan sold**, **Plan canceled** or **Team event**. ## Switch between stores If your account has more than one store, the store switcher at the top of the page shows one store or **All stores**. Every list in the portal follows your choice. | Role | What the switcher offers | | --- | --- | | Owner | Every store, and **All stores**. | | Admin | The stores assigned to them. | | Custom Installer | No switcher. They work in one store and see the service requests assigned to them. | If a plan, claim or request seems to be missing, check the switcher first. ## Find the training videos and the FAQ Open **Training** in the menu. The **Onboarding & Training** page holds short sales training videos, portal tours and the FAQ, and you can search across all three. The Dashboard can also show a **Getting started** panel with **Training videos** and **Quick links** to **FAQs**, **Take a Tour** and **Coverage explainer**. ## Where to go for each task | You want to | Go to | | --- | --- | | Price a job before the customer decides | **Quick quote** on the Dashboard | | Record a plan the customer bought | **Record sale** on the Dashboard | | Pick up a quote you saved | **Sales** > **Draft Proposals** | | Re-quote a proposal that ran out | **Sales** > **Expired Proposals** | | Find, change or cancel a plan | **Sales** > **Sold plans**, then open the plan | | File a claim for a customer | Open the customer's plan under **Sales**, then **File claim** in **Order details** | | Follow a claim | **Claims** > **Open claims** or **Resolved claims** | | Answer a new service request | **Service** > **New Request** | | Send an estimate, extend a job or close it | **Service** > **Ongoing** | | Submit an invoice for a finished job | **Invoices** > **Unpaid invoices** | | See what you have been paid | **Invoices** > **Paid Invoices** | | See what SureBright charges you for plans | **Warranty Cost to You** on the Dashboard, then **Show full ledger** | | Download a past bill from SureBright | **Settings** > **Billing** > **Billing history** | | Add or change your bank account | **Settings** > **Billing** > **Payment method** | | Add a store or change where you do service | **Settings** > **Manage stores** | | Invite a colleague | **Team management** > **Add team member** | | Change your email, phone or password | **Settings** > **Account details** | | Reach SureBright | **Settings** > **Contact us** | ## Related Price a job and record the plan once the customer buys. Respond to a repair job, estimate it and close it. Invoices for service work and the bill for plans you sold. Who can see and do what, and how stores work. --- # D-Tools SI, Portal.io and Specifi Source: https://docs.surebright.com/installers/proposal-tools > How to add the Whole System Warranty to a proposal in D-Tools SI, Portal.io, Specifi or another proposal tool, and what you must do afterwards so the plan exists. Use this page to add the plan to a proposal in your proposal tool and to make sure the sale reaches SureBright afterwards. **The rule:** only an integrated tool sends the sale to SureBright. In every other tool the plan is a line item on your proposal, and nothing is covered until you record the sale in the installer portal. | Tool | Sends the sale to SureBright | What you do after the customer buys | | --- | --- | --- | | **D-Tools SI** | No | Record the sale in the installer portal. | | **Portal.io** | No | Record the sale in the installer portal. | | **Specifi** | Yes | Check the sale appears under **Sold plans**. Do not record it again. | | **Another proposal tool** | No | Record the sale in the installer portal. | ## D-Tools SI D-Tools SI does not send anything to SureBright. The plan is a line item until you record the sale. **In D-Tools SI** 1. Have the Dealer Setup Sheet SureBright gave you to hand. It lists the Whole System Warranty SKUs. 2. Add the SKU that matches the term your customer wants, 2-year, 3-year or 5-year, to the proposal. 3. Enter the price. For the exact price for this job, run a **Quick quote** in the installer portal with the project cost and your installation warranty length. **Afterwards, in the installer portal** 1. Wait until your customer has bought the plan and the installation is complete. 2. Select **Record sale** and upload the invoice or the signed proposal, as a PDF, PNG or JPEG of up to 5 MB. 3. Review the items, choose the same term and price as on the proposal, add your customer's details and select **Submit**. **What to check:** the plan is under **Sales** > **Sold plans**, with the term and price your customer agreed to. Do this within 90 days of completing the installation. ## Portal.io Portal.io does not send proposal data to SureBright. The steps are the same as for D-Tools SI. **In Portal.io** 1. Add the Whole System Warranty SKU for the term to your proposal, using the Dealer Setup Sheet SureBright gave you. 2. Enter the price. Run a **Quick quote** in the installer portal if you need the exact price for this job. **Afterwards, in the installer portal** 1. Once your customer has bought and the installation is complete, select **Record sale**. 2. Upload the invoice or the signed proposal, review the items, choose the term, add your customer's details and select **Submit**. **What to check:** the plan is under **Sales** > **Sold plans**, recorded within 90 days of completing the installation. ## Specifi Specifi is integrated. The price comes from SureBright and the plan is created from inside Specifi, so you do not record the sale in the installer portal. **Before your first Specifi proposal** 1. Create your own SureBright installer account. See [Get set up](/installers/getting-started). 2. Enter your SureBright Store ID on Specifi's SureBright page. This is what records each sale under your account. If you do not have your Store ID, ask your SureBright contact. If your Specifi account has not been synced with SureBright yet, reach out to us at [support@surebright.com](mailto:support@surebright.com). Do this before you sell your first plan in Specifi, so every sale shows in your portal from the start. **In Specifi** 1. Build the proposal. Specifi gets the plan price from SureBright, from the proposal's line items and your installation warranty length. 2. When your customer buys the plan, it is created from inside Specifi. 3. If the plan has to be cancelled, cancel it from inside Specifi too. **Afterwards, in the installer portal** 1. Open **Sales** > **Sold plans** and find the sale. 2. If it is missing, your Specifi account may not be synced yet. Reach out to us at [support@surebright.com](mailto:support@surebright.com) with the proposal reference. Do not use **Record sale** for a job Specifi has sent, or you create a second plan. **What to check:** every plan sold in Specifi appears once under **Sold plans** in your portal. ## Another proposal tool If your proposal tool is not listed, treat it like D-Tools SI. 1. Add the plan to the proposal as a line item, using the values on the Dealer Setup Sheet SureBright gave you. 2. Enter the price. Run a **Quick quote** in the installer portal if you need the exact price for this job. 3. Once your customer has bought and the installation is complete, record the sale in the installer portal with **Record sale**. **What to check:** the plan is under **Sales** > **Sold plans**. Until it is, your customer has a proposal, not a plan. Want the plan to flow from your proposal tool by itself, the way it does from Specifi? [Tell us which tool you use](/platforms/request-a-platform?type=proposal). ## If a job did not go through your proposal tool Use the installer portal for the whole job: **Quick quote** for the price, then **Record sale**. See [Quote and record a sale](/installers/quote-and-record-a-sale). If you mix tools, read [Choose how you sell](/installers/ways-to-sell) first so that each job is recorded once. ## Related - [Choose how you sell](/installers/ways-to-sell) - [Quote and record a sale](/installers/quote-and-record-a-sale) - [What a plan can cover](/installers/eligibility) - [Change or cancel a plan](/installers/changes-and-cancellations) --- # Quote and record a sale Source: https://docs.surebright.com/installers/quote-and-record-a-sale > Get a Whole System Warranty price with Quick quote, save a proposal for later, and record the sale in the installer portal once your customer has bought. Use this page to price a plan for a proposal and to record the sale afterwards. Both start from two buttons on the **Dashboard**: **Quick quote** and **Record sale**. | Use | When | What you get | | --- | --- | --- | | **Quick quote** | At proposal stage, before your customer has decided. | A price for each plan term. Nothing is covered yet. | | **Record sale** | Your customer has bought the plan and the installation is complete. | A sold plan. | Record the sale within 90 days of completing the installation. ## Get a price with Quick quote Select **Quick quote** and type the **Total Project Cost**: the exact amount, including your installation cost and excluding taxes. Pick **3 Months**, **6 Months** or **12 Months** under **Select Installer Warranty Duration**. Under **Select Warranty**, each plan term shows its **Retail Price**, **Cost (Fixed)** and **Your margin**. **View coverage and cost details** explains what is covered and how margins work. Put the price in your proposal. To carry on in the portal, select a term and then **Next**, which opens **Record sale** with the quote. ### Your price and your margin - **Cost (Fixed)** is SureBright's share of the plan, a fixed amount for that plan. It is what SureBright bills you. - **Retail Price** starts at the suggested customer price. Select the pencil to change it. - **Your margin** is the retail price minus your cost. Anything you charge above the suggested price is extra margin for you. - You cannot set a price below your cost. If you cannot set a price above the suggested price, ask your Owner to do it. ### Save a proposal and come back to it A quote on its own is not saved. To keep it, take it into **Record sale**, add the items, then close the screen. When the portal asks "What would you like to do with this sale?", choose **Save as proposal** and enter the customer's **Full name** and **Email address**. Saved proposals are under **Sales**: - **Draft Proposals**: proposals you saved and have not sold. Open one to edit it or finish the sale, download it as a PDF, or delete it. - **Expired Proposals**: proposals whose quote ran out before a sale. An expired proposal cannot be sold. Run a new **Quick quote** for the job. ## Record a sale Select **Record sale**. If you have more than one store, choose the store the sale belongs to. Then add the items in one of three ways. | Way | Do this | | --- | --- | | **Upload** | Select **Tap to upload invoice or receipt**, choose the invoice or signed proposal (PDF, PNG or JPEG, up to 5 MB), then select **Next**. The portal reads the line items for you. | | **Enter by hand** | Select **Enter details manually**, then **Add item** for each line: **Product name**, **Product category**, **Unit price** and **Quantity**. Put the product type in the name, such as speaker or TV. | | **From a saved proposal** | Select **Select existing proposal**, pick the draft, then select **Next**. | The sale then moves through three steps: **Product**, **Warranty plan** and **Customer details**. Set the **Purchase date**, then check both tabs, **Eligible items** and **Not eligible items**. A **Categorizing** tab shows while the portal is still sorting an upload. - To move an item, open its menu and choose **Move to not eligible** or **Move to eligible item**. An item you move to eligible needs a product category. - To change several items together, tick them and use **Change category**. - To add something the file missed, select **Add item**. The screen shows **Total project cost** and **Total eligible project cost**. Items that are not eligible are left out of the price. See [What a plan can cover](/installers/eligibility). Confirm **Select Installer Warranty Duration**, pick the term under **Select Warranty**, and adjust the **Retail Price** if you need to. Enter the customer's **Full name**, **Email address** and **Phone number**, and the installation address. SureBright uses these to confirm the plan with your customer and to send service to the right place. Select **Submit**. The portal shows "Sale recorded successfully". ## What happens after you record the sale - **Your customer hears from SureBright.** They receive a confirmation of the plan, what it covers and how to file a claim. - **The plan appears under Sales > Sold plans.** Open it to see **Total warranty price**, **Your cost** and **Your Margin**. - **You are billed later.** SureBright bills its share of each plan to your bank account the month after the sale is recorded. The amount shows as **Warranty Cost to You** on the Dashboard. - **You can still change it.** See [Change or cancel a plan](/installers/changes-and-cancellations). ## Fix common problems | You see | What to do | | --- | --- | | **Quick quote** and **Record sale** are greyed out | The store you selected is not approved yet, or is deactivated. See [Get set up](/installers/getting-started). | | The upload is refused, or you see "Something Went Wrong with Your File" | Use a PDF, PNG or JPEG of up to 5 MB. Choose **Replace Invoice** to try another file, or **Add Details Manually**. | | An item is on the wrong tab, or missing | Move it with its menu, or select **Add item**. | | The eligible total is lower than your invoice | Check **Not eligible items** and move back anything that belongs on the plan. | | "At least one eligible product is required" | A plan needs an eligible product, not labour alone. Give a product a category. | | "System warranty not available for the selected purchase date" | The date is too far back. A sale must be recorded within 90 days of completing the installation. | | "No Warranty Quotes Available" | Adjust the eligible project cost or the items. If the message stays, ask SureBright. | | "This proposal has expired. Create a new quote before completing the sale." | Run a new **Quick quote** and record the sale from that. | | A plan you recorded is not under **Sold plans** | Choose **All stores** in the store switcher and check your role. If it is still missing, contact SureBright support with the customer's name. | ## Related - [Choose how you sell](/installers/ways-to-sell) - [D-Tools SI, Portal.io and Specifi](/installers/proposal-tools) - [What a plan can cover](/installers/eligibility) - [Change or cancel a plan](/installers/changes-and-cancellations) --- # Service requests: doing the repair Source: https://docs.surebright.com/installers/service-requests > What to do when SureBright sends you a repair job on a system you installed: respond in time, send an estimate, do the work once it is approved, and close the job so you can be paid. Use this page when a service request arrives. You decide whether to take the job, tell SureBright what the repair will take, do the work once it is approved, and close the job with a report. Closing the job is what lets you invoice for it. ## Why you received a service request A claim on a plan you sold was approved. As the original installer you have the first right to do the repair, and you are paid for the work. New requests appear under **Service** in the **New Request** tab, and SureBright also emails you. Open a request to see the customer, the affected products, the issue and the time you have left to respond. ## Respond within 24 hours You have 24 hours from when the request is sent. The request shows the time remaining. | Choose | What happens | | --- | --- | | **Accept** | You take the job and tell SureBright what it needs. | | **Extend timeline** | You get another 24 hours to decide. You can do this once. | | **Reject** | You decline, with a reason, and the job is passed on. | If you do not respond in time, the request is rejected automatically and goes to the next qualified technician in SureBright's network. Your customer is still looked after, but the paid work goes to someone else. ## Where a job sits at each stage | Tab | What is in it | | --- | --- | | **New Request** | Requests waiting for your answer. | | **Ongoing** | Jobs you accepted. A job shows **Under review** while SureBright looks at your estimate, then moves on as the work progresses. | | **Completed** | Jobs you marked as done. | | **Rejected** | Requests you declined, and requests that ran out of time. | ## Accept the job and send an estimate Select **Accept**. The portal asks **Has the unit been inspected on site?** - **Yes, inspected**: describe the service needed and say when you can complete the job. - **Not yet**: say when you will visit the customer. After the visit, open the job and select **Add inspection details**. Select **Submit estimate** and fill in: - **Labor cost**: the hours the repair will take and your repair team size. The hourly rate is fixed and already shown, so you do not enter it. - **Add part**: each part that needs replacing, with its name, quantity and cost. List parts at your own cost. The hint beside **Cost (Per unit)** tells you how to work out the figure to enter. - Photos or documents that support the estimate: up to 5 files, PDF, PNG or JPEG, 5 MB each. The job shows **Under review** until SureBright approves the estimate. Some estimates are approved straight away. If an estimate is sent back, update it and submit it again. Do not start work before the estimate is approved. Work done before approval is not paid. If you cannot source a part, say so, and SureBright arranges it. If the manufacturer supplies the part under its warranty, your estimate covers the labour only. ## When the job changes | What happened | Do this | | --- | --- | | The job will take longer | On the ongoing job select **Extend timeline**, pick a reason and give the new completion date. The time remaining updates once the extension is approved. | | You found more damage | Ask for additional authorisation before doing the extra work. In **Extend timeline**, answer **Yes** to **Will this bump up the repair cost?**, enter the extra cost and why, and attach photos or documents. SureBright may approve all, part or none of it. | | The product cannot be repaired | Say so in your estimate, with your assessment. If you find out after the job has started, select **Cancel** on the job, choose **Unit beyond repair** and say whether any work was completed. SureBright decides between a replacement and a reimbursement and tells the customer. | | The customer is not answering | Select **Extend timeline** with that reason. If they stay unreachable, contact SureBright support. | ## Close the job with a report When the repair is finished, select **Mark job as done**. This is your closing report. Check the labour time, team size and parts used against the work you did, use **Edit estimation** to correct them, attach your invoice or receipt for the parts, add a note and select **Submit**. The report has to match the approved estimate and any additional authorisation you were given. SureBright reviews the report. Once it is approved, the job appears under **Invoices** ready to be invoiced. See [Getting paid, and what you are charged](/installers/invoices-and-payouts). ## Decline a request Select **Reject**, choose the reason and add a note. - If you have already visited the site, send SureBright your assessment with the rejection. SureBright uses it to route the job and to review payment for the visit. - You can refer another installer. Give the company name, contact name, email, phone and address. The repair is then done by the installer you referred or by a qualified technician from SureBright's network. Your customer is told who is handling it. ## Fix common problems | What you see | What to do | | --- | --- | | You missed the response window | The request was rejected automatically and passed on. If you can still take the job, contact SureBright support. | | The request is outside your service area | Reject it with that reason. Then check your service locations under **Settings** > **Manage stores**, so future requests match where you work. | | You are not receiving service requests | Check that the store is **Active**, that its service locations cover the areas where you installed, and that your role includes service requests. | | A job is stuck in **Under review** | SureBright is reviewing your estimate. If it was sent back, update and resubmit it. Otherwise contact support with the request number. | | You cannot extend a new request again | The response time can be extended once. Accept or reject the request before the time runs out. | | You cannot find a request | Check the store switcher, then the **Rejected** tab in case it ran out of time. | ## Related How the claim behind a request is filed and approved. Invoice a closed job and track the payout. Service locations decide which requests reach you. --- # Team, roles and stores Source: https://docs.surebright.com/installers/team-and-stores > Give your team access to the installer portal with the right role, add stores, and set the service locations that decide which repair requests reach you. Use this page to invite your team, decide what each person can see and do, add a store, and set where you do service work. Team changes are made under **Team management**. Stores are under **Settings** > **Manage stores**. ## What each role is for There are three roles. You pick one in the **Select role** list when you invite someone. | Role | Who it is for | What they work with | | --- | --- | --- | | **Owner** | The person who runs the business | Everything: every store, quotes and sales, claims and service requests, the team, billing and payouts | | **Admin** | Whoever runs the day-to-day | Quotes and sales, claims and service requests, and the team | | **Custom Installer** | The person who does the installation and service work | The service requests assigned to them: respond, submit the estimate, close the job with a report | The Owner is responsible for the money side: the bank account, what SureBright charges you and what it pays you. If a team member cannot see earnings, costs, margins, invoices or **Billing**, that is down to their role. Ask the Owner to do that step, or to change the role. ## Invite a team member Select **Add team member**. Under **Select role**, pick the role. Choosing **Owner** gives full access to every store, and the portal asks you to confirm that. For any role other than Owner, use **Select store** to pick where the person works. Enter **Full name** and **Email address**, then select **Send invite**. The person gets an email with a link to sign up. The invite sits under **Pending invitations**, with the date it was sent, until the person accepts. From there you can **Reinvite** them, copy the invitation link to send it yourself, or **Remove** the invite. ## Change or remove a team member | You want to | Do this | | --- | --- | | Change someone's role or store | Open the member's menu and select **Edit access**. Change **Role** or **Store name** and select **Save**. The change applies the next time they load the portal. | | Remove someone | Open the member's menu, select **Remove** and confirm. Their access ends immediately. Their quotes, sales and other records stay with the store. | | See who has left | Open the **Removed members** tab. | | See whether someone is using the portal | **Last active** shows when they last signed in. | ## Add a store and set where you do service A store is one of your business locations, with its own service locations, team and records. Your account can hold several. To add one, go to **Settings** > **Manage stores** and select **Add new store**. Enter the store's details, then choose its service locations: **Nationwide**, specific states or provinces, specific cities, or an area around a point on the map. | Store status | What it means | | --- | --- | | **Setup incomplete** | Details or service locations are missing. Select **Continue setup**. | | **In review** | SureBright is reviewing the store. | | **Active** | You can quote, record sales and receive service requests for it. | | **Deactivated** | The store is switched off. Use **Request reactivation** to bring it back. | To change an active store's name, address or phone number, or to deactivate it, select **Request changes**. SureBright reviews the request. ### Why service locations matter SureBright sends you service requests within the service locations you set. If they do not cover the areas where you install, requests for those customers will not reach you. If they are wider than where you really work, you will receive requests you have to reject. ## Work in one store or all of them If you have more than one store, the store switcher at the top of the page shows a single store or **All stores**, and every list follows it. An Owner can switch to any store, an Admin to the stores assigned to them, and a Custom Installer has no switcher. ## Your own account details and password Under **Settings** > **Account details** you can change your personal details, email address, phone number and password. Changing your email asks you to verify both the old and the new address. If you forgot your password, select **Forgot password?** on the sign-in page. SureBright emails you a one-time code to set a new one. ## Access is separate from the POS portal If you also sell per-product plans in the POS portal, roles there do not carry over. An Owner or Admin in the POS portal needs their own role in the installer portal, and the two can differ. Invite the person here as well. See [POS portal overview](/pos/overview). ## Fix common problems | What you see | What to do | | --- | --- | | The invite never arrived | Select **Reinvite** on the pending invitation and ask the person to check their spam folder. You can also copy the invitation link and send it yourself. | | You cannot invite anyone | Only Owners and Admins manage the team, and an Admin can invite people only to their own stores. | | A team member cannot see a store | Open **Edit access** and check their store. An Admin sees only assigned stores. | | A team member signs in and sees nothing | A Custom Installer sees service requests only once one is assigned to them, so an empty screen at first is normal. For an Owner or Admin, check which store they are assigned to, then check the store switcher. | | A team member cannot see earnings, margins, invoices or **Billing** | Their role does not include them. Ask the Owner. | | A store shows **Setup incomplete** | Open it, select **Continue setup** and finish the business details and service locations. | | You are not receiving service requests | Check that the store is **Active** and that its service locations cover the areas where you installed. | | Someone cannot sign in | Use **Forgot password?** on the sign-in page. If they never accepted the invite, reinvite them. | ## Related What each screen is for. Set up your account and your first store. What reaches you once service locations are set. --- # Choose how you sell Source: https://docs.surebright.com/installers/ways-to-sell > Pick the right way to quote and record a Whole System Warranty for each job, whether you use D-Tools SI, Portal.io, Specifi, the installer portal, your own system, or several of them. Use this page to decide how each job reaches SureBright. You can put the plan in a proposal in several ways, but a plan only exists once the sale is recorded with SureBright, and each job must be recorded once. ## Find your route | You write proposals in | You do this | What SureBright receives | What you still do by hand | Where the sale shows | | --- | --- | --- | --- | --- | | **D-Tools SI** | Add the Whole System Warranty SKU for the term (2-year, 3-year or 5-year) from your Dealer Setup Sheet as a line item, and enter the price. | Nothing. D-Tools SI does not send the proposal to SureBright. | Record the sale in the installer portal once your customer has bought and the installation is complete. | **Sales** > **Sold plans**, after you record it. | | **Portal.io** | Add the Whole System Warranty SKU to the proposal as a line item, and enter the price. | Nothing. Portal.io does not send the proposal to SureBright. | Record the sale in the installer portal. | **Sold plans**, after you record it. | | **Specifi** | Enter your SureBright Store ID on Specifi's SureBright page once. Then quote and sell the plan inside Specifi. | Your proposal's line items, your installation warranty length, and the sale itself. | Check that each Specifi sale appears in your portal. If one is missing, do not record it again: send SureBright the proposal reference. | **Sold plans**, once your Specifi account is synced with SureBright. | | **No proposal tool**, or a job you did outside it | Run a **Quick quote** from the project cost, then use **Record sale**. | The items you upload or type in, and your customer's details. | Everything happens in the installer portal. | **Sold plans**. | | **Your own system** | Have your developer connect it to SureBright. | The quote, the sale, and any later change or cancellation. | Ask SureBright to confirm that your first few sales arrived as you expect. | Ask your SureBright contact where these plans are listed for your account. | Using Specifi? If your Specifi account has not been synced with SureBright yet, reach out to us at [support@surebright.com](mailto:support@surebright.com) before you sell your first plan. Until it is synced, your Specifi sales do not show in your portal. The steps for each tool are on [D-Tools SI, Portal.io and Specifi](/installers/proposal-tools). The portal steps are on [Quote and record a sale](/installers/quote-and-record-a-sale). ## Three things that are always true **A line item in a proposal is not coverage.** A SKU or a price on a proposal is a quote. Nothing is covered until the sale is recorded with SureBright, by you in the installer portal or by a connected platform. **Record each job once, through one route.** If you record a job in the portal and a connected platform also sends it, you create two plans for the same customer. **Everything lands in one list.** Every plan you recorded, and every plan a connected platform sent for you, appears under **Sales** > **Sold plans** in your portal. With more than one store, choose **All stores** in the store switcher to see them together. Record the sale within 90 days of completing the installation. After that the system is no longer eligible, even if the plan was on the proposal your customer signed. ## If you use more than one Decide the route for each job before you send the proposal, and tell your team. | Your mix | Do this | Avoid | | --- | --- | --- | | **Specifi for most jobs, the portal for the rest**, such as a service-only job | Let Specifi send the jobs you proposed in Specifi. Use **Record sale** only for jobs that never went through Specifi. | Recording a Specifi job in the portal "to be safe". Look under **Sold plans** first. If a Specifi sale is missing, your Specifi account may not be synced yet: reach out to us with the proposal reference. | | **D-Tools SI or Portal.io proposals, plus the portal** | This is the normal pairing: the proposal carries the line item and the portal carries the sale. Upload the signed proposal or the invoice in **Record sale** so you do not retype the items. | Treating the signed proposal as the sale. Recording the job twice, once from a saved proposal and once from a new upload. If you saved a proposal for the job, start from **Select existing proposal**. | | **Two proposal tools**, such as D-Tools SI for some projects and Specifi for others | Note on each job which tool it came from. Record D-Tools SI jobs yourself. Leave Specifi jobs to Specifi. | Assuming every proposal tool sends the sale. Only an integrated tool does. | | **Your own system, plus the portal** | Once your system sends sales, stop recording those jobs by hand. Keep the portal for jobs your system does not handle. | Sending a job that someone has already recorded in the portal. | | **Whole-system plans, plus per-product plans** | Use the Whole System Warranty for a system you installed, and a per-product plan for a single product sold on its own. | Looking for a counter sale under **Sold plans**. The two kinds of plan are recorded separately. | Recorded a job twice? Cancel the duplicate and choose **Duplicate sale** as the reason. See [Change or cancel a plan](/installers/changes-and-cancellations). ## Selling per-product plans as well A per-product plan is a different plan from the Whole System Warranty. It covers a single product, and you sell it where that product is sold: - **At a counter, over the phone or on an invoice**, in the POS portal. See [POS portal overview](/pos/overview). - **In your online store**, on your product pages. See [Supported platforms](/platforms/overview). If you do both: - **Access is set up separately in each portal.** A role in the POS portal does not give you one in the installer portal, and the two roles can differ. - **The POS portal links to the installer portal.** When your account is set up for whole-system warranties, the POS portal menu shows **Sell System Warranties**, which opens the installer portal. ## Related - [D-Tools SI, Portal.io and Specifi](/installers/proposal-tools) - [Quote and record a sale](/installers/quote-and-record-a-sale) - [What a plan can cover](/installers/eligibility) - [Whole System Warranty overview](/installers/overview) Building the connection yourself? The quote, create, update and cancel calls are on [Whole System Warranty API](/api-reference/whole-system-warranty). --- # What your customer gets Source: https://docs.surebright.com/installers/your-customer > What your customer receives when you record a Whole System Warranty sale, how the plan fits with the manufacturer warranty and your installation warranty, and how to explain it in a few sentences. Use this page to answer your customer's questions about the Whole System Warranty and to explain the plan when you present a proposal. It covers what they receive, who covers a problem at each stage, and how they ask for help. ## What your customer receives when you record the sale When you record the sale, SureBright sends your customer a confirmation of the plan, what it covers and how to file a claim. - **Nothing to register.** Your customer does not register products or keep receipts. The order and the protected products are already on file with SureBright. - **Proof of the plan.** The confirmation is their proof. You can also open the plan under **Sales** and select **Download Invoice**. - **Correct details matter.** The confirmation goes to the contact details you entered, and service is sent to the installation address. If something is wrong, open the plan and use **Update customer details**. Nothing is sent, and nothing is covered, until the sale is recorded. A plan line in your proposal is not a recorded sale. See [Quote and record a sale](/installers/quote-and-record-a-sale). ## Who covers a problem, and when The plan works alongside the manufacturer warranty and your own installation warranty. For a problem either of those covers, that warranty applies first, and the plan picks up when it ends. | When the problem happens | A product breaks down | Labour to diagnose, repair and reinstall | Accidental damage to portable electronics, or a power surge | | --- | --- | --- | --- | | While your installation warranty is running | Your installation warranty or the manufacturer warranty, whichever covers the problem | Handled under your installation warranty | The plan | | After your installation warranty ends, while the manufacturer warranty is still running | The manufacturer supplies the part | The plan pays the labour, and you are paid for the work | The plan | | After both have ended, until the plan ends | The plan | The plan | The plan | Two things close the gaps the other warranties leave: - **Accidental damage and power surge are covered from the plan purchase date.** Your customer does not wait for another warranty to end. - **Labour is covered during the manufacturer warranty** once your installation warranty has ended. A manufacturer warranty typically covers the part only. ## What the plan protects, in plain words One plan protects the system you installed as a whole, for 2, 3 or 5 years, instead of a separate warranty for each product. - **Parts and labour** to repair the eligible products in the system when they break down. - **Accidental damage** on the portable electronics in the system, such as a tablet used to control it. - **Power surge.** The plan protects the eligible products on your installation invoice. See [What is eligible](/installers/eligibility) for what counts. A deductible can apply to a claim. The customer guide and the plan's own documents carry the full detail, so point your customer there for anything beyond this summary. ## How your customer asks for help Your customer has three ways to report a problem. | Way | How | | --- | --- | | Online | File a claim at **customer.surebright.com**. | | SureBright support | Email [support@surebright.com](mailto:support@surebright.com) or call **+1 855-306-4874**. | | Through you | They call you, and you file the claim for them from their plan in the portal. | A failure must be reported within 30 days. Tell your customer not to arrange a repair on their own: service has to be authorised by SureBright first. See [Claims on a system you installed](/installers/claims). ## The customer guide to hand over SureBright has a plain-language customer guide to the Whole System Warranty. It explains the coverage, the deductible, claims and cancellation. Hand it over with the proposal or at the end of the installation. If you do not have a copy, ask your SureBright contact. ## How to explain it to a customer After a large equipment sale, a plan is easy to present when you keep it to a few plain points. Each of these comes straight from how the plan works. 1. **One plan for the whole system.** "This covers the system I installed as one, for 2, 3 or 5 years. You do not need a warranty for each product." 2. **It starts where the other warranties stop.** "The manufacturer warranty and my installation warranty come first. When they end, this plan takes over." 3. **It covers what they leave out from day one.** "Accidental damage to the portable devices and power surge are covered from the day the plan starts. Once my installation warranty ends, the labour is covered too, even while the manufacturer still covers the part." 4. **Nothing to keep track of.** "You do not register anything or keep receipts." 5. **One call when something fails.** "You file a claim online, contact SureBright support, or call me and I file it for you. I installed the system, so I am the first one asked to fix it." If your customer wants to trim the proposal to meet a budget, offer a shorter plan term before dropping the plan. ## Related Which products and jobs a plan can protect. How a claim is filed, reviewed and followed. Change a recorded plan, or cancel it for a customer. Short answers to what you are most likely to ask. --- # Omnisend Source: https://docs.surebright.com/integrations/omnisend > Connect Omnisend so your own automations send SureBright's abandoned-cart offers: what to connect, the two ways the offer reaches Omnisend, and how to test it. If you email shoppers from Omnisend, you can have Omnisend send your abandoned-cart follow-ups. SureBright still captures the cart, picks the plan and creates the single-use code. Omnisend sends the message with your design, your sending domain and your reporting. Omnisend is one of the connected tools for [Abandoned Cart Recovery](/abandoned-cart-guide/abandoned-cart). It is available on stores where Abandoned Cart is switched on. ## Before you start - Abandoned Cart switched on for your store, with automatic follow-ups on. Omnisend receives offers only while automatic follow-ups are on. - An **API key** from Omnisend's store settings. ## Connect Omnisend In the Merchant Portal, open **Abandoned Cart**, then **Messages → Connected tools**. Press **Connect** on the **Omnisend** card, paste the API key and follow **Where to find it in** Omnisend. Answer **How your Omnisend emails get the offer**. The two choices are described below. Choosing one also makes Omnisend the sender of your follow-up emails. Press **Connect Omnisend**. Connecting sends nothing to shoppers. Open the window again with **Manage**, then use **Send test**, or **Try it on a contact** when Omnisend gets the offer on the contact, to check the result in Omnisend. ## How Omnisend gets the offer | Choose | What you do | |---|---| | **Write to contact properties** (use your existing Abandoned checkout automation) | Keep your automation and its timing. SureBright adds the offer to each shopper's Omnisend contact as `sb_` fields: the code, a checkout link with the plans already added, the discount, the plans and their prices, and when the code ends. Paste the personalization tags the card gives you into your email. The card also gives you a block that shows nothing when an email goes out before the offer is ready. SureBright sends no email of its own. | | **Send as event** (start a new automation from SureBright's event) | Build an automation in Omnisend triggered by the custom event **SureBright: Offer sent**, which arrives each time a follow-up step is due. Set the trigger's frequency so it can start every time, and write the email with the event's tags: code, checkout link, plan, discount, prices, code end, which follow-up, and SureBright's subject and message for the step. | Avoid double emails. With **Send as event**, turn off your Abandoned checkout automation in Omnisend. In both cases, switch off Shopify's own abandoned checkout email in Shopify. ## Test before you switch over - **Try it on a contact** puts sample offer fields on a contact you name, ideally your own, so you can preview the email. Remove them with **Remove the sample properties** when you are done. - **Send test** sends one **SureBright: Offer sent** event to an address you can check, so the event appears in Omnisend's trigger list. Omnisend automations started by a custom event also email contacts who are not subscribed, unless you change that in the trigger's channel settings. ## See results or disconnect Once connected, the Omnisend card shows an **Insights** section: the automations triggered by SureBright events in the last 7, 30 or 90 days, with **Triggered**, **Delivered**, **Opened**, **Clicked**, **Orders** and **Revenue**. The numbers are Omnisend's own. When you disconnect Omnisend you choose whether SureBright first **removes the offers** from every contact that holds one, or **leaves them**. ## Related - [Channels and connected tools](/abandoned-cart-guide/channels) lists every event SureBright can send and the other tools you can connect. - [Automatic follow-ups](/abandoned-cart-guide/automatic-follow-ups) explains when each follow-up is sent. --- # Brand Managed Campaign Source: https://docs.surebright.com/klaviyo-integration/brand-managed-campaign-guide > Build a Klaviyo flow that offers protection to customers who bought an eligible product without a plan, using your own templates, and look up the SureBright event attributes you can use in it. With a brand-managed campaign, your own Klaviyo flow emails customers who bought an eligible product without protection, in your templates and your voice. SureBright sends the events that start and stop the flow. This page shows how to build the flow and lists the event attributes you can use in filters and emails. Share your Klaviyo API keys first, as described in [Email integrations](/klaviyo-integration/integration-guide). The SureBright events appear in Klaviyo only after SureBright has completed the setup on your account. ## What SureBright sends to Klaviyo | Event | Sent when | Use it to | |---|---|---| | **SureBright: Eligible Order** | A customer buys a product that can carry a SureBright plan | Start your flow and send timed follow-ups to customers who did not buy a plan at checkout | | **SureBright: Policy Purchased** | A customer buys a plan for their product | Stop the follow-ups, and send your own thank-you message | Each event carries the order and product details, the plan's coverage summary and a personal link where the customer can buy the plan. The full list is under [Event attributes](#event-attributes) below. ## Build the flow in Klaviyo Log in to Klaviyo and go to **Flows** in 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 the flow something like `SureBright Post-Purchase Warranty`. For the **Trigger**, select **Metric** and choose `SureBright: Eligible Order`. Do not use the generic "Placed Order" trigger. It does not pick up warranty-eligible orders. Click **Trigger Filters** and add a condition: - **Field:** `is_eligible` - **Condition:** `equals` - **Value:** `true` This keeps the flow to orders that can receive a post-purchase offer. Trigger filter example in Klaviyo Add your email steps and insert values from the event. The one to include every time is: - `{{ event.post_purchase_url }}`: the customer's own link to buy the plan. You can also use: - `{{ event.order_id }}` - `{{ event.product_title }}` - `{{ event.coverage_options }}` - `{{ event.person.first_name }}` Use **SureBright: Policy Purchased** to end the flow for a customer once they have bought a plan. Place an order that contains a SureBright-eligible product and check that the flow starts and the email shows the right details. Before you turn the flow on, send a preview or test email to the SureBright team. SureBright must approve every post-purchase email before it goes live. ## Ways to use each event **SureBright: Eligible Order** reaches customers who did not buy a plan at checkout: - **Timed drip flows.** Nudge non-buyers at set intervals after the purchase. - **Follow-up campaigns.** Send reminders to protect an eligible product. - **Direct to purchase.** Use `post_purchase_url` to take the customer straight to their own offer. **SureBright: Policy Purchased** lets you close the loop: - **Thank your customer** with your own message. - **Stop further emails** that were scheduled for that customer. Two things make these flows work harder: - Tailor the message with attributes such as `product_title`, `coverage_type` and `policy_price`. - Split your flows by plan type, for example breakdown or accidental damage, so each message is relevant. ![Example Klaviyo flow](/images/klaviyo-flowchart.png) ## Event attributes Type these names exactly as shown in Klaviyo filters and templates. ### Attributes of SureBright: Eligible Order Your platform's order ID (for example the Shopify order ID) Total order amount Currency code (for example "USD") When the order was created URL of your store's logo URL of SureBright's logo Your store's name The customer's link to buy a plan for this order Title of the purchased product Whether the order can receive a plan Type of coverage A heading for the coverage list, matched to the coverage type The coverage points that come with the plan. Icon for the coverage point Coverage text **Example** ```json SureBright: Eligible Order [expandable] { "order_id": "1234567890", "order_amount": "199.99", "currency_code": "USD", "order_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." } ] } ``` ### Attributes of SureBright: Policy Purchased Your platform's order ID (for example the Shopify order ID) Unique identifier of the SureBright contract Title of the product the plan covers Length of the coverage (for example 1 year, 2 years) Price the customer paid for the plan When the plan was purchased Type of coverage (for example AD for accidental damage, B for breakdown) **Example** ```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" } ``` ## Common questions No. SureBright events start arriving in Klaviyo only after the integration is switched on. Orders from before that are not sent to Klaviyo. The events (**SureBright: Eligible Order**, **SureBright: Policy Purchased**) appear once SureBright has completed the setup on your account. If you have shared your keys and still do not see them, wait for confirmation from the SureBright team or contact support. ## Related - [Email integrations](/klaviyo-integration/integration-guide) - [Post-purchase offer links](/post-purchase/offer-links) - For help with setup or strategy, contact your SureBright representative, email [support@surebright.com](mailto:support@surebright.com), or ask your Klaviyo account manager. --- # Email integrations Source: https://docs.surebright.com/klaviyo-integration/integration-guide > Which emails SureBright sends for you, which ones your own email tool can send instead, and how to connect Klaviyo, Omnisend or a webhook. SureBright sends two kinds of email to your shoppers, and you can take over one of them. - **Service emails**: plan confirmations, the request for missing details, cancellation notices. SureBright always sends these itself, from `support@surebright.com` with your store named in the message. See [Emails your customers receive](/customer-emails/overview). - **Offer emails**: offering a plan to a shopper who did not buy one at checkout, or who left a cart behind. Your own email tool can send these in your design. ## Two ways to run the offer emails | Mode | Who sends | Who writes the copy | Best for | |---|---|---|---| | **White-glove** (available on request) | SureBright, from its own templates | SureBright, using your store name and the plan details | Stores that want the program running with no email work on their side | | **Brand-managed** | Your tool (Klaviyo or Omnisend), triggered by SureBright events or offer fields on the contact | You, in your own templates and sending domain | Stores with an email team and a house style | You can run both: white-glove for post-purchase offers and brand-managed for abandoned carts, or the other way round. Only one tool should send a given message, so shoppers never receive two. For what SureBright's own offer emails do and how to turn them on, see [Offer emails](/post-purchase/offer-emails). ## Connect Klaviyo For brand-managed campaigns in Klaviyo, SureBright sends events to your Klaviyo account and your flows send the email. SureBright needs your Klaviyo **Public** and **Private API keys**. [This short walkthrough](https://app.storylane.io/share/gmb05pqr5zbj) shows where to create them. Send them to your SureBright contact, or paste the private key into **Abandoned Cart → Messages → Connected tools** for the abandoned-cart events. Create a flow triggered by **SureBright: Eligible Order**, filter it to eligible orders and personalise it from the event attributes. **SureBright: Policy Purchased** lets you stop the sequence once a plan is bought. SureBright checks the flow before it goes live so the offer link, pricing and coverage wording are right. The flow setup step by step, the event attributes, a flow example and FAQs. ## Connect Omnisend Connect Omnisend from the Merchant Portal under **Abandoned Cart → Messages → Connected tools** with an API key. SureBright still finds the cart, picks the plan and creates the single-use code. Your Omnisend automation sends the message. Connecting, the two ways the offer reaches Omnisend, and how to test it. ## Use a webhook for other tools If you use a tool SureBright does not connect to directly, choose **Webhook** under Connected tools. SureBright posts each abandoned-cart event to an https address you own, which suits Zapier, Make or your own system. The events are listed on [Channels and connected tools](/abandoned-cart-guide/channels), and the request format for your developer is on [Notifications and webhooks](/api-reference/notifications-and-webhooks). ## Related - [Abandoned Cart Recovery](/abandoned-cart-guide/abandoned-cart) - [Post-purchase offer links](/post-purchase/offer-links) - For help with setup, copy review or campaign strategy, contact your SureBright representative or email [support@surebright.com](mailto:support@surebright.com). --- # Reading your attach rate Source: https://docs.surebright.com/learn/attach-rate > How to judge whether your protection attach rate is healthy, why quoted averages mislead, and the changes that reliably move it. **The short answer.** There is no single normal attach rate. It varies widely by product, price and where the offer appears. Judge yours against your own history and your own tests. ## You might be asking - What attach rate should I expect? - Mine is lower than the figure I was quoted. Is something wrong? - What can I do to raise it? ## What you need to know **Averages hide a very wide spread.** Stores in the same category sit far apart, because attach rate depends on what you sell, at what price, to whom, and how visible the offer is. A figure quoted for a category tells you little about your store. **A drop is more useful than a level.** A sudden fall almost always has a cause you can find: a new theme, a cart app, a product launch without categories, or a change to the default plan. **The same few things move it.** Where the offer sits on the product page, whether a plan is pre-selected, whether the offer is repeated in the cart, and whether customers get a second chance after purchase. ## What to do | Situation | Do this | | --- | --- | | You want to know where you stand | Open [Sales](/merchant-portal/sales) and read **Attachment Rate** against the previous period, by platform and by category. | | Your attach rate fell | Work through [Offer not showing?](/help/offer-not-showing), starting with what changed on your store that week. | | Many of your products have no offer | See [New products without an offer](/learn/new-products). | | You want to raise it | Try one change at a time: placement, the default plan, the cart offer. On Shopify, test each one with [Design tests](/merchant-portal/design-tests). | | You want a second chance at the sale | Use post-purchase offers and, on Shopify, [Abandoned cart](/abandoned-cart-guide/abandoned-cart). | ## Get ahead of it Note your attach rate each month alongside what you changed. After a few months you have your own benchmark, which is the only one that matters. ## Related - [Sales](/merchant-portal/sales) - [Design performance](/merchant-portal/design-performance) - [Pre-selected plans and conversion](/learn/pre-selected-plans) --- # Exchanges and changes to a plan Source: https://docs.surebright.com/learn/changing-a-plan > What to do with a protection plan when a customer cancels it, exchanges or replaces the product, wants a different or longer plan, passes the product to someone else, or needs their details corrected. **The short answer.** A plan covers one specific product for one customer. When the product changes, point the plan at the replacement. When the customer wants a different plan, cancel the first one and sell the right one. | You want to | Go to | | --- | --- | | Cancel or refund a plan | [Cancel or refund a plan](#cancel-or-refund-a-plan) | | Move a plan to an exchanged product | [The customer exchanged the product](#the-customer-exchanged-the-product) | | Know what happens when you send a replacement unit | [You sent a replacement unit](#you-sent-a-replacement-unit) | | Change the plan's length or type | [The customer wants a different or longer plan](#the-customer-wants-a-different-or-longer-plan) | | Move a plan to a new owner | [The customer sold or gave the product away](#the-customer-sold-or-gave-the-product-away) | | Fix the customer's name, email or the purchase date | [Correct the customer's name, email or purchase date](#correct-the-customers-name-email-or-purchase-date) | ## Cancel or refund a plan Refund the plan line in your store admin, or cancel the whole order. That cancels the plan for the units you refunded, the customer gets a cancellation email, and a plan you were already billed for comes back as a credit on your next invoice. | Your platform | How to cancel the plan | | --- | --- | | Shopify, BigCommerce | Refund the plan line, or cancel the order | | WooCommerce | Refund the plan line, or delete the order | | Magento | Issue a credit memo for the plan | | Shift4Shop | Reduce the warranty quantity on the order | | Other platforms | Send support the order number | Refunding only the product does not cancel the plan. Customers cannot cancel a plan themselves in the customer portal. The step-by-step answer for each platform, and how a refund issued by SureBright is worked out, is in [Helping a customer: "I want to cancel my plan"](/help/helping-a-customer#i-want-to-cancel-my-plan). What it does to your invoice is in [Refunds and your credit](/learn/refunds-and-credits). ## The customer exchanged the product The plan follows the product, not the order. If the covered product is swapped and nobody updates the plan, the plan still names the product that went back. | Situation | Do this | | --- | --- | | The new product is in the same category and a similar price | On Shopify, open the sale in [Sales](/merchant-portal/sales#find-a-sale) and use **Edit Product Details** to pick the new product. If the order is in [Order Resolution](/merchant-portal/order-resolution), choose **Associate product** there instead. On other platforms, send support the order number and the new product | | The new product costs more or less, so its plan would cost something different | Cancel and resell: refund the old plan line, then sell the plan for the new product with the [Shopify draft order extension](/draft-order-guide/shopify-draft-order) or [Leads](/merchant-portal/leads). The customer pays the new plan's price | | The new product is in a different category | The same: refund the old plan and sell the plan for the new product | | The product you sold is out of stock and you send a different model | Treat it as an exchange. Update the plan the same day you ship the substitute | **Edit Product Details** only accepts a product in the same category whose price falls in the same price band as the plan. If the portal refuses the product, cancel and resell. **Do not swap the product by editing the order alone.** On Shopify, editing the order to remove the old product and add the new one does not move the plan. The plan stays on the removed product and the order appears in Order Resolution for a decision. Adding a second plan line to the edited order creates a second plan, so the customer ends up with two. Edit the order for the product only, then move the plan as shown above, or answer the case with **Associate product**. ## You sent a replacement unit | Situation | What happens | Do this | | --- | --- | --- | | Same model, sent without refunding the original (damaged on arrival, your own warranty repair or swap) | The plan stays active on that model, with the same dates | Nothing | | Same model, processed as a refund of the original and a new order | The refund raises a case in Order Resolution. On Shopify, the plan is refunded after 48 hours if nobody answers | Answer the case: **Associate product** with the replacement, or acknowledge and keep the plan | | A different model or price | The plan does not fit the new product | Follow [The customer exchanged the product](#the-customer-exchanged-the-product) | | You refunded the plan line while exchanging the product | Refunding the plan cancels it. You are credited on your next invoice | Sell a new plan for the replacement if the customer wants one | A replacement does not restart the plan. Its start and end dates stay as they were. ## The customer wants a different or longer plan There is no editing a plan from one length or type to another, and two plans on the same product do not add up. A customer who bought a 1-year plan and later a 2-year plan has two separate plans, not 3 years of cover. 1. Refund the plan they do not want. See [Cancel or refund a plan](#cancel-or-refund-a-plan). 2. Sell the single plan they do want, with a [post-purchase offer link](/post-purchase/offer-links), the [Shopify draft order extension](/draft-order-guide/shopify-draft-order) or [Leads](/merchant-portal/leads). If the customer already holds two plans on one product, write to support with the order numbers before you refund anything. On the POS portal, use **Change warranty plan** in [Sales History](/pos/sales-history#change-warranty-plan). ## The customer sold or gave the product away There is no self-serve transfer. SureBright support usually does not move a plan to a new owner. A change of plan holder soon after purchase, for example when the product was bought as a gift, can often be made. Ask SureBright support with the order number and the new holder's details. Write to [support@surebright.com](mailto:support@surebright.com) with the order number, the product, and the new holder's name and email. Tell the customer that support decides each request. ## Correct the customer's name, email or purchase date | What is wrong | Do this | | --- | --- | | Name, email, phone or address, on Shopify or WooCommerce | Correct it on the order. The plan picks it up | | Name or phone, any platform | The customer can change it under **Account settings** in the [customer portal](/customer-portal/overview) | | The email the plan is under | Write to support with the order number and the new address. The customer sees and claims on plans under the email on the order | | Details on other platforms | Ask your SureBright contact | | The product's purchase date | Write to support with the order number and the correct date. Before the sale, you can enter a **Corrected purchase date** in [Leads](/merchant-portal/leads) | More on each case: [Helping a customer: "My email, phone or address has changed"](/help/helping-a-customer#my-email-phone-or-address-has-changed). ## Get ahead of it Add the plan to your exchange checklist: when a covered product is swapped, update the plan the same day, and never add a plan line by editing the order. ## Related - [Helping a customer](/help/helping-a-customer) - [Order Resolution](/merchant-portal/order-resolution) - [Refunds and your credit](/learn/refunds-and-credits) - [Contract statuses](/contracts/lifecycle) --- # Chargebacks and leaving SureBright Source: https://docs.surebright.com/learn/chargebacks-and-leaving > What happens to a protection plan when a customer disputes a payment, and what to settle before you pause or uninstall SureBright. **The short answer.** A chargeback does not cancel a plan. Cancel or refund the order and the plan follows. If you stop using SureBright, plans you already sold do not disappear, and neither do the invoices for them. ## You might be asking - A customer disputed the charge. Is the plan cancelled? - We are pausing the program. What happens to customers who already bought? - We uninstalled. Why did we get another invoice? - Can SureBright help us fight a chargeback? - An order was flagged as a fraud risk. What happens to the plan? - Our business is being sold. What happens to SureBright? - Do we keep our customer and sales data if we leave? ## What you need to know **A dispute happens at your payment provider, not in your order.** SureBright sees orders, cancellations and refunds. It does not see a chargeback, so the plan stays active until the order itself is cancelled or refunded. **Pausing and removing are different.** Hiding the offer stops new sales and leaves everything else running. Uninstalling cuts the connection, so later refunds and cancellations no longer reach SureBright. **Plans already sold still have to be paid for.** Customers hold cover they bought from you. The plans sold up to the day you stop are invoiced as usual. ## What to do | Situation | Do this | | --- | --- | | A customer won a chargeback on an order with a plan | Cancel or refund the order, including the plan line. See [Refunds and your credit](/learn/refunds-and-credits). | | You want a break from offering protection | Pause the offer and keep SureBright connected. See [Pause or remove SureBright](/platforms/pause-or-remove). | | You are removing SureBright | Refund or cancel any open orders first, keep a working payment method until your last invoice is paid, and tell your SureBright contact. | | You refunded a plan after uninstalling | Email support with the order number so the plan is cancelled. | | A customer opened a chargeback and you want to contest it | Email support with the order number and ask what SureBright holds for that plan that could help. | | An order with a plan is flagged as a fraud risk | The plan follows the order. If you fulfil the order, the plan stays. If you reject it, cancel or refund the whole order, including the plan line, and the plan is cancelled. A plan cancelled before it is billed is never charged. | | Your bank disputed SureBright's own charge to you | See [Our bank disputed a SureBright charge](/merchant-portal/payment-questions#our-bank-disputed-a-surebright-charge). | | Your store is changing owner | See [If your business is sold](#if-your-business-is-sold). | ## If your business is sold Tell your SureBright contact before the handover, with the date and the new owner's contact details. Plans you have already sold stay with your customers whoever owns the store. | Before the handover | After the handover | | --- | --- | | Settle or agree who pays the invoices for plans sold up to the handover date. | The new owner adds their own payment method in **Billing → Payment Methods**, or asks to be invoiced. | | Download what you want to keep (see below). | The new owner sets up their team and removes people who no longer need access. See [Team and access](/merchant-portal/team-and-access). | | Ask support to change the business name and address on invoices from the handover date. | Any other question about the change of owner goes to your SureBright contact. | ## Your data if you leave You can take your records with you before you leave. | What | Where | | --- | --- | | Every plan you sold | **Download** on the Recent sales page in [Sales](/merchant-portal/sales#export-your-sales) | | Every order SureBright billed you for | **Download Billed Orders** in [Billing](/merchant-portal/billing) | | Your invoices | **Download PDF** on each invoice in **Billing → Billing History** | | Claims on your customers' plans | Ask your SureBright contact | ## Get ahead of it Before any change to how you run SureBright, read [Pause or remove SureBright](/platforms/pause-or-remove) and settle open orders and invoices first. ## Related - [Pause or remove SureBright](/platforms/pause-or-remove) - [After a theme or platform change](/platforms/after-a-theme-or-platform-change) - [Payment questions](/merchant-portal/payment-questions) --- # Claims and your role Source: https://docs.surebright.com/learn/claims-and-your-role > What you have to do when a customer has a problem with a covered product, and what SureBright handles. **The short answer.** SureBright handles the claim with your customer. You are contacted only if your input is needed. During the manufacturer's warranty, the manufacturer's cover comes first. A product that arrives faulty or damaged is a return to your store, not a claim. ## You might be asking - A customer came to us about a broken product. Do we handle it? - Are we expected to repair or replace the product ourselves? - The product is still under the manufacturer's warranty. Who deals with it? - The product arrived broken. Why was the claim sent back to us? - Where can we see how many customers have claimed? ## What you need to know **Customers come to you first.** Shoppers remember where they bought, not who protects the product. A clear pointer from you saves everyone time. **The claim runs between the customer and SureBright.** The customer files it, SureBright reviews it and arranges the outcome, and the customer is kept informed by email. Your team is asked for input only when something needs your help: confirming order or product details, inspecting a returned unit, or supplying a replacement or repair that SureBright pays you back for. **The first warranty on the product comes first.** That is usually the manufacturer's warranty. When your store gives its own warranty in its place, for example on used or refurbished stock, it is yours. For a breakdown during that period, whoever gives the warranty is the first stop: the manufacturer, or your store. The plan's breakdown cover begins when that warranty ends. See [Your own store warranty](/contracts/effective-dates#your-own-store-warranty-on-used-or-refurbished-stock). An accidental damage plan starts on the day it was bought. ## What to do | Situation | Do this | | --- | --- | | A customer tells you their product has failed | Send them to file a claim. See [Filing a claim](/claims/filing-a-claim) for the link and what they need. | | The customer cannot or will not file it themselves | Send SureBright the details and SureBright files it. See [File a claim for a customer without the Adjudicator Portal](/claims/filing-a-claim#file-a-claim-for-a-customer-without-the-adjudicator-portal). | | The product is within the manufacturer's warranty | Point the customer to the manufacturer for a breakdown. See [When coverage starts](/contracts/effective-dates). | | The product is within your own store warranty | Handle the breakdown under your warranty, as the manufacturer would on a new product. See [Your own store warranty](/contracts/effective-dates#your-own-store-warranty-on-used-or-refurbished-stock). | | The product arrived faulty or damaged | Handle it as a return or exchange with your store. See [below](#a-product-arrived-faulty-or-damaged). | | The customer cannot find their plan | Show them the [Customer portal](/customer-portal/overview). | | SureBright asks you for order or product details | Reply quickly. The claim waits on it. | | SureBright asks you to inspect a returned unit | See [When SureBright asks you to inspect a returned unit](/claims/merchant-adjudication#when-surebright-asks-you-to-inspect-a-returned-unit). | | SureBright asks you to ship a replacement or do a repair | See [When you supply the replacement, parts or repair](/claims/resolutions-and-payouts#when-you-supply-the-replacement-parts-or-repair). | | A customer is unhappy with how a claim is going | Send support the claim reference or the order number. See [When a claim seems stuck](/claims/overview#when-a-claim-seems-stuck). | ## A product arrived faulty or damaged A plan covers a product that was delivered in working condition. If a product arrives faulty, broken or damaged (dead on arrival), that is not a plan claim. A claim filed for it is usually declined or passed back to you. - Handle it as a return, exchange or replacement under your own store policy. - If the damage happened in transit and the shopper bought shipping protection, they can file a shipping claim instead. See [Shipping claims](/shipping-protection/claims). - For a bulk order where several units arrived damaged, deal with the units as returns or with your shipping carrier. Units that arrived working and fail later are claims as usual. ## When the manufacturer's warranty is involved | Situation | What happens | | --- | --- | | A breakdown during the manufacturer's warranty | The customer goes to the manufacturer. A claim filed with SureBright for it is usually redirected or declined. | | The manufacturer's warranty has ended | SureBright's breakdown cover applies from that day. The manufacturer's warranty is counted from the product's original purchase date. See [When coverage starts](/contracts/effective-dates). | | Accidental damage during the manufacturer's warranty | An accidental damage plan covers it from the day it was bought, because a manufacturer's warranty does not cover accidents. | | The manufacturer will not service the product where the customer lives, or does not cover a part or accessory | Send the claim number to [support@surebright.com](mailto:support@surebright.com) with what the manufacturer told the customer. SureBright reviews the claim with that in mind. | ## Where to see your customers' claims Claims are not shown in the Merchant Portal. The **Sales** pages show plans sold, not plans claimed. - **With the Adjudicator Portal**, you can read every claim filed against your contracts and export the list with **Export CSV**. See [Adjudicator Portal](/claims/adjudicator-portal). It is enabled per organisation; ask your SureBright contact. - **Without it**, ask your SureBright contact for a claims report. SureBright can prepare one for a quarter or a year, showing how many of your customers have claimed. - For one claim, email support with the claim number or order number. See [Contact support](/help/contact-support). ## Get ahead of it Give your support team one saved reply: where a customer files a claim, and that SureBright handles it from there. Add a line saying that a product which arrives broken should come back to your store as a return. See [Helping a customer](/help/helping-a-customer). ## Related - [How a claim moves](/claims/overview) - [Filing a claim](/claims/filing-a-claim) - [Resolutions and payouts](/claims/resolutions-and-payouts) - [Helping a customer](/help/helping-a-customer) --- # Ways to offer product protection Source: https://docs.surebright.com/learn/compare-protection-options > Compare the ways a store can cover products after the sale (the manufacturer's warranty alone, a warranty you run yourself, or a protection-plan provider such as SureBright) and the questions to ask any provider before you choose. Shoppers buying electronics, appliances, furniture, bikes or tools often ask "what if it breaks?". You can answer that in a few ways. This page compares them and lists the questions worth asking any protection-plan provider, with SureBright's answer to each. ## The options side by side | | Manufacturer's warranty only | A warranty you run yourself | A protection-plan provider such as SureBright | |---|---|---|---| | What the shopper gets | The manufacturer's cover, usually for a limited time and for defects only | Whatever cover you define and can stand behind | A plan bought with the product, covering it after the manufacturer's warranty ends, or against accidental damage | | Extra revenue for you | None | The plan price, less every claim you pay | Your margin on every plan sold, with no claim cost on your side | | Who handles claims | The manufacturer | Your team: assessing, repairing, replacing, refunding | The provider. With SureBright, the claim runs between your customer and SureBright | | Risk on your balance sheet | None | All of it | None on claims | | Work to set up | None | Terms, pricing, a claims process, staff time | Install and onboarding. See [How to start](/learn/what-is-surebright#how-to-start) | Shipping protection is a separate decision: it covers the parcel in transit, not the product after delivery. SureBright offers both, and a shopper can buy either or both on one order. See [Shipping protection](/shipping-protection/overview). ## Questions to ask any provider | Ask | SureBright's answer | |---|---| | Which of my platforms do you support, online and in store? | Shopify, Magento, Salesforce Commerce Cloud, BigCommerce, WooCommerce and Shift4Shop online; Shopify POS, Lightspeed and any register through the POS portal in store; several ERPs. See [Supported platforms](/platforms/overview) | | What do I pay, and is there a monthly fee? | No setup, monthly or subscription fee and no minimum commitment for standard integrations. SureBright invoices its share of the plans you sold, once a month. See [Pricing, margins and invoices](/merchant-portal/how-billing-works) | | Who takes the shopper's payment? | You do, in your own checkout or at your register. See [Who collects the shopper's money](/merchant-portal/how-billing-works#who-collects-the-shoppers-money) | | Can I set my own plan prices? | Yes, on request: per category and per product, above a minimum price. See [Warranty Pricing](/merchant-portal/warranty-pricing) | | Who handles claims, and what is asked of my team? | SureBright handles the claim with the customer and asks you only when your input is needed. See [Claims and your role](/learn/claims-and-your-role) | | Which products and countries can be covered? | Eligible categories in the United States and Canada. See [What can be covered](/contracts/what-can-be-covered) | | Can the offer match my brand? | Yes. Style it in Studio, choose a template and A/B test designs. See [Studio](/merchant-portal/studio) and [Design tests](/merchant-portal/design-tests) | | Can I sell plans after the order, or to shoppers who left their cart? | Yes. Offer emails are on request for Shopify stores. See [Post-purchase offer emails](/post-purchase/offer-emails) and [Abandoned cart recovery](/abandoned-cart-guide/abandoned-cart) | | What happens to refunds and cancellations? | You refund the shopper in your store; SureBright's part comes back on your next invoice without a request. See [Refunds and credits](/learn/refunds-and-credits) | | What if I leave? | See [Chargebacks and leaving](/learn/chargebacks-and-leaving) and [Pause or remove SureBright](/platforms/pause-or-remove) | | I already use another provider. Can I switch without a gap? | Yes: set SureBright up with its offer off, remove the other offer, then switch SureBright on. Plans already sold stay with the provider that sold them. See [Switching to SureBright](/platforms/switching-to-surebright) | ## Next steps - New to SureBright: [What is SureBright?](/learn/what-is-surebright) - Ready to install: [Supported platforms](/platforms/overview) - Want to talk it through: [support@surebright.com](mailto:support@surebright.com) --- # New products without an offer Source: https://docs.surebright.com/learn/new-products > Why a product you added or changed has no protection offer, how long a change takes to show on your storefront, and how to keep your catalogue covered as it changes. **The short answer.** A product gets an offer only once it has a SureBright category and protection is switched on for it. New and changed products do not always get there by themselves, so check after every catalogue change. | You want to | Go to | | --- | --- | | Get an offer showing on a product you just added | [A new product shows no offer](#a-new-product-shows-no-offer) | | Know how long a change takes to reach your storefront | [How long changes take to show](#how-long-changes-take-to-show) | | Stop an offer still showing on a product you switched off | [A product you switched off still shows an offer](#a-product-you-switched-off-still-shows-an-offer) | | Avoid losing offers when you rename or migrate products | [Before a catalogue change](#before-a-catalogue-change) | ## What you need to know **Categorising usually happens for you, but not always straight away.** SureBright categorises your catalogue, and most new products pick up their offer without any action from you. You do not need to tell SureBright each time you add a product. Some products do not get an offer by themselves: products that are hard to classify, accessories and parts that are not covered, and products added in bulk. **Changes can undo a product's set-up.** Renaming a product, changing its identifier, or moving your catalogue to a new platform can leave a product without its category. **A product can be fine and still show nothing** if its price falls outside the range its category covers, or if the manufacturer warranty length is missing where it is needed. ## A new product shows no offer | What you see in [Products](/merchant-portal/products) | Do this | | --- | --- | | The product has no category, or **Warranty status** is **Inactive** | Pick a category from the **Product category** dropdown. That also switches protection on | | The status reads **Under Review** | Wait. SureBright is checking the category | | The **Mfr warranty** chip reads **Add** | Click it and set the length | | The category is right and the status is **Active** | See [What can be covered](/contracts/what-can-be-covered) for price bands and other reasons | | Whole groups of products show nothing | [Coverage Intelligence](/merchant-portal/coverage-intelligence), where your store has it, lists every uncovered product and why | ## How long changes take to show | Change | When it usually shows on your storefront | | --- | --- | | A new product is categorised by SureBright | Not immediately. If a new product still has no category after a day or two, ask your SureBright contact | | You switch protection on or off, or change a category, in Products | Not immediately, it can take a few hours. If it has not changed by the next day, ask your SureBright contact | | A browser that visited your store recently | Can keep showing the earlier offer for up to two hours. Check in a private window | If a change has not shown after that, see [Offer not showing?](/help/offer-not-showing) and write to support with the product links. ## A product you switched off still shows an offer 1. Check **Warranty status** reads **Inactive** for that product in [Products](/merchant-portal/products). 2. Allow the time in [How long changes take to show](#how-long-changes-take-to-show), then check again in a private window. 3. On Magento, purge the full-page cache. 4. Still showing? Send support the product link and when you switched it off. ## Before a catalogue change Tell your SureBright contact before you rename products, change their identifiers or migrate your catalogue to a new platform, so their categories carry over. ## Get ahead of it Make a monthly habit of opening **Products** and clearing anything without a category. Do it straight after every product launch or sale event. ## Related - [Products](/merchant-portal/products) - [What can be covered](/contracts/what-can-be-covered) - [Offer not showing?](/help/offer-not-showing) --- # Common concerns Source: https://docs.surebright.com/learn/overview > The concerns that come up most often when you sell protection plans, what is behind each one, and what to do so it does not happen on your store. Every article in this section starts from a question you are likely to have at some point, because stores like yours have asked it. Each one gives you the short answer, what is behind it, what to do, and how to stay ahead of it. | Concern | The lesson in one line | Read | | --- | --- | --- | | Is the plan taxable, and why is there no tax on my invoice? | Your store's tax settings decide the tax on a plan. SureBright does not add or change it. | [Tax on protection plans](/learn/tax) | | I refunded an order. Do I still pay for the plan? | Refund the plan itself, not only the product, and the charge comes back on your next invoice. | [Refunds and your credit](/learn/refunds-and-credits) | | Is the pre-selected plan hurting my conversion? | Do not guess. Test it against no default on your own shoppers. | [Pre-selected plans and conversion](/learn/pre-selected-plans) | | My new products show no offer. | A product needs a category before it gets an offer. Check after every catalogue change. | [New products without an offer](/learn/new-products) | | Plans show up as extra orders in my shipping tool. | A plan is a line that does not ship. Filter it out where you fulfil. | [Plans in your order and shipping tools](/learn/plans-in-your-order-tools) | | A customer has a claim. What do I have to do? | SureBright handles the claim with your customer. You are asked only when your input is needed. | [Claims and your role](/learn/claims-and-your-role) | | My customer never got a confirmation. | The plan needs the customer's email on the order. | [Purchase confirmation](/customer-emails/purchase-confirmation#if-your-customer-has-not-received-it) | | How do I sell a plan over the phone or after the sale? | Always add a plan with SureBright's tools, never by typing a line in. | [Phone, draft and later sales](/learn/phone-and-later-sales) | | A customer exchanged the product. What about the plan? | A plan covers one product. Point it at the replacement or cancel it. | [Exchanges and changes to a plan](/learn/changing-a-plan) | | Is my attach rate normal? | Compare against your own tests, not a quoted average. | [Reading your attach rate](/learn/attach-rate) | | A customer filed a chargeback. | A chargeback does not cancel the plan. Cancel or refund the order. | [Chargebacks and leaving SureBright](/learn/chargebacks-and-leaving) | ## More answers - Charges, credits and invoices: [Payment questions](/merchant-portal/payment-questions). - Which products and shoppers can be covered: [What can be covered](/contracts/what-can-be-covered). - A missing or broken offer: [Offer not showing?](/help/offer-not-showing). - Short answers to everything else: [Merchant FAQ](/help/faq). --- # Phone, draft and later sales Source: https://docs.surebright.com/learn/phone-and-later-sales > How to sell a protection plan outside your storefront checkout or after the product was bought, handle draft orders, payments taken elsewhere, discounts and free plans, without creating plans that cannot be completed. **The short answer.** Add a plan only with SureBright's tools. A plan typed into an order by hand, or sold as a warranty product you created yourself, cannot be matched to a product, so the customer is not covered and you are billed late. | You want to | Go to | | --- | --- | | Sell a plan by phone, or add one to a past order | [Pick the right tool](#pick-the-right-tool) | | Fix a draft order plan that did not activate, was cancelled or doubled | [Draft orders: invoices, duplicates and cancellations](#draft-orders-invoices-duplicates-and-cancellations) | | Record a plan the customer paid for outside your checkout | [The customer paid outside your store checkout](#the-customer-paid-outside-your-store-checkout) | | Move your checkout to another provider | [Your checkout or payments run outside your platform](#your-checkout-or-payments-run-outside-your-platform) | | Sell plans for products bought on a marketplace or another store | [Products bought on a marketplace or another store](#products-bought-on-a-marketplace-or-another-store) | | Discount a plan or give one away | [Discounts and free plans](#discounts-and-free-plans) | | Add shipping protection to a phone order | [Shipping protection on phone and draft orders](#shipping-protection-on-phone-and-draft-orders) | ## What you need to know **A plan needs three things: the plan, the term and the product it covers.** SureBright's tools record all three. A line added by hand records none, so the plan cannot be set up. **A plan becomes active only when it is paid for.** A draft order or quote that is never paid creates no plan. **Customers can add a plan after the purchase, for a limited time.** The window and where it is counted from depend on how the plan is bought. See [What can be covered](/contracts/what-can-be-covered#buying-a-plan-after-the-product). ## Pick the right tool | Situation | Do this | | --- | --- | | Phone or quote sale on Shopify | Use the [Shopify draft order extension](/draft-order-guide/shopify-draft-order). | | Adding a plan to an order already placed, on Shopify or Magento | Use [Merchant Portal draft orders](/merchant-portal/leads). | | In-store sale, or a product that is not in your online catalogue | Record it in the [POS portal](/pos/recording-a-sale). | | A customer wants to add a plan themselves after buying | Send them a [post-purchase offer link](/post-purchase/offer-links) on Shopify, or see [Manual and draft orders](/manual-orders/overview) for your platform. | | You raised the plan quantity on an existing order | Do it through the same SureBright tool, not by editing the line. | ## Draft orders: invoices, duplicates and cancellations | Situation | Do this | | --- | --- | | The customer did not get the invoice email | Shopify sends draft order invoices, not SureBright. Resend it from the draft order in Shopify, or from Leads with **Resend payment link**. If you took payment another way, use **Mark as paid** in [Leads](/merchant-portal/leads#take-payment-on-shopify) | | You have several open drafts for the same purchase | Keep one. Delete the others before you send an invoice. Each paid draft that carries a plan creates its own plan, so two paid drafts mean two plans | | A draft expired or was deleted before it was paid | No plan was created and nothing is billed. Create a new draft with the SureBright tool and send that invoice | | The plan from a paid draft does not appear in [Sales](/merchant-portal/sales) | Check the plan was added with the SureBright tool, not typed in. Then write to support with the draft and order numbers | | A plan from a draft was cancelled | A refund or cancellation of that order cancels its plan. Check the order in Shopify, then sell the plan again with a new draft if the customer still wants it | | The customer ended up with two plans | Refund the extra plan line. See [Cancel or refund a plan](/learn/changing-a-plan#cancel-or-refund-a-plan) | ## The customer paid outside your store checkout A plan exists only once it is recorded through a SureBright tool, so a payment taken outside your checkout, for example by a PayPal invoice, needs recording. | Situation | Do this | | --- | --- | | On Shopify or Magento | Create the draft in [Leads](/merchant-portal/leads) and use **Mark as paid** (Shopify) or invoice the order (Magento). The plan activates once the order is marked paid | | On Shopify, from Shopify admin | Use the [Shopify draft order extension](/draft-order-guide/shopify-draft-order), then mark the draft paid in Shopify | | On other platforms, or a counter sale | Record it in the [POS portal](/pos/recording-a-sale) | SureBright still bills you for the plan on your normal invoice, whatever way the customer paid you. It does not collect plan money from your customer. See [How billing works](/merchant-portal/how-billing-works). ## Your checkout or payments run outside your platform Plans are created from the orders your store sends SureBright, and the plan line must reach the order exactly as the SureBright offer added it. Check before you change how orders are taken: | Situation | What to know | | --- | --- | | You move to a third-party checkout, funnel or payment app | Ask your SureBright contact first. The plan line must reach your platform's order with the details the offer added. Then [place a test order](/platforms/test-your-setup) and check it in **Sales** | | A separate system creates orders in your store through its API | The same. Orders that carry a plan line without SureBright's details cannot be matched to a product, and appear in [Order Resolution](/merchant-portal/order-resolution) | | Payment is authorised at checkout and captured later | Billing for the plan waits until the payment is captured. Capture it in your store admin as usual. See [Why a contract is on hold](/contracts/holds) | | Cancellations are recorded in another system | Cancel or refund the order in your store platform too, or send support the order numbers. SureBright only sees what your platform records | A developer building the checkout should read [Cart sync](/frontend-widget-integration/frontend-widget-kit/cart-sync#what-a-theme-developer-must-not-do). ## Products bought on a marketplace or another store You can sell a plan to a customer who bought the product elsewhere, for example on a marketplace, from a dealer or on your sister store. No marketplace connection is needed. | You want to | Do this | | --- | --- | | Sell the plan yourself, by phone or email | On Shopify, use the draft order extension: [Sell a plan for a product bought elsewhere that you list](/draft-order-guide/shopify-draft-order#sell-a-plan-for-a-product-bought-elsewhere-that-you-list), or [for a product you do not list yet](/draft-order-guide/shopify-draft-order#sell-a-plan-for-a-product-you-do-not-list-yet). On Shopify and Magento, **Record manual order** in [Leads](/merchant-portal/leads#record-a-manual-order) works too | | Let customers buy it themselves | Use a [product registration page](/shopify/product-registration) on Shopify. On other platforms, ask your SureBright contact | | Cover a whole channel, such as a marketplace store | Ask your SureBright contact which tool fits | The usual purchase window applies, counted from the date the customer bought the product. ## Discounts and free plans | Situation | What happens | | --- | --- | | A store-wide discount also cut the plan price | SureBright still bills the plan at its normal price, so the discount comes out of your share. On Shopify, build discounts on a collection that leaves SureBright products out. See [Shopify admin housekeeping](/shopify/admin-housekeeping#discounts-that-exclude-surebright-products) | | You discount the plan line on a draft order | The same: you are billed the plan's normal charge, and the discount comes out of your share | | You want to offer a free or discounted plan to win back shoppers | On Shopify, use [Abandoned Cart Recovery](/abandoned-cart-guide/abandoned-cart). It issues single-use codes that apply to the plan only. Your store funds the discount | | You want a free plan with every product, or another promotion | Ask your SureBright contact before you launch it. You pay SureBright's charge for every plan you give away | ## Shipping protection on phone and draft orders Shipping protection is bought by the shopper at checkout on your storefront. The draft order tools add product protection plans only. If you want to offer shipping protection on phone or draft orders, ask your SureBright contact. ## Get ahead of it Train everyone who creates orders by hand on one rule: **plans are added with the SureBright tool, never typed in**. See [Why are orders from months ago on this invoice?](/merchant-portal/payment-questions#why-are-orders-from-months-ago-on-this-invoice). ## Related - [Manual and draft orders](/manual-orders/overview) - [What can be covered](/contracts/what-can-be-covered) - [Payment questions](/merchant-portal/payment-questions) **See also:** [In-store plans paid outside your online checkout](/pos/recording-a-sale#plans-paid-for-outside-your-online-checkout). --- # Plans in your order and shipping tools Source: https://docs.surebright.com/learn/plans-in-your-order-tools > How the protection plan line is fulfilled, why it can appear as an extra order in your shipping, fulfilment or ERP tools, what the SureBright order notes are, which SKUs plans use, and what to do about plan-only checkouts. **The short answer.** A protection plan is a line on the order that does not ship. Tools that read your orders can show it as something to pick, pack or ship unless you tell them to ignore it. | You want to | Go to | | --- | --- | | Know why a plan line is unfulfilled, or who fulfils it | [How the plan line is fulfilled](#how-the-plan-line-is-fulfilled) | | Stop plans showing as extra orders in your shipping tool | [Plans in shipping and order tools](#plans-in-shipping-and-order-tools) | | Know what the SureBright notes on your orders are | [The SureBright notes on your orders](#the-surebright-notes-on-your-orders) | | Set up plan SKUs in your ERP or 3PL | [Plan SKUs for your ERP or 3PL](#plan-skus-for-your-erp-or-3pl) | | Deal with checkouts that contain only a plan | [Checkouts with only a plan in them](#checkouts-with-only-a-plan-in-them) | ## What you need to know **Your platform separates what ships from what does not.** Because the plan needs no shipping, your platform can place it in its own fulfilment group. A shipping or order-management tool that imports every group then shows a second "order" containing only the plan. **One route per order.** If your store is connected to SureBright, your orders already reach SureBright. Sending the same order again through another route can create a second plan. ## How the plan line is fulfilled The plan is a digital product. You never ship it. **On Shopify**, SureBright marks the plan line fulfilled for you when you fulfil the product it covers, unit for unit. If the product ships in two parts, the plan lines are fulfilled with each part. The shipping protection line is marked fulfilled the same way. See [Shipping protection](/shipping-protection/overview#what-happens-when-you-ship-the-order). | What you see | Why | Do this | | --- | --- | --- | | The plan line is unfulfilled and the product has not shipped | Expected. The plan line waits for the product | Ship the product as usual | | The plan line is still unfulfilled after the product shipped | The fulfilment did not reach SureBright, or the SureBright app lacks a permission it needs | Check the SureBright app has every permission it asks for in Shopify admin. Then write to support with the order number | | An open plan line stops your order closing or your payment being captured | Your payment or order rules wait for every line | Ship the covered product. The plan line follows. Do not fulfil the plan line by hand first | | Another app fulfils or cancels the plan line before the product ships | Automation apps that fulfil every line on payment | SureBright takes back an early fulfilment of the plan line and fulfils it again when the product ships. Set the app to skip SureBright products to avoid the back and forth | | Plan lines on a bundle did not fulfil | The covered product is a bundle, which is matched through its components | Write to support with the order number. See [Bundles](/shopify/bundles) | **On other platforms**, ask your SureBright contact how plan lines are handled. If your store starts plans when the order ships, the plan's cover dates are set at the same moment. See [Fulfillment](/merchant-portal/fulfillment). ## Plans in shipping and order tools | Situation | Do this | | --- | --- | | Your shipping tool shows plan-only orders | Add a rule in that tool to skip lines that do not require shipping, or to skip the SureBright plan products. | | Extra details on the plan line clutter your packing slips | Ask your SureBright contact whether they can be shortened for your store. | | You run a custom integration as well as a connected store | Use one route only. Ask your SureBright contact which one before you build. | | You see two plans on one product | See [I was billed twice for one order](/merchant-portal/payment-questions#i-was-billed-twice-for-one-order). | ## The SureBright notes on your orders Orders placed through the SureBright offer can carry one or two notes (order attributes), named `sb-cart-analytics-id` and `sb-li-offers-shown`, or a single note named `sb` on some stores. - They record which protection offers the shopper was shown and which visit led to the order. That is how your attach rate and design tests are measured. - They do not affect the plan or the customer's cover. - Leave them in place. Without them, your [Sales](/merchant-portal/sales) figures for attach rate and widget versions are incomplete. - If they land in buyer notes, packing slips or your ERP, filter them out in that tool, or ask your SureBright contact about the single shorter note. ## Plan SKUs for your ERP or 3PL Each plan is a product in your store catalogue, with one SKU per plan length, region, coverage type and price band. Download the SKU list for your store from the Merchant Portal (**Products > Download plan SKUs**) and load it into your ERP, 3PL or accounting tool. See [Download your plan SKUs](/erp/download-plan-skus). Ask your SureBright contact for cost values on the plan variants, if your ERP needs them. Mark these SKUs as non-stock or non-shipping in those tools. There are step-by-step guides for [Acumatica](/erp/acumatica-warranty-skus), [NetSuite](/erp/netsuite-warranty-skus), [Dynamics 365 Business Central](/erp/dynamics-365-warranty-skus), [SAP Business One](/erp/sap-business-one-warranty-skus) and [Odoo](/erp/odoo-warranty-skus). ## Checkouts with only a plan in them A plan should never be bought alone at checkout. | What you see | Why | Do this | | --- | --- | --- | | Completed orders with only a plan | Almost always a shopper who removed the product and left the plan behind | On Shopify, switch on the [Cart Validator](/shopify/enable-surebright-cart-validator). It stops a plan being bought without its product | | Many abandoned checkouts with only a plan, often at different prices | This pattern can be card testing by bots, which favours low-priced items such as plans. SureBright does not create checkouts on your store | Switch on the Cart Validator, and use your platform's own bot and fraud protection. Write to support if it continues | On Shopify, protection products must stay on the Online Store sales channel for the offer to work, so do not unpublish them to stop this. See [Shopify admin housekeeping](/shopify/admin-housekeeping#online-store-sales-channel). ## Get ahead of it When you connect a shipping, fulfilment or accounting tool, place one test order with a plan and look at how the plan line arrives. Fix the filter before real orders flow. ## Related - [Test your setup](/platforms/test-your-setup) - [Shopify admin housekeeping](/shopify/admin-housekeeping) - [Payment questions](/merchant-portal/payment-questions) --- # Pre-selected plans and conversion Source: https://docs.surebright.com/learn/pre-selected-plans > What to do when you worry that a pre-selected protection plan is costing you orders, and how to settle the question with a test. **The short answer.** A pre-selected plan can raise the share of orders that include protection. Whether it costs you any orders differs from store to store, and the only way to know for yours is to test it. ## You might be asking - A plan is added automatically and I think conversions are dropping. Can you turn it off? - Should the default be the cheapest plan, the longest plan, or nothing? - Customers say they did not mean to buy the plan. ## What you need to know **Opinions about defaults are usually stronger than the evidence.** When stores have tested a pre-selected plan against no default, the results have not all pointed the same way. Switching the default off because of a hunch gives up protection sales without proving that orders improve. **There are more than two options.** Besides a pre-selected plan or nothing, you can pre-select a shorter plan, show a **No coverage** choice so declining is one click, or leave nothing selected and rely on the offer at add to cart. **Shoppers must always be able to see and remove the plan.** A clear price, a visible plan line in the cart and an easy way to remove it prevent most "I did not mean to buy this" complaints. ## What to do | Situation | Do this | | --- | --- | | You want to know the real effect | Run two versions side by side. On Shopify, copy your live design, change only the default and click **Test against live**. See [Default plan selection](/merchant-portal/default-plan-selection). | | You do not have Studio | Ask your SureBright contact to set up the test or to change the default for you. | | Customers say the plan was added without them noticing | Check your cart shows the plan line and its price clearly, and consider showing the **No coverage** choice. | | You decide against a default | Keep the offer visible on the product page and in the cart so shoppers can still choose it. | ## Get ahead of it Decide your default at launch on purpose, write down why, and plan one test in your first weeks. A result from your own shoppers ends the debate. ## Related - [Default plan selection](/merchant-portal/default-plan-selection) - [Design tests](/merchant-portal/design-tests) - [Reading your attach rate](/learn/attach-rate) --- # Refunds and your credit Source: https://docs.surebright.com/learn/refunds-and-credits > What to do when you refund or cancel an order that carries a protection plan, so the plan is cancelled and its charge comes back to you. **The short answer.** You collected the plan price, so you refund the shopper. SureBright gives its share back to you on your next invoice once the plan itself is cancelled. Refunding the product alone does not cancel the plan. ## You might be asking - We refunded the whole order. Will we still be charged for the plan? - We were billed for a plan on an order we refunded months ago. Where is our credit? - Does SureBright refund the customer or do we? - What does "refund pending" mean when we already refunded the customer? - A customer wants to cancel months after buying. How much do they get back, and who handles it? ## What you need to know **Money back to the shopper and cancelling the plan are two different things.** A plan is cancelled when the plan line is refunded or removed, or when the whole order is cancelled or refunded. A refund that covers only the product, or a custom amount with no plan line selected, returns money and leaves the plan in place. **The credit follows the cancellation.** Once the plan is cancelled, what you were charged for it comes back on your next invoice under **Refund for Cancellations**. If the plan was never billed, it simply is never charged. **You refund the shopper.** The plan was paid for in your checkout, so the refund goes through your store like any other. ## What to do | Situation | Do this | | --- | --- | | You are refunding or cancelling an order with a plan | Select the plan line in the refund as well as the product, or cancel the order. | | You already refunded only the product | Open [Order Resolution](/merchant-portal/order-resolution). If the order is there, answer the case. If not, send support the order numbers. | | The customer keeps the product and only wants out of the plan | Refund the plan line. See [Helping a customer](/help/helping-a-customer). | | You want to check past refunds | Download **Billed Orders** from [Billing](/merchant-portal/billing) and compare it with your refunded orders. Send support any plan that was billed and refunded with no credit. | | Your store is not on Shopify | See [If SureBright cannot refund on your platform](/merchant-portal/order-resolution#if-surebright-cannot-refund-on-your-platform) and your platform's own page. | ## What refund pending on your next invoice means You see this in Sales and on the [Reconciliation Check](/merchant-portal/payment-reconciliation#what-the-banner-tells-you) when a plan was charged on an invoice and cancelled afterwards. It is about SureBright's refund to you, not your refund to the customer. - You have already refunded the customer. Nothing more is needed from you. - The amount you paid SureBright for the plan comes back on your next invoice, under **Refund for Cancellations**. - If the label stays after your next invoice, or the plan you refunded is not on the list, send support the order number. ## When a customer cancels later on | When the customer asks | What to do | | --- | --- | | Soon after buying, and you are handling the return | Refund the plan line in your store. The plan is cancelled and SureBright's share comes back on your next invoice. | | Later, or you are not handling a return | Send the customer to SureBright support at [support@surebright.com](mailto:support@surebright.com). SureBright looks at the purchase date and any claims, and decides whether the refund is in full or in proportion to the cover left. | | You want a longer full-refund period for your customers | Ask your SureBright contact. | When SureBright works out a refund in proportion to the cover left, it is the plan price multiplied by the days of cover remaining over the total days. See [How is a plan refund calculated?](/help/faq#how-is-a-plan-refund-calculated) and [Order Resolution](/merchant-portal/order-resolution). ## Get ahead of it Add one line to your returns routine: **refund the protection plan line with the product**. Once this is routine, missing credits stop. ## Related - [Payment questions](/merchant-portal/payment-questions#i-refunded-an-order-but-got-no-credit-for-the-plan) - [Contract statuses](/contracts/lifecycle) - [Order Resolution](/merchant-portal/order-resolution) --- # Tax on protection plans Source: https://docs.surebright.com/learn/tax > What decides the tax a shopper pays on a protection plan, what SureBright does and does not do about tax, and what your SureBright invoice shows. **The short answer.** Your store's own tax settings decide whether a shopper is charged tax on a protection plan. SureBright does not calculate, add or change tax in your cart or checkout. For questions about tax on SureBright's own invoice to you, ask your SureBright contact. ## You might be asking - Is a protection plan taxable? - Why was my customer charged tax on the plan, or not charged? - Is SureBright changing the tax in my cart? - Why is there no tax on the invoice SureBright sends me? - Can we get a tax breakdown, or SureBright's tax registration details, for our records? ## What you need to know **The plan is a product in your store, and your store taxes it.** A plan is sold as its own line item. Your platform or tax service applies tax to that line from the tax category or code the plan product carries, exactly as it does for your other products. **SureBright does not touch the calculation.** Nothing SureBright runs in the cart or checkout adds tax, removes it or overrides your tax service. **The rules are not the same everywhere.** Whether a plan is taxable, and at what rate, depends on where your customer is. SureBright cannot tell you how a plan should be taxed in a given state or province. Your tax advisor or tax service can. **Your SureBright invoice is a separate matter.** It is the bill for SureBright's share of the plans you sold. You sold the plan to the shopper, so any tax on that sale was charged by your store and is filed by you with the rest of your sales. For any question about tax on SureBright's own invoice to you, such as why it does or does not show tax, a tax breakdown, or SureBright's tax registration details, ask your SureBright contact. ## What to do | Situation | Do this | | --- | --- | | You want to set how plans are taxed | Find the SureBright plan products in your catalogue and check their tax category or code in your platform or tax service. On Shopify, plan products can carry Shopify's **Extended Warranties** product tax category. | | You use a separate tax service | Make sure the plan is treated as its own line with its own tax code, not folded into the product it covers. | | A shopper asks why the plan was taxed | Tell them the tax comes from your store's tax settings for their address. SureBright support gives shoppers the same answer and sends them to you. | | Two customers were taxed differently on the same plan | Look at their addresses and at any change you made to tax settings between the two orders. | | You edit orders with a tool that recalculates tax | Some tools remove and re-add every line to do it, which strips the details that tie a plan to its product. Avoid editing orders that carry a plan this way, or check the plan afterwards in [Order Resolution](/merchant-portal/order-resolution). | | Your accountant needs paperwork | Download the invoice PDF and **Billed Orders** from [Billing](/merchant-portal/billing). | | Your accountant asks about tax on SureBright's invoice, or for SureBright's tax registration details | Ask your SureBright contact, with the invoice numbers concerned. | ## Get ahead of it Before you launch, ask your tax advisor how protection plans are treated where you sell, then set the plan products' tax category once. It takes a few minutes and removes the most common tax question you will get from customers. SureBright does not give tax advice. This page describes what SureBright does and what its invoice shows. For how to treat plan sales and SureBright's charges in your own books and filings, ask your tax advisor. ## Related - [How the money works](/merchant-portal/how-billing-works) - [Invoices and charges](/merchant-portal/invoices-and-charges) - [Payment questions](/merchant-portal/payment-questions) --- # What is SureBright? Source: https://docs.surebright.com/learn/what-is-surebright > SureBright adds product protection plans (extended warranties) and shipping protection to your store's checkout and point of sale, and runs the program for you: offers, contracts, customer claims and billing. What you get, where it works, what it costs and how to start. **SureBright adds product protection plans and shipping protection to the products you sell, online and in store, and runs the program for you.** Your shoppers see a plan offer next to **Add to cart**, buy it in your own checkout, and get a plan for the product. SureBright creates the contract, emails the customer, handles their claims and invoices you once a month for its share. You keep a margin on every plan you sell. ## Quick facts | Question | Answer | |---|---| | Where are plans sold? | To shoppers in the United States and Canada only. Not in the United Kingdom, Australia, Mexico or elsewhere | | Where does shipping protection apply? | Shipments to United States addresses only | | Which languages? | English and French | | Is there a setup or monthly fee? | Not for standard integrations. SureBright invoices its share of the plans you sold | | Does SureBright pay me commission? | No payouts: you collect the plan price and keep your margin, then SureBright invoices you its share | | Can I set my own plan prices? | Yes, with Warranty Pricing, available on request | | Can a plan move to a new owner? | Not as a rule. Support can often change the holder soon after purchase, for example for a gift | | Is there an API sandbox? | No. Every API key is a live key | ## What you get | Part | What it does for you | Read more | |---|---|---| | Protection plans | Plans that cover a product after the manufacturer's warranty, and accidental damage plans, offered on eligible products | [What can be covered](/contracts/what-can-be-covered) | | Shipping protection | An optional add-on at checkout that covers a shipment against loss, damage and theft in transit, on Shopify and BigCommerce stores | [Shipping protection](/shipping-protection/overview) | | The offer on your store | A widget on product pages, the cart and checkout that you style to match your brand | [Studio](/merchant-portal/studio) | | Later sales | Offer emails and links after the order, and offers to shoppers who left their cart | [Post-purchase offers](/post-purchase/offer-emails), [Abandoned cart recovery](/abandoned-cart-guide/abandoned-cart) | | In-store sales | Plans sold at your register, through a POS extension or the SureBright POS portal | [In-store sales](/platforms/in-store-sales) | | Merchant Portal | Products, plan prices, sales, invoices and orders that need a decision, in one place | [Merchant Portal overview](/merchant-portal/overview) | | Claims | Your customer files a claim with SureBright; SureBright reviews it and arranges the repair, replacement or payout | [Claims and your role](/learn/claims-and-your-role) | ## Where it works SureBright connects to **Shopify** (including Shopify POS and headless Hydrogen stores), **Magento**, **Salesforce Commerce Cloud**, **BigCommerce**, **WooCommerce** and **Shift4Shop** online, to **Lightspeed X-Series and R-Series** and any other register through the POS portal in store, and to ERPs such as **Acumatica**, **NetSuite**, **Dynamics 365 Business Central**, **SAP Business One** and **Odoo**. Custom and headless storefronts use the SureBright SDK and API. See [Supported platforms](/platforms/overview) for how each one connects and a feature-by-platform table. If yours is not listed, [tell SureBright](/platforms/request-a-platform). ## Where plans are sold Product protection plans are sold to shoppers in the **United States** (in USD) and **Canada** (in CAD). Shipping protection is offered to shoppers in the United States. The widget follows your storefront's language, with French available. See [Languages and regions](/platforms/languages-and-regions). ## What it costs you For standard integrations there is **no setup fee, no monthly or subscription fee and no minimum commitment**. You collect the plan price from the shopper in your own checkout and keep your share (**Your Margin**). SureBright invoices you once a month for its share of the plans you sold (**Net to SureBright**), less refunds and credits. If your store needs a custom implementation, any cost for it is agreed with you before work starts. See [Pricing, margins and invoices](/merchant-portal/how-billing-works). ## How a sale works On an eligible product, the SureBright widget shows the plans for that product and their prices. The plan is a line on the same order, paid in your checkout or at your register. The customer gets a confirmation email and can find the plan in the SureBright customer portal. You see the sale in the Merchant Portal. SureBright handles it with the customer and contacts you only when your input is needed. ## How to start 1. Pick your platform on [Supported platforms](/platforms/overview) and follow its setup guide. 2. Sign in to the Merchant Portal and go through [Onboarding](/merchant-portal/onboarding). 3. [Test your setup](/platforms/test-your-setup) with a test order before you go live. Already selling plans through another provider? Read [Switching to SureBright](/platforms/switching-to-surebright). Comparing options? Read [Ways to offer protection](/learn/compare-protection-options). Questions: [support@surebright.com](mailto:support@surebright.com). --- # Lightspeed R-Series Source: https://docs.surebright.com/lightspeed/r-series > Connect a Lightspeed Retail (R-Series) account, see how completed sales, refunds and voids become contracts and cancellations, and pull missed sales in from the Merchant Portal. With Lightspeed R-Series connected, every completed register sale that includes a SureBright warranty item becomes a contract, and refunds and voids cancel it. If a sale has not reached SureBright, you can pull recent sales in yourself from the Merchant Portal. Use this page when connecting an R-Series account, checking why a sale has no contract, or running a sync. Lightspeed X-Series (formerly Vend) is a different integration with a sell-screen prompt; see [Lightspeed X-Series](/lightspeed/x-series). ## Connecting your account You connect together with your SureBright contact. You approve SureBright's access once, and it stays in place without you signing in again. Follow the authorization link your SureBright contact sends, sign in to Lightspeed Retail and approve the access. Only one authorization is needed per account. SureBright copies your items, including matrix items, so each warranty on a sale can be paired with the product it covers. An item you add later is picked up the first time it appears on a sale. A product needs a SureBright category to carry a plan; see [Products](/merchant-portal/products). Each shop's address is recorded on the contracts sold there, so make sure your shop addresses in Lightspeed are complete. If SureBright's access is revoked in Lightspeed, sales stop reaching SureBright and the portal's sync reports a failure. Ask your SureBright contact to re-run the authorization. ## When a sale becomes a contract A contract is created once the sale is **completed** in Lightspeed. The time the sale was completed is the contract's purchase date. | Sale in Lightspeed | What happens in SureBright | |---|---| | Completed, positive total | Contracts are created, or updated if the sale changed. | | Completed, negative total | Treated as a refund. The contracts for the refunded warranty quantities are cancelled. | | Voided | The sale's contracts are cancelled. | | Not completed | Nothing yet. | What goes on each contract: - **One contract per warranty unit**, paired with the product line it was sold against. The product's line total is the covered price. - **The contract holder** is the sale's customer: name, email, mobile and billing address. - **The point of sale** is the sale's shop and its address. If the customer has no email address, or a warranty cannot be paired with a product, you get a contract on hold or a case in **Order Resolution**. See [Why a contract is on hold](/contracts/holds). Each warranty unit covers one product unit. If a sale has two of a product and one warranty, one contract is created and the second unit is uncovered. The portal's **Warranties pending** list shows such sales so you can follow up. ## Pull in missed sales Now and then a completed sale does not reach SureBright straight away. Use the **Sync orders** card in the Merchant Portal to fetch recent completed sales yourself, either to check which are missing a warranty or to create the missing contracts. How to run it, what the two modes do and how to read the result are described in [Settings](/merchant-portal/settings#sync-orders-from-lightspeed-r-series). Sales that need a decision from you after a sync are listed under [Sales](/merchant-portal/sales#warranties-needing-attention-lightspeed-r-series). ## Where contracts appear Contracts show under **Recent Sales** on the portal's [Sales](/merchant-portal/sales) page, and **Sales by Location** breaks them down by shop. Warranties that could not be paired show in **Order Resolution**. --- # Lightspeed X-Series Source: https://docs.surebright.com/lightspeed/x-series > Connect a Lightspeed Retail (X-Series) account, offer protection at the register through a sell-screen prompt, and see how completed sales and returns become contracts and cancellations. Connect your Lightspeed Retail (X-Series) account and your cashiers are prompted to offer protection whenever they ring up an eligible product. Each completed sale that includes a warranty becomes a contract. Use this page to connect a store, or when a register sale did not produce the contract you expected. ## Connecting your account In the portal's [Settings](/merchant-portal/settings#connecting-a-storefront) click **Connect Store**, choose **LightSpeed** and click **Proceed**. You are sent to your Lightspeed domain (`.retail.lightspeed.app`) to sign in and approve SureBright's access. SureBright adds the sell-screen prompt to your Lightspeed account and copies your products and categories. The portal confirms **Store authorized successfully.** Your Lightspeed catalog now has one warranty product per plan term and price band, named like **1 Year Extended Warranty - SB12**, each with its own SKU and a price that includes tax. Their **Source** is **SureBright**. That is how a line on a sale is recognised as a warranty, so do not rename them or change their source. A product needs a SureBright category before the prompt can offer a plan for it. Check [Products](/merchant-portal/products). When you later edit a product in Lightspeed, SureBright picks up the change by itself, and a new product is picked up the first time it appears on a sale. For a product with variants, the plans offered are based on the parent product's details. ## What the cashier sees at the register When a cashier adds an eligible product to a sale, the sell screen shows a suggestion titled **Add Premium Product Protection** (or **Add accidental and breakdown warranty** for accidental-damage plans). The message lists what the plan provides under **Use your purchase worry-free for years to come**, a **Why SureBright?** list, and a link to the plan's terms. The suggested products are the matching warranty products. The cashier adds one with a tap, and the sale carries both the product and the warranty. A product is prompted once per sale: reopening the sale does not prompt for it again. If the prompt does not appear for a product, the product is either not covered or has no SureBright category yet. Look it up in [Products](/merchant-portal/products). ## When a sale becomes a contract A contract is created when the sale is closed with the warranty on it. You get one contract per warranty unit, each for the product the warranty was suggested for. The sale's customer becomes the contract holder. | If the sale | What happens | What to do | | --- | --- | --- | | Has no customer, or the customer has no email address | The contract is created on hold. | To avoid it, add a customer with an email address before you close the sale. See [Why a contract is on hold](/contracts/holds). | | Has a warranty product that was rung up without the prompt | SureBright does not guess which product it covers. The plan appears in **Order Resolution** as an unassociated warranty. | Resolve the case in **Order Resolution**. Ask cashiers to add warranties from the prompt. | ### When a product is returned Process the return in Lightspeed as usual. SureBright cancels the contracts for the quantities returned. If you return the covered product but leave the warranty on the original sale, the plan goes to **Order Resolution** for review. ## Disconnect your store Ask SureBright to disconnect the store. The sell-screen prompt and SureBright's other connections are removed from your Lightspeed account. The warranty products stay in your catalog until you archive them. Existing contracts are unaffected. ## Where contracts and problem sales appear - **Recent Sales** on the portal's [Sales](/merchant-portal/sales) page lists every contract. - **Order Resolution** lists warranties that could not be paired and sales with missing details. - Lightspeed R-Series stores use a different integration; see [Lightspeed R-Series](/lightspeed/r-series). SureBright connects through a Lightspeed workflow rule on the sell screen and Lightspeed's sale and product webhooks, listed in [Platform webhooks SureBright receives](/api-reference/endpoint/webhooks/platform-receivers). The plan options behind each prompt are recorded on the sale in a custom field named `quoteItemsList`. Leave that field in place: it is how a warranty on the sale is tied to the product it was suggested for. --- # Admin panel Source: https://docs.surebright.com/magento/admin-panel > Use the SureBright page in your Magento admin to check that the integration is authorised, open the merchant portal, run the built-in checks when something is not working, and disable or reinstall the module. After the module is installed, a **SureBright** item appears in the Magento admin sidebar. It opens the **SureBright Product Protection** page. Use it right after [installing](/magento/install-guide), and whenever offers stop showing or plans you sold stop appearing as contracts. | You want to | Do this | |---|---| | See whether the integration is working | Check **Status** at the top of the page. | | Open the merchant portal | Click **Login Now**. | | Finish or renew authorisation | Follow the steps under **Authorization pending** or **Reauthorization required**. | | Find out why offers or contracts stopped | Expand **Diagnostics** and run the checks. | | Find an order that did not reach SureBright | Open the **SureBright Webhook Errors** grid. | | Turn the module off or on, or move to a new version | Run the commands under [Disabling or removing the module](#disabling-or-removing-the-module). | ## Check status and open the merchant portal The header reads **Merchant Portal: Manage product protection, policies, sales and invoices.** Under it you see: - **Status**: **Authorized** when the *SureBright Product Protection* integration is active in Magento, otherwise **Authorization pending**. - **Installed version**: the version of the module on your server, for example **1.3.15**. The latest release is **v1.3.15**; see [Reinstall](#reinstall) to move to it. - **Login Now**: once the status is **Authorized**, this button opens the SureBright [merchant portal](/merchant-portal/overview) sign-in page in a new tab. Log in with the credentials shared by the SureBright team. Before authorisation, the page tells you that the SureBright team shares your login credentials once authorisation is complete. ## Authorise or reauthorise the integration **Authorization pending** shows until you activate the integration. The page lists the steps and offers a **Go to Integrations** button: 1. Open **System > Extensions > Integrations**. 2. Find **SureBright Product Protection** and click **Activate**. 3. Review the requested access and confirm. **Reauthorization required** shows when a module update needs permissions you have not granted yet. Magento does not grant new permissions on its own, so the page marks the missing ones **not granted** and asks you to: 1. Open **System > Extensions > Integrations**. The row shows that its resources changed. 2. Open **SureBright Product Protection**, confirm the new resources are checked, and **Save**. 3. Click **Reauthorize** to apply the new permissions. Until you reauthorise, SureBright cannot read the data behind the missing permissions. ### If activation or reauthorisation fails When you click **Activate** or **Reauthorize**, Magento and SureBright exchange keys over the internet, so SureBright must be able to reach your store. Activation fails when a firewall, a hosting security rule or an IP allow-list blocks SureBright. This is common on development and staging sites, which are often closed to outside traffic. Ask your SureBright contact, or [support@surebright.com](mailto:support@surebright.com), for the addresses SureBright connects from. Add them to the allow-list on your firewall, hosting panel or security service, for every site you connect, including development and staging sites. Open **System > Extensions > Integrations** and click **Activate** or **Reauthorize** on **SureBright Product Protection** again. If it still fails, send SureBright the exact error message and your store URL. ## Run the SureBright diagnostic checks Expand **Diagnostics** (subtitle *Access, webhook, reindex & cache checks*) to reach four checks. Each one runs from your browser and shows its result on the page. Nothing changes in your store except where noted. ### Check which permissions are granted Under **Access & Permissions** there is one card per group of Magento permissions the integration asks for, with a **granted / total** count and a **granted** or **not granted** pill for each resource. Click **Run test** on a card to try a real read of that data and see whether it worked. | Card | What it covers | |---|---| | **Backend Access** | Admin, system and store-view configuration scope. | | **Sales Access** | Read orders, credit memos and shipments. | | **Catalog Access** | Read products, categories and attributes. | | **Customer Information** | Read customer accounts and groups. | | **Inventory Access** | Read inventory sources and stock levels. | | **SureBright Custom API** | SureBright integration data and event APIs. | If an authorised integration shows a **not granted** pill, you need to reauthorise. ### Test that your server can reach SureBright Under **Webhook Connectivity**, click **Test webhook**. Your server sends a test message to SureBright and the page shows the result. If it fails, the message tells you what to fix: | Message | What to do | |---|---| | *No active SureBright integration found* | The integration is not activated. Authorise it first. | | *Stored SureBright credentials are incomplete* | Authorisation did not finish. Reauthorise. | | *Could not reach SureBright* | Your server could not connect. Check for an outbound firewall or DNS problem. | Your orders and product changes reach SureBright the same way, so a failing test means SureBright is not hearing about your orders. ### Rebuild indexes so SureBright sees current products Under **Reindex**, click **Reindex now** to rebuild every Magento indexer so SureBright reads current catalogue, price and stock data. It is the same as running `bin/magento indexer:reindex` and can take a while on a large catalogue. The result lists each indexer with **Reindexed** or the error it raised. ### Purge caches after a change Under **Cache**, click **Purge caches** after authorising, reauthorising or changing the module, so the storefront picks up the change. It cleans the cache types that affect SureBright: integration and web API configuration, layout, block HTML and full page. The result lists each cache type with **Cleaned**, **Not present on this install; skipped**, or an error. ## Find orders that did not reach SureBright Orders and product changes that failed to reach SureBright are listed in the **SureBright Webhook Errors** grid at `/surebright/webhookerror/index`. Each row shows when it happened (**Created At**), what it was about (**Event Type**, **Entity ID**, **SKU**, **Store ID**) and what went wrong (**Error Type**, **HTTP Status**, **Error Message**, plus the request and response). When an order has no contract, find its row and share it with SureBright support. ## Disabling or removing the module You turn the module off, turn it on again, or reinstall it from the command line on your Magento server. Removing the module does not cancel existing contracts. SureBright keeps serving them and your customers can still file claims. ### Disable the module ```bash php bin/magento module:disable Surebright_Integration --clear-static-content bin/magento setup:di:compile bin/magento cache:clean ``` The SureBright page in the admin and the storefront widgets disappear. While the module is off, your orders are not sent to SureBright, so orders placed in that time do not become contracts. ### Enable the module again ```bash php bin/magento module:enable Surebright_Integration bin/magento setup:di:compile bin/magento cache:clean ``` ### Reinstall Use this when support asks you to move to a new version or when the module files are damaged. ```bash php bin/magento module:disable Surebright_Integration --clear-static-content bin/magento setup:di:compile composer remove surebright/integration bin/magento setup:upgrade bin/magento setup:static-content:deploy -f -j5 bin/magento cache:clean ``` Replace the version tag with the one in the release note you received, for example `v1.3.15`. ```bash composer require surebright/integration:v1.3.15 php bin/magento module:enable Surebright_Integration bin/magento setup:upgrade bin/magento setup:di:compile ``` ```bash bin/magento setup:static-content:deploy -f -j5 php bin/magento cache:flush ``` Then open the SureBright page in the admin and check that the [status](#check-status-and-open-the-merchant-portal) shows the new version and **Authorized**. If it asks you to sign in again, use **Login Now**. ## Related - [Installation Guide](/magento/install-guide) - [Storefront widget](/magento/storefront-widget): what shoppers see and what to check when offers do not show. - [Pause or remove SureBright](/platforms/pause-or-remove) The module exposes a small REST API for registration and support. Every route needs an integration token that holds the **Surebright Integration** permission. | Route | Purpose | |---|---| | `POST /V1/surebright/integration` | Stores the SureBright credentials for the integration. | | `GET /V1/surebright/integration` | Lists the stored integration details. | | `GET /V1/surebright/log` | Returns the module's log for support. | | `GET /V1/surebright/log/toggle` | Turns module logging on or off. | | `GET /V1/surebright/webhook-errors` | Lists recorded webhook errors. | | `GET /V1/surebright/webhook-errors/:errorId` | Returns one webhook error. | --- # Installation guide Source: https://docs.surebright.com/magento/install-guide > Install the SureBright module on your Magento store, activate it in the Magento admin and sign in to the merchant portal, so you can offer product and shipping protection on your website. This page takes you from a Magento store without SureBright to one that is installed, authorised and ready to sell protection. It is written for the person who has SSH access to the Magento server and an admin login for Magento. ## What you get on Magento - Product and shipping protection offered on your website. [Storefront widget](/magento/storefront-widget) shows what shoppers see. - A **SureBright** page in your Magento admin for checking status and fixing problems. See [Admin panel](/magento/admin-panel). - Complete visibility into your warranty programme in the SureBright [merchant portal](/merchant-portal/overview). ## What you need to do | Step | Where | What | |---|---|---| | 1 | Your Magento server, over SSH | Run six commands to add the module and refresh Magento. | | 2 | Magento admin | Activate the **SureBright Product Protection** integration. | | 3 | SureBright merchant portal | Sign in with the credentials SureBright shares and add a payment method. | ## Install the module on your server Open each step in order and run its command. Use the terminal (PuTTY or any SSH client) on your computer to connect to your Magento server over SSH. ```bash ssh username@your.server.ip ``` - Replace **username** with your actual username. - Replace **your.server.ip** with your server IP address or website domain name, for example `127.0.0.1` or `mystore.com`. - Windows users can download PuTTY. This guide explains how: https://www.wikihow.com/Use-Putty-in-Windows Once you are connected, go to the main folder where all your store's files are kept. **Usually, it's /var/www/html** ```bash cd /path/to/magento/root ``` Run this command to install the integration. ```bash composer require surebright/integration ``` ```bash bin/magento setup:upgrade bin/magento setup:di:compile ``` Deploy static files (like images and styles) by running: ```bash bin/magento setup:static-content:deploy -f -j5 ``` Refresh Magento so everything works properly by running: ```bash bin/magento cache:clean ``` After completing these steps, the module is installed. Next, activate it. ## Activate the integration in the Magento admin ![Screenshot2025 05 30at16 06 45sure Bright Magento App Installation Guide Pn](/images/Screenshot2025-05-30at16-06-45SureBrightMagentoAppInstallationGuide.png) In the **System** menu, under the **Extensions** heading, click **Integrations**. ![Screenshot2025 05 30at16 07 21sure Bright Magento App Installation Guide Pn](/images/Screenshot2025-05-30at16-07-21SureBrightMagentoAppInstallationGuide.png) Find the **SureBright Product Protection** line and click **Activate** (or **Reauthorize** if it was activated before). ![Screenshot2025 05 30at16 07 29sure Bright Magento App Installation Guide Pn](/images/Screenshot2025-05-30at16-07-29SureBrightMagentoAppInstallationGuide.png) Approve the access it asks for. This lets SureBright see the catalogue and order information it needs to run your warranty programme. ![Screenshot2025 05 30at16 07 38sure Bright Magento App Installation Guide Pn](/images/Screenshot2025-05-30at16-07-38SureBrightMagentoAppInstallationGuide.png) If authorisation fails, a common cause is that SureBright cannot reach your store through its firewall or IP allow-list. See [If activation or reauthorisation fails](/magento/admin-panel#if-activation-or-reauthorisation-fails). ## Sign in and add a payment method Log in to the SureBright merchant portal using the credentials shared with you. The portal gives you complete visibility into your warranty programme. If you have not received the credentials, reach out to your Account Manager. ![Screenshot2025 05 30at16 07 57sure Bright Magento App Installation Guide Pn](/images/Screenshot2025-05-30at16-07-57SureBrightMagentoAppInstallationGuide.png) Click **Add Payment Method** and provide your payment details. SureBright uses it to charge you for the cost of the warranty plans sold to customers through your store. You are charged weekly or monthly, whichever you prefer. ![Screenshot2025 05 30at16 08 07sure Bright Magento App Installation Guide Pn](/images/Screenshot2025-05-30at16-08-07SureBrightMagentoAppInstallationGuide.png) You have now installed SureBright on your Magento store. ## Related - [Admin panel](/magento/admin-panel): check authorisation, run the built-in checks, disable or reinstall the module. - [Storefront widget](/magento/storefront-widget): what shoppers see and what to check when offers do not show. - [Merchant portal](/merchant-portal/overview) --- # Storefront widget Source: https://docs.surebright.com/magento/storefront-widget > What shoppers see on your Magento storefront once the module is installed, what happens after a plan is bought, and what to check when offers do not show. Once the module is installed and the integration is authorised, protection offers appear on your storefront by themselves. You make no theme changes. Use this page to see what shoppers get on each page, what happens after a sale, and what to check when an offer is missing. - **What you get:** offers on product pages, the cart and the mini-cart, and a contract for every plan sold. - **What you do:** keep the integration authorised, and decide in the merchant portal which products carry an offer. ## What shoppers see on each page | Page | What the shopper sees | |---|---| | Product page | The protection offer with the available plan terms and prices, a learn-more popup describing the coverage, and a link to the plan's terms. | | Cart page | An offer to add protection to each eligible item that does not have it yet. | | Mini-cart | The same per-item offer when the cart is opened from the header. | Offers appear only for products that have a SureBright category and are eligible for a plan. Use the **Status chips** and the per-product switch on [Products](/merchant-portal/products) to see and control which products carry an offer. The look and wording of the offer are controlled from your SureBright configuration rather than from Magento. Offers show only on the storefront domain SureBright registered when you authorised the integration. A second domain or a staging host pointing at the same Magento install will not be recognised. ## What happens after a shopper buys a plan When an order that includes a plan is placed, the contract is created for you. Later changes to the order (invoice, shipment, credit memo, cancellation) are picked up the same way, so refunds and cancellations reach the contract without a separate step. Contracts show under **Recent Sales** on the portal's [Sales](/merchant-portal/sales) page. For this to work, the **Sales Access** and **Catalog Access** permissions on the [admin panel](/magento/admin-panel#check-which-permissions-are-granted) must be granted. A **not granted** pill there is the usual reason a paid plan has no contract. ## When offers do not show View the source of a product page and search for `magentoSBSIMSDK`. If it is missing, the module is disabled or the full-page cache is serving an old copy. Run **Purge caches** on the [admin panel](/magento/admin-panel#purge-caches-after-a-change). The admin panel status must read **Authorized**. An **Authorization pending** or **Reauthorization required** alert means SureBright cannot read your catalogue, so there are no plans to offer. Open [Products](/merchant-portal/products) and search for the product. It needs a category and must be switched on. Run **Reindex now** from the admin panel if a recently added product is not listed. Run **Test webhook** on the admin panel. If your server cannot reach SureBright, offers may still show but orders will not become contracts. If the script is present, the integration is authorised and the product is eligible but no offer shows, send SureBright support the product URL. ## Related - [Admin panel](/magento/admin-panel): status, authorisation and the built-in checks. - [Products](/merchant-portal/products): choose which products carry an offer. - [Test your setup](/platforms/test-your-setup) The module adds a block named `sb.script.footer` at the start of the body on every storefront page. It outputs two tags: ```html ``` The first identifies your store by its storefront host name and tells SureBright the platform is Magento. The second loads the SureBright storefront script, the same one used on other platforms. --- # Manual and draft orders Source: https://docs.surebright.com/manual-orders/overview > The ways to sell a protection plan outside your storefront checkout, and which platforms each works on: draft orders from the Merchant Portal, the Shopify draft order extension, spreadsheet order intake and the POS portal. Not every sale goes through your storefront checkout. A customer may call to order, may want a plan for something they already bought, or your orders may live in a system SureBright is not connected to. These guides cover each case. Which ones you can use depends on your platform. | You want to | Use | Works on | |---|---|---| | Add a plan to an order a customer already placed, or record a sale by hand, without leaving SureBright | [Merchant Portal draft orders](/merchant-portal/leads) | Shopify and Magento | | Take a phone order inside Shopify admin and add the plan to the draft order there | [Shopify draft order extension](/draft-order-guide/shopify-draft-order) | Shopify | | Send SureBright a spreadsheet of orders and have the plans set up for you | [Spreadsheet order intake](/erp/spreadsheet-order-intake) | Any system, on request | | Record a sale made at a counter or by phone, one at a time or in bulk | [SureBright POS portal](/pos/overview) | Any register. The POS portal is separate from your online store's platform | Customers who bought the product on a marketplace, from a dealer or on another of your stores can be sold a plan too. See [Products bought on a marketplace or another store](/learn/phone-and-later-sales#products-bought-on-a-marketplace-or-another-store). ## Merchant Portal draft orders on Shopify and Magento On Shopify and Magento stores, the **Leads** page in the Merchant Portal lists every order placed on your store. Open an order, pick a plan for an eligible item and add it to a draft order, or click **Record manual order** to sell a plan for a product that was not bought through a listed order. The portal creates the draft order on Shopify or Magento, where you collect payment. The contract activates once the order is paid. Leads, manual orders, the draft order panel and what happens after the draft is created. ## Shopify draft order extension For Shopify stores only. The SureBright Draft Order extension works inside Shopify's own draft orders. Use it for over the phone sales, including selling a plan for a product the customer already owns. Installing the extension and the four common phone-sale scenarios. ## Spreadsheet order intake Works with any system. Use it when your orders do not come from a connected storefront or POS. You email a workbook of orders to the mailbox SureBright gives you, and SureBright sets up the plans for you. Available on request. What the workbook must contain and what happens after you send it. ## In-store sales Whatever platform your online store runs on, sales made at a counter are recorded in the SureBright POS portal, one at a time or in bulk. See [Recording a sale](/pos/recording-a-sale) and [Bulk upload](/pos/bulk-upload). ## A draft order in Shopify that you did not create SureBright tools create Shopify draft orders in these cases: | The draft | Where it came from | What to do | | --- | --- | --- | | A draft with a plan for one of your past orders, or a manual sale | Someone on your team used [Leads](/merchant-portal/leads), or asked [Ray](/merchant-portal/ray) or the [merchant AI connector](/ai-agents/merchant-connector) to create a draft order | Check with your team. It becomes an order only when paid | | A draft with the shopper's cart and a discounted or free plan | [Abandoned Cart Recovery](/abandoned-cart-guide/abandoned-cart) sends its offers as Shopify draft order invoices | Nothing. It is the offer the shopper was emailed | | A draft with a test item, tagged **Test** | A **Test send** from Abandoned Cart Recovery | Safe to delete | A draft order is not a sale. Nothing is billed and no plan exists until it is paid. If you find a draft that matches none of these, send support its number. ## Related - [Phone, draft and later sales](/learn/phone-and-later-sales) - [What can be covered](/contracts/what-can-be-covered#buying-a-plan-after-the-product) --- # Your analytics and page speed Source: https://docs.surebright.com/merchant-portal/analytics-and-page-speed > Where protection plan sales show up in the reports you already use, how to count them in or out, what SureBright reports for you, and how the SureBright offer affects how fast your pages load. Protection plans you sell show up in your own sales reports. Knowing where they are helps you keep your numbers right. You also want the SureBright offer to stay light, so your pages stay fast. This page is for you and whoever runs your store's reporting or website. It shows where plan sales appear, how to separate them, and what the offer adds when a page loads. | You want to | Go to | | --- | --- | | Find plan sales in your reports, or leave them out | [Plan sales in your own analytics](#plan-sales-in-your-own-analytics) | | Spot a plan in your order reports | [Spot a SureBright plan in your reports](#spot-a-surebright-plan-in-your-reports) | | See the plan reports SureBright gives you | [What SureBright measures for you](#what-surebright-measures-for-you) | | Know how the offer affects page speed | [What the offer adds when a page loads](#what-the-offer-adds-when-a-page-loads) | | Fix a page speed report that blames SureBright | [If SureBright's script is slowing your pages](#if-surebrights-script-is-slowing-your-pages) | ## Plan sales in your own analytics A plan is a product in your catalogue. When a shopper picks one, it goes into the cart as its own line. It shows on the order as its own line too. The shopper pays for it in your checkout with everything else. So your platform's sales reports include the plan like any other product. The same goes for any tracking that records the items and value of each order. SureBright does not send anything to Google Analytics, Meta or any other analytics or ad tool. Those tools only see what your own tracking already reports about carts and orders. | You want to | Do this | | --- | --- | | Report product sales without plans | Leave out items whose name contains **SureBright**. | | Report plan sales on their own | Keep only those items. | | Keep plans out of the order value you send to ad tools | Take the plan line off in your tracking set-up. If you do not, the order value includes the plan. | | Count how often plans are added to carts | Use your tag manager's preview mode to check if an "add to cart" is recorded for the plan. The plan is added along with the product, not with its own button, so some set-ups miss it. | | See which product a plan covered | Look at the plan line's **Product** and **Term** details on the order. | ### Spot a SureBright plan in your reports | What to look for | What it says | | --- | --- | | Product title | **Product Warranty Powered by SureBright** by default. **Shipping Protection Powered by SureBright** for shipping protection. If your store uses its own plan title, look for that instead. | | Product vendor (Shopify only) | **Surebright**. This is the same setting that keeps plans out of discounts. See [Shopify admin housekeeping](/shopify/admin-housekeeping#discounts-that-exclude-surebright-products). | | Details on the line | **Product** (the title of the product the plan covers) and **Term** (how long the plan lasts). Shoppers can see these. The line also carries hidden details. Never remove or rename them. | The plan price in your reports is what the shopper paid. Your share of it is shown under [Billing](/merchant-portal/billing). ## What SureBright measures for you You do not need to build plan reports yourself. [Sales](/merchant-portal/sales) shows **Total Revenue**, **Policies Sold** (plans sold) and **Attachment Rate**. Attachment rate is the share of orders that added a plan, out of the orders that could have had one. [Design performance](/merchant-portal/design-performance) compares this between your offer designs. Ask your SureBright contact if you want it. These numbers come from your orders and from what shoppers do with the offer. - **On Shopify**, what shoppers do is recorded only if they allowed it in Shopify's cookie banner. - **On other platforms**, SureBright cannot see the shopper's cookie choice, so it records what they do as it happens. If your own cookie tool must control this, tell your SureBright contact. Either way, the offer still shows. See [Analytics and consent](/frontend-widget-integration/frontend-widget-kit/analytics-and-consent). ## What the offer adds when a page loads SureBright adds a small piece of code (a script) to your store pages. It draws the offer. | Question | Answer | | --- | --- | | Does it hold up the page? | On Shopify, no. The same goes for custom stores that follow the install guide. The script loads in the background and runs once your page is ready. On other platforms, ask your SureBright contact. | | Which pages load it? | On Shopify, the pages where an offer can appear: product, cart, collection and home pages, plus any others SureBright has added for your store. Some stores load it on every page. Ask your SureBright contact if you want this changed. On BigCommerce, every store page except checkout. On other platforms, ask your SureBright contact. | | Does it download everything again on every page? | No. Your offer settings, and the plans for products a shopper has already looked at, are kept in that shopper's browser for up to two hours. | | Does the page jump when the offer appears? | Space is kept for the offer while plans load. If the product has no plan, the space is released. | | What if SureBright is slow or down? | The offer may not show. The rest of your page works as normal. | | Can it slow down add to cart? | Only briefly. If SureBright has not added the plan within five seconds, the product goes into the cart without it. If a shopper clicks before SureBright is ready, the click waits and then goes through, after 20 seconds at most. | | Does it change how my store looks? | No. The offer's styles are kept apart from your store's, both ways. It hides only one thing: SureBright's own plan products on collection pages, so shoppers do not see them as products to buy. | | How big is it? | It depends on your store's set-up. Your developer can check how much your shoppers download. See **For developers** at the end of this page. | Load SureBright only once. On Shopify, that means only the **SureBright Offering** app embed (the switch in your Shopify theme settings that turns SureBright on). Do not also paste SureBright code into your theme. On other platforms, keep only the code your install guide added. ## If SureBright's script is slowing your pages A page speed report (a tool that measures how fast your pages load) may list SureBright's script as one of the heaviest. If so, go through this list. | What you see | Do this | | --- | --- | | The report names an older SureBright script | Ask SureBright to move your store to the current script. SureBright makes this switch for you. On Shopify, the **SureBright Offering** app embed still loads it, so nothing changes in your theme. | | SureBright is loaded twice | Remove any SureBright code pasted into your theme by hand. Only the app embed, or the code from your install guide, should load it. See the tip above. | | It loads on pages where no offer appears | Ask your SureBright contact to load it on fewer pages. See **Which pages load it?** above. | | You still see the old script after a change | Your store may be showing a saved copy of the page. Clear your store's page cache, then test again in a private browser window. | When you write to SureBright, include the page link and the report, or a screenshot of it. ## Related - [Sales](/merchant-portal/sales) and [Design performance](/merchant-portal/design-performance): SureBright's own reports on your plan sales. - [Storefront setup](/shopify/storefront-setup): where you switch SureBright on in your Shopify theme. - [Offer not showing?](/help/offer-not-showing): what to do when the offer does not appear. - SureBright does not write to your data layer. Analytics tools only receive what your own tags report about carts and orders. - An order value sent with a purchase event includes the plan line unless your tag subtracts it. - Plan lines carry hidden line-item properties, such as `_sbQuoteId`. Do not remove or rename them. - An older SureBright script that page speed reports may name is `sbsimsdk.js`. - After a script change, clear your storefront's CDN or page cache before testing. - To see what your shoppers download, read the transfer size of the SureBright script in your browser's developer tools. - How the script is loaded, what it requests, and how to forward plan selections to your own tags are covered in [SDK Installation](/frontend-widget-integration/frontend-widget-kit/sdk-installation) and the [JavaScript API Reference](/frontend-widget-integration/frontend-widget-kit/javascript-injection). --- # Billing Source: https://docs.surebright.com/merchant-portal/billing > Add and manage payment methods, find and download invoices, see what each invoice charged you for, and export your billed orders. **Billing**, in the [Merchant Portal](/merchant-portal/overview), is where you set how SureBright charges you and see every invoice. It has two tabs, **Payment Methods** and **Billing History**. | You want to | Do this | | --- | --- | | Add a card or bank account | **Payment Methods → Add Payment Method**. See [Payment methods](/merchant-portal/payment-methods#add-a-payment-method). | | Change which method is charged | **Set To Default** on the method. See [Payment methods](/merchant-portal/payment-methods#change-the-method-that-is-charged). | | Download an invoice PDF | The download icon on the invoice's row in **Billing History**, or **Download PDF** on the invoice page. | | See what an invoice charged you for | Click the invoice's row, then **View full invoice details →**. See [See what an invoice charged you for](#see-what-an-invoice-charged-you-for). | | Get every billed order in one file | **Download Billed Orders** exports a CSV of every order billed to you across all processed invoices, for both product and shipping protection. | ## Payment Methods SureBright charges each invoice to your default payment method. Until you add one, the header shows **You haven't added any payment method yet**; the Billing tab shows the same message with a **Know why we require payment Method** link and an **Add Payment Method** button. | You want to | Do this | | --- | --- | | Add a method | **Add Payment Method** (or **Add New Payment Method** when you already have one), fill in the form and click **Save Payment Method**. | | Change which method is charged | **Set To Default** on another saved method, then confirm. The default is the card marked **Default Payment Method**. | | Remove a method | The bin icon on a method that is not your default. You cannot remove your default or your only method. | Which methods you can save, how bank verification works, who can manage them and what to do when the form refuses are covered in [Payment methods](/merchant-portal/payment-methods). ## Billing History One row per invoice, newest first, with unpaid invoices pinned to the top. | Column | What it shows | | --- | --- | | **Date** | The invoice date. | | **Billing Status** | **Processed** (paid) or **Pending** (issued, not yet paid). An invoice whose charge failed is not listed; its plans are billed again on a later invoice. See [Payment questions](/merchant-portal/payment-questions#my-charge-failed). | | **Payment Method** | The provider the invoice was charged through. | | **Type** | **Product Protection** or **Shipping Protection**. Stores that sell both get one invoice of each per cycle. | | **Amount** | The net amount. | | **Invoice** | A download icon for the invoice PDF. | Click a row to expand its summary: - **How this invoice was generated** explains charges, carryover charges and refunds for cancellations. - **Missing from Invoice** and **Late Cancellations** counts, checked against Sales, or **All warranties from this period are accounted for on this invoice.** - **Net Amount Calculation** (see below) and **View full invoice details →**. ## See what an invoice charged you for Click **View full invoice details →** on an expanded row. The invoice page opens with a status pill, the **Invoice** number, the billing period, its length in days and the type, the **net amount**, and a **Download PDF** button. An **Invoice breakdown** bar shows **Charges**, **Refund for Cancellations** and **Credits** as shares of the invoice. Under **Activity** you see a timeline of the invoice's progress, and **Charged to** with the card brand and last four digits (or **Payment method not on file**). ### How the net amount is worked out **Net Amount Calculation** shows how the net amount was reached: ```text Charges current cycle · N + Charges carryover · N − Refund for Cancellations current cycle · N − Refund for Cancellations carryover · N − Credits N = Net amount charged ``` - **Charges** are plans that became fully active in this cycle. - **Carryover** rows appear when plans sold in earlier cycles only became ready to bill this time. Carryover refunds give back what you paid for plans billed on an earlier invoice and cancelled since. - **Credits** are coupons and adjustments applied to the invoice. - The last line reads **Net amount to be charged** while the invoice is still pending. ### See charges and refunds month by month **Monthly Activity** lists charges and refunds by month, split into **Current invoice period** and **Carryover from past periods**. Carryover is grouped by the invoice that first billed those months (**Invoice #…**) with each group's net; months older than any recorded invoice appear under **Older than tracked invoices**. Two links sit next to the current period: - **Analyse →** opens Sales for this invoice's period, with the [Reconciliation Check](/merchant-portal/sales#check-an-invoice-against-your-sales). - **Check Contracts →** opens Recent sales limited to this invoice's contracts, with the date filter set to the period. For the month-close routine from start to finish, and what every figure on this page means, see [Invoice analysis](/merchant-portal/invoice-analysis). ### Find a plan or an order on an invoice **Warranties in this invoice** is a table of every contract billed on the invoice, with **Sr.**, **Date**, **Customer**, **Email**, **Order #**, **Status** and **Total Warranty Price**. Use **Search by customer name, email, or order number...** and the page controls at the bottom. On a shipping invoice the table is **Orders in this invoice**, since shipping protection is billed per order, and the last column is **Amount Charged**. Click an order number to open the order: its **Date**, **Platform**, **Order #**, **Order ID**, **Warranties on this order**, **Total Warranty Price**, **Your Margin**, **Net to SureBright**, the **Customer**, and the **Covered Products** with each plan, price, margin and status. On Shopify stores, **Open in Shopify ↗** opens the order in your admin. ## Related Close a month from one invoice and trace every figure. What to do when an invoice and your sales differ. --- # Coverage Intelligence Source: https://docs.surebright.com/merchant-portal/coverage-intelligence > See how much of your catalogue has a protection offer, which products should be covered next, what the gaps cost you, and whether your bundles can be covered. **Coverage Intelligence**, in the [Merchant Portal](/merchant-portal/overview), shows you which of your products have no protection offer, why, what that costs you, and the one action that fixes each. Where [Products](/merchant-portal/products) shows every item and its switch, this page tells you where to act first. It is available on request: once SureBright switches it on, a card on the Products page reads **Open Coverage Intelligence →**, or go to **Products → Coverage Intelligence**. All figures use the last 30 days of sales. Hover a tile to see how each number is counted. ## The headline coverage numbers | Tile | What it answers | |---|---| | **Catalog coverage** | The share of your product revenue that comes from products with a live protection offer, with the product count beneath (*N of M products covered*) | | **Uncovered revenue (30d)** | Sales of products with no offer: revenue where protection was never offered | | **Missed warranty revenue** | A cautious estimate of the plan revenue those sales would have produced, using your own attach rate and a typical plan price, per 30 days and per year | | **Needs attention** | Products waiting for a person to decide (see below) | | **Bundle support** | How many of the kinds of bundle in your catalogue can be covered, and how many bundle products are covered | ## See where products drop out A product gets a protection offer once SureBright knows what it is, it has a coverage category, and protection is switched on. **Where products drop out** shows how many products and how much monthly revenue sit at each stage: | Stage | Meaning | |---|---| | **Not classified yet** | SureBright has not yet worked out what the product is | | **Classified, no coverage category** | SureBright knows the product's type, but that type has no coverage category yet | | **Category set, protection off** | The category is set and protection is switched off for the product | | **Protection offered** | Customers see an offer on these products today | Click a stage's product count to open the product list below filtered to it. A **Biggest leak** line names the stage holding the most monthly sales. Most of it is cleared by choosing categories, not by changing your products. ## Find what to fix first **Opportunities** ranks the actions open to you. Each shows the monthly sales it would bring under protection, the plan revenue that implies, a **Next step**, and **See the N products**. | Label | What it asks | |---|---| | **Map category** | SureBright knows these products' type, but the type has no coverage category | | **Turn on protection** | Products have a category and protection is off. Switch them on from [Products](/merchant-portal/products#turning-protection-on-or-off) | | **Extend price band** | Products are priced outside the price range their category covers | | **Split product type** | One product type spans items that should be covered differently | | **Improve listings** | The product listing says too little for SureBright to work out what the product is | ## Products that should be covered Every product with no protection offer, with what is stopping it. Filter by reason (**All reasons**, **No category mapping**, **Protection off**, **Not classified**, **Price outside band**), search by product, type or category, and sort by **Top 30d sales**, price or name. | Column | Meaning | |---|---| | **Product** | Title and product type | | **Price** | Current price | | **30d sales** | Sales in the last 30 days, or *no sales* | | **Suggested category** | The coverage category SureBright suggests | | **Why it isn't covered** | The reason | | **What unblocks it** | The one action that fixes it | | **Open** | **Store site ↗** opens the product on your storefront; **Products screen** opens the Products page searched to it | ## Products that need special handling SureBright does not set every category automatically. These products wait for a person, ordered by revenue at stake, each with the suggested category and a confidence bar. | Badge | Why it is waiting | |---|---| | **In review** | SureBright is between 60% and 85% sure of the category, so a person confirms it | | **High-value check** | SureBright is at least 85% sure, but your highest-revenue products always get a human check | | **Needs mapping** | The product's type has no coverage category yet. These are never set automatically | | **Wide price range** | Products of this type span a wide price range, so one price range would misprice them | | **Too little signal** | SureBright is less than 60% sure. The product waits until its listing improves | SureBright's team works through this list. You can speed it up by improving the listing (title, type, description) or by confirming the category with your SureBright contact. ## Check whether your bundles can be covered The bundles section opens with a plain answer for your catalogue, then one card per kind of bundle with **How coverage works** and its counts, and a table of the bundle products themselves (**Bundle**, **Shape**, **Price**, **30d sales**, **Status**, **Note**, **Open**). | Shape | Support | Description | |---|---|---| | **Fixed kits** | Supported | Same components in every unit, sold at one price | | **Main item + accessories** | Supported | One product that can be covered, bundled with low-value add-ons | | **Multi-item sets** | Supported with review | Several items that could each be covered, sold as one SKU | | **Build-your-own** | Not yet supported | Contents and price vary per order, so the bundle has no fixed price to base a plan on | A **Sample data preview** badge next to the title means the page is showing generated sample data and not your catalogue. Ask your SureBright contact if you see it on a store that should be live. ## Related Set categories and turn protection on or off per product. Where protection sells well and where sales are being missed. --- # Default plan selection Source: https://docs.surebright.com/merchant-portal/default-plan-selection > Choose which protection plan is already picked when a shopper opens your product page, and whether shoppers see a No coverage choice. On Shopify, you can test which choice sells more. When a shopper opens your product page, one protection plan can already be picked for them. A good choice saves the shopper a click. The wrong one can feel pushy. This page shows you how to choose that plan, or to pick none. On Shopify, you can also test which choice works best for your store. Shoppers can always change the plan or remove it. You make these choices in [Studio](/merchant-portal/studio). Ask SureBright to turn Studio on for you. | You want to | Go to | | --- | --- | | Choose which plan is picked first, or none | [Choose which plan is picked first](#choose-which-plan-is-picked-first) | | Pick the plan by price instead | [Pick by price instead](#pick-by-price-instead) | | Let shoppers say no with one click | [Show or hide the No coverage choice](#show-or-hide-the-no-coverage-choice) | | Draw attention to a plan without picking it | [Highlight a plan without picking it](#highlight-a-plan-without-picking-it) | | Know how this changes the pop-up after **Add to cart** | [How this affects the add-to-cart pop-up](#how-this-affects-the-add-to-cart-pop-up) | | Find out which choice sells more | [Test which choice works (Shopify only)](#test-which-choice-works-shopify-only) | ## Choose which plan is picked first In Studio, open **Plans**. Pick an option under **Default Selected Plan**. | Choose | What your shopper sees | Good when | | --- | --- | --- | | **None** | No plan is picked. The shopper picks one if they want it. | You want buying a plan to be the shopper's own choice. | | **1st** | The first plan is picked. | You want your starter plan to lead. | | **2nd** | The second plan is picked. | You want the middle plan to lead. | | **3rd** | The third plan is picked. | You want your biggest plan to lead. | Plans are counted in the order they appear on your product page. The **No coverage** card does not count. Some products have only two plans. If you choose **3rd**, those products pick the last plan. So a shopper never sees an empty choice. Studio shows your current setting in a few words, for example **2nd plan selected** or **No plan selected**. ## Pick by price instead Your SureBright contact can pick the plan by price instead of by place: - the cheapest plan - the most expensive plan - the plan with the lowest monthly price - **No coverage**, so every shopper has to choose a plan themselves Once it is set, Studio shows it as your current choice until you pick another. ## Show or hide the No coverage choice A **No coverage** card next to the plans lets a shopper say no with one click. In the same **Plans** section, set **"No coverage" option**: - **Shown**: shoppers see the card and can pick it. - **Hidden**: shoppers see only the plans. If your plans show as a **Dropdown menu**, the No coverage choice is always there. To hide it, show your plans as cards or rows instead. ## Highlight a plan without picking it You set the **Best-seller badge** in the **Plans** section too. It draws attention to a plan but does not pick it. So you can highlight one plan and have a different one picked. ## How this affects the add-to-cart pop-up SureBright can switch on a pop-up that shows the plans. It opens when a shopper clicks **Add to cart** without a plan. The pop-up does not open if a plan is already picked. So if you pick a plan for shoppers, fewer of them see the pop-up. SureBright turns the pop-up on or off for you. They can also show it on only some **Add to cart** buttons. See [Turn the add-to-cart pop-up on or off](/merchant-portal/widget-options#turn-the-add-to-cart-pop-up-on-or-off). ## Test which choice works (Shopify only) The best choice is different for every store. On Shopify you do not have to guess. You can show some shoppers one choice and the rest another, then compare. This is called a design test. It is not available on other platforms. In Studio, open the **Designs** tab. Click **Duplicate** on the design shoppers see now. Open the copy. Set **Default Selected Plan** to the option you want to try. Save it. It stays a draft, which only you can see. Click **Test against live** and start the test. Some shoppers see your current choice. The rest see the new one. When the test shows a clear winner, make that design live. See [Design tests](/merchant-portal/design-tests) and [Design performance](/merchant-portal/design-performance). ## Related Every setting in the Plans section, and all the other ways to change the offer. Show two designs to different shoppers and see which sells more plans. Building a custom storefront? The selection events in the [JavaScript API reference](/frontend-widget-integration/frontend-widget-kit/javascript-injection) tell your code which plan was pre-selected. --- # Design performance Source: https://docs.surebright.com/merchant-portal/design-performance > Find out which look of your SureBright offer sells more protection plans. Compare your designs, see the result of a design test, see the difference in money, and see where shoppers drop off. Some designs of the SureBright offer sell more protection plans than others. This page shows you which of your designs works best, so you can keep the one that earns you more. **Design performance** is part of [Sales](/merchant-portal/sales) in the [Merchant Portal](/merchant-portal/overview). You find it on the **Product Protection** dashboard. While a [design test](/merchant-portal/design-tests) is running, it compares the two designs in the test and tells you if there is a winner yet. You see this section only once SureBright turns it on for your store. Ask your SureBright contact if you want it. ### Words used on this page - **Attach rate**: the share of orders that added a protection plan, out of the orders that could have had one. - **Eligible orders**: orders with at least one product that can have a plan. Only these count. - **Policy**: one protection plan sold. - **Version**: one design of your offer. - **Live**: the design shoppers see now. - **Variant** or **challenger**: the new design you are testing against your live one. - **Previous**: an older design that shoppers no longer see. ## What you can do here | You want to | Go to | | --- | --- | | Choose which dates the numbers cover | [Choose the dates to look at](#choose-the-dates-to-look-at) | | See how many orders added a plan with each design | [Compare your designs](#compare-your-designs) | | Find out if a test has a winner | [See who won a design test](#see-who-won-a-design-test) | | See which design made more money | [See the difference in money](#see-the-difference-in-money) | | See where shoppers drop off before adding a plan | [See where shoppers drop off](#see-where-shoppers-drop-off) | | See what is different between two designs | [See what is different between the designs](#see-what-is-different-between-the-designs) | ## Choose the dates to look at The section has its own switch with two choices: - **Whole test**: every order since the test started. The result of a test is based on this. It is picked for you while a test is running. - **Selected period**: only the dates you chose at the top of Sales. A line of text tells you which one you are looking at, for example **Showing the whole test, Sep 1, 2026 to Oct 2, 2026**. Days are counted in US Eastern time. Judge a test on **Whole test**. If your store gets few orders, the last thirty days are often not enough to tell. The section tells you so instead of guessing. ## Compare your designs While a test is running, the heading reads **Attach rate by experiment**. At other times it reads **Attach rate by widget version**. Each design has its own row with these numbers: - **Orders**: all orders. - **Eligible**: orders that could have had a plan. - **Policy**: plans sold. - **Attach**: the attach rate (share of eligible orders that added a plan). Each row is marked **Live**, **Variant** or **Previous**. Every design is compared with your live design. The **By category** table below splits plans sold and money earned by type of product. Only designs that were part of the test are compared. A design is not ranked if it was replaced before the test began, or if it has no eligible orders yet. ## See who won a design test A test is always in one of five states: | Where the test stands | What it means | | --- | --- | | Too early | One or both designs do not have enough eligible orders yet. The section reads **Not settled yet** and shows how many orders each design has and needs. Any lead shown here is greyed out. It is not a result. | | No clear difference | Both designs have enough orders, but the gap between them could be luck. | | The challenger wins | The new design adds plans to orders more often than your live design, and the gap is not luck. | | The live design held | The new design does clearly worse, so your current design wins. | | No result | Nothing could be compared for these dates, for example because there were no orders. | A lead only counts once both designs have enough orders. This stops a design with very few orders from making the other one look like a winner. Until then, its row reads **Not enough orders yet for this difference to mean anything**. **Previous tests** lists your past tests. For each one you see the designs, the share of shoppers each design was shown to, eligible orders and attach rate. A short **Result** tells you how it ended, such as **won**, **the current design held**, **no clear difference** or **stopped before there were enough orders to tell**. ## See the difference in money Attach rate counts orders, not money. One design can sell fewer plans but more expensive ones. The **If one version served everyone** card shows each design in money: | Column | What it tells you | | --- | --- | | **Per eligible order** | Money from plans that design earned for each eligible order. | | **Accidental damage** | The share of that design's plans that also cover accidents. | | **Projected policies** | How many plans that design would have sold if every shopper in the test had seen it. | | **Projected revenue** | The same, in money. | | **Difference** | How much more that design would have earned than the lowest-earning design. | The design that earns the most per eligible order gets a badge. These figures count only plans added on the product page or in the cart. Plans sold after the purchase are left out, and the card tells you how much that was. These figures are simple maths on the orders so far. They are not a forecast. They also do not tell you whether the gap is real or luck. The test result above tells you that. ## See where shoppers drop off The funnel card shows the steps shoppers take, and how many make it to each step. It covers web checkouts and orders for your chosen dates. | Sequence | Steps | | --- | --- | | **Sessions** | **Sessions** (store visits) → **Checkouts started** → **Orders** → **Protected orders** | | **Checkouts** | **Checkouts started** → **Protectable product** (a product that can have a plan) → **Protection in cart** | | **Orders** | **Orders** → **Protectable product** → **Protected orders** | Each step shows what share of the first step made it that far. You see the **Sessions** row only if your store records visits to the offer. Buttons above the funnel change which number the designs are compared on: - **Attach Rate** - **Session CVR** - **Cart Conversion** - **Avg Order Value** (average order size) - **Protection per Order** Each one is shown for every design. If the test dates allow, it is also compared with the time before the test. **Cart Conversion** is hidden when Shopify's data on unfinished checkouts for those dates is incomplete. Without it, the figure would look too high. The section ends with three more cards: - **Store trend**. - **Insights**: short sentences about the numbers, such as money from plans per order for each design. - **How long shoppers take to buy**: the time from a shopper's first visit to their order. ## See what is different between the designs Open a design's card to see **What changes**. It lists every design setting that is different between the designs, with each design's own setting. Colours show as small colour squares. If nothing is different, the card reads **This version is design-identical to the other versions in the test**. ## Related Start, pause and stop a test, and make the winning design live. The rest of the Product Protection dashboard. --- # Design targeting Source: https://docs.surebright.com/merchant-portal/design-targeting > Give one Shopify theme, or one kind of product page, its own offer design. All your other pages keep your live design. Early access. Ask your SureBright contact to turn this on for your store. Sometimes one part of your store looks different from the rest, like a new theme or a special range of products. Design targeting lets the protection plan offer match that part, without changing it anywhere else. You can give its own design to: - **a Shopify theme**: the overall look of your store in Shopify. - **a product page template**: a page layout in your theme that you use for some of your products. Shoppers on every other page keep seeing your live design. ## What you can do | You want to | Choose | Go to | | --- | --- | --- | | Try a design on a new theme before that theme goes live | **A Shopify theme** | [Give a theme or template its own design](#give-a-theme-or-template-its-own-design) | | Give a holiday or seasonal theme its own look | **A Shopify theme** | [Give a theme or template its own design](#give-a-theme-or-template-its-own-design) | | Show the offer differently for one group of products, for example products that use a `product.premium` template | **A product page template** | [Give a theme or template its own design](#give-a-theme-or-template-its-own-design) | | Check which pages see which design | | [Which design a shopper sees](#which-design-a-shopper-sees) | | Turn a targeted design off | | [See or stop a targeted design](#see-or-stop-a-targeted-design) | ## Give a theme or template its own design In [Studio](/merchant-portal/studio), open the **Designs** tab. Pick the draft (a saved design that is not live) you want to use and click **Publish for…**. A panel called **Publish `design` for…** opens. **For a Shopify theme**, fill in **Theme id**. This is the theme's number. To find it, in Shopify go to **Online Store › Themes › Customize**. The number comes after `/themes/` in your browser's address bar. You can also paste the whole address. **For a product page template**, fill in **Template suffix**. This is the last part of the template's name. For example, if a product's **Theme template** in Shopify says `product.premium`, type `premium`. Typing `product.premium` also works. Use **Name this rule** to add a label, such as "Holiday theme" or "Premium range". This makes it easy to find later. Click **Publish for this rule**. Shoppers on that theme or template now see this design. Your live design gets a new saved version that remembers this choice. The targeted design stays a draft, so you can keep changing it. You must fill in a theme id or a template suffix before you can publish. So a targeted design can never replace your design on every page by mistake. ## Which design a shopper sees - A page on a targeted theme or template shows the design you chose for it. - Every other page shows your live design, just as before. - Each theme or template can have only one design. If you publish another design for the same one, it replaces the first. - A page can match two choices, for example a targeted template on a targeted theme. Then the one listed first wins. - If you delete a targeted design, shoppers on that theme or template see your live design. A page never ends up with no offer. - Template names work with or without capital letters. A theme id must match exactly. ## See or stop a targeted design | Where to look | What you see | | --- | --- | | The targeted draft's card | **Live on a theme** or **Live on a template**. Hover over it to see which one. | | Your live design's card | **Also live, by rule**: every targeted design and where it shows, each with a **Stop** button. | Click **Stop** to turn a targeted design off. Shoppers on that theme or template go back to your live design. A targeted design is still a draft. Changes you make to it do not go live on their own. When you want shoppers to see them, click **Publish for…** again, or make it your live design. ## If your store is custom-built On a normal Shopify theme, targeting a theme needs no extra setup. Targeting a template works when your theme tells the SureBright offer which template a page uses. Some stores are custom-built and do not use a normal Shopify theme for the pages shoppers see (these are called headless stores, for example built with Hydrogen). On these stores, your developer must tell the offer both the theme and the template. How to pass the theme and template to the widget is in the [JavaScript API reference](/frontend-widget-integration/frontend-widget-kit/javascript-injection#platform-and-page-overrides). Set them only when your store has a design for a specific theme or template. ## Related Make and change the designs you target. Show two designs to different shoppers and see which gets more orders to add a plan. --- # Design tests Source: https://docs.surebright.com/merchant-portal/design-tests > Show your live offer design to some shoppers and a new design to others, then see which one gets more orders to add a protection plan. Start a test, pause or end it, and know when the result is real. Small changes to how the offer looks can change how many shoppers add a protection plan. A design test shows you which design works better in your store, using real shoppers instead of guesses. A design test (also called an A/B test) splits your shoppers into two groups. One group sees your live design. The other group sees a new design. SureBright then counts which group added more plans. Tests are in [Studio](/merchant-portal/studio), in the [Merchant Portal](/merchant-portal/overview), under the **A/B Testing** tab. Design tests come with Studio and are turned on when you ask for them. They work on Shopify only. Good to know before you start: - Only one test can run at a time. - You need a live design first. Every test compares something against it. - On the test screens, your live design is called **control**. The design you compare it with is called the **challenger**. ## What you can do | You want to | Go to | | --- | --- | | Try a new design on some of your shoppers | [Start a test](#start-a-test) | | Take a break, end a test or pick a design | [Pause or end a test](#pause-or-end-a-test) | | Know which design is better, and when to trust it | [Know when you have a winner](#know-when-you-have-a-winner) | | Understand which shoppers see which design | [Which design each shopper sees](#which-design-each-shopper-sees) | | Look at results or older tests | [See results and past tests](#see-results-and-past-tests) | ## Start a test Click **New test**. Under **Pick what to test against**, choose a design from **Drafts** (designs you saved but never made live) or **Previously live** (designs you used before). You can also click **New version** to copy your live design and change it first. On the right, **What changes** lists every setting that is different between the two designs, side by side. If a design was live before, you also see how it did in its last 30 days. Under **Traffic split**, pick 50, 70 or 90 percent for your live design, or type your own number. The other number fills in so they add up to 100 percent. The new design can go to anywhere from 10 to 90 percent of shoppers. Click **Start test**. Studio asks **Start this A/B test?** and tells you what share of shoppers will see the new design. Confirm to start. A test has no end date. It starts straight away and runs until you stop it or pick a design. ## Pause or end a test The test card shows **Running** or **Paused**. Your two designs are labelled **Live · control** and **Challenger**. For each one you see: - **Shoppers**: how many shoppers saw it. - **Sold**: how many plans it sold. - **Revenue**: how much money those plans brought in. Bars underneath show each day. Use the buttons above the figures to switch between **Attach rate** (the share of orders that added a plan), **Policies sold** (plans sold) and **Revenue**, or to look at one kind of plan only. | You want to | Click | What happens | | --- | --- | --- | | Take a break and keep your results | **Pause**, then later **Resume** | While the test is paused, every shopper sees your live design. When you resume, the split starts again. Results so far are kept. | | End the test and keep your live design | **Stop** | Studio asks **Stop this test?** Every shopper sees your live design. You cannot restart a stopped test, but you can still make the new design live later. | | End the test and use one design for everyone | **Make `design` live** | That design goes live for every shopper. Studio first asks **End the test and publish `design`?**, or **End the test and keep `design` live?** if your live design is the one ahead. | After you stop a test, a shopper who already had a page open may still see their design for up to two hours. While a design is in a running test, you cannot edit it in Studio. Edit a copy instead, or pause and end the test first. ## Know when you have a winner The better design is the one where a bigger share of orders added a plan. Only orders with a product that a plan can cover are counted. These numbers are measured on Shopify only. The results page tells you where the test stands in one line: | You see | What it means | What to do | | --- | --- | --- | | **No winner yet** | Neither design is far enough ahead. | Keep the test running. | | **Early signal** | One design is ahead, but it could still be luck. | Keep the test running. Do not decide on this alone. | | **Clear winner** | One design is ahead and it is not luck. The lead is shown in points. | Make it live. If your live design won, keep it. | Only trust a result that says **Clear winner**. It shows up when both designs have had enough orders, and the gap between them is too big to be luck. Early in a test, one design can look far ahead just by chance. That is why it is shown as an **Early signal** and not as a result. Your live design can win too. If the new design does clearly worse, the result is that your current design stays the better one. In the **Designs** tab, each design shows the result of its latest test, for example **Won 4.6% vs 4.2%**, **Lost …** or **Tie …**. While a test runs, it shows **Testing · … so far**. You also see the plan money brought in per order that could have had a plan. Two designs can get the same share of orders to add a plan, while one sells more expensive plans. See [Design performance](/merchant-portal/design-performance) for that view and for what each result message means. ## Which design each shopper sees Each shopper keeps seeing the same design, on every page and every visit, for as long as the test runs. Each order counts for the design that shopper saw, so the two sets of results never mix. ## See results and past tests Click **View results** to open a test's own page. It shows: - the one-line result - a box for each design with its share of orders that added a plan, plans sold and revenue - a chart over time, which you can switch between those three figures - the **Pause**, **Stop** and **Promote winner** buttons When a test has ended and the new design won, the card shows **Publish `design`** so you can make it live straight away. Older tests are listed under the current one. Each design's card keeps the result of its latest test. If a card says **A test was set up but never started**, nothing is running and every shopper sees your live design. Starting a new test clears it. On Shopify, the protection plan line in the cart carries a hidden value that links the order to the design the shopper saw. A custom cart or checkout must leave it in place. See [Cart line-item properties](/frontend-widget-integration/frontend-widget-kit/javascript-injection#cart-line-item-properties). ## Related Make and change the designs you test. See how each design is doing and what the result messages mean. --- # Developers: API keys and playground Source: https://docs.surebright.com/merchant-portal/developers > Create, name, replace and revoke API keys, try the SureBright API against your store from the portal, and find the pages to send your developer. Use the **Developers** page of the [Merchant Portal](/merchant-portal/overview) when your own systems need to talk to SureBright. Here you create the API key your developer needs, replace or revoke a key, and try a request against your store before any code is written. Developers is **enabled on request**. When it is on, it appears under **Others** in the sidebar and as a **Developers and API** card on Settings. Contact [support@surebright.com](mailto:support@surebright.com) to have it enabled for your store. | You want to | Do this | | --- | --- | | Give your developer access | [Create a key](#create-a-key) and pass it to them securely. | | Replace a key that was lost or shared too widely | Click **Rotate** on the key. | | Cut off a system that should no longer have access | Click **Revoke** on its key. | | See a working request and response | [Try the API from the portal](#try-the-api-from-the-portal). | ## Create and manage API keys An API key lets your own systems call the SureBright API for your store. How the key is used in a request is on [Authentication](/api-reference/authentication). ### Create a key Enter a label (for example **Production server**) and click **Generate new key**. An empty label is saved as **Untitled key**. The **Copy your new API key** dialog shows the full key once. Click **Copy** and store it securely, then **Done**. This is the only time the full key is shown. The list only ever shows a masked version. If you lose a key, rotate it to get a new one. Keys start with `sb_live_`. The list shows each active key's label, its masked value, when it was created and when it was last used (or **Never used**). ### Replace or revoke a key - **Rotate** gives you a replacement key and shows it once, as above. Give the new key to whoever runs the system that uses it. - **Revoke** opens **Revoke this API key?**. Confirm with **Revoke key**. The key stops working immediately, anything still using it starts failing, and it cannot be undone. ## Try the API from the portal The **API playground** sends real requests to your store, so you can see a valid request and response before anyone writes code. 1. Pick an **Endpoint**: - **GET List categories**: the warranty categories set up on your store. No API key needed. - **GET Get a quote (by category)**: plan options for a category and price. Pick a **Category (from your List categories result)**. No API key needed. - **POST Record an order**: creates warranty contracts for an order. **This creates real data**; it appears on your Sales screen. 2. For **Record an order**, enter one of your keys in the **API key** field and edit the prefilled **Request body (JSON)**. The sample order is marked as a test order. 3. Click **Send request**. The **Response** panel shows **Success** or **Error** with the full response. A recorded order confirms **Your order went through** and offers a jump to **Sales**. **Call it from your server** shows the same request as a curl command your developer can reuse; **Copy curl** copies it. It uses the key you entered, or the placeholder `sb_live_YOUR_API_KEY` if none. You do not need the API to put the widget on your storefront. That is set up for you from [Studio](/merchant-portal/studio), which is available on request. See [The storefront scan](/merchant-portal/onboarding#the-storefront-scan). ## Where to send your developer The page ends with links into these docs. Share them with whoever builds the integration: - [API overview](/api-reference/introduction) - [Authentication](/api-reference/authentication) - [Record an order](/api-reference/endpoint/order/create-contract) - [Get a quote](/api-reference/endpoint/quote/list-warranty-quotes-by-category) --- # Fulfillment Source: https://docs.surebright.com/merchant-portal/fulfillment > For stores whose plans start when the order ships: see which orders are still waiting on a shipment, find an order, and decide whether coverage should start at sale or at shipment. Most stores have a plan in place the moment it is paid for. If you ship weeks or months after payment, a pre-order store for example, your plans can instead start on the day the product ships. The **Fulfillment** tab, in the [Merchant Portal](/merchant-portal/overview), is for those stores. It lists every order that bought a plan and shows, per order, how many plans have started, how many are still waiting on a shipment, and how many were cancelled. The tab is available on request for Shopify and BigCommerce stores. SureBright sets when your plans start for the whole store; ask your SureBright contact to change it. The dating rules are on [When coverage starts](/contracts/effective-dates). ## Choose when coverage starts: sale or shipment | | Coverage starts at sale | Coverage starts at shipment | |---|---|---| | Coverage starts | From the purchase (adjusted for the plan type, see [When coverage starts](/contracts/effective-dates#ordinary-orders-cover-dated-from-the-purchase)) | From the day the product ships | | Customer email at checkout | **Plan confirmation** with the contract number and terms | **Order received**, saying coverage begins on the day the order ships | | Customer email at shipment | None | **Plan confirmation**, once the shipment sets the dates | | Until the product ships | Nothing is pending | The plan has no dates yet and shows as pending. Billing does not wait for the shipment | | A shipment is cancelled | No effect | The plan goes back to waiting for the re-shipment. It is not cancelled | | Several units ship separately | One contract per unit, all dated at sale | Each shipment starts only the units it contains | Choose shipment when your customers would otherwise receive a confirmation for coverage on a product they do not have yet, or when a term counted from the sale would run out part of the way into the product's life. Choose sale when products ship promptly. The setting applies to the whole store. The two customer emails are described on [Emails your customers receive](/customer-emails/overview). On the Sales dashboard, stores whose plans start at shipment also see a note under **Overall Stats** explaining why activated figures run behind sold ones (see [Sales](/merchant-portal/sales#if-your-plans-start-when-the-order-ships)). ## See how many plans are waiting Four cards across the top, each a filter you can click: | Card | Counts | |---|---| | **Warranties sold** | Plans bought on the orders in view | | **Fulfilled** | Plans that are active because the product shipped | | **Pending fulfillment** | Plans sold but not yet fulfilled or cancelled | | **Cancelled** | Plans that were cancelled | Clicking **Fulfilled**, **Pending fulfillment** or **Cancelled** narrows the list to orders with at least one plan in that state; clicking it again clears the filter. ## Find an order - **Search by order number or customer**. - The status dropdown offers **All warranties**, **Fulfilled**, **Pending fulfillment** and **Cancelled**, the same filter as the cards. - **From** and **To** limit the list by order date. The end date is included. - **Clear** removes every filter. A note under the toolbar reminds you that plans start once an order ships through an authorized carrier, and that the counts depend on the period you selected. | Column | Meaning | |---|---| | **Order #** | The platform order number | | **Customer** | The customer's name | | **Order date** | When the order was placed | | **Sold** | Plans on the order | | **Fulfilled** | Plans that are active | | **Pending** | Plans still waiting on a shipment | | **Cancelled** | Plans that were cancelled | Click a row to expand it. It repeats the order date and lists each plan with **Product**, **Policy purchased** (the plan and its price), **Coverage** (the term, for example *3 years*) and **Fulfillment / Warranty status**: **Fulfilled** with the fulfillment date, **Fulfillment pending**, or **Cancelled**. The list shows 50 orders per page with **Previous** and **Next** controls. An empty list reads **No warranty orders yet** or, with filters on, **No orders match your filters**. ## What to do about a pending order Ship the product and record the fulfillment in your platform as usual. The plan starts by itself once the fulfillment is recorded; there is nothing to do in SureBright. If an order has been pending for far longer than your shipping lead time, check that the fulfillment was recorded against the order and that the shipping carrier is one SureBright recognises. [Warranty Intelligence](/merchant-portal/warranty-intelligence#orders-missing-contracts) lists orders whose plan is held up by something other than an unshipped product. ## Related How start and end dates are set for each kind of order. The confirmation emails at checkout and at shipment. --- # Pricing, margins and invoices Source: https://docs.surebright.com/merchant-portal/how-billing-works > Who collects the plan price, what you keep, what SureBright invoices you and when, how you pay, and how refunds, credits, currency and fees show up. This page answers the money questions about selling protection plans: who takes the shopper's payment, what you keep, what SureBright bills you, and what to do when a figure needs checking. The screens themselves are covered in [Billing](/merchant-portal/billing), [Invoice analysis](/merchant-portal/invoice-analysis) and [Payment reconciliation](/merchant-portal/payment-reconciliation). ## What you can do | You want to | Do this | |---|---| | See what you kept and what you owe on one order | **Billing → Billing History**, open the invoice, click the order number. It shows **Total Warranty Price**, **Your Margin** and **Net to SureBright** | | Change the card or bank account you are charged on | **Billing → Payment Methods**, then **Set To Default** on the method you want. See [Payment methods](/merchant-portal/payment-methods) | | Check an invoice against what you sold | Open the invoice and click **Analyse →**. See [Invoice analysis](/merchant-portal/invoice-analysis) | | Give your accountant the paperwork | **Download PDF** on the invoice, and **Download Billed Orders** for a CSV of every billed order | | Change what shoppers pay for a plan | [Warranty Pricing](/merchant-portal/warranty-pricing), available on request | | Refund a shopper for a plan | Refund it in your own store, or cancel the sale from **Sales History** on the POS portal. SureBright's part comes back on your next invoice without a request | | Understand a charge, a credit or a line you do not recognise | [Payment questions](/merchant-portal/payment-questions) | | Know whether there are other fees | [What SureBright charges you](#what-surebright-charges-you) | | Offer a plan at a discount, or free | [Discounted and free plans](#discounted-and-free-plans) | | Question a figure you cannot trace | Write to [support@surebright.com](mailto:support@surebright.com) with the invoice number | ## Who collects the shopper's money | Where the plan is sold | Who takes the payment | What SureBright does | |---|---|---| | Your online store's checkout, on Shopify and the other connected platforms | You. The plan is a line item in your own checkout | Invoices you the net amount | | Draft orders and [post-purchase offer links](/post-purchase/offer-links) | You. The plan is paid for as an order on your own store | Invoices you the net amount | | The [POS portal](/pos/overview) | You. **Record Sale** records the plan and does not take the customer's payment, so you collect the plan price with the sale | Invoices your account the net amount | ## What you keep Every plan has three figures, shown side by side on any billed order: | Figure | What it is | |---|---| | **Total Warranty Price** | What the shopper paid you for the plan | | **Your Margin** | Your share. You keep it | | **Net to SureBright** | The difference. This is what the invoice charges you | Sales pages show the same three as **Total Revenue**, **Margin** and **Warranty Cost**. Your share is agreed with SureBright when you join. To see it, open any billed order: **Your Margin** next to **Total Warranty Price** shows it in money. Your SureBright contact can confirm the agreed share. If you set your own plan prices in [Warranty Pricing](/merchant-portal/warranty-pricing), pricing a plan below the SureBright base price gives up part of your own share on it. The page warns you with **Heads up** before you publish, and refuses a price under the floor. ## What SureBright charges you For standard integrations there is no setup fee, no monthly or subscription fee and no minimum commitment. The only thing SureBright invoices you for is its share of the plans you sold (**Net to SureBright**), less refunds and credits. If your store needs a custom implementation, any cost for it is agreed with you before work starts. The one other line you may see is the [card processing fee](/merchant-portal/payment-methods#the-card-processing-fee), on accounts where it applies, which you can avoid by paying from a bank account. ### Why SureBright bills you directly, not through Shopify Shopify app charges suit a fixed monthly price. SureBright's charge is a share of each plan you sell, at prices that can differ per plan and per product, and plans can be sold outside your online store too, for example at your counter on the [POS portal](/pos/overview) or on other platforms. One SureBright invoice covers all of them, so SureBright bills you directly rather than through your platform's app billing. ## Discounted and free plans If you give a shopper money off a plan, or a plan for free, your store funds the discount. SureBright invoices the plan at its normal price, as if the shopper had paid in full, and the plan covers the customer in the same way. This is the same for a [recovery offer](/abandoned-cart-guide/abandoned-cart) code, a discount code of your own, or a plan you add at no charge. To lower the price every shopper pays instead, change the plan price in [Warranty Pricing](/merchant-portal/warranty-pricing). There, a price under the SureBright base price comes out of your own share, and the page warns you before you publish. ## When you are invoiced - **Once a month.** SureBright invoices you at the start of the month for the plans that became billable since your last invoice, and charges it to your payment method. Each invoice shows the period it covers. Some accounts are billed on a different schedule by arrangement. See [The billing cycle](/merchant-portal/invoices-and-charges#the-billing-cycle). - **One invoice per type.** If you sell both, you get one **Product Protection** and one **Shipping Protection** invoice per cycle. - **Late plans roll over.** A plan that was not ready when the invoice was cut is still fully active for the customer. It appears on your next invoice as a carryover charge. You do not need to do anything. ## How you pay Keep a credit card, debit card or bank account on file. A bank account may need to be verified before it can be used. See [Payment methods](/merchant-portal/payment-methods). | Your account | What happens | |---|---| | Payment method on file | The invoice is charged to your default payment method. Any credit left from an earlier invoice is used first. Once the payment is confirmed, the invoice reads **Processed** and the PDF is emailed to you | | Invoiced without an automatic charge | You pay by wire or bank transfer. The invoice reads **Pending** until SureBright records the payment. The PDF shows a **DUE DATE** 15 days after the **GENERATED DATE**, and the bank details to pay to. Ask your SureBright contact if you want to pay this way. See [Pay by invoice instead](/merchant-portal/payment-methods#pay-by-invoice-instead) | If a charge fails, the plans on that invoice are billed again on a later invoice. Update your default payment method, then ask support to run the charge. See [Invoices and charges](/merchant-portal/invoices-and-charges) and [Payment questions](/merchant-portal/payment-questions). ## Refunds, cancellations and credits You collected the plan price, so the shopper's refund goes through your store. SureBright then returns its part on an invoice. You never have to request it. | What happened | What you see | |---|---| | A plan was cancelled before it was billed | Nothing. It is never charged | | A plan was cancelled after it was billed | A **Refund for Cancellations** line on your next invoice, for what you were charged | | An order was charged for more plans than it bought | SureBright cancels the extras. The charge returns as a credit on next month's invoice | | SureBright gave you an adjustment | A **Credits** row on the invoice. On the PDF it is a named row above **Sub total** | | Refunds and credits came to more than the charges | A negative invoice total. The PDF notes a **Credit balance**, which is taken off your next invoice automatically | A refund is listed under the month the plan was sold, not the month it was cancelled. ## Which currency you are billed in You are invoiced in your store's currency, as set on your store platform. Each invoice is in one currency, and the PDF writes Canadian dollar amounts as `CA$`. If you sell in more than one currency through Shopify Markets, read [Shopify Markets pricing](/shopify/markets): a plan priced in one currency and paid in another is not billed until SureBright has reconciled the amounts. ## Tax and fees on your invoice **Tax.** Your SureBright invoice is the bill for SureBright's share of the plans you sold. The tax your shoppers pay on a plan, if any, is charged by your store. For any question about tax on SureBright's invoice to you, such as a tax breakdown or SureBright's tax registration details, ask your SureBright contact. See [Tax on protection plans](/learn/tax). **Fees.** On accounts where a card fee applies, the invoice PDF shows a **Payment Gateway Fee** row between **Sub total** and **Total due**, labelled with its rate, for example **Payment Gateway Fee (2.9% + 30 cents)**. The row is part of the invoice total, so **Total due** on the PDF matches the **net amount** in the portal. Paying from a bank account avoids it. See [The card processing fee](/merchant-portal/payment-methods#the-card-processing-fee). This page describes what the invoice shows. For how to treat plan sales and SureBright's charges in your own books, ask your accountant. ## What you are billed for shipping protection Shipping protection is billed per order, on its own **Shipping Protection** invoice. You are billed only for orders where the shopper bought SureBright Shipping Protection and the shipment was covered. | The order | Billed? | | --- | --- | | The shopper bought SureBright Shipping Protection and the shipment was covered | Yes | | No cover could be created, for example the shipment went outside the United States or had no eligible items | No. The shopper's fee is refunded. See [Orders that cannot be covered](/shipping-protection/overview#orders-that-cannot-be-covered) | | The shipment's carrier could not be matched and your store is set to refund the fee | No. No cover is created | | The order came from a channel where SureBright's offer was not shown, or the shopper bought another provider's protection | Only a SureBright Shipping Protection line from the SureBright offer is billed | To check, open the shipping invoice: **Orders in this invoice** lists every order you were billed for. If you want to pay for shipping protection on every order yourself, rather than offering it to shoppers, ask your SureBright contact. ## Test orders are not billed Plans on a test store, and plans from an order marked as a test, are not billed. Playground orders carry a **Test** tag in **Recent Sales** so you can tell them apart. ## Related Payment methods, Billing History and the invoice detail page. Close a month from one invoice and trace every figure. Why an invoice and Sales can differ, and what happens about it. Payment methods per store and invoices in the POS portal. --- # Invoice analysis Source: https://docs.surebright.com/merchant-portal/invoice-analysis > Close a month from one invoice: read the month-by-month charges and carryover, check the invoice against your sales, look up the plans on it, and understand every figure. Use this page when you close a month. Starting from one invoice in the [Merchant Portal](/merchant-portal/overview) you can see what it charged and refunded month by month, confirm it against what you sold, look up any plan or order on it, and download the PDF for your accounts. The routine covers **Product Protection** invoices. Shipping Protection invoices have the same page and **Monthly Activity** but no reconciliation lists, because shipping protection is billed per order. ## What an invoice covers Each invoice bills the plans that were ready to bill on the day it was generated, takes off the cancellations that were ready to refund, and leaves everything else for the next invoice. | Question | Answer | |---|---| | Which dates does it cover? | From the day your previous **Processed** invoice of the same type was generated to the day this one was generated. A **Pending** invoice still starts at your last paid invoice, even if an older invoice is unpaid. Your first invoice has no start date, so all of it counts as the current period | | When is a plan billed? | Once the plan is complete and the amount you owe for it is fixed: the plan price minus your margin. A plan on a **Processed** invoice is never billed again | | What is carryover? | A plan on this invoice whose order date is on or before the period start. It became ready to bill after your previous invoice was issued. Refunds are split the same way | | When is a cancellation refunded? | You get back what you were charged, on the first invoice generated after the cancellation is ready to refund | Charges and refunds are shown under the month of the plan's order date, not the date it was billed or cancelled. A refund for a plan sold in March appears under March even if the cancellation happened in June. ## Close a month, step by step Go to **Billing → Billing History**. Unpaid invoices are pinned above paid ones, and only the latest **Pending** invoice is listed because it replaces any older unpaid one. Click the row to expand it. The expanded row shows **How this invoice was generated**, then either **All warranties from this period are accounted for on this invoice.** or two counts, **Missing from Invoice** and **Late Cancellations**, each with a note on what happens next. While the counts load it reads **Checking reconciliation against Sales…**. On the right is the **Net Amount Calculation** and **View full invoice details →**. Check the status pill (**Processed**, **Pending** or **Failed**), the **Invoice** number, the period, the type and the **net amount**. The **Invoice breakdown** bar shows **Charges**, **Refund for Cancellations** and **Credits** as shares of the invoice. **Activity** lists **Invoice generated**, **Awaiting payment** (or **Charge attempt failed**), the charge step and **Settled**, then **Charged to**. **Charges** and **Refund for Cancellations** each appear once for the **current cycle** and, when there is any, once more as **carryover**. **Credits** are subtracted last. The final line is **Net amount charged** on a processed invoice and **Net amount to be charged** on a pending one. A row with a zero count is greyed out. **Monthly Activity** lists each month in the period under **Current invoice period**, most recent first, with a blue bar for charges (**N · $X**) and a red bar for refunds (**N · -$X**). An empty month reads **no activity**. Bars share one scale, so months are comparable at a glance. **Carryover from past periods** groups older plans by the invoice whose period they were sold in: **Invoice #…** with that invoice's period and the group's net, then the same month rows in grey. Plans older than any invoice on record sit under **Older than tracked invoices**. The month containing the period start can appear in both sections, once for each side of the boundary. **Analyse →** sits next to **Current invoice period**. It opens Sales with a **Custom** range set to the invoice period and a banner, **Showing analysis for invoice #…**, with **← Back to Invoice** and **Clear filter**. A second banner compares Sales with the invoice: - **All warranties from this period are accounted for.** The two totals match. - **N warranties are pending invoicing · $X**: you sold more than the invoice billed. These plans are active and appear on your next invoice. - **N warranties cancelled after billing · refund of $X**: the invoice billed more than Sales now shows. The amount is credited on your next invoice. A separate red alert, **N duplicate contracts across N orders**, appears only when an order carries more contracts than the plans it bought. [Payment reconciliation](/merchant-portal/payment-reconciliation) explains each banner in full. Click **View details →** (or **Review duplicates →**) to open the **Reconciliation Check**: three tabs, **Missing from invoice**, **Late Cancellations** and **Duplicate Contracts**, each with its count and its own **Download CSV**. Files are named `reconciliation---.csv`. The tabs are described on [Payment reconciliation](/merchant-portal/payment-reconciliation#see-the-plans-behind-each-number). Back on the invoice, **Check Contracts →** opens **Sales → Recent sales** with the banner **Showing warranties for invoice #…**, the date filter set to the invoice period and the list limited to this invoice's contracts. Use it to look up one order or customer, or **Download** the list. **Warranties in this invoice** at the foot of the invoice page lists the same contracts. Click **← Back to Invoice**, then **Download PDF** for your accounts. If the invoice is **Pending** and you have no payment method on file, add one under [Billing](/merchant-portal/billing#payment-methods). ## What to do with each finding | Finding | What it means | Your action | |---|---|---| | **All warranties from this period are accounted for** | Sales and the invoice agree within one dollar | None | | **Missing from invoice** | Sold in the period, not yet billed; coverage is active | None. They appear as **Charges · carryover** on the next invoice, grouped under this invoice's number | | **Late Cancellations** | Billed here, cancelled since | None. They appear as **Refund for Cancellations · carryover** on the next invoice | | **Duplicate Contracts** | An order was charged for more contracts than it bought | None. SureBright cancels the **Duplicate** rows and the charge returns as a credit on next month's invoice | | **N orders have duplicates; showing the N with the largest overcharge** | More than 100 orders are affected | The CSV covers the same orders; contact support for the rest | Timing differences never need a ticket. Contact support only for a figure you cannot explain with the tables below, for example a **Charges** count that does not match **Warranties in this invoice**. ## What each figure on the invoice means Use these tables when you need to explain a number to your accountant or check one yourself. ### Status, period and net amount | Figure | What it means | |---|---| | Status pill | **Failed** when the last attempt to charge you failed; **Processed** when paid; otherwise **Pending** | | Period and **N days** | The period described under [What an invoice covers](#what-an-invoice-covers). Days are rounded, with a minimum of one. Your first invoice shows no day count | | **net amount** | The invoice total. A negative total is a credit balance that goes towards your next invoice | | **Invoice breakdown** | Each segment is that item's share of charges, refunds and credits added together | | **N contracts billed** | The number of charges plus the number of refunds | ### Charges, refunds and credits For one plan, the amount is the plan price minus your margin. Elsewhere in the portal this is the **Warranty Cost** column. | Row in **Net Amount Calculation** | Which plans it counts | |---|---| | **Charges · current cycle** | Plans charged on this invoice whose order date is after the period start | | **Charges · carryover** | Plans charged on this invoice whose order date is on or before the period start. Hidden when zero | | **Refund for Cancellations · current cycle** | Refunds for plans whose order date is after the period start | | **Refund for Cancellations · carryover** | Refunds for plans whose order date is on or before the period start. Hidden when zero | | **Credits** | Adjustments applied to the whole invoice; the count is the number of adjustments. On the PDF they appear as named rows above **Sub total** | | **Net amount charged / to be charged** | The invoice total. The PDF may also show a **Payment Gateway Fee** where it applies; that line is on the PDF only | ### Months and carryover groups | In **Monthly Activity** | What it means | |---|---| | A month row | The month of the plan's order date. Months follow UTC | | **Current invoice period** | Every month from the start of the period to its end, including months with no activity, with this period's charges and refunds | | **Carryover from past periods** | Carryover charges and refunds, shown by month in the same way | | **Invoice #…** group | Carryover plans sold during that earlier invoice's period, with that invoice's period and the group's net (charges minus refunds) | | **Older than tracked invoices** | Carryover plans sold before any invoice on record. Shown last. An earlier invoice with no number yet reads **Invoice from** followed by the date | ### When Sales and the invoice count as matching | Figure | What it means | |---|---| | Sales total | What shoppers paid minus your margin, for plans ordered in the period that are not cancelled | | Invoice total | This period's charges minus this period's refunds. Carryover is left out, so it never causes a difference | | A match | The two totals differ by one dollar or less | | **N warranties are pending invoicing · $X** | Sales is higher by more than one dollar. N is the **Missing from invoice** count | | **N warranties cancelled after billing · refund of $X** | The invoice is higher by more than one dollar. N is the **Late Cancellations** count | ### Which plans each Reconciliation Check tab lists | Tab | Which plans | |---|---| | **Missing from invoice** | Ordered inside the period, not on this invoice, and not cancelled. A plan cancelled before it was ever billed is left out because there is nothing to charge | | **Late Cancellations** | Charged on this invoice and cancelled since. Plans already refunded on this invoice, and plans cancelled as duplicates, are left out | | **Duplicate Contracts** | Every order this invoice charged, compared plan by plan: plans bought against contracts created. A plan that is still being set up counts as pending, not as a duplicate. At most 100 orders are shown, largest overcharge first | In the first two tabs **Status** is **Active**, **Cancelled** or **Pending**; **Total Revenue** is what the shopper paid, **Margin** is your share and **Warranty Cost** is the difference, which is what the invoice charges. Their CSVs add **Order ID**, **Contract ID**, **Fulfillment Stage** and **Cancellation Reason** to the on-screen columns. In **Duplicate Contracts**, **Overcharged** is what this invoice charged for the extras; when some extras were billed on another invoice the chip reads **Extra cost** with their full value. ## Related Payment methods, Billing History and the invoice page. What each banner and tab means and what happens about it. --- # Invoices and charges Source: https://docs.surebright.com/merchant-portal/invoices-and-charges > When SureBright charges you, what happens between the invoice and the payment, what each line on an invoice is, and how invoices and receipts reach you. This page follows one invoice from the day it is issued to the day it is paid, and explains every kind of line you can find on it. | You want to know | Go to | | --- | --- | | When you will be charged | [The billing cycle](#the-billing-cycle) | | Why a bank payment shows at your bank before the invoice arrives | [Bank payments take a few days](#bank-payments-take-a-few-days) | | What a line on your invoice is | [What you can find on an invoice](#what-you-can-find-on-an-invoice) | | Where your invoice was emailed | [How invoices reach you](#how-invoices-reach-you) | | Whether an invoice is a bill or a payout | [Is this a bill or a payment to us?](#is-this-a-bill-or-a-payment-to-us) | | When your first invoice arrives | [Your first invoice](#your-first-invoice) | | Whether you can get an invoice now, outside the monthly cycle | [Ask for an invoice outside the cycle](#ask-for-an-invoice-outside-the-cycle) | | How to change the name or address on your invoices | [The name and address on your invoice](#the-name-and-address-on-your-invoice) | | How to pay an invoice by bank transfer | [If you are invoiced without an automatic charge](#if-you-are-invoiced-without-an-automatic-charge) | | Whether your payment arrived and was applied | [Check that a payment was received](#check-that-a-payment-was-received) | ## The billing cycle SureBright invoices you once a month, at the start of the month, for the plans that became billable since your last invoice. Product protection and shipping protection are invoiced separately, so a store that sells both gets two invoices and two charges. Any credit balance on your account is used first. The rest is charged to your [default payment method](/merchant-portal/payment-methods), in your store's currency. A card payment is confirmed within minutes. A bank payment takes several business days. Once the payment is confirmed, the invoice reads **Processed** in **Billing → Billing History** and SureBright emails you the invoice PDF. The invoice is generated at the start of the month, before the charge runs, so you can see it as **Pending** in **Billing → Billing History**, and check it, before your method is charged. The invoice email only arrives after the payment is confirmed. Some accounts are billed on a different schedule by arrangement. Each invoice states the period it covers. If you need a different billing day, ask your SureBright contact. ### Is this a bill or a payment to us? A SureBright invoice is always a bill you pay. You collected the full plan price from your shoppers, so SureBright never sends you a payout for plan sales. The invoice charges you SureBright's share of the plans you sold, less any refunds and credits. See [How the money works](/merchant-portal/how-billing-works#who-collects-the-shoppers-money). ### Your first invoice Your first invoice comes at the start of the month after your first plans become ready to bill. Add a payment method before you go live so it can be paid. See [Payment methods](/merchant-portal/payment-methods#until-you-add-a-payment-method). ### Ask for an invoice outside the cycle If you want an invoice now, for example because you have not received one or you want to settle everything sold so far, email support. SureBright can issue an invoice for every plan that is ready to bill and not yet invoiced, with any cancellations taken off. ### Which plans are on this month's invoice A plan is invoiced once it is ready to bill, which is not always the month it was sold. - A plan sold near the end of a month can land on the following invoice. - On stores where coverage starts when the order ships, a plan is not billed until the product has shipped. - A plan that was held up, for example because the product it covers could not be identified, is billed once that is resolved. It then appears on a later invoice with its original order date. These are first-time charges, not repeats. To check a plan, open the invoice and use **Find a plan or an order on an invoice** on the [Billing](/merchant-portal/billing#find-a-plan-or-an-order-on-an-invoice) page, or download **Billed Orders**. ### Bank payments take a few days A bank payment leaves your account before SureBright receives confirmation of it. For a few business days you may see the debit at your bank while the invoice has not yet been emailed and is not yet shown as **Processed**. Nothing is wrong. The invoice email follows as soon as the payment is confirmed. ## What each status means | Status | Where you see it | What it means | | --- | --- | --- | | **Processed** | Billing History and the invoice page | The invoice is paid. | | **Pending** | Billing History and the invoice page | The invoice is issued and not yet paid. | | **Failed** | The invoice page | A charge was attempted and did not go through. See [Payment questions](/merchant-portal/payment-questions#my-charge-failed). | The invoice PDF carries the same three as **PAID**, **PENDING** and **FAILED**. ## What you can find on an invoice | Line | What it is | | --- | --- | | **Charges** | Plans billed for the first time. Each is charged at the plan price less your margin. | | Carryover charges | Plans from an earlier month that were not ready when that month's invoice was issued. | | **Refund for Cancellations** | Money back for plans you were charged for earlier and that have since been cancelled. | | **Credits** | An adjustment SureBright has applied to your account, named on the PDF. | | An order marked **(Previous Invoice Adjustment)** | A correction to a plan that was billed on an earlier invoice. A positive amount means the plan was billed for less than it should have been. A negative amount is money back. It is not a second charge for the plan. | | **Payment Gateway Fee** | The card processing fee, on accounts where it applies. The row names the rate. See [The card processing fee](/merchant-portal/payment-methods#the-card-processing-fee). | If refunds and credits add up to more than the charges, the invoice total is negative. Nothing is paid back to your card or bank. The amount stays on your account as a credit balance and is taken off your next invoice automatically. For a line-by-line walk through a real month, see [Invoice analysis](/merchant-portal/invoice-analysis). ## How invoices reach you | What | Where | | --- | --- | | The invoice email | Sent from support@surebright.com once the payment is confirmed, with the PDF attached. It goes to the contact email of your store. | | Invoice PDFs | **Billing → Billing History**, the download icon on each row, or **Download PDF** on the invoice page. | | Every billed order in one file | **Download Billed Orders** in **Billing**, a CSV with the order behind every charge. | To have invoices sent to a different address, for example your accounts team, email support with the address. It cannot be changed from the portal. ### The name and address on your invoice Under **BILL TO**, the invoice shows the business name and address held on your SureBright account. Under **FROM**, it shows the SureBright company that bills you: SureBright's US company for US dollar invoices, and its Canadian company for Canadian dollar invoices. To change the business name or billing address printed on your invoices, email support with the legal name and full address you want. Say whether past invoices need to be reissued as well. ## If you are invoiced without an automatic charge Some accounts are invoiced and pay by bank transfer instead of being charged automatically. You can ask your SureBright contact to be set up this way. Your invoice then reads **Pending** until SureBright records the payment. It shows a **DUE DATE**, 15 days after the **GENERATED DATE**, and the bank details to pay to: domestic wire and ACH transfer details, and international wire details. Pay the amount shown as **Total due**, in the invoice currency. For invoices from SureBright's US company, international wires must be sent in US dollars. Put the invoice number in the payment reference. If you pay several invoices in one transfer, list every invoice number. Email support once you have paid, with the invoice numbers, the amount and the date sent, so the payment is matched quickly. If you are charged automatically, you do not need to send a transfer as well. Pay the exact invoice total. Do not take off plans that were cancelled after the invoice was issued. Those come back to you as **Refund for Cancellations** on your next invoice, so deducting them yourself leaves the invoice short. See [Payment questions](/merchant-portal/payment-questions#can-we-deduct-cancellations-from-this-payment). ## Check that a payment was received | Your situation | Do this | | --- | --- | | You want to know whether a payment arrived and was applied | Look at the invoice in **Billing → Billing History**. **Processed** means it is paid. If it still reads **Pending** a few business days after your bank sent the money, email support with the invoice number, amount and date sent. | | Your bank or an intermediary bank took a fee, so less arrived than you sent | Email support with the invoice number and your remittance details. Support tells you what was received and whether anything is still owed on the invoice. | | Your payment quoted the wrong invoice number, or no number | Email support with the remittance details and the invoice you meant to pay. SureBright applies the payment to the right invoice and can reissue an invoice that shows it. | | An invoice does not show a payment you already made | Email support with proof of payment. SureBright marks the payment received and can send you a corrected invoice. | | You have more than one SureBright account and want to know what is still open | Each account has its own **Billing History**, with unpaid invoices pinned to the top. To get one statement across all your accounts, email support with the store addresses. | | You want billing emails to go to your accounts team | Email support with the address. See [How invoices reach you](#how-invoices-reach-you). | ## Related Add a card or bank account and choose which one is charged. Failed charges, missing credits, charges you do not recognise and more. Who collects the plan price, what you keep and what SureBright invoices. Check an invoice against what you sold. --- # Leads Source: https://docs.surebright.com/merchant-portal/leads > Add protection plans to past orders or record a manual sale, with the order created and paid on Shopify or Magento. Use **Leads** to sell a protection plan outside your storefront checkout. You can add a plan to a product a customer already bought, or record a sale by hand. The portal creates the order on your platform, where you collect payment. The page lists every order placed on your store as a sales lead. Leads is available on **Shopify** and **Magento** stores. On other platforms the page says the feature is not available for the store and points you to [support@surebright.com](mailto:support@surebright.com). The page header says where payment happens: **The order is created and paid on Shopify** (or **Magento**). ## Find an order to add a plan to | Column | What it shows | | --- | --- | | **Sr. No** | Row number. | | **Date** | Order date. | | **Order** | Order number. | | **Customer** | Name and email. | | **Items** | Number of line items. | | **Total** | Order total. | Use **Search orders by number, customer or product** to find an order. The list is paged (**Previous** / **Next**). ## Add a plan to a past order Click the chevron on a lead. Each line item is listed with its SKU, quantity, price and category. Eligible items load their plan options. Select a plan to see what it covers and a link to its full terms, then click the **Add … plan** button (it names the plan length and price, for example **Add 2 Years plan · $29.99**). Added items are marked **Added to draft order** and collected in the **Draft order** panel at the top of the page. Items that already have protection show **Warranty already added**. ### If an item shows no plan options - **Uncategorized** products show **No Extended Warranty Options Available**. Choose **No, I will categorize the product**, pick a category under **Select Category** and click **Fetch Quotes** to load plans. - Items **Outside the protection-plan window** offer a correction: pick a category (**Select category — it may allow a longer window**) and click **Check plans with this category**, or enter a **Corrected purchase date** and click **Use corrected purchase date**. - Items that are not eligible say why (**Not eligible for a protection plan**). ## Record a manual order Click **+ Record manual order** to sell protection for a product that was not bought through a lead. 1. **Product**: **Search products by name or SKU** and pick the product. If it is not in your catalogue, add the SKU to your store first and allow a few hours for categorisation. 2. **Variant** (when the product has several), **Customer country** (when your store quotes in more than one market) and **Quantity**. 3. Tick **Customer already owns this product (bill the warranty only)** for a warranty-only sale and enter the **Product purchase date**. The date must fall within your store's protection-plan window (30 days by default; the page tells you the limit) and cannot be in the future. 4. Under **Protection plan**, pick a plan and add it. **↻ Refresh price** reloads the latest published prices. Leave the box unticked to sell the product and the plan together in one order. ## Create the draft order The **Draft order · N lines** panel lists every queued line with its plan, price, order number (for leads) and whether it is **warranty only** or **with product**. Remove a line with the bin icon. Totals show **Warranties** and, when products are included, **+ products**. - **Shopify**: click **Create draft order in Shopify**. Customer details are optional here; they are collected at checkout or when you mark the order paid. - **Magento**: for manual items, fill in **Customer details** (**First name**, **Last name**, **Email**) and the **Billing address** (**Street address**, **City**, **State** or **Province**, **ZIP code** or **Postal code**, **Phone**). Magento cannot place the order without them. Then click **Create draft order in Magento**. ## Take payment and activate the plan A **Draft order created** dialog confirms the order, and it joins the **Created draft orders** list on the page. Each card shows a timeline, **Draft created → Awaiting payment → Paid → Contract active**, the lines, totals and links to **Open in Shopify admin** / **Open in Magento admin** and the **Customer invoice link** when there is one. ### Take payment on Shopify - Enter the customer's email and click **Send payment link**. The customer pays through Shopify; the status moves to **Awaiting payment** and the button becomes **Resend payment link**. - If you took payment another way, click **Mark as paid**. Enter the customer's email first so the existing Shopify customer and address are attached to the order. Once the order is paid, the plan becomes active by itself and the card reads **Paid · warranty contract active**. ### Take payment on Magento The card reads **Draft order … created successfully in Magento**. Open the order in the Magento admin, click **Invoice**, review the lines and click **Submit Invoice**. That marks the order paid. The plan becomes active and the timeline updates by itself. On Shopify you can also sell over the phone from inside Shopify's own draft orders. See [Over the Phone Sales using Draft Order Extension](/draft-order-guide/shopify-draft-order). ## Related Every way to sell a plan outside your storefront checkout. See the plans you have sold and their status. --- # Onboarding Source: https://docs.surebright.com/merchant-portal/onboarding > What happens after you install SureBright or sign up, who does what before you go live, what to do when a pop-up or setup screen is in the way, and how the storefront scan builds your first widget design. This page answers "I have installed SureBright: what happens now?". It walks through the path from install to your first protected sale, says who does each step, explains the pop-up and screens you meet on the way, and then covers the storefront scan that builds your first widget design. ## After you install: the path to going live Every new store follows the same path. SureBright does most of the setup on its side. Your part is a call, a payment method, switching the offer on and a test order. | Step | Who | What happens | Where you see it | |---|---|---|---| | 1. Install or sign up | You | Install the SureBright app or plugin for your platform, or sign up with SureBright. | [Supported platforms](/platforms/overview) | | 2. Confirm your contact details | You | The first time you open the portal, a pop-up asks you to confirm the email address and phone number SureBright should use. | [The pop-up after you install](#the-pop-up-after-you-install) | | 3. Onboarding call | You and SureBright | Every new store goes through an onboarding call before it goes live. Book it from **Book a Call**. On the call SureBright goes through which products can be covered, plan prices and your share, and how the offer will look. | The **Book a Call** prompt at the top of the portal | | 4. Review and set-up | SureBright | SureBright reviews your store, sets up the categories and plan prices for your catalogue, and prepares the offer for your storefront. | Your store card reads **In review** | | 5. Approve the design | You | In [Studio](/merchant-portal/studio), where it is enabled for your store, the [storefront scan](#the-storefront-scan) builds a design for you to review. Otherwise SureBright shares the design with you for approval, and can show you other layouts to choose from. | Studio, or your SureBright contact | | 6. Add a payment method | You | SureBright bills you for the plans you sell. Add a card or bank account before you sell your first plan. | [Payment methods](/merchant-portal/payment-methods) | | 7. Switch the offer on | You | On Shopify, turn the SureBright Offering embed on in your live theme. On other platforms, follow your platform guide. | [Storefront setup](/shopify/storefront-setup) | | 8. Test | You | Run one order from the offer to the cancellation. | [Test your setup](/platforms/test-your-setup) | | 9. Go live | SureBright | SureBright approves the store and the offer shows to shoppers. | Your store card reads **Live** | How long going live takes depends on how quickly the call is booked and the design approved. Your SureBright contact can give you a date once the call is done. If you want to start on a few products first, see [Start with a few products](/platforms/test-your-setup#start-with-a-few-products). ### Why the portal looks empty while you are in review - **Products** opens on **Warranty Inactive**, because nothing is offered yet. Your products and their categories are still being set up. See [Products](/merchant-portal/products). - A store that has not connected a storefront sees only **Sales**, so you can watch your first test order arrive. - No offer shows on your storefront until the store is **Live** and the offer is switched on in your theme. None of this needs action from you. If the store has been **In review** for longer than you expected, reply to your onboarding email or write to [support@surebright.com](mailto:support@surebright.com). ## The pop-up after you install While your store is **In review**, the portal opens a pop-up headed **Congratulations! Your installation of the SureBright app was successful**. It asks you to **Please confirm your contact details**, with your **Email Id** and **Phone Number**. | You want to | Do this | |---|---| | Confirm your details | Check them, complete the form and click **Update**. The pop-up then says someone from SureBright will reach out within 48 hours. | | Book the onboarding call | Click **Book a Call** in the pop-up and pick a time. Once booked, the pop-up shows the date of your call. | | Get past the pop-up to the portal | Click the close icon in its top-right corner. The pop-up comes back each time you open the portal until your store is **Live**. The **Book a Call** button stays at the top of the page. | | Change your details later | Click **Edit** in the pop-up, or see [Settings](/merchant-portal/settings#update-your-contact-details). | The first time you sign in you may also see a short introduction of a few screens. Click **Skip** to go straight to the portal. ## When you cannot get in If Shopify returns you to a page reading **Bad Install.**, the installation could not be completed at that moment. Try again a little later. If it keeps failing, or the app does not install at all, email [support@surebright.com](mailto:support@surebright.com) with your store URL (for example `mystore.myshopify.com`) and what you saw. The page reads **Something went wrong** with **Try again** and **Sign out**. You are still signed in: the portal could not load your store's details. Click **Try again**. If it happens again, email [support@surebright.com](mailto:support@surebright.com) with your store URL and the **Reference** line at the foot of the page. On Shopify it can mean the app needs a permission you have not approved yet: see [Approve an updated permission request](/platforms/store-access#approve-an-updated-permission-request). If an agency is opening the app for you, see [Agencies and developers](/platforms/store-access#agencies-and-developers). A reinstall reconnects the same store and puts it back **In review**. If the portal does not open, email [support@surebright.com](mailto:support@surebright.com) with your store URL so SureBright can reactivate it. See [Reinstall the Shopify app](/platforms/pause-or-remove#reinstall-the-shopify-app). See [Collaborator requests from SureBright](/platforms/store-access#collaborator-requests-from-surebright). Never send your store password. ## Questions before you go live ### Is my store eligible? Plans are sold to shoppers in the United States and Canada. See [Languages and regions](/platforms/languages-and-regions#where-plans-are-sold). If your shoppers are all in other countries, SureBright cannot offer them plans yet; your SureBright contact can tell you when that changes. Whether a store is approved is decided by SureBright during review, and a store that is not approved shows **Not approved** on its store card. If you are a new brand, or your store was not approved, ask your SureBright contact what would change the decision. ### Can I offer only one kind of cover on some products? Yes. Which plans a product gets, for example accidental damage only for products that already carry a long manufacturer warranty, is set by SureBright per category or brand. Tell your SureBright contact which products or brands, and which kind of cover you want on them. See [Dual coverage](/shopify/dual-coverage) for how products with both kinds look. ### Can I launch on one store and add my others later? Yes. Each store is installed and reviewed on its own, so you can go live on one and add the next when you are ready. Tell your SureBright contact which store comes next, and whether you want the same design and prices. See [Work with more than one store](/merchant-portal/team-and-access#work-with-more-than-one-store). ## The storefront scan The scan is how Studio builds your first widget design, without a developer. SureBright's **store onboarding agent** visits your storefront as a shopper would, reads one product page for your colours, fonts and corner style, and works out where the widget goes on the product page and in the cart. You get a draft design: the widget in your store's colours and fonts, placed on your product page and in your cart. Nothing is added to your storefront's code, and nothing goes live until you publish. The scan starts when you open [Studio](/merchant-portal/studio) on a store that has never published a design. You can run it again later with **New store look?**. Studio is available on request on Shopify; on other platforms, ask your SureBright contact whether it is available for your store. ### Choose the product page to read The set-up screen shows the three steps ahead of you: **Set up**, **Review in editor** and **Publish**. Under **Product page to read**, Studio proposes a product from your catalogue. You can **Search catalogue** for another or **Paste a URL**. Pick a page that looks like the rest of your store. If your storefront is password-protected, enter its password here. Without it the scan cannot read the page. You can also pick a **Starting layout**, which sets how the plans are arranged. Then click **Generate design**. ### What you see while the scan runs The card reads **Building your widget** and ticks off three steps: **Reading your product pages**, **Matching your brand** and **Building your preview**. **View full progress** opens a full-screen view, **Our AI is building your widget**, with a line saying what the scan is doing now. The scan takes a few minutes. You can leave the page: the scan keeps going, and the portal picks it up when you come back, in another tab or after a reload. The scan checks its work against your live storefront: the product page near **Add to cart**, your add-to-cart flow so a chosen plan follows the product into the cart, the cart page, and quantity changes and removals in the cart. It also checks quick-view pop-ups and the cart drawer when your storefront has them. Those two are best effort: a scan can finish without them, and the ready screen then carries a note saying what it could not confirm. ### Review the design when it is ready The heading changes to **Your widget is ready**, with the programs it was built for. Click **Review your design** or **See it on my store →** to open it. You can open and edit the draft as soon as its look and product-page placement are in, while the cart is still being checked. Publishing waits until that check finishes. Reviewing and publishing are described in [Studio](/merchant-portal/studio). Under **While you wait** are things you can do that do not depend on the design: | Card | Marked | Where | | --- | --- | --- | | **Add a payment method** | **Needed to finish setup** | See [Billing](/merchant-portal/billing). | | **Switch on SureBright in your theme** (Shopify stores) | **Needed to show** | See [Settings](/merchant-portal/settings#check-your-shopify-storefront-setup). | | **Check your plan prices** | **Optional** | See [Warranty Pricing](/merchant-portal/warranty-pricing). | The first two cards disappear once they are done. The theme card is for Shopify, where the offer is switched on in the theme editor; on other platforms the offer reaches your storefront through your platform's install guide, listed on [Supported platforms](/platforms/overview). ## Related Review, edit and publish the design the scan built. Confirm the offer, the order and the contract work before you launch. App permissions, collaborator requests and agency access. Add the card or bank account SureBright bills. For developers: the positions the scan works out are the same anchors a developer would set by hand. They are described in [Placements](/frontend-widget-integration/frontend-widget-kit/placements). --- # Order Resolution Source: https://docs.surebright.com/merchant-portal/order-resolution > Find the orders that need a decision from you, answer each case, keep an order for yourself or give yourself more time, and know what SureBright does if nobody answers within 48 hours. **Order Resolution** lists the orders where a protection plan cannot be completed without your answer: which product a plan covers, whether to refund an extra unit, or a customer detail the order never carried. It is available on request. Once SureBright switches it on for your store, **Order Resolution** appears in the [Merchant Portal](/merchant-portal/overview) sidebar with a badge counting the orders waiting on you. | You want to | Do this | | --- | --- | | See what is waiting on you | Open **Order Resolution**. It opens on **Action needed**. | | Deal with the most urgent orders first | Click the **Due soon** chip. | | Answer a case | Open the order, pick an answer on the case card and press **Submit resolution**. | | Stop SureBright deciding for you | Click **I'll handle it**, or **or give me until** a date. | | Tell SureBright something about an order | Use the case's **Comments**. | For what each case means for the plan itself, see [Why a contract is on hold](/contracts/holds). ## Find the orders that need you The page is a list of orders beside the open order. On a phone the open order replaces the list, and the browser Back button returns to it. Above the list, **Search orders** matches the order number, the issue or a note, and a view selector narrows the list: | View | What it lists | |---|---| | **All orders** | Every order with a case, whatever its state | | **Action needed** | Orders waiting on you. This is the default view and what the sidebar badge counts | | **Unassociated warranties** | Orders where a plan could not be tied to a product. Shown only when there are some | | **Submitted** | Orders you have answered and SureBright is still applying | | **Resolved** | Finished | | **Cancelled** | Cases that stopped being relevant, for example because the order changed in your store. Shown only when there are some | Chips under the search box narrow the view further and show how many orders each would leave: - **Due soon** keeps orders SureBright will act on within 12 hours. - **You're handling** keeps orders you have kept for yourself. - One chip per kind of issue: **Product refunded**, **Quantity mismatch**, **Region not covered**, **Product not identified**, **Missing details**, **Shipping** and **Other**. A chip appears only when at least one order in the view matches it. A summary line adds up what is on screen, for example the value of the plans involved and how many orders are due within 12 hours. Each row shows: - how many **days** the order has been waiting (grey for the first two days, amber from day 3, red from day 7); - the order number and, when there is more than one, the count of issues; - the value of the plans at stake; - a one-line summary of the issue, for example *Covered product was refunded*, *Excess warranty bought*, *Cover not available in the customer's region* or *Missing customer email*; - when SureBright will act on its own (**Due now**, **5h left**), or **You're handling** if you have kept it; otherwise the time of the last activity. Orders sort with the soonest deadline first and are grouped under **Action needed**, **Submitted**, **Resolved** and **Cancelled** when more than one state is listed. Press **J** and **K** to step to the next and previous order. The page address keeps the open order, the view and the search term, so you can share a link to a specific order, and a refresh comes back to the same place. ## What you see when you open an order The top of the order names it, shows its position in the list with previous and next arrows, and gives its state (**Awaiting review** once you have submitted, **All resolved** when nothing is open). On Shopify stores a button opens the order in your Shopify admin; other platforms get a link to their order list. Below that: - **Customer**: who bought and when. Region cases also show **Customer country** and **Shipping address**. - **Policies on this order**: each plan with the product it covers, **Covered product price**, **Warranty tenure** and a **Coverage details** link that opens **What's covered** and **Not covered**. - **What the customer bought**: the order's lines. A plan line says what it covers: **Covers a product on this order**, **Covers a product on another order** (see [Plans bought in a later order](/contracts/plans-bought-later)), **External warranty**, or *Nothing recorded yet* when nothing on the line says which product it covers. - One **case card** per issue. Every case card opens with a one-line explanation, for example *We couldn't work out which product on this order this plan was sold against.* The ⓘ beside it expands into **What this means**, **Why it happened** (the specific reason when SureBright knows it, such as *The product it covered was refunded.* or *Priced for CA, the customer is in US.*) and **What happens next**. ## Answer a case Each case card offers the answers it accepts. Pick one, add a **Note (optional)** for SureBright's team if you want, and press **Submit resolution**. When an order has several cases the button submits all of them at once (*Ready to submit 2 answers*). | Case card | What you are asked | |---|---| | **We couldn't identify the product this plan covers** | **Associate product** when the plan has nothing to attach to; **Refund excess units only (N unit(s))** when some units already cover a product; a refund of the plan line, with the most you can refund shown and a custom amount allowed; **Acknowledge: keep the contract, no refund** for some reasons | | **Multiple eligible products** | The products the plan could cover, as cards. Pick the one the customer meant and the plan is completed for it | | **Missing required details** | The missing details themselves: the customer's name, email or address. The form says which, for example *Customer address is required* | | **Shipping carrier not recognized** or **Tracking details missing** | **Select the shipping carrier** or provide the tracking number, or **Refund shipping insurance** | After you submit, the message *Resolution submitted. We'll take it from here.* confirms it, the order stays open so you can see what was sent, and its row moves under **Submitted**. **Next order** jumps to the next order that still needs you. Once your answer has been applied, the card reads *Resolved. This is the response that was submitted.* On stores with Order Resolution switched on, the Sales screens show the same cases as **Action needed** on the affected sales, and you can answer them there in a dialog. The answers and the result are the same as on this page. ### Tell SureBright which product a plan covers Choosing **Associate product** opens a two-part panel: 1. **This warranty covers**: the eligible products on this order, or **Another product from your catalogue**, which you find by name or SKU and, where it applies, a variant. 2. **Warranty the customer bought**: the plan for that product that matches what the customer paid, with its term shown. When you submit, SureBright completes the plan for that product. ### Name a product SureBright cannot identify Some cases have no answer button because SureBright is finishing them itself, but it still needs to know a product only you can name. The card then asks **Which product did the customer buy?**, or, when the plan was priced for a product that is not on the order, shows **Plan was quoted for** beside **This order contains**. Search your catalogue by name or SKU, add anything that helps, and press **Send product details**. The details go to SureBright's team, who attach the plan by hand. ### Leave a comment for SureBright Every case has a **Comments** thread. Use it to tell SureBright anything about the order; the team reads it. A comment does not resolve a case by itself. ## If SureBright cannot refund on your platform Refunds through SureBright are available on Shopify. On other platforms a case whose only outcomes are refunds is shown read-only under **These outcomes can't be issued on your platform**, with each outcome marked **Not available here**. Refund the plan line in your store admin, then press **Tell us what you did**. Where the case offers an answer that is not a refund you can still submit it: - **Acknowledge: handled in my store admin, no SureBright action**. - **End cover on the N extra warranty unit(s), I'll refund the customer myself**. This ends the cover and tells the customer, while the refund stays yours to make. The card says so plainly: *SureBright will not refund the customer.* ## What happens after 48 hours Some cases are safe for SureBright to settle on its own. Today that is a plan whose covered product was refunded, on a Shopify store. A product removed by editing the order, without a refund, is left for you to decide. If nobody answers one of these within 48 hours of it being raised, SureBright settles it, and the default outcome is a refund of the customer's plan. The open order states this in a deadline bar: *SureBright resolves this in 31 hours. If nobody resolves it, SureBright refunds the customer's warranty.* The bar turns amber in the last 12 hours, and the same countdown is the chip on the order's row. You can change that: | Button | Effect | |---|---| | **I'll handle it** | The order is yours. Nothing is settled automatically, and the bar reads *You're handling this order. SureBright won't resolve it. It stays here until you do.* **Hand it back to SureBright** restores the automatic deadline | | **or give me until** a date | Pushes the deadline out by 3, 7 or 14 days. The bar then reads *You pushed this back. Resolve it before then, or SureBright will.* | Either choice applies to every case on the order that has a deadline, so an order is never half kept. Cases without a deadline show no bar; SureBright's team reviews them. A case can also close by itself when the order changes in your store, for example when you refund the plan line there. It then appears under **Cancelled** with the reason shown. Nothing was answered; the case simply no longer applies. ## Related What each hold and case means for the plan. Find any sale and see its current status. --- # Merchant Portal overview Source: https://docs.surebright.com/merchant-portal/overview > What you can do in the SureBright Merchant Portal, how to sign in, what each section is for and where to get help. The Merchant Portal is where you manage SureBright on your store: choose which products offer protection, see what you have sold, check what you are billed, and set up your storefront. ## Sign in to the Merchant Portal The Merchant Portal is at [merchant.surebright.com](https://merchant.surebright.com). How you sign in depends on your platform. | Platform | How you sign in | | --- | --- | | Shopify | Open the Merchant Portal, enter your **Store URL** (for example `mystore.myshopify.com`) and click **Sign in**. Shopify asks you to approve access and then returns you to the portal. | | BigCommerce | Open the SureBright app from your BigCommerce control panel. | | WooCommerce | Open the plugin's **Merchant Portal** page in your WordPress admin and click **Login**. | | Magento | Click **Login Now** on the SureBright page in your Magento admin, then use the credentials SureBright shared with you. | | Other platforms | Use the Store ID and password SureBright shared with you. | The steps for each platform are on [Team and access](/merchant-portal/team-and-access#how-you-sign-in). After signing in you land on **Sales**. If this is your first sign-in, the portal takes you through onboarding first. There are no role settings to manage. To give a colleague access or remove someone, see [Team and access](/merchant-portal/team-and-access). ## What each section is for The menu on the left has two groups, **Analysis** and **Others**, with **Help** pinned at the bottom. Turn protection on or off per product, set categories, and check warranty prices. Not shown on Custom-platform stores. Revenue, margins, policies sold and attach rate, with period comparison and the full list of recent sales. Payment methods, invoices and the breakdown behind every charge. Add protection plans to past orders or record a manual sale. Shopify and Magento stores only. Contact details and store details on every store, storefront setup on Shopify, and order sync on Lightspeed R Series. API keys and an in-page playground. Enabled on request. **Products**, **Sales**, **Billing** and **Leads** sit under **Analysis**; **Settings** and **Developers** sit under **Others**. A store that has not connected a storefront yet sees only **Sales** in the Analysis group, so you can watch your first (test) order arrive while the rest of the portal has nothing to show. Some sections appear only when SureBright has switched them on for your store: **Studio**, **Warranty Pricing**, **Order Resolution**, **Abandoned Cart** and **Fulfillment**. They are available on request. ## Check your store's status At the foot of the sidebar is your store's account card. It shows the store name, its status and its platform: | Status | Meaning | | --- | --- | | **Live** | Approved. Protection is offered on your storefront. | | **In review** | SureBright is still reviewing the store. | | **Not installed** | No storefront is connected yet. | | **Not approved** | The store was not approved. Contact support. | The card's **Store** menu offers **Open store admin** (Shopify and BigCommerce), **Switch to POS portal** (stores that also use the SureBright POS portal) and **Sign out**. The page header also shows one prompt at a time when something needs your attention: - **You haven't added any payment method yet** with an **Add Payment Method** button. See [Billing](/merchant-portal/billing). - A **book a call** prompt while the store is in review. ## Getting help Click **Help** at the bottom of the sidebar. The Help page offers: - **Common questions**, organised by topic (warranty, coverage and claims; getting paid and sales; the checkout extension, and more). Use the search box to search every question. - **Tour the portal**: short guided walkthroughs of key screens. - **Training Videos** (coming soon). Under **Still need help?** you can reach the team at [support@surebright.com](mailto:support@surebright.com) or **+1 855-306-4874**. ## Related Sign in on each platform, give a colleague access, or remove someone. How to reach the team and what to include. --- # Payment methods Source: https://docs.surebright.com/merchant-portal/payment-methods > Which payment methods you can save, how to add a card or bank account, how bank verification works, and how to change the method SureBright charges. SureBright charges each invoice to a payment method you save in the Merchant Portal. This page tells you what you can save, how to add it, and how to change which one is charged. | You want to | Do this | | --- | --- | | Add a card or bank account | **Billing → Payment Methods → Add Payment Method** | | Change which method is charged | **Set To Default** on the method you want | | Remove a method | The bin icon on any method that is not your default | | Stop paying a card fee | Save a bank account, make it your default and tell support. See [The card processing fee](#the-card-processing-fee) | | Pay by wire or bank transfer instead of an automatic charge | See [Pay by invoice instead](#pay-by-invoice-instead) | | Finish verifying a bank account | See [If your bank account needs verifying](#if-your-bank-account-needs-verifying) | ## What you can save | Your store is in | You can save | | --- | --- | | United States | A credit or debit card, or a US bank account | | Canada | A credit or debit card, or pre-authorized debit from a Canadian bank account | Card and bank details are entered in a secure form provided by Stripe. SureBright does not see or store the full numbers. ## Card or bank account | | Card | Bank account | | --- | --- | --- | | Ready to use | Straight away | After your bank verifies it, usually 1 to 2 business days | | When a charge is confirmed | Within minutes | After several business days | | Fee | On accounts where a card fee applies, the invoice shows a **Payment Gateway Fee** row | No **Payment Gateway Fee** row | If your invoice was charged to a card when you expected your bank account, check which method is marked **Default Payment Method**. SureBright always charges the default. See [Change the method that is charged](#change-the-method-that-is-charged). ## The card processing fee On some accounts, a card payment to SureBright carries a fee. It shows on the invoice PDF as its own row, labelled with the rate, for example **Payment Gateway Fee (2.9% + 30 cents)**. | Question | Answer | | --- | --- | | What is it? | The cost the payment provider charges to process a card payment, passed on to you. It is not part of SureBright's share of your plans. | | What is it charged on? | Your payment to SureBright for an invoice. It has nothing to do with how your shoppers paid you, so it can appear even when your shoppers paid through Shopify Payments or another provider. | | Where do I see it? | On the invoice PDF, between **Sub total** and **Total due**. It is included in **Total due** and in the net amount shown in the portal. | | How do I stop paying it? | Save a bank account, set it as your default, and email support to say you have switched. Bank payments do not carry the **Payment Gateway Fee** row. | | I do not think it should apply to my account | Ask your SureBright contact. They can tell you what was agreed for your account. | ## Add a payment method Go to **Billing → Payment Methods** and click **Add Payment Method**. If you already have one, the button reads **Add New Payment Method**. Choose a card or a bank account under **Payment Details**, fill it in and click **Save Payment Method**. **Payment Method Added Successfully!** means the method is ready to use. A bank account may show one of the messages below first. The first method you add becomes your default. ### If your bank account needs verifying | You see | What it means | What you do | | --- | --- | --- | | **Your bank account is being verified** | Your bank is confirming the account. This usually takes 1 to 2 business days. | Nothing. The account becomes usable when verification completes. | | **One more step to verify your bank account** | Two small deposits are on their way to the account. | Confirm the two amounts once they arrive. If you cannot find where to enter them, email support and ask for your verification link. | | **Your bank could not verify this card** | The card issuer declined the check. | Try again, or save a different method. | Other problems are named in the dialog, for example **Payments are busy right now** or **This form expired**, with a button to retry and a reference you can quote to support. ### If you are told you do not have permission Payment methods are managed by the store owner. If you see **Only a store owner or admin can add or change payment methods**, ask the person who set SureBright up for your store to add the method. If that is you and you still see the message, email support with your store address. See [Team and access](/merchant-portal/team-and-access). ## Change the method that is charged Your default method is the one SureBright charges. It is the card marked **Default Payment Method**. - To change it, click **Set To Default** on another saved method and confirm. You then see **Default payment method updated.** - A new method does not become the default by itself unless it is your first. If you add a bank account to replace a card, remember to set it as the default. - The change applies to the next charge. It does not re-run a charge that has already been made. ## Remove a method Click the bin icon on a method that is not your default. - To remove your default method, first set another method as the default. - You cannot remove your only method: **This is your only payment method**. Add another one first. ## Until you add a payment method The portal header reads **You haven't added any payment method yet** with an **Add Payment Method** button, and the last setup step reads **Needs a payment method**. Add one before you go live so your first invoice can be paid. In the POS portal, a store with no payment method can record up to ten sales, and no single sale above $1,000. See [POS billing](/pos/billing). ## More than one store or account Payment methods belong to your SureBright account, and every invoice on that account is charged to the account's default method. - If your business has more than one SureBright account, for example one per store or one per country, add a payment method in each. - If you want different stores to pay from different bank accounts, tell your SureBright contact before go-live so the accounts are set up that way. ## Pay by invoice instead Instead of an automatic charge, you can ask to be invoiced and to pay each invoice yourself by bank transfer. Ask your SureBright contact to set this up. Once it is, your invoices read **Pending** until SureBright records your payment. | Way to pay | Accepted | | --- | --- | | Card, US bank account, or Canadian pre-authorized debit, charged automatically | Yes. Save it in **Billing → Payment Methods** | | Domestic wire or ACH transfer to the bank details on the invoice | Yes, on invoiced accounts. The details are printed on the invoice PDF | | International wire to the bank details on the invoice | Yes, on invoiced accounts. For invoices from SureBright's US company, send US dollars only | | Any other method, such as PayPal or Interac e-Transfer | Not listed on the invoice. Ask your SureBright contact before you pay this way | How to pay an invoice by transfer, and how to check it arrived, is on [Invoices and charges](/merchant-portal/invoices-and-charges#if-you-are-invoiced-without-an-automatic-charge). ## Related When you are charged, what the statuses mean and how invoices reach you. Answers to the most common questions about charges, credits and invoices. The Payment Methods and Billing History tabs, screen by screen. Who collects the plan price, what you keep and what SureBright invoices. --- # Payment questions Source: https://docs.surebright.com/merchant-portal/payment-questions > The questions that come up most about charges, credits and invoices, with what is happening in each case and what to do about it. These are the payment questions you are most likely to have, with what is happening in each case and what you can do. They are in order of how often they come up. When you write to support about any of them, include your store address, the invoice number and the order numbers involved. ## I refunded an order but got no credit for the plan **What is happening.** SureBright gives you money back for a plan when the plan itself is cancelled. That happens when the plan is refunded or removed in your store, not when only the product is refunded or when a refund is entered as a lump sum with no items selected. **What to do.** - When you refund or cancel an order, refund the protection plan line as well as the product. - If you already refunded only the product, open the order in [Order Resolution](/merchant-portal/order-resolution) if it appears there, or send support the order numbers and the plans will be cancelled. - Look for the money on your next invoice, under **Refund for Cancellations**. A plan cancelled after an invoice was issued is credited on the following one. **Avoid it next time.** Make refunding the plan line part of your returns routine. See [Helping a customer](/help/helping-a-customer). ## I cannot add or change my payment method | You see | Why | What to do | | --- | --- | --- | | **Only a store owner or admin can add or change payment methods** | Payment methods are managed by the store owner. | Ask the person who set SureBright up to add it, or email support with your store address. | | The form asks you to connect a bank when you wanted to enter a card | The form offers both. | Choose the card option at the top of **Payment Details**. | | Your bank is not listed or will not connect | Not every bank supports instant connection. | Choose manual entry of your account details. Verification then takes 1 to 2 business days. See [Payment methods](/merchant-portal/payment-methods#if-your-bank-account-needs-verifying). | | An error with a reference | Something went wrong while saving. | Try again. If it repeats, send support the reference shown in the dialog. | ## My charge failed **What is happening.** The charge to your default method did not go through, for example because the card expired or the bank declined it. The plans on that invoice are still owed, and they are billed again on a later invoice. **What to do.** 1. Add a working method in **Billing → Payment Methods** and click **Set To Default**. See [Payment methods](/merchant-portal/payment-methods). 2. Email support to say the method is updated and ask for the charge to be run again. Changing the method does not retry the charge by itself. If you want the charge run on a particular date, say so in the same email. **Avoid it next time.** Keep two methods saved, and update the default before a card expires. ## What happens if we do not pay an invoice? **What is happening.** Your customers paid you for their plans, and SureBright's share of those plans is what the invoice collects. Your customers' plans depend on that invoice being paid. | Situation | What it means | | --- | --- | | The invoice is paid | The plans on it are in place and claims on them are handled as normal. | | A charge failed or an invoice is overdue | SureBright cannot process claims on the unpaid plans until the invoice is paid. Once it is paid, they are handled as normal. | | You need time to review an invoice before paying | Tell support straight away, with the invoice number and what you are checking. Claims on the plans wait until the invoice is paid, so check quickly. [Invoice analysis](/merchant-portal/invoice-analysis) shows how to trace every figure. | | An invoice stays unpaid after SureBright has asked for payment | SureBright can cancel the unpaid plans and switch off new plan sales on your store. | **What to do.** Keep a working default payment method, or pay invoiced amounts by the **DUE DATE** on the PDF. If you cannot, talk to support before the date passes. ## Can we pay an overdue balance in instalments? Ask support. A payment plan, or charges on dates you choose, can be arranged case by case. The plans on the unpaid amount stay unpaid until each part is paid, so claims on them wait until then. ## Can we deduct cancellations from this payment? No. Pay the exact invoice total. A plan cancelled after an invoice was issued is credited on your next invoice, as **Refund for Cancellations**. If you take it off your payment as well, the invoice is left short and the credit still arrives next month. This applies whether you are charged automatically or pay by transfer. To see what will come back, open the invoice and look at **Late Cancellations** in the [Reconciliation Check](/merchant-portal/payment-reconciliation#what-the-banner-tells-you). ## Has our payment been received? Look at the invoice in **Billing → Billing History**. **Processed** means it is paid. For bank transfers, short payments after bank fees, payments that quoted the wrong invoice, and balances across several accounts, see [Check that a payment was received](/merchant-portal/invoices-and-charges#check-that-a-payment-was-received). ## Our bank disputed a SureBright charge Talk to support before you dispute a SureBright charge with your bank or card issuer, and include the invoice number. Most questions about a charge are answered from the invoice itself. - A dispute does not cancel the plans you sold or what is owed for them. - If a dispute has already been opened, email support with the invoice number and the dispute details, and add a working payment method in **Billing → Payment Methods** if the old one is the problem. ## There is a charge I do not recognise | What you see | Likely reason | | --- | --- | | Two charges close together | Product protection and shipping protection are invoiced and charged separately. | | A debit at your bank, but no invoice yet | Bank payments take a few business days to confirm. The invoice email follows once the payment is confirmed. | | A charge, and you cannot find the invoice email | The email goes to your store's contact address. Every invoice is also in **Billing → Billing History**. | If none of these fits, send support the amount, the date and the last four digits of the card or account. ## Why are orders from months ago on this invoice? **What is happening.** Those plans were sold to your customers earlier but could not be billed at the time, usually because the plan could not be matched to a product. Once that is sorted out the plan is billed, and it appears with its original order date. It is a first-time charge. You have not paid for it before. The usual causes: - The plan was sold against a product typed in by hand, not picked from your catalogue. - The plan was added to the order, or its quantity was raised, after the order was placed and without SureBright's tools. - The plan was sold as a warranty product created in your own catalogue, not one of the SureBright plan products. **Avoid it next time.** Sell and add plans only through SureBright: the storefront offer, [Merchant Portal draft orders](/merchant-portal/leads) on Shopify and Magento, the [Shopify draft order extension](/draft-order-guide/shopify-draft-order), or the [POS portal](/pos/recording-a-sale) on any platform. Plans recorded that way are billed in the month they are sold. ## What is a "Previous Invoice Adjustment"? It is a correction to a plan that was billed on an earlier invoice. The order appears again with **(Previous Invoice Adjustment)** after its number. - A positive amount means the plan was billed for less than your agreed terms on the earlier invoice, and this line makes up the difference. - A negative amount is money back, for example because the plan was cancelled. It is not a new plan and not a second charge for the same plan. If an adjustment does not match your records, send support the order number. ## I was billed twice for one order | What you see | What it usually is | | --- | --- | | The same order number on two lines | The order carries more than one plan. Each plan is billed separately. | | A plan listed under an order you did not expect | The plan was bought later, in its own order, and is listed with the product it covers. | | Two identical plans on one product | A real duplicate. | Check the **Duplicate Contracts** tab in [Payment reconciliation](/merchant-portal/payment-reconciliation#read-the-duplicate-contracts-tab). SureBright cancels real duplicates and the charge comes back on your next invoice. If you spot one first, send support the order number. ## We have not been billed for a sale yet A plan is billed once it is ready, which can be after the month it was sold. - A sale late in the month can fall on the next invoice. - If your plans start when the order ships, nothing is billed until the product has shipped. - A plan waiting for an answer in [Order Resolution](/merchant-portal/order-resolution) is not billed until the case is answered. If a whole month shows no invoice and you made sales, tell support. You can also ask for an invoice now, outside the monthly cycle. See [Ask for an invoice outside the cycle](/merchant-portal/invoices-and-charges#ask-for-an-invoice-outside-the-cycle). ## Why is there a fee on my invoice? A **Payment Gateway Fee** row is the card processing fee, on accounts where it applies. The row names the rate, for example **Payment Gateway Fee (2.9% + 30 cents)**. It is the payment provider's cost of taking your card payment to SureBright, and it does not depend on how your shoppers paid you. To stop it, save a bank account, set it as your default and tell support. See [The card processing fee](/merchant-portal/payment-methods#the-card-processing-fee). ## Can we pay by wire, EFT, PayPal or Interac? You can ask to be invoiced instead of charged automatically, and then pay by wire or bank transfer to the details on the invoice. Other methods, such as PayPal or Interac e-Transfer, are not listed on the invoice; ask your SureBright contact first. See [Pay by invoice instead](/merchant-portal/payment-methods#pay-by-invoice-instead). ## The margin on my invoice looks wrong Each billed order shows **Total Warranty Price**, **Your Margin** and **Net to SureBright**. Open the invoice, click an order number and compare **Your Margin** with the share you agreed with SureBright. If it does not match, send support two or three order numbers as examples. Corrections appear on a later invoice as **(Previous Invoice Adjustment)** lines. ## Can invoices go to our accounts team? Yes. Email support with the address and future invoice emails are sent there. Past invoices and the **Billed Orders** file are always available in **Billing**. ## How do we change the name or address on our invoices? Email support with the legal business name and billing address you want printed. See [The name and address on your invoice](/merchant-portal/invoices-and-charges#the-name-and-address-on-your-invoice). ## Is tax charged on my invoice or on the plans I sell? Your store's own tax settings decide the tax on the plans you sell. For any question about tax on SureBright's own invoice to you, such as a tax breakdown or SureBright's tax registration details, ask your SureBright contact. See [Tax on protection plans](/learn/tax). ## How do I pay an invoice that is still outstanding? - If you pay by card or bank account, make sure a working method is your default, then ask support to run the charge, on a date of your choice if you need one. - If you are invoiced without an automatic charge, pay by bank transfer using the details on the invoice PDF and quote the invoice number. See [Invoices and charges](/merchant-portal/invoices-and-charges#if-you-are-invoiced-without-an-automatic-charge). ## Related Add a card or bank account and choose which one is charged. The billing cycle, statuses and every kind of line on an invoice. Check an invoice against what you sold. How to reach SureBright and what to include. --- # Payment reconciliation Source: https://docs.surebright.com/merchant-portal/payment-reconciliation > Check an invoice against what you sold: what Missing from invoice, Late cancellations and Duplicate contracts mean, and what happens about each. Use the **Reconciliation Check**, in the [Merchant Portal](/merchant-portal/overview), to confirm that an invoice matches what you sold in the period it bills. It tells you whether the two agree, explains any difference, and flags any order that was charged for more plans than it bought. It is available on every store. A difference is settled on your next invoice without any action from you. This page tells you what each message means. ## Open the check for an invoice On [Billing](/merchant-portal/billing), click the invoice's row in **Billing History**, then **View full invoice details →**. **Analyse →** sits next to **Current invoice period**. Sales opens for that invoice's period with a banner reading **Showing analysis for invoice #…**, **← Back to Invoice** and **Clear filter**. A second banner above the dashboard gives the result. Click **View details →** to see the plans behind it. The check covers one invoice's period at a time. Open it from each invoice you want to review; the Sales page without an invoice selected shows no banner. The same counts also appear on Billing when you expand an invoice's row. [Invoice analysis](/merchant-portal/invoice-analysis) walks through the whole month close. The Sales page itself is described on [Sales](/merchant-portal/sales#check-an-invoice-against-your-sales). ## What the banner tells you | Banner | What it means | What happens | |---|---|---| | **All warranties from this period are accounted for.** | Sales and the invoice match to the cent | Nothing to do | | **N warranties are pending invoicing · $X** | Plans sold in the period that were not on this invoice yet. They are fully active | They appear on your next invoice automatically | | **N warranties cancelled after billing · refund of $X** | Plans charged on this invoice and cancelled since | The amount is credited on your next invoice automatically | The two differences are timing differences, not errors: a plan became ready to bill after the invoice was issued, or a cancellation arrived after it. Click **View details →** to see the plans behind the number. ## If you see a duplicate contracts alert A separate red alert, **N duplicate contracts across N orders**, appears when an order carries more contracts than the plans it bought. This is a billing error, not a timing difference. It has its own alert because it never shows up as a gap between Sales and the invoice. You do not need to request a refund or do anything else: - SureBright cancels the extra contracts. - The amount you paid for them is **automatically refunded as a credit on next month's invoice**. - The customer's coverage is not affected. The contract that is kept already covers everything the duplicate did. When the duplicates were charged on an earlier invoice and not this one, the alert says so and the credit still follows. Click **Review duplicates →** to see each affected order. ## See the plans behind each number **View details →** and **Review duplicates →** open the **Reconciliation Check** window. It has three tabs, each with its count and its own **Download CSV**. | Tab | What it lists | What happens | |---|---|---| | **Missing from invoice** | Plans sold in the period but not on this invoice, with a date, **Customer**, **Product**, **Order**, **Status** and the amount columns | These are active plans. They appear on your next invoice | | **Late Cancellations** | Plans charged on this invoice and cancelled afterwards, with the same columns | The charge comes back as a credit on your next invoice | | **Duplicate Contracts** | Orders charged for more plans than they bought | SureBright cancels the extras and credits you on next month's invoice | ### Read the Duplicate Contracts tab The tab shows one card per affected order, headed by the order number, date and customer, with four counts: | Count | Meaning | |---|---| | **Bought** | Plans the customer bought on the order | | **Created** | Contracts that exist for it | | **Extra** | Contracts beyond what was bought | | **Overcharged** | What this invoice charged for the extras. When some extras were billed on another invoice the chip reads **Extra cost** and shows their total value instead | Under the counts, each plan lists its contracts, every one marked **Kept** or **Duplicate** with its creation time, status and *billed on this invoice* where that applies. The **Kept** contract is the genuine one; the **Duplicate** rows are the copies SureBright cancels. A footnote says how thorough the check was: how many orders on the invoice were checked, how many were skipped because SureBright could not tell how many plans the order bought, and how many contracts could not be matched to a plan on the order and were left out. An order SureBright cannot verify is never reported as a duplicate. When there are many affected orders the tab shows those with the largest overcharge and says so; the CSV covers the same set. With no duplicates the tab reads **Every order was charged for exactly what it bought**. ## Download the details as CSV Each tab's **Download CSV** gives you what the tab shows. The duplicates CSV has one row per contract in every affected order, kept contracts included, with **Order Number**, **Order ID**, **Order Date**, **Customer**, **Email**, **Product**, **Warranties Bought**, **Contracts Created**, **Contract ID**, **Contract Created**, **Classification** (Kept or Duplicate), **Billed On This Invoice**, **Status** and the amount columns. ## Related The month-close routine, from the invoice page to this check. Payment methods, Billing History and the invoice page. --- # Products Source: https://docs.surebright.com/merchant-portal/products > Turn protection on or off per product, set categories, set manufacturer warranty lengths, manage shipping protection and see the plan prices shoppers are offered. **Products**, in the [Merchant Portal](/merchant-portal/overview), lists every product from your store, the SureBright category each one is in, and whether protection is offered on it. Use it to decide which products offer protection and to check the plan prices your shoppers see. The Products page is not shown on Custom-platform stores, which have no product catalogue in the portal. | You want to | Do this | | --- | --- | | Offer or stop offering protection on a product | Set **Warranty status** to **Active** or **Inactive** on its row. | | Put a product in the right category | Pick one in the **Product category** dropdown. | | Change many products together | Tick them and use the bar at the bottom. See [Change many products at once](#change-many-products-at-once). | | See what shoppers pay for a plan | Click **View Pricing** on the row. | | Get an offer showing on a product whose **Mfr warranty** chip reads **Add** | [Set the manufacturer warranty length](#set-the-manufacturer-warranty-length). | | Get a list of every product that offers protection | [List the products that offer protection](#list-the-products-that-offer-protection) | | Understand why the plan length on your product page differs from the portal | [Plan lengths on your product page look different](#plan-lengths-on-your-product-page-look-different) | | Keep shipping protection off freight, vendor-shipped or large items | [Keep shipping protection off some products](#keep-shipping-protection-off-some-products) | ## Find a product - **Status chips.** Three chips at the top switch the list and show counts: **All**, **Warranty Active** (products that offer protection) and **Warranty Inactive** (products that do not). On a **Live** store the page opens on **All**. While a store is still **In review** it opens on **Warranty Inactive**, since nothing is offered yet. - **Search.** Type in **Find your product here** and press Enter. Clearing the field and pressing Enter resets the search. On Shopify the search matches the product name, its description and its variants' SKUs, so you can search by SKU. On other platforms, search by product name if a SKU finds nothing. - **Filters.** Click **Filters** to open the filter panel. The badge on the button shows how many filters are applied. Click **Apply** to run the filters, or **Clear Filters** to reset everything, including the search. | Filter | Options | | --- | --- | | **Select Product Type** | Your store's own product types, plus **No Product Type**. | | **Select Category** | SureBright categories, plus **Uncategorised** and **Categorisation Under Review**. | | **Shipping protection** | **On**, **Off** or **Not eligible**. Shown only on stores that can set shipping protection per product (see below). | | **Show archived/ deleted products** | Shopify only. Ticked by default; untick it to hide products that are archived or deleted in Shopify. | The list is split into pages. Use the controls at the bottom to move between pages and to change how many products are shown per page. ## What the product list shows | Column | What it shows | | --- | --- | | **Product details** | Image and name. Products whose plan price depends on the manufacturer warranty also show a **Mfr warranty** chip (see below). | | **Product price** | The product's average price. | | **Product category** | A dropdown with the SureBright category. | | **Warranty status** | **Active** / **Inactive** dropdown, or an **Under Review** pill while SureBright reviews the category. | | **Shipping protection** | **On** / **Off** dropdown or a **Not eligible** pill. Shown only on stores that can set shipping protection per product. | | **Warranty details** | **View Pricing** opens the product's details panel. | On small screens each product is shown as a stacked card instead of a row. ### List the products that offer protection Click the **Warranty Active** chip. The count on the chip is the number of products that offer protection, and the list shows each one. Combine it with **Filters** to narrow by category or product type. The Products page has no download. For a file of every product that offers protection, ask your SureBright contact or write to support. ## Turning protection on or off Use the **Warranty status** dropdown on the row and pick **Active** or **Inactive**. - A product with no category shows **Inactive** and cannot be turned on. Pick a category first; the row says **Please select a category of the product to enable warranty** if you try. - A product whose category is **Under Review** cannot be changed until the review completes. - A product in a category SureBright does not support cannot be turned on. ## Change a product's category Pick a category from the **Product category** dropdown. A confirmation dialog opens; confirm to save. Changing the category also turns protection on for the product. ## Set the manufacturer warranty length In some categories (for example major appliances) the plan price depends on how long the manufacturer covers the product. Products in those categories show a **Mfr warranty** chip under the product name. Until you set the length, your storefront shows no protection offer for that product, and the chip reads **Add**. Click the **Mfr warranty** chip. The **Manufacturer warranty length** popover opens. Choose one of the listed durations, or pick **Other** and type the number of months. Click **Save**. The chip now shows the length, and plan prices for the product take it into account. Click the chip again to change it. Products in other categories show no chip. For them SureBright uses a standard length, 12 months unless your store is set up otherwise. If your products have a different manufacturer's warranty, or a plan was sold with the wrong length, see [Correct a manufacturer warranty length](/contracts/effective-dates#correct-a-manufacturer-warranty-length). ## Choose which products count towards shipping protection On stores that sell SureBright shipping protection, the **Shipping protection** column lets you decide per product whether it counts towards shipping protection. - **On** / **Off**: choose from the dropdown. **On** is the default for eligible products. - **Not eligible**: the product's category is not a shipping category, or the product has no category yet. Hover the pill for the reason (**Select a product category first** or **Not available for this product's category**). This is supported on **Shopify** and **BigCommerce** stores and is switched on store by store. If you sell shipping protection and do not see the column, ask support to enable it. ### Keep shipping protection off some products | You want to exclude | Do this | | --- | --- | | One product, such as a TV or a large item | Set its **Shipping protection** dropdown to **Off** | | A whole category or product type | Open **Filters**, pick the **Select Category** or **Select Product Type**, tick the header box to select the page, and set **Shipping protection** to **Off** in the bar at the bottom. Repeat for each page | | A brand, vendor, tag or collection, such as products your suppliers ship | The page cannot filter by these. Send your SureBright contact the list, or the tag or vendor that marks them | | Items shipped by freight or LTL carriers | Turn shipping protection **Off** on them. Cover is created for shipments with a carrier SureBright recognises, such as UPS, USPS, FedEx and DHL. Ask your SureBright contact whether your freight carrier is one | Turning shipping protection off leaves product protection on the same product unchanged. See [Shipping protection](/shipping-protection/overview). ## Change many products at once Tick the checkbox on each product you want to change, or tick the box in the header to select every product on the page. A bar appears at the bottom of the screen showing **N Selected** with: - **Select Category**: move the selected products to one SureBright category. - **Active / Inactive**: turn protection on or off for all of them. - **Shipping protection** (**On** / **Off**): on stores that can set shipping protection per product. Click **Apply Changes**, or **Cancel** to clear the selection. You must choose at least one change; otherwise the portal says **Please select a change to apply to the selected products**. After a category or status update the portal confirms **Category Updated for N Products**. After a shipping update it reports how many products were turned on or off and how many were **skipped (category not eligible)**. ## See the prices shoppers are offered Click **View Pricing** on a row to open the product's details panel underneath it. Click **Close** to collapse it. **Product Information** shows the **Product ID**, **Product type** (your store's type) and a **View in store** link, followed by a table of variants with **Variant**, **Variant ID** and **Cost**. **Warranty Prices** shows the plan prices your shoppers are offered for this product, by variant. Switch between **US** and **CA** when the store sells in both countries. - Each row shows the **Variant**, its **Device price** and one column per plan length (**1Y**, **2Y**, **3Y** and so on). - The note above the table says which category the prices come from: **Prices come from the _Category_ category. An override changes this product only.** - Under each price the source reads **category**, or **override** when the product has its own price. ### Plan lengths on your product page look different **Warranty Prices** in the portal always shows the length of SureBright's plan: **1Y**, **2Y** and so on. Your product page can label the same plan in another way, depending on how your widget is set up: | Product page label | What it means | | --- | --- | | **+2 Year** | Two years added after the manufacturer's warranty | | **3 Year Total** | The manufacturer's warranty plus the plan, added together | | **1 Yr Manufacturer + 2 Yr Protection** | Both, shown separately | | **2 Year Coverage** or **2 Years** | The plan's own length | So a 2-year plan on a product with a 1-year manufacturer's warranty can read **3 Year Total** on the product page and **2Y** in the portal. Both are right. To change the label your shoppers see, ask your SureBright contact. **Edit prices** and the **Change History** tab belong to [Warranty Pricing](/merchant-portal/warranty-pricing), which SureBright enables per store. They are available on request. **Coverage Intelligence**, a view of which products should be covered next and the revenue you are missing, is available on request. See [Coverage Intelligence](/merchant-portal/coverage-intelligence). ## Related Set the plan prices your shoppers see, per category and per product. See how protection is selling on the products you switched on. --- # Ray Source: https://docs.surebright.com/merchant-portal/ray > Ray, the Merchant Portal assistant: what you can ask it, which changes it can make for you, and how you preview and confirm each change. Ray is the assistant inside the Merchant Portal. Ask it about your store's protection program and it answers from your portal data and the portal's help. It can also make a set list of changes for you. You see a preview of each change first, and nothing is changed until you confirm. Ray is available on request; ask your SureBright contact to enable it for your store. ## Open Ray Ray's launcher sits at the bottom right of every portal page. Click it to open the panel. On first open it greets you with **Hi, I'm Ray. What can I help with?**, explains that it looks up your sales, billing, products and abandoned carts and only changes something after you confirm it, and offers four starters you can click: - How many plans did I sell last month? - Do I have any unpaid invoices? - Which carts were abandoned this week? - How do I turn protection off for a product? The header shows **Online · `store name`**. The second header button opens **Previous chats**, where you can reopen a chat, start a **New chat** or **Delete chat**. **Esc** closes the panel. Send unlocks when the current answer finishes. ## What you can ask Ray Ray stays on the Merchant Portal and your store's protection plans. Ask about: - Sales numbers and reports: plans sold, revenue, attach rate, breakdowns by period, category or coverage, and sales exports. - Products: which products have protection on, their categories, plan prices and price history, and your price grid. - Billing: payment methods, invoices and the orders behind a charge. - Leads and draft orders, on Shopify and Magento stores: recent orders you could sell a plan on, plan prices for a lead, and the state of a draft order. - Order Resolution: open cases, their order lines and notes, missing contracts and orders awaiting fulfillment. - Abandoned Cart, on Shopify stores: carts, offers sent, messages, follow-up rules and templates, and how the program is set up. - How the Merchant Portal works, from the same help content as the **Help** page. Answers come as text and cards: tables, breakdowns, trends, funnels, record lists and help links. **Today** means the portal's analytics day, in Eastern time. A feature that is not switched on for your store is not offered; Ray says so and suggests contacting SureBright if you would like it. For anything else, Ray declines and points you to [support@surebright.com](mailto:support@surebright.com) or +1 855-306-4874. You can write to Ray in any language; its fixed replies and cards are in English. ## Changes Ray can make Every change goes the same way: Ray shows a change card with the **Setting**, its value now and **After**, and anything you should know: for example that the change messages a shopper, cannot be undone, or changes what shoppers see on your live store. The card asks you to check before it changes anything. Click **Confirm**, or **Cancel**. Nothing happens until you confirm. When you confirm, Ray checks that nothing has moved since the preview. If something has, it stops. Otherwise it makes the change once. The card then reads done, **Partly done**, or **Couldn't make this change. Nothing was changed.** If Ray cannot tell whether a change went through, it does not try again by itself. It tells you where in the portal to check first, so a change is never made twice. | Area | Changes | | --- | --- | | Store | Update your store's contact details. | | Billing | Change your payment methods. | | Developers | Revoke an API key. | | Products | Change product protection on or off; set the manufacturer warranty on a product. | | Pricing | Publish plan prices for a category; set a product price override. See [Warranty Pricing](/merchant-portal/warranty-pricing). | | Leads (Shopify and Magento) | Save a product category, create a draft order, send a payment link, mark a draft order paid. See [Leads](/merchant-portal/leads). | | Orders | Correct the covered product on a plan. | | Order Resolution | Answer an Order Resolution case, add a case note, hold or resume auto-resolution. See [Why a contract is on hold](/contracts/holds). | | Lightspeed R Series | Run a Lightspeed order sync. See [Settings](/merchant-portal/settings#sync-orders-from-lightspeed-r-series). | | Abandoned Cart (Shopify) | Prepare, change or send a cart's offer, send offers to several carts, change a cart's plan or discount code, extend or expire a discount code, skip a cart or put it back, send a message again, refresh cart statuses. | | Abandoned Cart set-up (Shopify) | Save or delete an offer rule or email template, send a test email, change Abandoned Cart or connected tool settings, disconnect a tool, request Abandoned Cart for your store. | Ray makes one change per request. A change follows the same rules as the portal page it belongs to; for example, publishing prices is limited to the store owner or an admin. ## Who can use Ray Ray is for the store's owner and admin accounts. SureBright staff looking at your store through the portal see Ray read-only: it answers for the store they are viewing and makes no changes. ## Related What each section of the portal is for. Connect Claude to your Merchant Portal account. --- # Sales Source: https://docs.surebright.com/merchant-portal/sales > See how protection is selling, compare periods, break sales down, find or export a sale, and check an invoice against what you sold. **Sales** is the home page of the [Merchant Portal](/merchant-portal/overview). Use it to see how protection is selling, compare one period with another, find or export a sale, and check an invoice against what you sold. Two pills at the top switch between **Product Protection** and **Shipping Protection**. Each has its own dashboard and its own list of sales. | You want to | Go to | | --- | --- | | Look at another date range, location, channel or device | [Choose the period and scope](#choose-the-period-and-scope) | | See revenue, margin, plans sold and attach rate | [See your headline numbers](#see-your-headline-numbers) | | Know whether this month beat last month | [Compare two periods](#compare-two-periods) | | See which platform, location or category sells most | [Break sales down by platform, location or category](#break-sales-down-by-platform-location-or-category) | | Look up one order or customer | [Find a sale](#find-a-sale) | | Get a file of your sales | [Export your sales](#export-your-sales) | | Find a plan you sold that is not listed | [A paid plan is missing from Sales](#a-paid-plan-is-missing-from-sales) | | Find out why a plan was cancelled | [Why a plan was cancelled](#why-a-plan-was-cancelled) | | Confirm an invoice matches what you sold | [Check an invoice against your sales](#check-an-invoice-against-your-sales) | ## Choose the period and scope The date filter at the top governs the whole page. The summary on the left reads **Showing** followed by the active period and any scope filters. The button on the right opens the filter panel, where you can set: - **Today**, **Last 7 days**, **Last 30 days** or **Custom**. For **Custom**, pick a range under **Select Dates** and click **Done**. - **Location**: shown when your store has locations. Pick one to narrow the page to it. - **Sales channel**: shown when your orders carry a sales channel. - **Select Tags**: narrow to orders with the chosen tags. Click **Apply**, or **Clear Filters** to go back to **Last 30 days** with no scope. Applied location, channel and tag filters appear as removable chips next to the period. **Clear scope filters** removes them without touching the date. To look at one device or one platform only, use the **Break down by** row. It appears when the period has data by device or by platform, with chips such as **All traffic**, **Mobile**, **Desktop** and one chip per platform. Pick one and the headline numbers, the period comparison and the platform chart show that segment only. Sections that cannot be narrowed this way say so (for example **all platforms**). ## See your headline numbers **Overall Stats** shows four tiles for the selected period: | Tile | What it is | | --- | --- | | **Total Revenue** | What shoppers paid for protection plans. | | **Margins Earned** | Your share of that revenue. | | **Policies Sold** | Number of plans sold. | | **Attachment Rate** | Orders that bought a plan as a share of eligible orders. The tile also reads **N of M eligible orders attached a warranty**. | Each tile carries a change badge against the comparison period. The badge is hidden on a **Custom** range. ## Compare two periods The selector beside the **Overall Stats** heading sets what every section compares against: - **Previous Period** (the same number of days immediately before) - **Same Period Last Month** (only when the range sits inside one calendar month) - **Same Period Last Year** - **Same Period 2 Years Ago** - **No Comparison** With a comparison on, each tile shows the comparison value and its percentage change underneath. **Period Comparison** is a line chart of the current period against the comparison period. Use the chips to pick the metric: **Revenue**, **Policies Sold**, **Attach Rate** or **Margins**. The large figures show **Current**, the comparison period and the percentage change. ## Break sales down by platform, location or category Scroll down the dashboard for these views of the same period: | Section | What it tells you | | --- | --- | | **Revenue by Platform** | Daily revenue per platform (Shopify, Post Purchase, In Store, POS, WooCommerce, BigCommerce, Magento and so on). With a comparison on, **Faded = Previous period** and **Solid = Current period**. It reads **No Sales Data** when the period is empty. | | **Sales by Location** | Shown on stores with locations. A bar per location of **Policies Sold**, with each location's policies and revenue listed beneath. If locations are set up but no sale has been matched to one, the section says so and asks you to contact support. | | **Policies by Category** and **Revenue by Category** | Two side-by-side cards that split the period's policies and revenue across your SureBright categories, with a comparison bar under each category when a comparison is on. | | **Attach rate by widget version** | Shown when your sales can be traced to the widget version that made them. It compares attach rate across versions (**Orders**, **Eligible**, **Policy**, **Attach**) with a **By category** breakdown. While a split test is running it is titled **Attach rate by experiment**. With nothing to compare it reads **No experiment data for this period**. | ## Find a sale The dashboard ends with **Recent Sales**, your most recent plans. Click **View All** to open the full list at **Sales → Recent sales**. | Column | What it shows | | --- | --- | | **Sr. No** | Row number. | | **Date** | Contract date. | | **Product** | Image and name. Playground orders carry a **Test** tag. | | **Category** | The SureBright category. On stores with both coverage types the name ends in **-AD** (Accidental Damage) or **-B** (Breakdown). | | **Order number** | The platform order number. | | **Platform** | Where the sale came from. | | **Warranty status** | The plan's current status, for example **Active** or **Cancelled**. See [Contract statuses](/contracts/lifecycle). | To narrow the list on the Recent sales page: - **Search sales here** searches by order, customer or product. Press Enter. - **Filter** opens a panel with **Select Dates**, **Platform** (Shopify, In Store, POS, Post Purchase, Registration Post Purchase, Shift4Shop, WooCommerce, BigCommerce), **Store Category** and, when the store sells in more than one country, **Country**. Click **Apply** or **Clear Filters**. - On stores that sell both coverage types, the **Store Category** filter lists each category twice, as **-AD** and **-B**. Click a row's chevron to open its details: - **Contract Details**: **Variant Name**, **Category**, **Covered Product Price**, **Policy Price**, **Merchant Margin**, **Warranty Tenure** and **Policy ID**. - **Client Details**: the customer's name, address, phone and email. - **Edit Product Details**: on Shopify stores, for eligible active contracts, lets you correct the covered product. ## Export your sales Click **Download** on the Recent sales page, pick a date range under **Select Dates**, click **Done**, then **Download**. The portal prepares a CSV of every contract in that range and opens it. The CSV has one row per plan, with these columns: | Column | What it holds | | --- | --- | | **Date** | Contract date | | **ContractId (Policy Id)** | The plan's number, as the customer sees it | | **Customer Name**, **Customer Email** | Who holds the plan | | **Order Number**, **Order Id** | The order on your platform | | **Platform** | Where the sale came from | | **Product Title**, **Product SKU** | The covered product | | **Warranty Status** | For example **Active** or **Cancelled** | | **Warranty Price** | What the customer paid for the plan | | **Warranty Tenure** | The plan length, for example **2 Years** | | **Your Margin** | Your share | | **Covered Amount** | The covered product's price | To count plans over a period, export that range and count the rows, or read **Policies Sold** on the dashboard. Invoices and the orders billed on each are under [Billing](/merchant-portal/billing). There is no API for sales data; for a recurring report in another format, ask your SureBright contact. ## A paid plan is missing from Sales Work down this list: | Check | Why it matters | | --- | --- | | The pill at the top | Shipping protection sales are only listed under **Shipping Protection** | | The date filter and **Filter** panel | The list shows the chosen period, platforms and categories only. **Clear Filters** and widen the dates | | How the plan was added | A plan typed into an order by hand, or a warranty product you created yourself, never becomes a plan. See [Phone, draft and later sales](/learn/phone-and-later-sales) | | Whether the order is paid | On Shopify, a plan is created once its order is paid. An unpaid draft order creates none | | [Order Resolution](/merchant-portal/order-resolution) | A plan SureBright could not tie to a product exists only once you answer its case | | Your platform's set-up | On WooCommerce, plans become contracts only once the four order webhooks are set up. See [WooCommerce](/woocommerce/overview). On Lightspeed R Series, see **Warranties needing attention** below | | Which store you are signed in to | Each sign-in opens one store, with its own Sales list. See [Work with more than one store](/merchant-portal/team-and-access#work-with-more-than-one-store) | Still missing? Send support the order number, the platform and the date. See [Contact support](/help/contact-support). ## Why a plan was cancelled The Sales list shows that a plan is **Cancelled**, not who cancelled it. These are the usual causes: | Cause | Where to check | | --- | --- | | The order was cancelled, or the plan line refunded, in your store admin, by your team or by another app | The order's history in your store admin | | On Shopify, the covered product was refunded and nobody answered the case within 48 hours | **Order Resolution**, under **Resolved** | | The order was charged for more plans than it bought, and the extras were cancelled | The **duplicate contracts** alert. See [Check an invoice against your sales](#check-an-invoice-against-your-sales) | | The customer is in a country where plans are not sold | **Order Resolution** | | The customer asked SureBright support to cancel | Ask support | If none of these explains it, send support the order number and ask who cancelled the plan and when. ## Shipping protection sales Switch the top pill to **Shipping Protection** for the shipping dashboard: **Overall Stats** (**Total Revenue**, **Margins Earned**, **Policies Sold**, **Attachment Rate**) with the same comparison selector, **Period Comparison**, **Revenue by Platform**, and the recent shipping sales list. The shipping list (**Sales → Recent shipping sales**) has **Sr. No**, **Order**, **Ordered**, **Shipped**, **Customer**, **Items** and **Protection**. Expand a row for **Tracking ID**, **Carrier**, **Customer**, **Address**, the covered **Items**, and an **Order summary** with **Total covered value**, **Shipping protection** and **Total**. It has its own **Filter** (dates) and **Search sales here** box. ## If your plans start when the order ships Some stores are set up so that a plan becomes active only once the order is fulfilled. On those stores the dashboard adds a **Warranty sales & activation** strip above the tiles, and the tiles become **Warranty Sales**, **Margins (activated so far)**, **Policies Sold** and **Attachment Rate**. They count what was sold at checkout, so they stay current while recent orders are still waiting to ship. The strip follows each sale from checkout to activation: **Sold at checkout** → **Awaiting activation** → **Activated** → **Cancelled**. It also gives you: - a **Sold N vs N previous** change against the comparison period; - a note while recent sales are still activating; - **view list**, the orders awaiting activation, with **Order**, **Sold on**, **Warranties**, **Value**, **Fulfillment** and **Waiting**; - a fulfillment summary; - **Show daily sold vs activated**, a day-by-day chart. SureBright switches this view on per store. See [Fulfillment](/merchant-portal/fulfillment) for the choice between starting plans at sale or at shipment. ## Check an invoice against your sales Open Sales from an invoice (**Billing → invoice → Analyse →**) and the page shows that invoice's period only, with a banner reading **Showing analysis for invoice #…**, **← Back to Invoice** and **Clear filter**. The invoice side of the same check, including **Monthly Activity** and carryover, is on [Invoice analysis](/merchant-portal/invoice-analysis). Above the dashboard a second banner tells you whether your sales for the period and the invoice agree: | Banner | What it means for you | | --- | --- | | **All warranties from this period are accounted for.** | Sales and the invoice match to the cent. | | **N warranties are pending invoicing · $X** | Plans sold in the period that are not on this invoice yet. They are fully active and appear on your next invoice. | | **N warranties cancelled after billing · refund of $X** | Plans charged on this invoice and cancelled since. The amount is credited on your next invoice automatically. | A separate red alert, **N duplicate contracts across N orders**, appears when an order was charged for more warranties than it bought. SureBright cancels the extras and credits them on next month's invoice. You do not need to do anything. Click **View details →** (or **Review duplicates →**) to open the **Reconciliation Check**. It has three tabs, each with its count and its own **Download CSV**: - **Missing from invoice**: the plans still to be invoiced, with a date, **Customer**, **Product**, **Order**, **Status**, **Total Revenue**, **Margin** and **Warranty Cost**. - **Late Cancellations**: the same columns for plans cancelled after billing. - **Duplicate Contracts**: one card per affected order with **Bought**, **Created**, **Extra** and **Overcharged** counts, and each contract marked **Kept** or **Duplicate**. The footnote states how many orders were checked and how many could not be verified. [Payment reconciliation](/merchant-portal/payment-reconciliation) explains each banner and tab in full. ## Warranties needing attention (Lightspeed R Series) Lightspeed R Series stores see a **Warranties needing attention** card on the dashboard: protection plans customers paid for that are not active yet, split into **sold but never activated** and **no warranty created**, with the most common reason. Click **Review →** to open **Sales → Warranties pending**, which lists each sale with **What stopped it**, its **Protection plans**, **Warranty id** and **Activation stage**, and offers **Download CSV**. To bring in missing orders, run a sync from [Settings](/merchant-portal/settings#sync-orders-from-lightspeed-r-series). **Warranty Intelligence**, attach rate by product type and price segment, and the order-resolution screens (**Action needed**, policy detail, **Cancel & refund**, **Refund requests**) are available on request. ## Related Payment methods, invoices and the breakdown behind every charge. What each reconciliation banner and tab means and what happens next. --- # Settings Source: https://docs.surebright.com/merchant-portal/settings > Update your contact details and, depending on your platform, check that protection is switched on in your Shopify theme and checkout, sync Lightspeed R Series orders, or connect a storefront. Use **Settings**, in the [Merchant Portal](/merchant-portal/overview), to keep your contact details current. The page is a stack of cards, and which cards you see depends on your platform: Shopify stores can check that protection is switched on in their storefront, and Lightspeed R Series stores can bring in sales that have not reached SureBright yet. | You want to | Card | Shown on | | --- | --- | --- | | Change the email or phone SureBright contacts you on | **Contact details** | Every store. Read-only on BigCommerce. | | Reach your API keys | **Developers and API** | Stores with the developer API enabled | | Check or switch on protection in your Shopify theme or checkout | **Storefront setup** | Shopify | | Bring in recent Lightspeed R Series sales | **Sync orders** | Lightspeed R Series | | Connect a Shift4Shop or Lightspeed store | **Connect Store** | Accounts that have not connected a storefront yet | The **Developers and API** card is shown when the developer API is enabled for your store, which is done on request. **Open developer tools** opens the [Developers](/merchant-portal/developers) page; **Read the API docs** opens the API reference. ## Update your contact details The **Contact details** card holds your **Email** and **Phone**. These are the details SureBright uses to reach your store. Edit them and click **Save**, or **Cancel** to discard. On BigCommerce stores they are read-only and come from BigCommerce. The **Store details** card shows your **Store name**, **Store URL** and **Store platform**, all read-only. On Shopify stores a note reads **You can edit these in Shopify** with a link to your admin. ## Check your Shopify storefront setup The **Storefront setup** card is shown on Shopify stores only. It is the easy way to switch SureBright on: each link on the card opens the right Shopify editor at exactly the right place, so you do not have to find your way through Shopify's menus. | You want to | Click on the card | What opens | | --- | --- | --- | | Show the offer on product pages and in the cart | **Turn on in Shopify ↗** next to your theme | The Shopify theme editor, on the App embeds panel, with **SureBright Offering** already switched on. You only click **Save**. | | Take the offer off a theme | **Turn off in Shopify ↗** | The same panel for that theme. Switch **SureBright Offering** off and **Save**. | | Offer protection inside checkout, on Shopify Plus | **Open checkout editor ↗** | Your live checkout in Shopify's checkout editor, on the **Apps** panel, ready for you to add the SureBright blocks. | Each link opens in a new tab. When you come back to the portal, it checks your themes again and updates the status. On other platforms there is no switch in Settings: the offer is put on your storefront by your platform's own install guide, listed on [Supported platforms](/platforms/overview). ### Turn on protection on Shopify product pages The SureBright Offering app embed shows protection offers near **Add to cart**. One row per theme shows the theme name, its role (**Live theme**, **Not published** or **Development theme**) and a status: - **Turned on**: offers show on this theme. The link reads **Turn off in Shopify ↗**. - **Not turned on**: the link reads **Turn on in Shopify ↗**. It takes you straight to the embed with the switch already on. - **Can't check right now**: the portal could not read the theme. Click **Check again**. **Turn on in Shopify ↗**. Your live theme is the one shoppers see. Check that the **SureBright Offering** switch is on, then click **Save**. The status changes to **Turned on**. If it has not changed after a few seconds, click **Check again**. **Show steps** on the card repeats these steps in the portal. More detail, and what each status means, is on [Storefront setup](/shopify/storefront-setup). ### Add protection to Shopify Plus checkout Shown on Shopify Plus stores, which can also offer protection inside checkout through the **SureBright Protection Block and Badge**. It opens your live checkout on the **Apps** panel. Under **SureBright - Extended Warranty**, click **+** next to **SureBright Protection Block** and **SureBright Protection Badge**. Turn on **Include app in Shop Pay**. Click **Save** in the checkout editor. Shopify does not report checkout placement back, so this row shows no status. See [Checkout extensions](/shopify/checkout-extensions). ## Sync orders from Lightspeed R Series Shown on Lightspeed R Series stores. A sale in Lightspeed does not always reach SureBright the moment it completes, so the **Sync orders** card lets you bring recent sales in whenever you need to. Under **What should this sync do?** choose: - **Check only**: updates your orders and shows which sales are missing a warranty, without creating any. - **Check and create missing warranties**: does the same and creates warranties for sales that qualify. Sales that do not qualify are listed with a reason. Click **Sync orders now**. The card shows progress (**Queued**, **Running**, **Finished**, **Finished with issues**, **Failed**) and reports **Sales found**, **Orders updated**, **Warranties created** and **Needs attention**. When something needs attention, **Review warranties needing attention →** opens [Sales → Warranties pending](/merchant-portal/sales#warranties-needing-attention-lightspeed-r-series). A long sync keeps running if you leave the page. Reload Settings to see its progress again. ## Connecting a storefront Accounts set up to run several stores that have not connected a storefront yet see **You haven't connected your storefront yet.** instead of the cards above. Click **Connect Store**, pick the platform under **Select store platform to proceed** (Shift4Shop or LightSpeed) and click **Proceed** to authorize the connection. The portal confirms **Store authorized successfully.** The portal has no team-member, notification or billing-preference settings. Payment methods are managed on [Billing](/merchant-portal/billing). To give a colleague access, see [Team and access](/merchant-portal/team-and-access). ## Related Sign in, give a colleague access, or remove someone. Payment methods and invoices. --- # Design your SureBright offer Source: https://docs.surebright.com/merchant-portal/studio > Make the protection plan offer look like part of your store. Studio builds a first design for you, lets you change colours and layout, shows you the result on your own product page, and lets you go back to an older design at any time. When shoppers look at a product, they see the SureBright protection plan offer next to **Add to cart**. If that offer looks like it belongs to your store, shoppers trust it more. **Studio** is the place in the [Merchant Portal](/merchant-portal/overview) where you choose how the offer looks. You see every change on a picture of your own product page, on a computer screen and on a phone. Shoppers see nothing new until you click **Publish changes**, and you can always go back to the design you had before. You will see **Studio** in the Merchant Portal menu once SureBright turns it on for your store. Shopify stores can ask for it. On other platforms, ask your SureBright contact. ## What you can do in Studio | You want to | Go to | | --- | --- | | Get a ready-made design without starting from zero | [Let Studio make your first design](#let-studio-make-your-first-design) | | Use your brand colours | [Change how the offer looks](#change-how-the-offer-looks) | | Show plans as cards, a list or a dropdown | [Change how the offer looks](#change-how-the-offer-looks) | | Choose which plan is picked when the page opens | [Change how the offer looks](#change-how-the-offer-looks) | | Change the shipping protection box in your cart | [Change the shipping protection offer](#change-the-shipping-protection-offer) | | Make your design live, or undo it | [Make a design live or go back](#make-a-design-live-or-go-back) | | Find out which of two designs sells more plans | [Design tests](/merchant-portal/design-tests) (Shopify only) | | Change the words in the offer or where it sits on the page | [Ask SureBright](#what-surebright-changes-for-you) | ## Let Studio make your first design The first time you open Studio, it looks at one of your product pages and makes a design that matches it: your colours, your fonts, your style. You then change only what you want. (More about this first step in [Onboarding](/merchant-portal/onboarding).) Under **Product page to read**, Studio suggests one of your products. Keep it, or choose another with **Search catalogue** or **Paste a URL** (a page link). Choose a page that looks like most of your store. If your store has a password, Studio asks for it here. You can also pick a **Starting layout**. Studio shows **Our AI is building your widget** while it works. You can close the page; the design will be ready when you come back. When you see **Your widget is ready**, click **See it on my store**. Then choose **Edit** to change it, or **Finish setup** to use it as it is. Studio then takes you through each part one by one: the protection plan offer (**Warranty widget**), the shipping offer (**Shipping widget**, only if your store offers shipping protection) and **Finish setup**. Click **Next** to move on. ## Find your way around The big area in the middle shows your own product page with the offer on it. Loading it the first time can take up to a minute. If Studio cannot load your page, you can keep working on a sample page. - **See each kind of plan:** the buttons under **Preview** switch between **Accidental Damage Protection**, **Breakdown Protection** and **Shipping Protection** (only the ones your store offers). - **See it on a phone:** switch between **Desktop** and **Mobile**. - **Change the "What's covered?" box:** click **What's covered?** on the page and edit the box right there. - **Undo a change:** press Cmd+Z on a Mac or Ctrl+Z on Windows. Add Shift to redo. - **Save without going live:** click **Save draft**. A draft is a design only you can see. - **Go live:** click **Publish changes**. At the top you can always see whether a design is live (**Live since** a date) and how many changes you have not published yet. ## Change how the offer looks Click any of these on the left to open it. | What you want to change | Click | What you can do there | | --- | --- | --- | | Everything at once | **Templates** | Pick a ready-made style. **Designed by our AI for you** is the one Studio made from your page. Picking a style changes the layout only; your colours stay. See the [Template gallery](/merchant-portal/template-gallery). | | Colours | **Colors** | Pick a light or dark look, then set the colours of the background, the heading, the plan boxes and the tick mark. Studio suggests colours from your own store, or you can type a colour code (like #0558FF). If text would be hard to read, Studio warns you. | | How plans are arranged | **Layout & style** | Show plans as **Side by Side Cards**, **Stacked rows** or a **Dropdown menu**. You can also choose square or round corners, whether boxes have a border, and how the chosen plan is highlighted. | | Text size | **Text size** | Make the text, the badge and the price bigger or smaller. **Reset** puts it back. | | Which plan is picked first | **Plans** | Choose the plan that is already selected when the page opens, and whether to show a "No coverage" choice (see [Default plan selection](/merchant-portal/default-plan-selection)). You can also show the price as a monthly amount or as a % of the product price, and add a **Best-seller** badge. | | The "What's covered?" box | **Coverage popup** | Choose how the box looks, add your own logo next to SureBright's, and show how long the maker's own warranty lasts and how much longer the plan covers. See [Show the included manufacturer warranty](/merchant-portal/widget-options#show-the-manufacturer-warranty-that-is-already-included). | ## Change the shipping protection offer If your store offers shipping protection, Studio shows it in your cart. | What you want to change | Click | What you can do there | | --- | --- | --- | | Everything at once | **Templates** | A big button at the top of the cart, or a simple tick box. | | Colours | **Colors** | The tick box, the background and the text. | | How shoppers add it | **Style** | A tick box or a button, and the small badge next to it in the cart. | | The "What's covered?" box | **Coverage popup** | How the box looks and what it shows. | ## What SureBright changes for you You cannot change these yourself in Studio. Ask your SureBright contact and they will do it: - the words in the offer and in the "What's covered?" box - where the offer sits on your product page - whether the offer also shows in the cart or in a pop-up after **Add to cart** - how the plan length is written - where the SureBright logo links to More in [What you can change on your widget](/merchant-portal/widget-options). ## Make a design live or go back 1. Click **Publish changes**. 2. Studio asks **Publish to your store?** Confirm, and shoppers see the new design straight away. 3. Click **See it on your store** to check it. **First time on Shopify?** Studio also asks you to switch on SureBright in your Shopify theme. Until you do, shoppers do not see the offer. See [Settings](/merchant-portal/settings#check-your-shopify-storefront-setup). **Don't like it?** Click **Restore previous design**. Your old design comes back straight away. **Is it working?** The **Publish** step shows how your live design has done in the last 30 days: how many orders added a plan, how many plans were sold and how much money they brought in. ## Keep and reuse your designs Every time you save, Studio keeps a copy. You can come back to any of them under **Your designs**. Give a design a name in **Version note**, for example "Holiday look", so it is easy to find. | You want to | Click | | --- | --- | | Change a design | **Edit**. If the design is live, Studio edits a copy, so shoppers see nothing until you publish. | | Try an idea without losing the original | **Duplicate** | | Test a new design against your live one to see which sells more | **Test against live** (Shopify only) | | Start from a suggested style, in your colours | **Use this design** | | Bring back an older design | **Restore to live** | | Rename a design | **Rename** | | Remove a draft | **Delete**. This does not change your store. | If a design is being tested, you cannot edit it. Click **Edit a copy** instead. ## Changed your store's look? If you have a new theme, colours or logo, click **New store look?** at the top. Studio looks at your store again and makes a design to match. Your current design stays live until you publish the new one. ## Try a design on your real store first Early access. Ask your SureBright contact to turn this on. You get a private link that opens your real store with your draft design in place. Only you can see it, so you can click around like a shopper. Nobody else sees the change until you publish. ## Related Ready-made designs you can start from. Choose which plan is already picked for shoppers. On Shopify, show two designs to different shoppers and see which sells more. On Shopify, give one theme or one kind of product page its own design. Where the offer sits, the pop-up after Add to cart, and other changes SureBright makes for you. --- # Team and access Source: https://docs.surebright.com/merchant-portal/team-and-access > How to sign in to the Merchant Portal on each platform, give a colleague access, work on another store, and remove someone. This page tells you how to sign in to the Merchant Portal, how to get a colleague in, and how to take access away. The portal has no team page and no invitations: access comes from your store platform, or from the sign-in SureBright gave you. ## Quick answers | You want to | Do this | | --- | --- | | Sign in on Shopify | Enter your **Store URL** and click **Sign in**, then approve in Shopify with your own Shopify login. | | Sign in on another platform | Open the portal from your store admin, or use the Store ID and password SureBright shared. See [How you sign in](#how-you-sign-in). | | Give a colleague access on Shopify | Have them sign in with the same **Store URL** and their own Shopify staff login. No invitation is needed. | | Give a colleague access on another platform | On BigCommerce and WooCommerce, give them access to your store admin. Magento and other password sign-ins have one sign-in for the store. See [Give a colleague access](#give-a-colleague-access). | | Give someone a limited view, such as finance only | Not available. Everyone who signs in sees the same pages. | | Work on another of your stores | **Sign out**, then sign in to the other store the way you sign in on its platform. On Shopify, that is with that store's **Store URL**. | | Remove someone | Remove their access to your store admin, then ask SureBright to remove them from the portal. | | Recover a lost password | Click **Need help? Contact support** at the foot of the sign-in page. | | Let an agency work on your store | Give them access through your platform, never your password. See [Agencies and developers](/platforms/store-access#agencies-and-developers). | | Work out which SureBright email or code you received | See [Emails and codes from other SureBright portals](#emails-and-codes-from-other-surebright-portals). | ## How you sign in | Platform | Steps | | --- | --- | | Shopify | Enter your **Store URL** (for example `mystore.myshopify.com`) and click **Sign in**. Shopify asks you to approve access, then returns you to the portal. Installing the SureBright app from your Shopify admin signs you in the same way. | | BigCommerce | Open the SureBright app from your BigCommerce control panel. See [BigCommerce](/bigcommerce/overview). | | WooCommerce | In the WordPress admin open the plugin's **Merchant Portal** page and click **Login**. You need no separate credentials. See [WooCommerce](/woocommerce/overview). | | Magento | Click **Login Now** on the SureBright page in your Magento admin, then sign in with the credentials SureBright shared with you. See [Magento admin panel](/magento/admin-panel). | If you sign in with a password, the form asks for **Store ID or email** and **Password**. The same form has **Continue with Shopify**, which asks for your **Shopify store URL** and takes you to Shopify instead. You land on this form after signing out. Good to know: - **No codes by email.** The Merchant Portal does not send one-time codes or magic links. Those are for your shoppers in the [customer portal](/customer-portal/overview). - **No password reset on the page.** Use **Need help? Contact support** at the foot of the sign-in page. - **First sign-in.** A newly installed store opens a short introduction first. A colleague who signs in later, once the store is set up, goes straight to **Sales**. See [Onboarding](/merchant-portal/onboarding). - **Permission requests.** On Shopify, a request to approve new app permissions appears when you sign in with your **Store URL**. See [Approve an updated permission request](/platforms/store-access#approve-an-updated-permission-request). - **Signing out.** Open the **Store** menu on the account card at the foot of the sidebar and choose **Sign out**. This signs you out of your other portal tabs too. ### Emails and codes from other SureBright portals The Merchant Portal never emails you a code. If you received one, or an invitation, it came from another SureBright portal: | You received | It is from | What to do | |---|---|---| | An invitation to join a team, with a link to sign up | The SureBright POS portal, sent when someone adds you to a store's team | Follow the link to set your password. That login also opens the Merchant Portal for owners whose account has one. See [Locations and team](/pos/locations-and-team). | | A code to finish signing up or to reset your password | The SureBright POS portal | Enter it on the **Enter the code** screen. | | A code to sign in to see a protection plan | The customer portal, where shoppers see their plans | You do not need it to manage your store. It was sent because someone asked to sign in with your email address. See [Customer portal](/customer-portal/overview). | If a POS code or invitation does not arrive, check your junk or spam folder, wait at least 30 seconds, then use **Resend Code** on the code screen, or ask the person who invited you to resend the invitation. If it still does not arrive, email [support@surebright.com](mailto:support@surebright.com) with the email address you signed up with. ## Give a colleague access The Merchant Portal has no **Team** or **Users** screen. What your colleague needs depends on your platform. | Platform | What to do | | --- | --- | | Shopify | Give them a Shopify staff account that can open your store's SureBright app. They then sign in to the portal with your **Store URL** and their own Shopify login. | | BigCommerce, WooCommerce | Give them access to your store admin. They open the portal from the SureBright app or plugin page there. | | Magento and other password sign-ins | You have one sign-in for the store, not one per person. | If a colleague cannot get in this way, SureBright adds people on request. Write to [support@surebright.com](mailto:support@surebright.com) with your store URL and the person's name and email address. ## Roles and permissions You cannot assign roles or limit a person to part of the Merchant Portal. There is no finance-only or design-only user: everyone who signs in to your store sees the same pages. Two actions are limited to the store owner or an admin: - Publishing prices in [Warranty Pricing](/merchant-portal/warranty-pricing). - Adding or changing [payment methods](/merchant-portal/billing#payment-methods). If you see **You do not have permission to manage payment methods**, ask the store owner to make the change, or contact support. The portal has no screen for viewing or changing who the owner and admins are. If a colleague is refused something they need, contact SureBright support. ## Work with more than one store Each sign-in opens one store. The account card at the foot of the sidebar shows which one, with its status and platform. - **Another store.** The portal has no store switcher. Choose **Sign out** from the **Store** menu, then sign in to the other store the way you sign in on its platform (on Shopify, with the other store's **Store URL**). - **Your store admin.** On Shopify and BigCommerce, **Open store admin** in the **Store** menu takes you there. - **Connecting a storefront.** Accounts set up to run several stores that have not connected a storefront yet see **Connect Store** in Settings. See [Connecting a storefront](/merchant-portal/settings#connecting-a-storefront). - **Adding a store later.** You can go live on one store and add others when you are ready. Each store is installed and reviewed on its own, and its design and plan prices are set for that store. Tell your SureBright contact which store comes next and whether it should match the first. If different stores should pay from different accounts, see [More than one store or account](/merchant-portal/payment-methods#more-than-one-store-or-account). - **The POS portal.** If you also use the SureBright POS portal, **Switch to POS portal** appears in the **Store** menu. The POS portal is a separate product where you can invite staff and give each a role per store. See [Locations and team](/pos/locations-and-team). ## Remove someone's access The Merchant Portal has no button for removing a person. Take access away where it was given: | Platform | What to do | | --- | --- | | Shopify | Remove or restrict the person's staff account in your Shopify admin. Without it they cannot sign in to the portal again. | | BigCommerce, WooCommerce | Remove their access to your store admin. | | Password sign-ins | Ask SureBright to change the password. | SureBright removes people on request. Email [support@surebright.com](mailto:support@surebright.com) with your store URL and the name and email address of the person who should no longer have access. ## Related Signing in, the sidebar, your store card and where to get help. Contact details, store details and connecting a storefront. App permissions, collaborator requests and agency access. The POS portal's stores, invitations and roles. A different product. How to reach the team and what to include. --- # Template gallery Source: https://docs.surebright.com/merchant-portal/template-gallery > Ready-made designs for your protection plan offer. Pick one, Studio puts it in your colours, change what you like, and publish. On Shopify, you can test a design on your shoppers first. A good-looking offer helps shoppers trust it, but you do not have to design one from scratch. The template gallery gives you ready-made designs to start from. Each template is a complete, tested look for the protection plan offer on your product page. It sets how the plans are laid out, the corners, the badge, how the picked plan looks, and the "What's covered?" box. You pick one, Studio puts it in your brand, and you publish. You do not need code, a developer or a design file. The gallery is in [Studio](/merchant-portal/studio). SureBright turns Studio on for your store when you ask. Ready-made designs that show plans as cards, rows or a dropdown. Your colours, font, corners and logo, taken from your own store. You can change them. On Shopify, try a design on real shoppers next to your live one before you switch. | You want to | Go to | | --- | --- | | See what designs there are | [What is in the gallery](#what-is-in-the-gallery) | | Find the gallery in Studio | [Where to find the gallery](#where-to-find-the-gallery) | | Know how a template gets your colours | [Every design comes in your brand](#every-design-comes-in-your-brand) | | Change a design to match your brand | [Change a design without code](#change-a-design-without-code) | | Find out if a design sells more plans before you switch (Shopify only) | [Test a design on your shoppers first](#test-a-design-on-your-shoppers-first-shopify-only) | | Go from the gallery to your live store | [From gallery to live in five steps](#from-gallery-to-live-in-five-steps) | ## What is in the gallery Templates are grouped by how the plans are laid out. Each group has several looks. SureBright adds new designs once they have worked well on other stores. Studio always shows the latest set. | Layout | Looks you will find | Good for | | --- | --- | --- | | **Side by side cards** | Several card styles: classic, compact, two-line, pill-shaped, a filled card for the picked plan, cards in a panel with short benefit labels, and cards with a short note under each price. | Product pages that show sizes or colours as tiles or swatches. | | **Stacked rows** | Roomy rows with the price on the right, and a tighter list. | Narrow pages, long product pages and phones. | | **Dropdown menu** | All plans folded into one dropdown list. | Stores that already use dropdowns for sizes or colours, or want the offer to take up the least space. | A template is only a starting point. You can change everything in [Change a design without code](#change-a-design-without-code) after you pick one. ## Where to find the gallery | Where | What you see | | --- | --- | | **Your first visit** | Before Studio looks at your store, **Starting layout** lets you choose the template your first design is built from. If you skip it, Studio's AI chooses for you. | | **The Templates row** | Every template as a live preview. The one Studio recommends for your store is marked **SUGGESTED**. Click one to use it. The one you picked shows **Selected**. | | **Recommended for your store** | Studio's own AI design first, marked **AI pick**, then the gallery in your store's colours. **Try this design** saves one as your own draft (a design shoppers do not see yet) and shows it on your product page. | | **The Designs tab** | **Recommended** templates next to your live design, your drafts, and designs you had live before. **Use this design** saves one as a draft. **Test against live** starts a test with it (Shopify stores). | ## Every design comes in your brand You never see a template in SureBright's colours. Studio looks at one of your product pages and uses what it finds in every design. - **Colours.** Your brand colour, button colour and the outline of the picked plan show in every template preview. So you compare looks, not colours. - **Font and corners.** The offer uses the same font and corner shape as the rest of your page. - **Your store name and logo.** The "What's covered?" box shows your store's name and, if you add one, your logo. - **Your own page.** Each design is shown on a picture of your real product page, on a computer screen and on a phone. Picking a different template changes only the layout. Your colours and words stay the same. So you can try five looks in a minute without redoing your brand settings. If your store's look changes, click **New store look?** in Studio. Studio looks at your store again and picks up new colours, a new font or a new logo. Your live design stays as it is until you publish. ## Change a design without code Every brand setting has its own control in Studio. You change it, the preview updates, and nothing changes on your store until you publish. | You want to | Where in Studio | | --- | --- | | Use your exact brand colours | **Colors**. Pick a colour taken from your store, or type its colour code. Studio warns you when a heading would be hard to read on your page. | | Switch between light and dark | **Colors › Theme**. | | Show plans as cards, rows or a dropdown | **Layout & style**: **Side by Side Cards**, **Stacked rows** or **Dropdown menu**. | | Make corners square, soft or round | **Layout & style › Corners**. | | Make the picked plan filled in or outlined | **Layout & style › Selected plan**. | | Show short benefit labels under the plans | **Layout & style › Benefit pills**. You can set their shape and size. | | Make the text, badge or price bigger or smaller | **Text size**. Each one has a reset. | | Mark a best seller, or show the price per month or as a % of the product price | **Plans**. | | Offer two kinds of cover as tabs | SureBright turns this on per store. See [Dual coverage tabs](/shopify/dual-coverage). | | Choose which plan is already picked | **Plans › Default Selected Plan**. See [Default plan selection](/merchant-portal/default-plan-selection). | | Change the "What's covered?" box and add your logo | **Coverage popup**. | | Change the phone view on its own | Switch the preview to **Mobile**. Phone-only settings change only the phone view. | You can undo and redo your last 50 steps. **Save draft** keeps unfinished work. Every design you publish is kept as a numbered version you can bring back. The full list of controls is on the [Studio](/merchant-portal/studio#change-how-the-offer-looks) page. You can design without code on every platform. Getting the offer onto your store depends on your platform. On Shopify, you turn on a switch in your theme editor. Other platforms have their own setup guide. ### Different designs for different parts of your store One store can use more than one design. With [Design targeting](/merchant-portal/design-targeting), you publish a design for one Shopify theme (store design) or one kind of product page. Every other page keeps your live design. Use it for a premium range, a seasonal look, or a theme you have not launched yet. ### When the gallery does not have your look If your brand needs something the gallery and Studio cannot make, tell your SureBright contact. SureBright also sets the words in the offer (the heading, the line under it and the text in the "What's covered?" box) when you ask. ## Test a design on your shoppers first (Shopify only) A template that works for another store may not work for yours. On Shopify, Studio lets you try it on your own shoppers instead of guessing. Design tests are not available on other platforms. On any draft or recommended template, click **Test against live**. Your live design is what you compare against. The template is the new design you are trying. Studio lists every setting that is different between the two. Send anywhere from 10 to 90 percent of shoppers to the new design. Each shopper sees the same design on every page and every visit while the test runs. Studio compares, for each design, the share of orders that added a plan (out of orders that could have had one). It tells you if one design is a **Clear winner**, shows an **Early signal**, or if there is **No winner yet**. Next to it, Studio shows the plan money brought in per order that could have had a plan. Click **Make this design live**. The test ends and every shopper sees the winning design. If your current design did better, nothing changes. Studio also suggests which templates to test, using your store's own numbers where it has them. For example: a design that sold more when it was live, a test you won but never published, a gap between phones and computers, or something your live design is missing, such as a best-seller badge. Each suggestion leads to a test, because a test is the only way to know what works on your store. The rules, the controls and how the winner is chosen are on [Design tests](/merchant-portal/design-tests). SureBright measures the share of orders that added a plan on Shopify only, so tests run only there. ## From gallery to live in five steps Studio looks at one of your product pages and makes a first design in your brand. Open **Templates** and click through the looks. Each one is shown on your own page. Change colours, corners, text size, the badge or the "What's covered?" box until it matches your brand. Click **Publish changes** to make it live straight away. On Shopify, you can instead click **Test against live** to try it on real shoppers first. Try the next recommended design. You can bring back an older version at any time. On Shopify, see [Design performance](/merchant-portal/design-performance) for how each design sells. ## Related Every control in Studio, plus saving, publishing and going back to an older design. On Shopify: run a test, choose how many shoppers see each design, and see how the winner is chosen. On Shopify, a different design for one theme or one kind of product page. On Shopify: how each design sells, on computers and on phones. --- # Warranty Intelligence Source: https://docs.surebright.com/merchant-portal/warranty-intelligence > See where protection lifts your order value, where sales are being missed, which orders have a plan sold but no contract yet, and what to act on first. **Warranty Intelligence**, in the [Merchant Portal](/merchant-portal/overview), tells you where protection is lifting your order value, where you are missing sales, and what to act on first. It builds on the figures in [Sales](/merchant-portal/sales) and is available on request: once SureBright switches it on, a card on the Sales page opens it, or go to **Sales → Warranty Intelligence**. | You want to | Look at | | --- | --- | | Know how protection is doing overall | [The five headline numbers](#the-five-headline-numbers) | | Find the biggest thing to fix or repeat | [Find where you are missing sales](#find-where-you-are-missing-sales) | | See whether things are getting better | [Track a metric over time](#track-a-metric-over-time) | | Sort out orders where a plan was paid for but has no contract | [Orders missing contracts](#orders-missing-contracts) | | Compare channels, devices, countries or price ranges | [Explore every breakdown](#explore-every-breakdown) | The page uses the same period selector as Sales (**Last 7 days**, **Last 30 days**, custom dates and so on) plus a comparison selector (**Previous period** and the other comparison periods the chosen period allows). Every number is compared with that period. ## The five headline numbers Five tiles across the top, each with a small trend line for the period and a change against the comparison period. Hover a tile to see how it is counted. | Tile | What it answers | |---|---| | **Attach rate** | Orders that added a protection plan, out of orders that could have. The line beneath reads *N of M eligible orders* | | **AOV lift from warranties** | Plan revenue spread across every order: the direct boost plans give your average order value, in money per order and as a share of AOV | | **Warranty sales** | What customers paid for plans at checkout in the period, with how many were *sold* and how many are *activated so far*. On stores where plans start when the order ships, the activated figure runs behind the sold one; that is expected | | **Avg warranty value** | Average price paid per plan | | **Bought at checkout** | Share of plans bought in the original order and not later. When there are post-purchase buyers it adds how many days they typically take | ## Find where you are missing sales **Insights & opportunities** shows cards ranked by estimated impact, each labelled **Issue**, **Opportunity** or **Working well**, with a one-line recommendation and, where it can be sized, *up to +$X this period*. Examples of what the cards say: - a sales channel, device, country or product type that attaches far below your overall rate, with the revenue that closing the gap would add; - price ranges where plans are a hard sell; - *Almost all warranty sales happen at checkout*, when post-purchase buyers are a small share of plans (see [Offer links](/post-purchase/offer-links)); - the second half of the period converting better or worse than the first; - your strongest audience, for example refurbished-item buyers. The top three show by default; **Show N more** expands the rest. **View evidence ↓** on any card jumps to the Explorer tab that holds the numbers behind it. ## Track a metric over time **Performance over time** is one line chart with a metric picker: **Attach rate**, **AOV lift per order**, **Warranty revenue** or **Basket gap (with vs without)**, the difference in basket size between orders with and without a plan. The comparison period is the dashed line, lined up day by day. Beside it, **Observations** lists plain facts about the period, for example the average basket with and without a plan, the share of orders placed on mobile and how attach runs there, which product type sells the most protection, and which coverage type customers prefer. Each has a **detail ↓** link into the Explorer. ## Orders missing contracts This section lists orders in the period where a customer paid for a plan but the plan has no contract yet, grouped by what is holding it up. Switch between **Product protection** and **Shipping protection**. The tiles read **Orders missing contracts**, **Revenue held up** (collected from customers, with no contract yet) and **Needs your attention**. Each reason expands into the affected orders, with the order number (on Shopify stores, linked to the order in your Shopify admin where available), date, channel, plan, covered product and **What the pipeline reported**. Expand an order to see all of its line items with their fulfillment status. | Reason | Status | What to do | |---|---|---| | **Fulfillment hasn't happened yet** | **Waiting** | Nothing. On your store plans start when the order ships, so the list clears as orders ship. See [Fulfillment](/merchant-portal/fulfillment) | | **Warranty meta properties missing** | **Action needed** | The plan was added to the order without the link to the item it covers. This usually happens when the plan line is added by hand or through a custom checkout. Add the plan again through the SureBright widget, or have your developer add the covered-product reference to the line | | **No covered product details** | **Action needed** | SureBright cannot find the product the plan covers: its SKU changed after purchase or it was deleted. Restore the product or correct its SKU | | **Plan sold on a bundle's constituent** | **Action needed** | The order holds a bundle but the plan points at a product inside it. Offer protection on the bundle itself, or sell it per item in the bundle | | **Shipping carrier not recognized** (shipping only) | **Action needed** | The carrier named on the shipment is not one SureBright supports, so the shipment cannot be protected. Use a supported carrier name, or ask SureBright to add the carrier | | **Policy not live** | **Action needed** | A plan was bought while its policy is not live for your store. Contact SureBright | | **Processing error, retrying** | **Retrying** | A temporary error. SureBright retries these by itself; contact support if an order stays here for days | For shipping protection the first three read **Order hasn't shipped yet**, **Shipping meta properties missing** and **No eligible items in the shipment**, because shipping protection always starts when the order ships. ## Explore every breakdown The **Explorer** holds every breakdown behind the numbers above, one tab per question. Each tab opens as a compact chart with a **Table** toggle for the exact figures, and marks your overall attach rate as the benchmark. | Tab | What it shows | |---|---| | **Channels** | Attach rate by sales channel (online store, POS, marketplaces, social, draft orders) | | **Product types** | Attach rate by product type, with each type's plan volume | | **Condition** | Attach rate by product condition: new, refurbished, open box, used | | **Geography** | Attach rate by the customer's country | | **Devices** | Attach rate by the device the order was placed on. If one device lags, review how the widget looks there | | **Price bands** | How willingness to buy a plan changes with the item's price: **Under $50**, **$50 to $150**, **$150 to $400**, **$400 to $1,000**, **Over $1,000**, with the average plan price and the plan as a share of the item price | | **Coverage** | Which coverage type customers pick (**Breakdown** or **Accidental damage**), by product type | | **When people buy** | Plans bought **At checkout** versus in the days and weeks after the order, with the typical (median) delay for late buyers | | **Competitors** | Competitor protection products found in past orders, and how SureBright's share of protected orders has moved since | Segments with too few eligible orders are not compared, so a small channel cannot swing a conclusion. A **Sample data preview** badge next to the title means the page is showing generated sample data and not your store's numbers. Ask your SureBright contact if you see it on a store that should be live. ## Related The dashboard and list of sales these figures build on. Orders still waiting on a shipment before their plan starts. --- # Warranty Pricing Source: https://docs.surebright.com/merchant-portal/warranty-pricing > Set the protection plan prices your shoppers see, per category and per product, publish them when you are ready, and see how each price performed. **Warranty Pricing** lets you set what shoppers pay for protection plans, per product category and, when a product needs its own price, per product. It appears in the [Merchant Portal](/merchant-portal/overview) sidebar once SureBright has switched it on for your store. Available on request. Nothing changes for shoppers until you review and publish. Every publish is kept as a version, and the page shows how each version sold. | You want to | Do this | | --- | --- | | Change the price of a plan for a whole category | [Set prices for a category](#set-prices-for-a-category) | | Price one product differently | [Give one product its own price](#give-one-product-its-own-price) | | Go back to SureBright's price | Click **Reset** on the price under **Price Variants**, or **Remove** on a product price. | | Know whether a price change helped | [See how each price performed](#see-how-each-price-performed) | | Run a promotion for a set time | [Run a temporary promotion](#run-a-temporary-promotion) | | Find out why a shopper sees a different price than you expected | [Questions about plan prices](#questions-about-plan-prices) | ## Who can publish prices Anyone with portal access can open the page and its analytics. Publishing prices is limited to the store owner or an admin; a publish by anyone else is refused. See [Team and access](/merchant-portal/team-and-access). ## Set prices for a category Tabs at the top switch between the countries your store sells protection in (for example **US** and **CA**). The page says so under the tabs: all prices below apply to that country's customers only. Under **Category Rules**, pick a category chip. The page shows the **Pricing strategy** on the left and **Preview, what customers will see** on the right. | Strategy | What it does | | --- | --- | | **SureBright rate card** | The default. Shoppers see SureBright's base price everywhere, except where you have set a price of your own. | | **Manual Pricing** | Lets you edit individual prices in the preview grid. Each edit is listed as a named price variant. | The preview is a grid. Rows are **price bands**: fixed ranges of product price. A product's price decides its band, and the price in the band applies to every product in it unless the product has its own price. Columns are the plan terms the category offers (**1Y**, **2Y**, **3Y** and so on). Each cell shows the price a shopper sees; a cell you have repriced is labelled **version N (date)** or **price variant**. **Price Variants** lists every price you have set yourself, with the base price beside it and a **Reset** that returns it to the rate card. Your price variants are kept when you change strategy. Under **Manual Pricing**, click a cell and type the new price. The preview heading counts **N cells changing**. **Discard** drops the edits you have not published. Each cell has a lowest price. The page refuses to publish while any edited cell is under it (**Can't publish**) and names the cells. A price at or above the lowest price but under the SureBright base price can be published, with a **Heads up** warning that you are giving up part of your own share on it. Click **Review & publish**. The review lists each change as band and term, old price to new price. Click **Publish**. A chip reads **Updating prices…** until shoppers can see and buy plans at the new prices, then **Live ✓**. **Publish effects failed** means your prices were saved but your storefront has not picked them up; contact support. ## Give one product its own price Open **Product Rules**, search products by title and pick one. The page shows which category and country the product takes its prices from. What you set here applies to this product only. - **Inherited pricing** (the default): the product uses its category's prices, or the rate card. - **Manual Pricing**: edit prices in the product's grid, one row per variant with its product price and one column per term. **Remove** takes a product price away, with **Undo** until you publish. Shoppers see the product's own price if it has one, otherwise the category price, otherwise the rate card. The same lowest price and the same **Review & publish** steps apply. ## How price versions work The base price is version 1 of every price. Each publish that changes a price adds a version, labelled with its publish date. Product prices have their own versions, labelled by product. One publish makes one version for everything it changed, so the time from one publish to the next is the period the analytics below compare. ## See how each price performed | Where | What it shows | | --- | --- | | **Analyze** (on a category) | Pick a date range. Attach rate and your revenue per day for the category, and **Term preference**: which plan terms shoppers chose. | | Trend icon beside a band | **How each price version performed for this band**: for every term, each price version's attach rate and your revenue per day it was live. | | Compare icon in a repriced cell | **Attach rate comparison** between that cell's price versions, with the difference in points. Versions with too few offers are flagged **Some versions need more data**. | | **Analyze** (on a product) | Policies sold and your revenue for plans that cover the product, over a date range. | Attach rate here is plans bought out of offers shown, counted for each product and each plan term on offer. It never goes above 100 percent. ## Run a temporary promotion Prices do not switch back by themselves on a date. To run a promotion: Edit the prices and click **Review & publish**. They apply once the chip reads **Live ✓**. Note the date the promotion should end. Click **Reset** on each price under **Price Variants** (or **Remove** on a product price), then **Review & publish** again. Each publish is kept as a version, so you can compare the promotion with the prices before it. The wording on the plan buttons, such as the plan names, is set by SureBright. To change it for a promotion, ask your SureBright contact, give them the start and end dates, and ask how much notice they need. If **Warranty Pricing** is not in your sidebar, ask your SureBright contact to change prices for you. ## Questions about plan prices ### Why is the plan price on my site different from what I expected? | What you notice | Why | What to do | | --- | --- | --- | | The price changed when the product price changed | A plan's price comes from the product's [price band](/contracts/what-can-be-covered#price-bands). A new product price can move it into another band. | Check the band in the grid, or **View Pricing** on the product in [Products](/merchant-portal/products#see-the-prices-shoppers-are-offered). | | A shopper in another country or currency sees a different price | On Shopify Markets, the plan is priced from the product's price in the shopper's market. | See [Shopify Markets pricing](/shopify/markets). | | You published a new price and shoppers still see the old one | The new price applies once the chip reads **Live ✓**. | Wait for **Live ✓**. If you see **Publish effects failed**, contact support. | | The plan price on a bundle changed | A bundle's plan price is the plan prices of its covered components added up. | See [Bundles](/shopify/bundles). | | A plan name on the site does not match a row on your price sheet | Some plans are named by the years they add to the manufacturer's warranty, for example **+2 Year**, while a price sheet can list the total years of cover. | Ask your SureBright contact which row the plan matches. | | You changed the price of a SureBright plan product in your store admin | Plans stop working when those products are repriced or edited. | Do not edit them. Ask support to restore them. See [Offer not showing](/help/offer-not-showing). | If you think shoppers were offered the wrong price, send support the product, the price shown and the date, and say what you expected. Support checks it and tells you what happens next. ### How are plan prices set? - **By category.** Each product is in a SureBright category, which decides the plans and terms it can have. The category names group products that are covered the same way, so a product can sit in a category whose name does not describe it exactly. Check or change a product's category in [Products](/merchant-portal/products#change-a-products-category). - **By price band.** Within a category, the product's price picks the band, and the band sets the price of each term. - **By term.** Each term is priced on its own, so a longer term does not cost a fixed amount more per year. - **By country.** US and Canadian prices are set separately. The tabs at the top of this page switch between them. ### How do I get my full price list? Open the grid on this page: each row is a band and each column a term, per category and country. Without **Warranty Pricing**, use **View Pricing** on a product in [Products](/merchant-portal/products#see-the-prices-shoppers-are-offered), or ask your SureBright contact for a price list. Ray, the portal assistant, can read your price grid, check the status of a publish, and publish category or product prices after you confirm. See [Ray](/merchant-portal/ray). ## Related See the plan prices shoppers are offered on each product. Who can publish prices and manage payment methods. --- # What you can change on your widget Source: https://docs.surebright.com/merchant-portal/widget-options > See which changes to the SureBright offer on your store you make yourself in Studio, which ones SureBright makes for you, and how to ask. The SureBright widget is the box on your product page that offers shoppers a protection plan. When it fits your store and sits in the right place, more shoppers notice it and add a plan. This page answers "can we change this on our widget?" Some changes you make yourself in [Studio](/merchant-portal/studio). SureBright makes the rest for you when you ask. Either way, you never need to change your store's code. ## What you can change, and who does it | You want to | Who does it | Go to | | --- | --- | --- | | Change colours, layout, corners, text size or the plan boxes | You, in Studio | [Studio](/merchant-portal/studio) | | Choose which plan is already picked, or show a **No coverage** choice | You, in Studio | [Default plan selection](/merchant-portal/default-plan-selection) | | Add your logo next to SureBright's in the "What's covered?" box | You, in Studio | [The SureBright logo](#remove-or-relink-the-surebright-logo) | | Turn protection on or off for a product | You, in **Products** | [Products](/merchant-portal/products#turning-protection-on-or-off) | | Move the widget, for example below **Add to cart** | SureBright | [Move the widget](#move-the-widget-on-the-product-page) | | Make it look different on phones | Partly you, partly SureBright | [Change how it looks on phones](#change-how-it-looks-on-phones) | | Add or remove a place where the offer shows, such as the cart page | SureBright | [Where the offer can appear](#where-the-offer-can-appear) | | Turn the pop-up after **Add to cart** on or off | SureBright | [The add-to-cart pop-up](#turn-the-add-to-cart-pop-up-on-or-off) | | Change the words, or how plan length is written | SureBright | [How plan length is shown](#how-plan-length-is-shown) | | Show the maker's warranty that already comes with the product | Partly you, partly SureBright | [Show the included manufacturer warranty](#show-the-manufacturer-warranty-that-is-already-included) | | Try the offer on one product or one page first | Partly you, partly SureBright | [Try it on one product or page first](#try-it-on-one-product-or-page-first) | To ask SureBright for a change, see [How to ask for a change](#how-to-ask-for-a-change). ## Move the widget on the product page The widget sits next to your **Add to cart** button. At first it sits above the button, so shoppers see the plans before they add the product. SureBright can move it: | Where | What that means | | --- | --- | | Above **Add to cart** | Where it starts. | | Below **Add to cart** | Under the button, before the rest of the buying area. | | Somewhere else on the page | Next to a part of the page you name, for example a block your developer has added. | You cannot move the widget in Studio. Send SureBright the product page link and say where it should go. SureBright may suggest keeping it above **Add to cart**. They may also ask someone who can approve changes to your store to confirm the move. If you use the [Claude connector](/ai-agents/merchant-connector), you can also ask it to move the widget. The change waits in a draft (a saved change shoppers do not see yet) until you approve it. ### Change how it looks on phones | You want to | Do this | | --- | --- | | See how the widget looks on a phone | In Studio, switch the preview to **Mobile**. | | Make the widget smaller on phones | Ask SureBright. | | Hide the **Remove** link on phones | In Studio, set **"Remove" on phones** to **Hide**. | | Show one short line on phones that opens the plans in a pop-up | Ask SureBright. The line shows a heading and a **What's covered?** button. | | Write plan length in a shorter way on phones | Ask SureBright. Plan length can be written differently on phones and computers. | | Put the widget somewhere else on phones only | Ask SureBright. | ## Where the offer can appear Each place below is turned on or off for your store on its own. Turning one off does not change the others. For example, SureBright can remove the **Add Warranty** button from your cart page and keep the offer on your product pages. | Place | What the shopper sees | Who turns it on or off | | --- | --- | --- | | Product page | The plans next to **Add to cart**. | SureBright | | Quick view (a small product window some stores open from a list of products) | The same plans inside that window. Pages that list many products never show the offer. | SureBright | | Pop-up after **Add to cart** | The plans in a pop-up when the shopper adds a product without a plan. See [below](#turn-the-add-to-cart-pop-up-on-or-off). | SureBright | | "Added to cart" message | An offer for the product just added, inside the message your store already shows. | SureBright | | Cart page | An **Add Warranty** button next to each product that has no plan. | SureBright | | Bottom of the cart | One switch that covers the whole cart. | SureBright | | Side cart (a cart that slides out from the side) | The cart offers inside it. | SureBright | | Change plan in the cart | A link on the plan line so the shopper can pick another plan length. | SureBright | | Buy-now and fast checkout buttons | The plan goes with the product when a shopper skips the cart. | SureBright | | Checkout, on Shopify Plus | A protection box inside checkout. | You add it in Shopify's checkout editor. See [Checkout extensions](/shopify/checkout-extensions). | | Order confirmation page | A pop-up offering plans for what the shopper just bought. | SureBright | | A landing page or home page that sells a product | The product page offer, on a page that has its own **Add to cart**. | SureBright | | Product registration page | A page where customers buy a plan for something they already own. See [Product registration pages](/shopify/product-registration). | SureBright | | Shipping protection | A tick box or button next to your checkout button. See [Shipping protection](/shipping-protection/overview). | SureBright. You choose how it looks in Studio. | Not every place works on every platform. See [What works on each platform](/platforms/overview#what-works-on-each-platform). ## Turn the add-to-cart pop-up on or off This pop-up opens when a shopper adds a product to the cart without a plan. It shows the plans and a button to say no. That button reads **No, Thanks** unless your store uses other words. | You want to | What happens | | --- | --- | | Turn the pop-up on | Ask SureBright. It stays off until SureBright turns it on for your store. | | Turn the pop-up off | Ask SureBright. Shoppers can still pick a plan on the product page and in the cart. | | Change the words on the "no" button | Ask SureBright. | | Stop it opening from one button, for example an **Add to cart** button for an accessory, or the first of two buttons | Send SureBright the page link and say which button. SureBright can limit the pop-up to the buttons you want. | How it works: - It opens only when no plan is picked. A shopper who already picked a plan is not asked again. - A shopper who picked **No coverage** on the product page still sees it after **Add to cart**. The pop-up shows only the plans. - If the shopper closes it, or says no, the product goes into the cart without a plan. The product is always added. Not sure the pop-up helps your store? Compare the share of orders that added a plan before and after, or ask SureBright about a test. See [Reading your attach rate](/learn/attach-rate). ## How plan length is shown Plan length can be written in more than one way. SureBright sets this for your store. Ask your SureBright contact to change it. | Style | How a 2-year plan reads, on a product that already has a 1-year maker's warranty | | --- | --- | | Years added | **+2 Year** | | Plain years | **2 Years** | | Total cover | **3 Year Total** | | Both parts | **1 Yr Manufacturer + 2 Yr Protection** | SureBright can also add words after the length, for example "Extended Warranty". They can use a different style on phones or for one kind of plan. ### Why the length differs between your product page and the Merchant Portal Your product page may show the total length, with the maker's warranty included. **Sales** in the Merchant Portal shows only the length of the SureBright plan. So **3 Year Total** on the product page and a 2-year plan in **Sales** are the same plan. The customer's confirmation email can show both parts, for example `12 months manufacturer warranty + 24 months extended warranty`. See [Customer emails](/customer-emails/overview). ## Show the manufacturer warranty that is already included Some shoppers think a product has no warranty unless they buy a plan. You have three ways to show the maker's warranty that already comes with it. | You want to | Who does it | | --- | --- | | Show a timeline in the "What's covered?" box: how long the maker covers the product, and how much longer the plan adds | You, in Studio. Open **Coverage popup** and set **Manufacturer warranty** to **Show timeline**. | | Include the maker's warranty in each plan's length, for example **3 Year Total** or **1 Yr Manufacturer + 2 Yr Protection** | SureBright. See [How plan length is shown](#how-plan-length-is-shown). | | Rename the **No coverage** choice so it names the warranty already included, for example "1 Year Manufacturer Warranty" at no charge | SureBright. The choice must be shown first: see [The No coverage choice](/merchant-portal/default-plan-selection#show-or-hide-the-no-coverage-choice). | The maker's warranty length comes from the product. If a product shows a **Mfr warranty** label in **Products**, set the length there. See [Set the manufacturer warranty length](/merchant-portal/products#set-the-manufacturer-warranty-length). If your refurbished products have a different maker's or seller's warranty from new ones, tell your SureBright contact. Then the offer shows the right length. ## Remove or relink the SureBright logo The SureBright logo tells shoppers who provides the plan. It shows on the widget and in the "What's covered?" box. | You want to | Do this | | --- | --- | | Show your own logo too | In Studio, open **Coverage popup** and enter a **Brand logo URL** (the web link to your logo image). Your logo shows next to SureBright's. Leave it empty to show only SureBright's. | | Change where the logo goes when clicked | Ask SureBright. At first it opens a SureBright page about what the plan covers, in a new tab. If there is no such page, it opens SureBright's website. SureBright can send it to a different page about what is covered, or make it open the **What's covered?** pop-up. | | Remove the logo | Ask your SureBright contact. SureBright asks stores to keep it, so it is removed only if you both agree. | ## Try it on one product or page first You do not have to start everywhere at once. Pick the way that suits you. | You want to | Do this | | --- | --- | | Offer protection on a few products only | In **Products**, set **Warranty status** to **Active** for those products and **Inactive** for the rest. See [Products](/merchant-portal/products#turning-protection-on-or-off). | | See the offer on your store before shoppers do, on Shopify | Turn SureBright on in a theme (your store's design) that is not live yet, and look at a product page. See [Storefront setup](/shopify/storefront-setup). | | Click through a Studio draft on your real store | Use a private preview link. Early access: see [Try a design on your real store first](/merchant-portal/studio#try-a-design-on-your-real-store-first). | | Give one theme or one kind of product page its own design, on Shopify | Use [Design targeting](/merchant-portal/design-targeting). Early access. | | Show the offer only on a landing page, or a page people reach from a direct link | Ask your SureBright contact. | | Approve a layout before it goes live | Ask your SureBright contact for other layouts, or make them yourself as Studio drafts. Nothing changes on your store until you publish. | Before you show the offer to everyone, place one test order. See [Test your setup](/platforms/test-your-setup). ## Shipping protection options | You want to | Who does it | | --- | --- | | Pick a tick box or button, and its colours | You, in Studio. See [Change the shipping protection offer](/merchant-portal/studio#change-the-shipping-protection-offer). | | Have it already ticked | The tick box is already ticked the first time a shopper sees it. With a button, the shopper has to choose it. See [Shipping protection](/shipping-protection/overview#cart-page-widget). | | Change its words, for example to "Strongly recommended" | Ask SureBright. SureBright sets the words. | | Add it by itself for one product only | Ask your SureBright contact if this can be set up for your store. | | Choose which products count towards it | You, in **Products**. See [Products](/merchant-portal/products#choose-which-products-count-towards-shipping-protection). | ## Accessibility The widget works for shoppers who use a keyboard instead of a mouse, or a screen reader (software that reads the page out loud). - Shoppers can move between plans with the arrow keys and pick one with the Space key. - Screen readers read the plans as a list of choices and say which one is picked. - While a pop-up is open, the keyboard stays inside it. When it closes, the shopper is back where they were. - Moving effects are reduced for shoppers whose device asks for less motion. - The screen reader can also say out loud when a plan is added or changed. Ask your SureBright contact to turn this on. If you find something a keyboard or screen reader user cannot do, email [support@surebright.com](mailto:support@surebright.com). Include the page link, the web browser, and the tool the shopper uses (for example, which screen reader). ## How long changes take to appear | Change | When shoppers see it | | --- | --- | | You publish a design in Studio | Straight away. | | SureBright changes something for you, such as where the widget sits or the pop-up | As soon as SureBright has made the change. Your contact tells you when it is done. | | You turn protection on or off for a product | Not straight away. It can take a few hours. If nothing has changed by the next day, ask your SureBright contact. | | Any change, for a shopper who visited recently | Their browser can keep showing the old offer for up to two hours. To check, open your store in a private window. | | On Magento | Also clear the stored copy of your pages (the full-page cache). See [Storefront widget](/magento/storefront-widget). | ## How to ask for a change Email [support@surebright.com](mailto:support@surebright.com) or your SureBright contact with: - Your store's web address. - A product page link, or the page where the change applies. - What you want. For example: "move the widget below Add to cart on phones only" or "turn off the add-to-cart pop-up for the accessory button". - If it is about where things sit, a screenshot with the spot marked. - Whether it is for every product or only some. ## Building your own offer Most stores use the offer SureBright shows for you. This works on supported platforms, and on custom stores that load SureBright's code. You choose the colours and layout in Studio, where Studio is available. SureBright sets where it sits, the words, and which places show it, when you ask, as this page explains. Some stores have their developers build the offer themselves, or sell plans inside a phone app. If that is you, talk to SureBright before you start. Your developers will find the details below. | Your set-up | How much you control | | --- | --- | | You want to draw the offer yourself | Your developers can get plans and record sales through the SureBright API, and design the offer as they like. Shoppers must still be able to see the plan's price and remove it. Ask SureBright before you add plans automatically or at no charge. See [Integrate with the API](/api-reference/integration-tutorial). | | A native mobile app | The SureBright widget runs on your storefront's web pages, not inside a native app. To sell plans in an app, your developers use the SureBright API. A plan line added in your app without SureBright's details does not become a plan, so talk to SureBright before you build. | If you draw the offer yourself, SureBright's reports, such as attach rate per design, only see the offer views and clicks your developers send. See [Event Collector](/frontend-widget-integration/frontend-widget-kit/event-collector). ## Related Change colours, layout, the plan boxes and the "What's covered?" box. Choose which plan is already picked, and show a No coverage choice. Step-by-step checks when the offer, or the plan in the cart, is missing. What to check after a new store design or a new side cart. **See also:** [Request an accessibility review](/help/security-and-compliance#request-an-accessibility-review). --- # After a theme or platform change Source: https://docs.surebright.com/platforms/after-a-theme-or-platform-change > What to check on each platform so the SureBright offer keeps showing after you publish a new theme, redesign your storefront, change your domain, or move your store to another platform. A new theme or a new platform can make the protection offer disappear without any error. This page says what to check before and after the change, and what to ask SureBright for when you move platform. | You are | Go to | |---|---| | Publishing a new theme on Shopify | [Publish a new theme on Shopify](#publish-a-new-theme-on-shopify) | | Redesigning your storefront or changing its domain on Magento, BigCommerce, Shift4Shop or WooCommerce | [Other platforms: theme and domain changes](#other-platforms-theme-and-domain-changes) | | Moving your store to a different platform | [Moving to another platform](#moving-to-another-platform) | | On a platform not listed here | Ask your SureBright contact before you make the change. | ## Publish a new theme on Shopify On Shopify, SureBright is switched on per theme. A new theme does not show the offer until the **SureBright Offering** app embed is turned on in it, so publishing one can remove the offer from your store. ### Before you publish a Shopify theme | You want to | Do this | |---|---| | Have the offer ready the moment the theme goes live | In the Merchant Portal open **Settings → Storefront setup**. Find the new theme, listed as **Not published**, click **Turn on in Shopify ↗**, check the **SureBright Offering** switch is on and **Save**. Shoppers see nothing until you publish the theme. | | See the offer on the new theme | Open a product that offers protection in the theme editor preview and look near **Add to cart**. | | Give the new theme its own widget design before launch | Use [Design targeting](/merchant-portal/design-targeting) to publish a design for that one theme while your live design keeps every other page. Early access: ask your SureBright contact. | The steps and the status badges are on [Storefront setup](/shopify/storefront-setup). ### After you publish a Shopify theme | Check | If it is wrong | |---|---| | In **Settings → Storefront setup**, the badge next to your **Live theme** reads **Turned on** | Click **Turn on in Shopify ↗**, switch the embed on and **Save**. Then click **Check again**. See [Settings](/merchant-portal/settings#check-your-shopify-storefront-setup). | | The offer shows near **Add to cart** on a product that offers protection, and in the cart | If the embed is on but the offer is missing or sits in the wrong place, the new theme's pages may be laid out differently from the ones your design was built on. In [Studio](/merchant-portal/studio), click **New store look?** to read your storefront again, then review and publish the new design. Without Studio, send the product URL to [support@surebright.com](mailto:support@surebright.com). | | A product with a plan, added to the cart, shows the plan line in the cart page and in the cart drawer | A new theme can add to cart in a different way, or bring a new cart drawer. The offer then still shows but the plan does not reach the cart, or appears in the drawer only after a reload. Send SureBright the product URL so the add to cart and the drawer can be matched again. Tell SureBright before you switch if you can. | | The widget's colours and font match the new theme | **New store look?** also picks up new colours, a font or a logo. Your live design stays as it is until you publish the new one. | | A design you targeted at the old theme | A targeting rule applies to one theme only. Pages on the new theme get your live design. Publish the design for the new theme, or make it your live design. | | Your post-purchase offer links and product registration pages still work | Both rely on the embed. They work again once it is on in the live theme. See [Offer links](/post-purchase/offer-links) and [Product registration pages](/shopify/product-registration). | | On Shopify Plus, the offer still shows in checkout | The checkout blocks are placed in Shopify's checkout editor, and the Merchant Portal cannot tell you whether they are there. Preview your checkout to confirm. See [Checkout extensions](/shopify/checkout-extensions). | Finish with one test order. See [Test your setup](/platforms/test-your-setup). ## Other platforms: theme and domain changes | Platform | What to check | |---|---| | Magento | The module needs no theme changes. After a redesign, check a product page. If the offer is missing, run **Purge caches** on the SureBright page in your Magento admin. If your storefront's domain changes, tell your SureBright contact first: the offer is recognised only on the domain SureBright registered. See [Storefront widget](/magento/storefront-widget). | | BigCommerce | Check that the two SureBright entries are still listed in **Storefront > Script Manager**. If one is missing, ask your SureBright contact to recreate it. See [BigCommerce](/bigcommerce/overview). | | Shift4Shop | Check that the two SureBright entries are still listed under **Frontend Scripts**. If one is missing, ask your SureBright contact to recreate it. See [Shift4Shop](/shift4shop/overview). | | Any platform: a redesigned product page, buy box or cart drawer | Add a product with a plan and open the cart. If the plan is missing or appears only after a reload, send SureBright the product URL. See [Offer not showing?](/help/offer-not-showing#what-commonly-gets-in-the-way). | | WooCommerce | If you move your WordPress site to another domain, tell your SureBright contact before you do, or plans sold afterwards will stop becoming contracts. See [WooCommerce](/woocommerce/overview). | ## Moving to another platform Each platform connects to SureBright in its own way, so a store that moves platform needs a new connection on the new platform. Tell your SureBright contact before you start. Features differ by platform. Compare the two columns in [What works on each platform](/platforms/overview#what-works-on-each-platform). Follow the new platform's guide from [Supported platforms](/platforms/overview). Your products come in from the new platform, so review their categories again in [Products](/merchant-portal/products). Run a full order through on the new store. See [Test your setup](/platforms/test-your-setup). Once the old store takes no more orders, uninstall or disconnect it. See [Pause or remove SureBright](/platforms/pause-or-remove), which also says what happens to plans already sold on each platform. Ask your SureBright contact about anything this page does not state, in particular: - whether the new store joins your existing SureBright account; - whether your prices and widget design carry over; - how sales and invoices from the two stores are shown together. ## Related - [Storefront setup](/shopify/storefront-setup), for Shopify - [Studio](/merchant-portal/studio) - [Design targeting](/merchant-portal/design-targeting), for Shopify - [Pause or remove SureBright](/platforms/pause-or-remove) - [Supported platforms](/platforms/overview) --- # Custom platform integration Source: https://docs.surebright.com/platforms/custom-platform > Offer SureBright protection on a custom-built or unsupported store platform: create the plan products from your SKUs, add the SureBright SDK to your storefront, and send your orders to SureBright. Use this page when your store runs on a platform SureBright has no app or plugin for, such as a custom-built site, an in-house commerce stack or a platform not on [Supported platforms](/platforms/overview). The integration has three parts: 1. **Plan products in your store.** SureBright shares your plan SKUs, and you create one product for each in your catalogue. 2. **The SureBright SDK on your storefront.** It shows the protection offer on product and cart pages, and tells your code which plan the shopper picked. 3. **Your orders sent to SureBright.** Each order that includes a plan is sent to SureBright's order webhook, and SureBright creates the contracts and emails your customer. ## Who does what | Step | Who | What happens | |---|---|---| | Set up your store in SureBright | SureBright | Your catalogue is categorised, plan prices are set, and you get your store ID and API key. | | Share the plan SKUs | SureBright | You get the SKU list as a CSV. You can also [download it from the Merchant Portal](/erp/download-plan-skus). | | Create the plan products | You | One product per plan SKU in your store catalogue. | | Design the offer | SureBright, with you | The look and placement of the offer, set in the Merchant Portal's widget designer. | | Add the SDK and handle plan selection | Your developers | One script tag, plus a few lines of code that add the plan product to the cart. | | Send orders | Your developers | A call to SureBright's order webhook when an order is paid, and again when it is cancelled or refunded. | | Create contracts and email customers | SureBright | One contract per plan unit sold, emailed to the customer. | ## Step 1: create the plan products SureBright shares a CSV with one row per plan SKU: the SKU, a description and the price. Each SKU stands for a plan length, region, coverage type and price band, for example `SBW-1U-CEAD-49999`. See [Download your plan SKUs](/erp/download-plan-skus) for every column. Create one product in your store for each row: | Setting | Set it to | Why | |---|---|---| | **SKU** | The `InventoryID` value, exactly | SureBright matches the plan line on your orders by this SKU. | | **Title** | The `Description` value, or your own wording | Shown on the cart, the checkout and the order confirmation. | | **Price** | The `BasePrice` value | The price the shopper pays for the plan. | | **Shipping** | Not shipped, no weight | There is nothing to pick, pack or deliver. | | **Tax** | Your setting for service or warranty items | Agree it with your accountant. | | **Visibility** | Hidden from search, collections and product listings | Shoppers add a plan through the SureBright offer, never from a product page. | | **Discounts** | Excluded from store-wide discounts and coupons | A discounted plan still costs you the full plan price. | If your platform has product variants, you can also create one plan product with one variant per SKU. What matters is that each SKU exists exactly once. When SureBright adds new price bands later, it tells you. Download the SKUs again and create the new rows. ## Step 2: add the SureBright SDK to your storefront Add the SDK script to every page of your storefront, with your store ID and the `CUSTOM` platform: ```html ``` On product and cart pages the SDK shows the offer where SureBright has placed it for your store. It needs to know which product the shopper is looking at, and it tells your code when a plan is chosen. Your developers wire both, following [Headless and custom storefronts](/frontend-widget-integration/frontend-widget-kit/headless-and-custom-storefronts). ### Add the plan to the cart When the shopper picks a plan, the SDK calls your handler with the plan and the product it covers: ```javascript window.SureBright.onSelectionChange(function (change) { if (change.action === "selected" && change.quote) { // Add the plan product whose SKU matches the selected plan, // linked to the cart line of the product it covers. addPlanToCart(change.quote, change.product); } else if (change.action === "deselected") { removePlanFromCart(change.product); } }); ``` Keep the plan's quote details with the plan line (at least `quoteId`, `quoteItemId` and the covered product's ID), and carry them through to the order. SureBright needs them to know which product the plan covers. The full payload is in the [JavaScript API reference](/frontend-widget-integration/frontend-widget-kit/javascript-injection). A plan line that reaches the order without its quote details cannot be matched to the product it covers, so no contract is created for it. Test that your cart, checkout and any app that edits orders keep them. ## Step 3: send your orders to SureBright When an order that includes a plan is paid, your system sends it to SureBright's order webhook with your API key. SureBright creates one contract per plan unit and emails the customer their cover. | When | Send | Reference | |---|---|---| | The order is paid | The order, its customer and line items, and for each covered line the plan bought | [Create contracts](/api-reference/endpoint/order/create-contract) | | A plan is cancelled, refunded or its quantity changes | The order ID and the plan lines that changed | [Update or cancel contracts](/api-reference/endpoint/order/update-contract) | | The covered product ships, on stores where cover starts at fulfilment | The fulfilment date, once SureBright turns this on for your store | [Set fulfilment dates](/api-reference/endpoint/order/fulfillment) | What every order needs: - the order ID, date and currency; - the customer's name, email and address, so the customer can be sent their plan and can claim; - each covered product line, with its product ID, title, price and quantity; - each plan line, with its SKU, price, quantity and the quote details from Step 2. Send each order once when it is paid. Sending the same order again does not create duplicate contracts. After a server error, look the order up with [Get contracts](/api-reference/endpoint/order/get-contracts) before you send it again. If your system cannot call a webhook yet, you can start with a [spreadsheet of orders](/erp/spreadsheet-order-intake) and switch later. ## Step 4: test before you launch On a product page that should show protection, the offer appears where SureBright placed it. Pick a plan and check the plan product is added to the cart with the right SKU and price. Complete an order with one product and one plan. Check that your system sent it to SureBright and got a success response. The plan shows in [Sales](/merchant-portal/sales) in the Merchant Portal, and the test customer receives the plan email. Cancel or refund the test order and check the contract is cancelled. Tell your SureBright contact when the test passes. SureBright checks the contract details with you before your store goes live. ## Related - [If your platform is not listed](/platforms/other-platforms): the smaller ways to start, and other checkouts, apps and native mobile apps. - [Request a platform](/platforms/request-a-platform): ask SureBright to build an app for your platform. - [Headless and custom storefronts](/frontend-widget-integration/frontend-widget-kit/headless-and-custom-storefronts): the developer guide for the SDK. --- # Sell protection in store Source: https://docs.surebright.com/platforms/in-store-sales > Offer SureBright plans at the counter as well as online: the point-of-sale options, what each one does, and how in-store and online sales sit side by side. If you sell in person as well as online, you can offer protection plans in both places. Your online store and your point of sale are set up separately and run side by side, so adding one does not change the other. Pick your point of sale under **Your point of sale** in the sidebar and the guides for it appear here. Your online store choice stays as it is. ## Choose how you sell in store | You use | What happens at the counter | Start here | | --- | --- | --- | | **Lightspeed X-Series** | Your cashier is prompted to offer protection when an eligible product is rung up. A completed sale with a plan becomes a plan for the customer. | [Lightspeed X-Series](/lightspeed/x-series) | | **Lightspeed R-Series** | A completed register sale that includes a SureBright warranty item becomes a plan. A refund or void cancels it. | [Lightspeed R-Series](/lightspeed/r-series) | | **Shopify POS** | Staff add a plan to the cart in a few taps and sell it on the same receipt as the product. | [POS extension](/shopify/pos-extension) | | **Any other register, or no register at all** | Staff record the sale in the SureBright POS portal, on a phone, tablet or computer, one sale at a time or in bulk. | [POS portal](/pos/overview) | Not sure which fits? If your register is not listed, the POS portal works alongside any till, because it does not connect to it. ## What changes when you add in-store sales | | Online store | Point of sale | | --- | --- | --- | | Who offers the plan | The offer on your product page, cart or checkout | Your staff, at the counter | | How the sale is recorded | By itself, from the order | By itself on Lightspeed and Shopify POS. Entered by staff in the POS portal | | Where you see it | **Sales** in the Merchant Portal | **Sales** in the Merchant Portal for Lightspeed and Shopify POS. **Sales History** in the POS portal for portal sales | | What the customer receives | A confirmation email from SureBright | The same. Make sure staff capture the customer's email address | In the Merchant Portal, **Sales** can break your numbers down by platform and, where your store has locations, by location, so you can see online and in-store sales separately. ## Before your staff start Follow the guide for your point of sale in the table above. In-store products need a category before a plan can be offered, the same as online. See [What can be covered](/contracts/what-can-be-covered). Tell staff when to offer protection, to take the customer's email address on every sale, and where the customer goes if they need to make a claim. See [Claims and your role](/learn/claims-and-your-role). Ring up one sale with a plan and confirm it appears where you expect, with a confirmation email. See [Test your setup](/platforms/test-your-setup). ## Related - [Supported platforms](/platforms/overview) - [Request a point of sale that is not listed](/platforms/request-a-platform?type=pos) - [Phone, draft and later sales](/learn/phone-and-later-sales) - [POS billing](/pos/billing) **See also:** [Already have a register or POS system](/pos/overview#already-have-a-register-or-pos-system). --- # Languages and regions Source: https://docs.surebright.com/platforms/languages-and-regions > Where SureBright plans are sold, which currency they are priced in, and what shoppers see in French or English on the widget, the coverage popup, checkout and in emails. Use this page if you sell outside the United States or to French-speaking shoppers. It says where plans are sold, in which currency, which parts of the SureBright experience appear in French, and how to get wording changed. ## What you can do | You want to | Do this | |---|---| | Sell plans in Canada as well as the United States | Ask your SureBright contact to set up plans for your categories in both countries. You then see **US** and **CA** tabs under **Warranty Prices** on a product | | Price plans against each market's product price | On Shopify, use Shopify Markets and ask SureBright to enable it for your store. See [Shopify Markets pricing](/shopify/markets). On other platforms, ask your SureBright contact | | Show the widget in French on a French storefront | Usually nothing: the widget follows your storefront's language. Check a product page in French, then send SureBright anything still in English | | Show the widget in one fixed language whatever the storefront language | Ask your SureBright contact to set the widget language for your store | | Change the offer heading, subtext or popup wording | Ask your SureBright contact. Wording is set by SureBright and cannot be edited in Studio | | Get French for wording written specially for your store | Send SureBright the French text you want alongside the English | ## Where plans are sold | Plan type | United States | Canada | Other countries | |---|---|---|---| | Product protection plans | Yes, priced in USD | Yes, priced in CAD | Not offered | | Shipping protection | Yes | Not offered | Not offered | - The shopper's country decides what they are offered, not where your business is based. A shopper in another country sees no offer. - You need plans set up for a country before shoppers there see an offer. A store with plans only in the United States shows nothing to a Canadian shopper. - On Shopify stores using Shopify Markets, a market serving other countries is still synced, but shoppers there are not offered a plan. ### Selling in Canada: provinces and French documents | Question | Answer | |---|---| | Are all provinces covered? | Plans in Canada are set up for your categories by SureBright, and plan prices can differ by province. Before you launch to shoppers in a particular province, Quebec included, ask your SureBright contact to confirm that your plans cover it. | | Can plan documents be in French as well as English? | The widget and pop-up are shown in French on French pages (see [Which languages shoppers see](#which-languages-shoppers-see)). Customer emails and the customer portal are in English. Ask your SureBright contact whether French plan documents are available for your programme. | | What must I tell shoppers in my province before I sell a plan? | SureBright cannot advise you on that. Ask your own adviser. Your SureBright contact can show you what SureBright already presents to shoppers in the widget, the pop-up and the plan documents. | ### Shipping protection and where you ship from Shipping protection is offered on orders shipped to addresses in the United States. If your orders leave from outside the United States, for example from a Canadian warehouse or straight from an overseas manufacturer, ask your SureBright contact before you switch shipping protection on. See [Shipping protection](/shipping-protection/overview). For everything else that decides whether a product gets an offer, see [What can be covered](/contracts/what-can-be-covered). On Shopify stores using Markets, [Shopify Markets pricing](/shopify/markets) explains how plan prices follow the price a shopper sees in their market, and what happens when a plan is priced in one currency and paid in another. ## Which languages shoppers see SureBright's shopper-facing text exists in **English** and **French**. No other language is available: a storefront in Spanish or German shows the widget in English. ### How the widget picks a language 1. If SureBright has set a widget language for your store, that language is used on every page. 2. Otherwise the widget follows your storefront's language. On Shopify this is the language the shopper is browsing in. On other platforms it is the language your page declares. 3. Regional variants count as their base language, so Canadian French is shown in French. 4. Any language other than French is shown in English. ### What appears in French | Text | In French? | |---|---| | Built-in widget and popup labels, such as **Add Extended Warranty**, **What's covered?**, **Protect My Purchase**, **No, Thanks**, **Best Seller**, plan and term labels, and the shipping protection text | Yes. For example *Ajouter une garantie prolongée*, *Qu'est-ce qui est couvert?*, *Protéger mon achat*, *Non, merci* | | Coverage points listed in the widget and the coverage popup | Partly. Each point is shown in French when SureBright has a French version of it, and in English when it does not, so a list can mix the two | | Wording written specially for your store, such as a custom heading or subtext | Only if the phrase matches one of the built-in ones. Otherwise it is shown exactly as written; ask SureBright for a French version | | Plan prices | Formatted for the shopper's language and shown in the plan's currency | | Offers and badges inside Shopify checkout (Shopify Plus only) | English. Prices are formatted by Shopify for the shopper | | Customer emails, such as the plan confirmation | English | | The customer portal at customer.surebright.com | English | If your French pages show the widget in English, send your SureBright contact the page address. Some stores need an update on SureBright's side before French appears. ### Checking your store Use your storefront's language selector, then open a product that shows the SureBright offer. Click **What's covered?** and read the heading, the coverage points and the buttons. Note the exact phrases and the page address, and send them to your SureBright contact with the French you want. ## Change the wording shoppers see Wording is not something you edit yourself. In [Studio](/merchant-portal/studio), the **Text size** row controls size only, and the wording itself (heading, subtext, details link and popup copy) is set by SureBright. On the shipping widget the **Language** row holds the **Offer**, **Subtext** and **Coverage link** wording, also set by SureBright. Customer emails are operated by SureBright and cannot be edited from your store or the portal. See [Customer emails](/customer-emails/overview#what-you-can-change) for what can be configured for your programme. ## Related On Shopify, how plan prices follow the price in each market. Countries, categories, condition and price bands. Design your SureBright offer: colours, layout and text size, previewed on your own product page. Every platform SureBright connects to. Developers: the quote endpoints accept a language parameter for French coverage text. See [Order quotes](/api-reference/endpoint/quote/order-quotes) and [Registration quotes](/api-reference/endpoint/quote/list-registration-quotes). --- # If your platform is not listed Source: https://docs.surebright.com/platforms/other-platforms > What it takes to offer SureBright protection on a platform without a SureBright app, who does what, how to report sales made outside an integrated checkout, and how SureBright fits with native apps, other checkouts and your other tools. This page is for stores whose platform is not on [Supported platforms](/platforms/overview), or that sell through channels the SureBright apps do not reach. It says what has to be built, what SureBright does for you, and the smallest way to start. On **Wix**, follow [Install SureBright on Wix](/wix/install-guide). On **Ecwid**, **Squarespace** or another platform without a guide on these pages, [ask SureBright](/platforms/request-a-platform) whether an app is available for it, and start here meanwhile. Want SureBright to build an app for your platform? [Tell us which one you use](/platforms/request-a-platform). You can still start today with the steps below. Ready for the full integration on a custom-built store? Follow [Custom platform integration](/platforms/custom-platform), the step-by-step version of the table below. ## What an integration needs Every SureBright integration does three things. On a supported platform the app does them for you. On any other platform, each one has a simple option and a fuller one. | Piece | What it does | Simplest option | Fuller option | |---|---|---|---| | Show the offer | Puts the protection offer on product and cart pages | Add SureBright's storefront script to your site. SureBright designs the offer and sets where it sits. | Your developers draw the offer themselves from SureBright's prices. | | Sell the plan | Lets the shopper pay for the plan in your checkout | Create the plan products, or warranty SKUs, from a sheet SureBright gives you, so a plan is an item like any other. | The same SKUs, added to the cart by your own code. | | Report the sale | Turns each plan sold into a contract | Send SureBright your sales as a file, or through the order email you already send. See [Report sales made outside an integrated checkout](#report-sales-made-outside-an-integrated-checkout). | Send each order to SureBright as it happens, through the API or an order webhook. | ## Who does what | Task | Who | |---|---| | Categorising your catalogue and setting plan prices | SureBright | | Designing the offer and choosing where it sits on your pages | SureBright | | Adding the storefront script to your site | You, your developer or your platform vendor | | Creating the warranty SKUs from SureBright's sheet | You, or whoever manages your catalogue | | Sending sales: a file, your existing order email, or an order feed | You, or your developer for a feed | | Turning sales into contracts and emailing your customers | SureBright | You do not need to build everything before you start. The smallest working set is the storefront script, the warranty SKUs and a sales file. You can move to an automatic order feed later. If your platform vendor quotes for the work, share this page and the developer links below with them, and talk to your SureBright contact first: SureBright can tell you which pieces you can skip. You do not need an existing warranty programme or existing warranty SKUs. SureBright gives you the SKUs to create. ## Report sales made outside an integrated checkout Plans sold where no SureBright integration sees the order, such as a platform without an order feed, phone sales or a separate sales system, reach SureBright as a sales report: - **A spreadsheet of orders**, emailed to a SureBright mailbox. See [Spreadsheet order intake](/erp/spreadsheet-order-intake). Available on request. - **A regular sold report**, for example monthly, agreed with your SureBright contact. SureBright checks every report and asks you about any line that does not add up before it sets up the plans: | In your report | What happens | |---|---| | A plan sold at a discount | SureBright asks you to confirm the sale. The plan is set up once you confirm. A discount you gave the shopper does not change what SureBright bills you for the plan. | | A cancelled order | Tell SureBright the order was cancelled. A plan on a cancelled order is not set up, or is cancelled if it already was. | | A plan with no matching product | SureBright asks which product the plan covers. | Reply to SureBright's questions on a report promptly: plans in it are set up only after they are answered. ## Native mobile apps The SureBright storefront script runs in web pages. It does not run inside a native iPhone or Android app. To offer protection in your app, your developers fetch the offer from SureBright, show it in the app, add the plan to the order, and send the order to SureBright. Sales from your website are not affected. Ask your SureBright contact before you plan the work. ## Other checkouts The plan has to reach your order with the details that link it to the product it covers. If your checkout is not your platform's own, or another system rebuilds the cart or the order, those details can be lost and the plan cannot be matched to a product. Tell SureBright which checkout or system you use before you launch, and run a test order through it. See [Test your setup](/platforms/test-your-setup). ## Other apps and tools | Tool | What to know | |---|---| | Email and SMS tools | See [Email integrations](/klaviyo-integration/integration-guide) and [Omnisend](/integrations/omnisend). | | Help desks and support tools | Your support team can look up any plan in [Sales](/merchant-portal/sales) in the Merchant Portal. For a link from your help desk or other tools, ask your SureBright contact. | | Installer and quoting software | See [D-Tools SI, Portal.io and Specifi](/installers/proposal-tools). For a tool that is not there, [tell us which one you use](/platforms/request-a-platform?type=proposal). | | Order-editing apps | A plan line is linked to the product it covers by details hidden on the line. Editing an order with an app that rebuilds its lines can break that link, so the plan is no longer matched to its product. Ask SureBright before you use one on orders that carry plans, and test an edited order first. | ## Related Platforms with a SureBright app or plugin. Send orders as a spreadsheet, with no storefront integration. Run one order through before you launch. Permissions and access requests. For developers: add the storefront script as described in [SDK installation](/frontend-widget-integration/frontend-widget-kit/sdk-installation) and [Custom storefronts](/frontend-widget-integration/frontend-widget-kit/headless-and-custom-storefronts); send orders with the [Integration tutorial](/api-reference/integration-tutorial); for a native app, also report offer views with the [Event collector](/frontend-widget-integration/frontend-widget-kit/event-collector). --- # Supported platforms Source: https://docs.surebright.com/platforms/overview > Every commerce platform, point-of-sale system and ERP SureBright connects to, with the guide to start from for each. SureBright connects to your store, reads your catalogue and orders, shows the protection offer to shoppers, and turns paid orders into contracts. Pick your platform below to find its setup guide. Platform not here? [Tell us which one you use](/platforms/request-a-platform) and we reply with the best way for your store to start. ## Online stores | Platform | How SureBright connects | Start here | |---|---|---| | **Shopify** | The SureBright app, a theme app embed for the storefront, and checkout and POS extensions | [Storefront setup](/shopify/storefront-setup) | | **Shopify Hydrogen** and other headless Shopify storefronts | The same SureBright app, with the storefront script added by your developer in place of the theme app embed | [Headless and Hydrogen](/shopify/headless-hydrogen) | | **Magento** | The SureBright module, with its own page in the Magento admin | [Installation Guide](/magento/install-guide) | | **Salesforce Commerce Cloud** | A cartridge for SFRA stores, set up in Business Manager | [SFCC Integration Guide](/salesforce-commerce-cloud/integration-guide) | | **BigCommerce** | The SureBright app from the BigCommerce app flow | [BigCommerce](/bigcommerce/overview) | | **WooCommerce** | The Surebright Product Protection Plan plugin for WordPress | [WooCommerce](/woocommerce/overview) | | **Shift4Shop** | A connected store with storefront scripts and order webhooks | [Shift4Shop](/shift4shop/overview) | | **Wix** | The SureBright app for Wix Stores, which places the offer on your product page | [Wix](/wix/install-guide) | ## Point of sale Your point of sale is separate from your online store, and you can run both. See [Sell protection in store](/platforms/in-store-sales). | Platform | How SureBright connects | Start here | |---|---|---| | **Lightspeed X-Series** | A connected Lightspeed Retail account with a prompt on the sell screen | [Lightspeed X-Series](/lightspeed/x-series) | | **Lightspeed R-Series** | Completed sales are turned into contracts and the item catalogue is kept in sync | [Lightspeed R-Series](/lightspeed/r-series) | | **Shopify POS** | The SureBright POS extension inside Shopify POS | [POS extension](/shopify/pos-extension) | | **Any other register** | The SureBright POS portal, where staff record sales by hand or in bulk | [POS portal overview](/pos/overview) | ## ERP | Platform | How SureBright connects | Start here | |---|---|---| | **Acumatica** | The SureBright warranty catalogue is added as non-stock items and published through your existing Acumatica to Shopify connector | [Acumatica warranty SKUs](/erp/acumatica-warranty-skus) | | **Oracle NetSuite** | The plan SKUs are added as non-inventory items for sale, so plan lines on synced orders match an item | [NetSuite warranty SKUs](/erp/netsuite-warranty-skus) | | **Microsoft Dynamics 365 Business Central** | The plan SKUs are added as non-inventory items, so plan lines on synced orders match an item | [Dynamics 365 warranty SKUs](/erp/dynamics-365-warranty-skus) | | **SAP Business One** | The plan SKUs are added as sales items that are not inventory items | [SAP Business One warranty SKUs](/erp/sap-business-one-warranty-skus) | | **Odoo** | The plan SKUs are added as service products, so no delivery is created for a plan line | [Odoo warranty SKUs](/erp/odoo-warranty-skus) | Every guide starts from the plan SKU CSV you download from the Merchant Portal: [Download your plan SKUs](/erp/download-plan-skus). On another ERP, accounting tool or 3PL, load the SKUs from that file as non-stock, non-shipping items. See [Plan SKUs for your ERP or 3PL](/learn/plans-in-your-order-tools#plan-skus-for-your-erp-or-3pl). ## Custom and headless storefronts On a custom-built or unsupported platform, follow [Custom platform integration](/platforms/custom-platform): create the plan products from your SKUs, add the SureBright SDK to your storefront and send your orders to SureBright. A headless Shopify storefront, such as Hydrogen, runs the SureBright widget with built-in support. Start with [Headless and Hydrogen](/shopify/headless-hydrogen). If your storefront is custom built on another stack, or your platform is not listed, you can still offer SureBright. [If your platform is not listed](/platforms/other-platforms) says what has to be built, what SureBright does for you, and how to report sales made outside an integrated checkout. It also covers native mobile apps, other checkouts and tools such as help desks and order-editing apps. Your developers start here: Run the SureBright widget outside a platform app: declare your store, give the SDK page context and keep cart line properties intact. Fetch quotes and record orders from your own backend. ## What works on each platform Not every feature runs on every platform. The two tables below show where each one stands. Read a cell as follows: | Value | Meaning | |---|---| | **Yes** | Works on this platform. | | **No** | Not available on this platform. | | **On request** | SureBright switches it on for your store. Ask your SureBright contact. | | **Ask** | Not confirmed for this platform in these docs. Ask your SureBright contact before you plan around it. | | Anything else | A short condition, explained under the table. | ### Storefront platforms | Feature | Shopify | Magento | Salesforce Commerce Cloud | BigCommerce | WooCommerce | Shift4Shop | Wix | |---|---|---|---|---|---|---|---| | Product-page offer widget | Yes | Yes | Yes | Yes | Yes | Yes | Yes | | Cart offer | Yes | Yes | Ask | Yes | Yes | Yes | Ask | | In-checkout offer | Shopify Plus | No | Ask | No | No | No | No | | Automatic contract creation from orders | Yes | Yes | Scheduled job | Yes | Yes | Yes | Yes | | Automatic cancellation on refund or cancel | Yes | Yes | Ask | Yes | Yes | Yes | Yes | | [Shipping protection](/shipping-protection/overview) | Yes | Ask | Ask | Yes | Ask | Ask | Ask | | Post-purchase offer emails | Yes | Ask | Ask | Ask | Ask | Ask | Ask | | [Abandoned cart recovery](/abandoned-cart-guide/abandoned-cart) | On request | No | No | No | No | No | No | | [Product registration](/shopify/product-registration) | Yes | Ask | Ask | Ask | Ask | Ask | Ask | | [Draft and manual orders](/manual-orders/overview) | Yes | Yes | No | No | No | No | No | | [Studio](/merchant-portal/studio) widget design | On request | Ask | Ask | Ask | Ask | Ask | On request | | [Design A/B tests](/merchant-portal/design-tests) and attach-rate measurement | On request | No | No | No | No | No | No | | Catalogue sync | Yes | Yes | Scheduled job | Yes | Ask | Copied once | Yes | | [Ray](/merchant-portal/ray) assistant | On request | On request | On request | On request | On request | On request | On request | - **Shopify Plus**: Shopify shows checkout blocks on Plus plans only. See [Checkout extensions](/shopify/checkout-extensions). - **Scheduled job**: on Salesforce Commerce Cloud, orders and products reach SureBright through jobs you schedule in Business Manager, not as each order is placed. See [Jobs](/salesforce-commerce-cloud/jobs). - **Copied once**: on Shift4Shop the catalogue is copied when the store is connected. Ask your SureBright contact to refresh it after a large product update. See [Shift4Shop](/shift4shop/overview). - **Wix**: the SureBright app is not listed in the Wix App Market yet, so it is installed with a link from your SureBright contact. Your store's currency must be USD or CAD. See [Install SureBright on Wix](/wix/install-guide). - **WooCommerce** is in limited release and is installed with your SureBright contact. Contracts are created once the order webhooks described on the [WooCommerce](/woocommerce/overview) page are set up. - **Post-purchase offer emails** are sent by SureBright or, if you prefer, by your own email tool. Both are set up with your SureBright contact. See [Email integrations](/klaviyo-integration/integration-guide). - **Draft and manual orders** here means the **Leads** page of the Merchant Portal. Shopify stores also have the [draft order extension](/draft-order-guide/shopify-draft-order). On any platform, orders can be sent as a spreadsheet on request. - Shopify stores can also sell at the counter with the [POS Extension](/shopify/pos-extension). ### Point of sale and API | Feature | Lightspeed X-Series | Lightspeed R-Series | API-only or custom storefront | POS portal | |---|---|---|---|---| | Product-page offer widget | No | No | Built by you | No | | Cart offer | No | No | Built by you | No | | In-checkout offer | No | No | Built by you | No | | Automatic contract creation from orders | Yes | Yes | Via API | Recorded by staff | | Automatic cancellation on refund or cancel | Yes | Yes | Via API | By staff | | [Shipping protection](/shipping-protection/overview) | No | No | Ask | No | | Post-purchase offer emails | Ask | Ask | Ask | Ask | | [Abandoned cart recovery](/abandoned-cart-guide/abandoned-cart) | No | No | No | No | | Product registration | No | No | Ask | No | | Draft and manual orders | No | No | Via API | Yes | | [Studio](/merchant-portal/studio) widget design | No | No | Ask | No | | [Design A/B tests](/merchant-portal/design-tests) and attach-rate measurement | No | No | No | No | | Catalogue sync | Yes | Yes | No | CSV import | | Ray assistant | On request | On request | On request | On request | - **Lightspeed X-Series** has no storefront widget. The plan is offered through a prompt on the sell screen when an eligible product is rung up. See [Lightspeed X-Series](/lightspeed/x-series). - **Lightspeed R-Series** creates contracts from completed sales. When a sale is missed you can pull it in from the Merchant Portal with [Sync orders](/merchant-portal/settings#sync-orders-from-lightspeed-r-series). - **Built by you**: with an API-only integration your developers show the offer in your own pages. A headless Shopify storefront, such as Hydrogen, uses the SureBright widget instead and follows the Shopify column. See [Headless and Hydrogen](/shopify/headless-hydrogen). - **Via API**: your own system tells SureBright about each order and about each change or cancellation. SureBright keeps no synced catalogue for such a store. For developers: see [Orders](/api-reference/endpoint/order/index) and [Quotes](/api-reference/endpoint/quote/index). - **Recorded by staff** and **By staff**: in the POS portal a sale becomes a contract when a team member records it, one at a time or in bulk, and is cancelled from **Sales History**. See [Recording a sale](/pos/recording-a-sale) and [Sales history](/pos/sales-history). - **CSV import**: the POS portal keeps its own product catalogue, added by hand or imported from a CSV. See [Product catalogue](/pos/catalogue). - **Ray** in the POS portal is a separate assistant in early access. See [Ray assistant](/pos/ray-assistant). ## Before and after launch See the offer, place a test order, confirm the contract and cancel it before you go live. Moving from another protection provider: what to set up, in what order. Bring the offer back after you publish a new theme or move platform. Stop showing offers without uninstalling, and what uninstalling does. App permissions, collaborator requests and agency access. What to build, who does what, and reporting sales by file. ## Orders taken outside your storefront Phone sales, past orders and orders that arrive in a spreadsheet are covered in [Manual and draft orders](/manual-orders/overview). --- # Pause or remove SureBright Source: https://docs.surebright.com/platforms/pause-or-remove > How to stop showing protection offers without uninstalling, what uninstalling does on each platform, and what happens to plans you have already sold. You can stop offering protection for a while without removing SureBright, and you can remove it altogether. The two are different: pausing hides the offer and keeps everything else running, while uninstalling cuts the connection between your store and SureBright. This page covers both, and says what happens to plans you have already sold. ## What you can do on your platform | You want to | Where | |---|---| | Stop the offer on chosen products, or stop shipping protection | Every platform with a **Products** page. See [Stop the offer on chosen products](#stop-the-offer-on-chosen-products). | | Keep the offer off a product template, a page type or particular pages | Ask SureBright. See [Keep the offer off chosen pages](#keep-the-offer-off-chosen-pages). | | Hide every offer for a while, on Shopify | [Pause offers on Shopify](#pause-offers-on-shopify) | | Remove SureBright from a Shopify store | [Uninstall the Shopify app](#uninstall-the-shopify-app) | | Disable or remove SureBright on Magento, BigCommerce, Shift4Shop, Lightspeed or another platform | [Pause or remove on other platforms](#pause-or-remove-on-other-platforms) | | Know what happens to your data and your plans when you leave | [When you leave SureBright](#when-you-leave-surebright) | ## Stop the offer on chosen products This works on every platform whose Merchant Portal has a [Products](/merchant-portal/products) page. | To stop | Do this | |---|---| | The offer on some products only | In [Products](/merchant-portal/products), set **Warranty status** to **Inactive**. Tick several products to change them together from the bulk bar. | | Shipping protection | Set **Shipping protection** to **Off** per product in Products, on Shopify and BigCommerce stores that show the column. The store-wide switch is set by your SureBright contact. See [Shipping protection](/shipping-protection/overview#turn-on-shipping-protection). | To start again, reverse the same step. ## Keep the offer off chosen pages What you can do yourself, and what to ask SureBright for: | You want the offer off | Do this | |---|---| | Some products, everywhere they appear | In [Products](/merchant-portal/products), set **Warranty status** to **Inactive** on those products. | | Every product that uses one product template, a page type, or particular pages such as a landing page | Ask SureBright. Email [support@surebright.com](mailto:support@surebright.com) with the template name or page type, one example URL, and whether the products should stay covered on other pages. | Nothing in your theme's code needs to change for either. On Shopify, do not remove or edit the SureBright Offering embed as a way to hide the offer on some pages: it is one switch for the whole theme. After SureBright confirms the change, check the pages again after any theme change, because a new theme can rename your templates. See [After a theme or platform change](/platforms/after-a-theme-or-platform-change). ## Pause offers on Shopify | To stop | Do this | |---|---| | The offer on product pages and in the cart | In the Merchant Portal open **Settings → Storefront setup**. Next to the theme with the **Turned on** badge, click **Turn off in Shopify ↗**, switch **SureBright Offering** off and **Save**. The setting belongs to each theme, so check your **Live theme**. See [Storefront setup](/shopify/storefront-setup). | | The offer in checkout (Shopify Plus) | The **SureBright Protection Block** and **SureBright Protection Badge** are placed in Shopify's checkout editor, separately from the theme embed. Remove them there. See [Checkout extensions](/shopify/checkout-extensions). | To start again, reverse the same step. ### What keeps working while the Shopify embed is off - The app is still installed, so SureBright still sees your orders, refunds, cancellations and fulfilments. A plan sold earlier is still cancelled when you refund it. - The Merchant Portal and everything in it stay as they are. - Anything that the embed loads stops with it: [post-purchase offer links](/post-purchase/offer-links) open no popup, and [product registration pages](/shopify/product-registration) show no SureBright widget. ## Uninstall the Shopify app Uninstalling is not a pause. Use [Pause offers on Shopify](#pause-offers-on-shopify) if you plan to come back soon. When you uninstall the **SureBright - Extended Warranty** app in Shopify admin: | What changes | What it means for you | |---|---| | Your store is disconnected | SureBright marks the store as uninstalled and stops working on it. No new plans are sold. | | SureBright stops hearing from your store | Orders, refunds, cancellations and fulfilments no longer reach SureBright. | | Plans already sold are not cancelled | Uninstalling does not cancel them. A plan you refund in Shopify after uninstalling is not cancelled automatically either: email [support@surebright.com](mailto:support@surebright.com) to have it cancelled. | | Shopify passes on a data erasure request | Shopify sends it 48 hours after you uninstall the app. SureBright records the request. What that covers, and how to follow up, is on [GDPR webhooks](/shopify/gdpr). | ### Reinstall the Shopify app Install the app again from Shopify and it reconnects the same store. Your existing SureBright account, your billing details and the plan products SureBright created before are reused, not created again. The store goes back to **In review**, and protection is offered again once your store card reads **Live**. See [Your store card](/merchant-portal/overview#check-your-stores-status). After a reinstall, open **Settings → Storefront setup** and check the badge next to your **Live theme**. ## Pause or remove on other platforms Stopping the offer for chosen products works the same everywhere: see [Stop the offer on chosen products](#stop-the-offer-on-chosen-products). Disabling or removing SureBright differs by platform: | Platform | Disable or remove | Plans already sold | |---|---|---| | Magento | Disable, enable or remove the module from the command line. While the module is off, the storefront widgets disappear and orders placed in that time do not become contracts. See [Disabling or removing the module](/magento/admin-panel#disabling-or-removing-the-module). | Removing the module does not cancel existing contracts, and your customers can still file claims. | | BigCommerce | Uninstall the app from the BigCommerce control panel. No new contracts are created. Reinstalling reconnects the same SureBright store. Do not delete the two storefront scripts by hand as a way to pause. See [Uninstalling](/bigcommerce/overview#uninstall-the-app). | Existing contracts stay in force and remain visible to their holders. | | Shift4Shop | Ask SureBright to disconnect the store. You then remove the two frontend scripts yourself. See [Disconnecting](/shift4shop/overview#disconnect-your-store). | Existing contracts stay in force. | | Lightspeed X-Series | Ask SureBright to disconnect the store. The sell-screen prompt is removed. The warranty products stay in your catalogue until you archive them. See [Disconnecting](/lightspeed/x-series#disconnect-your-store). | Existing contracts are unaffected. | | Lightspeed R-Series | If you revoke SureBright's access in Lightspeed, sales stop reaching SureBright and **Sync orders** in the Merchant Portal reports a failure. See [Lightspeed R-Series](/lightspeed/r-series#connecting-your-account). | Ask your SureBright contact. | | WooCommerce, Salesforce Commerce Cloud | No switch is documented. Ask your SureBright contact. | Ask your SureBright contact. | ## When you leave SureBright | Question | Answer | |---|---| | What happens to plans already sold? | They stay in force, and your customers can still file claims. See the platform tables above. | | Can I still cancel a plan after I leave? | Once your store is disconnected, refunds in your store no longer reach SureBright. Email [support@surebright.com](mailto:support@surebright.com) with the order number to cancel a plan. | | What happens to my store's data? | On Shopify, uninstalling sends SureBright a request to erase your store's data, 48 hours later. What SureBright holds about your customers, and why plan details are kept while a plan is in force, is on [GDPR webhooks](/shopify/gdpr). On other platforms, ask your SureBright contact. | | Can I take my records with me? | Yes. Download your sales, billed orders and invoices before you leave. See [Your data if you leave](/learn/chargebacks-and-leaving#your-data-if-you-leave). | | Do I still receive invoices? | Yes, for plans sold up to the day you stop. See [Chargebacks and leaving](/learn/chargebacks-and-leaving). | | My business is being sold | Tell your SureBright contact before the handover. See [If your business is sold](/learn/chargebacks-and-leaving#if-your-business-is-sold). | ## Related - [Storefront setup](/shopify/storefront-setup), for Shopify - [GDPR webhooks](/shopify/gdpr), for Shopify - [Contract statuses](/contracts/lifecycle) - [After a theme or platform change](/platforms/after-a-theme-or-platform-change) - [Supported platforms](/platforms/overview) - [Access SureBright needs to your store](/platforms/store-access) --- # Tell us which platform you use Source: https://docs.surebright.com/platforms/request-a-platform > Ask SureBright to support your online store platform, point of sale, ERP or proposal tool, and see how to start offering protection while you wait. If your platform is not on [Supported platforms](/platforms/overview), tell us which one you use. Your request shows us where an app is needed, and we reply with the best way for your store to start. ## What to put in your request - **The platform's name**, as its maker spells it, with the edition or plan if it has more than one. - **Your store's website**, so we can see how your product, cart and checkout pages work. - **How you sell**: online, in store, through proposals, or a mix. If you already work with SureBright, use the email address on your Merchant Portal account so we can find your store. A store can run an online platform and a point of sale side by side. If both are missing, send one request for each. ## What happens after you send it SureBright replies to the email address you gave. The reply tells you which of these fits your store: | Your situation | What we suggest | |---|---| | Your platform can load a script and sell an extra product | Start now with the storefront script and plan products. See [If your platform is not listed](/platforms/other-platforms). | | You sell in store on a register SureBright does not connect to | Record sales in the SureBright POS portal, which works beside any register. See [Sell protection in store](/platforms/in-store-sales). | | Your orders live in an ERP or order system | Send sales as a spreadsheet. See [Spreadsheet order intake](/erp/spreadsheet-order-intake). | | Your developers want to build the connection | Use the SureBright API. See the [Integration tutorial](/api-reference/integration-tutorial). | A request does not commit SureBright to building an app for your platform. It does tell us that one is wanted. ## Start without waiting You do not need a SureBright app to offer protection. The smallest working setup is a storefront script, plan products you create from a sheet SureBright gives you, and a regular sales file. [If your platform is not listed](/platforms/other-platforms) walks through each piece and who does it. ## Related Platforms with a SureBright app or plugin today. What it takes to start on any other platform. Options for registers and point-of-sale systems. Other ways to reach SureBright. --- # Access SureBright needs to your store Source: https://docs.surebright.com/platforms/store-access > Which permissions the SureBright app asks for on Shopify and why they must stay granted, how to approve a new permission request, and how to handle collaborator requests, staff accounts and agency access safely. This page answers what SureBright can reach in your store and why. It covers the permissions the SureBright app asks for on Shopify, how to approve an updated request, and what to do when SureBright or your agency asks for access to your admin. ## Quick answers | You want to | Do this | |---|---| | Know what the Shopify app can do in your store | See [Shopify app permissions](#shopify-app-permissions). | | Approve a new permission request | Sign in to the Merchant Portal with your **Store URL**. Shopify shows the request on the way in. See [Approve an updated permission request](#approve-an-updated-permission-request). | | Check that a collaborator request really comes from SureBright | See [Collaborator requests from SureBright](#collaborator-requests-from-surebright). If in doubt, email [support@surebright.com](mailto:support@surebright.com) before you accept. | | Remove a SureBright staff or collaborator account | You can. The app keeps working without it. See [A SureBright account on your staff list](#a-surebright-account-on-your-staff-list). | | Let your agency or developer work on SureBright | Give them access through your platform, never your own password. See [Agencies and developers](#agencies-and-developers). | | Share your store login with SureBright | Do not. See [Never share passwords](#never-share-passwords). | ## Shopify app permissions When you install **SureBright - Extended Warranty**, Shopify lists the permissions the app asks for, and you approve them. They are wide because a protection plan follows the whole life of an order: the plan products must exist in your catalogue, every paid order must become a contract, and every refund, cancellation, edit and shipment must reach that contract. | Permission area | What SureBright uses it for | |---|---| | Products | Creating and keeping the plan products that shoppers add to the cart, and reading your catalogue so products can be categorised and offered a plan. | | Orders, including older orders | Turning paid orders into contracts, and cancelling or updating contracts when you refund, cancel or edit an order. Older orders are read when you add a plan to a past order from **Leads**. | | Draft orders | The [draft order extension](/draft-order-guide/shopify-draft-order) and plans added to past or phone orders. See [Manual and draft orders](/manual-orders/overview). | | Fulfilment, stock locations and inventory | Following when an order ships, for stores whose coverage starts at shipment, and handling the plan line, which has nothing to ship. | | Sales channels | Keeping the plan products available on your **Online Store** channel so the plan can be added to the cart. | | Files | The image on the plan products. | | Themes | Showing in **Settings → Storefront setup** whether the SureBright Offering embed is turned on in each theme. See [Storefront setup](/shopify/storefront-setup). | | Shipping | [Shipping protection](/shipping-protection/overview). | | Markets | [Shopify Markets pricing](/shopify/markets), where plan prices follow each market. | | Script tags | Stores set up before the theme app embed existed. New stores use the embed. | | Discounts | Only for stores that use [Abandoned Cart Recovery](/abandoned-cart-guide/abandoned-cart), for the single-use codes on the plan. Other stores are not asked for it. | ### Why they must stay granted SureBright works in the background on every order. If a permission is missing, the part that depends on it stops without a visible error: plans are not created for new orders, refunds do not cancel plans, or the portal cannot show your theme status. Shopify does not let you withdraw one permission from an app. Uninstalling withdraws all of them, which is not a pause. See [Pause or remove SureBright](/platforms/pause-or-remove). ### Approve an updated permission request When SureBright needs a permission your store has not granted yet, for example when you switch on a feature that needs it, Shopify asks you to approve it. Enter your **Store URL** (for example `mystore.myshopify.com`) and click **Sign in**. Do this as the store owner, or as a staff member allowed to approve app permissions in Shopify. Shopify shows the SureBright app and the permissions it is asking for. Review them and approve. Shopify then returns you to the portal. Sign out of the portal and sign in again with the **Store URL**. If Shopify still shows nothing, email [support@surebright.com](mailto:support@surebright.com) with your store URL. SureBright sends the request again. If you run more than one store, do this on each one. ## Collaborator requests from SureBright The app works through the permissions above and needs nothing else to run. Some tasks need someone from SureBright to look inside your Shopify admin, for example checking a theme during setup, reconciling orders with you, or fixing a plan on a specific order. For those, SureBright may send a **collaborator request** from Shopify. Before you accept: - **You should expect it.** A collaborator request from SureBright follows a conversation with SureBright about that task. If one arrives out of the blue, do not accept it. Email [support@surebright.com](mailto:support@surebright.com) and ask whether it is genuine. - **Check the permissions it asks for.** Accept only what the task needs. You can change or remove the collaborator's permissions in Shopify at any time. - **Request code.** If your store asks collaborators for a request code, send that code to SureBright when asked, so the request can be made. Shopify shows the code in your admin's user settings. When the task is done you can remove the collaborator account in Shopify. ## A SureBright account on your staff list A SureBright staff or collaborator account on your store is there to help with setup and support. The SureBright app does not depend on it: offers, contracts and cancellations run through the app's own permissions. You can remove it, for example when you need the seat for your own staff. Tell SureBright first, so the team knows to ask again the next time it needs to look at your admin. ## Agencies and developers The Merchant Portal has no separate agency login. Give your agency the access they need through your platform: | Platform | How your agency gets in | |---|---| | Shopify | Accept their collaborator request, or give them a staff account. They then sign in to the Merchant Portal with your **Store URL** and their own Shopify login. See [Team and access](/merchant-portal/team-and-access#give-a-colleague-access). | | BigCommerce, WooCommerce | Give them access to your store admin. They open the portal from the SureBright app or plugin page there. | | Other platforms | Ask your SureBright contact. | For theme work, point your agency at [Storefront setup](/shopify/storefront-setup) and [Shopify admin housekeeping](/shopify/admin-housekeeping). The offer's position on the page is set by SureBright, so there is no SureBright code for them to add to your theme. If the portal opens on **Something went wrong** for your agency, see [When you cannot get in](/merchant-portal/onboarding#when-you-cannot-get-in). ## Never share passwords Do not send your store password or admin login to SureBright, and do not ask your agency to. SureBright does not need it: - On Shopify, everyone signs in with their own login, and SureBright asks for access through a collaborator request. - On WooCommerce, the plugin signs you in to the portal without separate credentials. - On Magento and other platforms where SureBright gave you a sign-in, that sign-in is for the Merchant Portal only. If SureBright needs access that your platform cannot give through its own tools, your SureBright contact will tell you what to create. ## Other platforms | Platform | What you approve | |---|---| | Magento | The integration's access, when you activate it and again when an update needs more. See [Authorise or reauthorise the integration](/magento/admin-panel#authorise-or-reauthorise-the-integration). | | BigCommerce | The app's access when you install it. See [BigCommerce](/bigcommerce/overview). | | WooCommerce | The plugin, and the four order webhooks you create. See [WooCommerce](/woocommerce/overview). | | Lightspeed | The connection to your Lightspeed account. See [Lightspeed X-Series](/lightspeed/x-series) or [Lightspeed R-Series](/lightspeed/r-series). | ## Related Sign in, give a colleague access, or remove someone. What happens after you install, and who does what before you go live. What uninstalling does to the app's access and your plans. What SureBright holds about your customers. For developers: the webhooks SureBright registers on each platform are listed in [Platform webhooks SureBright receives](/api-reference/endpoint/webhooks/platform-receivers). --- # Switching to SureBright Source: https://docs.surebright.com/platforms/switching-to-surebright > For stores that already sell protection through another provider: run one offer at a time, know what happens to plans already sold, set SureBright up in order and tell your customers. If your store already sells protection plans through another provider, you can move to SureBright without a gap and without showing shoppers two offers. This page gives the order to do things in and says what does, and does not, carry over. ## Switching in brief | You want to | Do this | |---|---| | Avoid two offers on the same page | Remove or disable the other provider's offer before you switch SureBright's on. Never run both. | | Get everything ready without shoppers seeing it | Set SureBright up first and leave its offer switched off until the day you change over. | | Know who looks after plans you already sold | The provider that sold them. SureBright has no record of those plans. | | Tell customers what changed | Update your own pages and messages. SureBright's plan confirmation goes to customers who buy a SureBright plan. | ## Run one offer at a time Two protection offers next to **Add to cart** confuse shoppers, and a shopper could pay for both. Take the other provider's offer off every place it shows before SureBright's goes live: product pages, the cart, the cart drawer, checkout and any follow-up emails that provider sends for you. ### Remove the other provider's code yourself SureBright does not edit or remove code in your theme, including code another provider left behind. You or your developer take the other offer off: 1. Uninstall or disable the other provider's app or plugin. 2. Check your theme for anything it left behind: app blocks or embeds in the theme editor, snippets in product, cart and cart drawer templates, and scripts pasted into the theme. Uninstalling an app does not always remove code it added to your theme. 3. Open a product page, the cart and the cart drawer, and confirm the old offer is gone. If you are not sure whether something on the page belongs to the old provider, send SureBright the page URL and a screenshot. SureBright can tell you which parts are its own. ### Removing a specific provider The steps are the same whichever provider you are leaving. What differs is what you are replacing. | Leaving | It sold | Replace it with | Also check | |---|---|---|---| | **Extend** | Product protection plans, and on some stores shipping protection | The matching SureBright protection | Offers on product pages, the cart and the cart drawer, and any post-purchase offer emails it sent | | **Mulberry** | Product protection plans | SureBright product protection | Offers on product pages and the cart, and any post-purchase offer emails | | **Clyde** | Product protection plans | SureBright product protection | Offers on product pages and the cart, and any registration or after-sale offer pages | | **Route** | Shipping protection | [SureBright shipping protection](/shipping-protection/overview), on Shopify and BigCommerce | The checkout or cart toggle, and any shipping protection product it added to your catalogue | | Another provider | Either | The matching SureBright protection | Every place its offer appears | Plans and shipments those providers covered stay with them, as described in [Plans you have already sold](#plans-you-have-already-sold). Uninstall their app, then work through [Remove the other provider's code yourself](#remove-the-other-providers-code-yourself) above. ### Hold the SureBright offer back How you hold the SureBright offer back until the day depends on your platform. **On Shopify** you control the moment. The SureBright offer shows only on themes where the **SureBright Offering** app embed is turned on, so you can: 1. Leave the embed off in your **Live theme** while you set up. 2. Turn it on in an unpublished copy of your theme and preview there. That only affects previews of that theme. 3. On the day, remove the other offer from the live theme and turn the SureBright embed on. See [Storefront setup](/shopify/storefront-setup). **On other platforms**, follow your platform guide from [Supported platforms](/platforms/overview) and agree the change-over day with your SureBright contact. ## Plans you have already sold Plans sold before the switch stay with the provider that sold them. - SureBright creates a contract only when a shopper buys a plan from a SureBright offer. Earlier plans do not appear in your Merchant Portal, and their holders do not see them in the SureBright customer portal. - Customers with an earlier plan keep the documents they were sent and go to that provider for questions and claims. - Note the date you change over. Your support team can then tell from an order's date which provider a customer's plan belongs to. ## Set SureBright up in this order Pick your platform on [Supported platforms](/platforms/overview) and follow its guide. On Shopify, do not turn the embed on in your live theme yet. Sign in to the Merchant Portal and follow the prompts. Check that the products you want covered have a category and show **Active** in [Products](/merchant-portal/products). See [Onboarding](/merchant-portal/onboarding). Review what shoppers will pay in [Warranty Pricing](/merchant-portal/warranty-pricing), where it is enabled for your store. Otherwise ask your SureBright contact for your prices. In [Studio](/merchant-portal/studio), [the storefront scan](/merchant-portal/onboarding#the-storefront-scan) builds a first design from your own product page. Edit it and publish. Studio is available on request. Save a card or bank account in [Billing](/merchant-portal/billing). Run a full order through, from the offer to the cancellation. See [Test your setup](/platforms/test-your-setup). Remove the other provider's offer, switch SureBright's on, and check a product page and the cart straight away. ## Tell your customers - Shoppers who buy a SureBright plan get their plan confirmation from SureBright by email, with your store named in it. You do not send anything yourself. See [Emails your customers receive](/customer-emails/overview). - They see their plan and file claims in the [customer portal](/customer-portal/overview). - Update the places on your own site that name your protection provider or explain how to claim: your warranty or support page, your FAQs and your order emails. Say that plans bought before the change-over date stay with the earlier provider. - Brief your support team with the change-over date and both sets of contact details. - Need words for your own warranty page or FAQ? SureBright can share example FAQ pages and a media kit you can adapt, and can create a dedicated protection page for your store. Ask your SureBright contact. On Shopify, see also the [protection and registration pages](/shopify/product-registration). ## Related - [Supported platforms](/platforms/overview) - [Test your setup](/platforms/test-your-setup) - [After a theme or platform change](/platforms/after-a-theme-or-platform-change) - [Emails your customers receive](/customer-emails/overview) - [Merchant FAQ](/help/faq) --- # Test your setup Source: https://docs.surebright.com/platforms/test-your-setup > Confirm the offer, the order, the contract, the customer email and the cancellation all work before you launch SureBright on your store. Before you launch, run one order through SureBright from the product page to the cancellation. The flow is the same on every platform: see the offer, buy a plan, find the contract, then cancel. This page says what you need first, gives the steps for Shopify in full, points to the checks for other platforms, and ends with a launch checklist. ## Before you start | You need | Where to get it | |---|---| | SureBright installed and switched on in the storefront you test in | Your platform's guide, from [Supported platforms](/platforms/overview). On Shopify this is the SureBright Offering app embed, turned on in the theme you test in under **Settings → Storefront setup** in the Merchant Portal. An unpublished theme is enough for a preview: the embed then only affects previews of that theme. See [Storefront setup](/shopify/storefront-setup). | | A product that offers protection | [Products](/merchant-portal/products), under the **Warranty Active** chip. The offer only renders on products in an eligible category, so a product picked at random can look as if nothing works. | | An email address you can read | The customer emails go to the address on the order. | ## Run the test on Shopify Open the product on your storefront, or in the theme editor preview. The protection offer shows near **Add to cart**. If it does not, work through [No offer on product pages](/shopify/storefront-setup#troubleshooting). Pick a plan and add the product to the cart. The cart holds two lines: the product and the plan. Change the product quantity and check that the plan line follows it. Check out with one of Shopify's test payment methods and your own email address. Shopify marks such an order as a test order, and SureBright treats it as one. The contract is created once the order is paid. In the Merchant Portal open [Sales](/merchant-portal/sales) and look under **Recent Sales**. There is one row per plan unit, with the order number and a **Warranty status**. If the plan is missing, look in **Order Resolution** and read [Why a contract is on hold](/contracts/holds). The plan confirmation arrives with the subject `SureBright warranty policy details of your recent purchase`. On stores whose coverage starts at shipment you get **Order received** first, and the confirmation follows when you fulfil the order. You can also sign in to the [customer portal](/customer-portal/overview) with the same email address and see the plan. All the emails are listed in [Emails your customers receive](/customer-emails/overview). Cancel the order in Shopify admin, or refund the plan line. The contract's **Warranty status** changes to **Cancelled** and the cancellation confirmation email arrives. If you refund only the product and keep the plan, nothing is cancelled: a case appears in [Order Resolution](/merchant-portal/order-resolution) instead. On Shopify, if the SureBright Cart Validator is active, also test it: put a plan in a cart without its product and go to checkout. The purchase should be blocked. See [Enable the SureBright Cart Validator](/shopify/enable-surebright-cart-validator). ## Test orders and billing - An order paid with a real payment method is a real sale, whatever your intent. Cancel or refund it: a plan cancelled before it is charged is not billed. - A whole store can be treated as a test store, so that nothing sold on it is billed. SureBright sets that for you: ask your SureBright contact if you are testing on a development store or a copy of your shop. - On Shopify, you are not billed for a plan on an order that Shopify marked as a test. Its **Warranty status** can still read **Active**, so do not take that as a sign that it will be charged. - On other platforms, ask your SureBright contact how test orders are treated before you place one. ## Test on other platforms The flow is the same everywhere: see the offer, buy a plan, find the contract under **Recent Sales**, then cancel. Whether a cancellation or refund in your store admin cancels the contract for you is shown per platform in [What works on each platform](/platforms/overview#what-works-on-each-platform). Platform pages that describe their own checks: | Platform | Where the checks are | |---|---| | Magento | [When offers do not show](/magento/storefront-widget#when-offers-do-not-show) and **Test webhook** under [Webhook Connectivity](/magento/admin-panel#test-that-your-server-can-reach-surebright) | | Salesforce Commerce Cloud | [Testing](/salesforce-commerce-cloud/testing), in your sandbox before production | | BigCommerce | [Where contracts appear](/bigcommerce/overview#find-your-contracts-in-the-merchant-portal) | | WooCommerce | [Order webhooks](/woocommerce/overview#set-up-the-four-order-webhooks): check that all four read **Active** in WooCommerce | | Headless Shopify storefronts | [Verify](/frontend-widget-integration/frontend-widget-kit/headless-and-custom-storefronts#verify) | | Bundles on Shopify | [Bundles](/shopify/bundles) | ## Test an API integration If your developers record orders through the SureBright API, they can try it first from the **Developers** page in the Merchant Portal. Its playground sends a sample order that is marked as a test, and playground orders carry a **Test** tag in **Recent Sales**. See [Developers](/merchant-portal/developers#try-the-api-from-the-portal). For developers: how to mark your own orders as tests is in [Create contracts for an order](/api-reference/endpoint/order/create-contract), and keys and hosts are in [Authentication](/api-reference/authentication). ## Start with a few products You do not have to launch on your whole catalogue at once. Ways to try SureBright on a small scale first: | You want to | Do this | |---|---| | See and approve the design before anyone else does | In [Studio](/merchant-portal/studio#try-a-design-on-your-real-store-first), preview a draft on your own storefront before you publish. Without Studio, ask your SureBright contact to share the design, and other layouts to compare, for your approval. | | See plan prices before go-live | Check [Warranty Pricing](/merchant-portal/warranty-pricing) where it is enabled, or ask your SureBright contact for the plan prices for your products. | | Offer protection on one product, such as a slow-moving item | In [Products](/merchant-portal/products), set **Warranty status** to **Active** on that product only and **Inactive** on the rest. Widen it later from the same page. | | Keep the offer away from your main pages | Ask your SureBright contact to run the offer only on a landing page or product page that you share by direct link. | | Try it on Shopify without shoppers seeing it | Turn the embed on in an unpublished copy of your theme and preview there. See [Before you start](#before-you-start). | When the pilot looks right, go through the launch checklist below. ## Launch checklist | Check | Where | |---|---| | Your store card reads **Live** | [Merchant Portal overview](/merchant-portal/overview#check-your-stores-status) | | A payment method is saved | [Billing](/merchant-portal/billing) | | The products you want covered show **Active** and have a category | [Products](/merchant-portal/products) | | Plan prices are the ones you expect | [Warranty Pricing](/merchant-portal/warranty-pricing), where enabled | | Your widget design is published | [Studio](/merchant-portal/studio), where enabled | | The test order produced a contract and an email, and cancelling it cancelled the contract | This page | | On Shopify, the embed reads **Turned on** next to your **Live theme**, not only next to an unpublished one | [Settings → Storefront setup](/merchant-portal/settings#check-your-shopify-storefront-setup) | | On Shopify, discounts leave SureBright products out and the Cart Validator is active | [Shopify admin housekeeping](/shopify/admin-housekeeping) | | On Shopify Plus, the checkout blocks are placed and show in the checkout preview | [Checkout extensions](/shopify/checkout-extensions) | ## Related - [Supported platforms](/platforms/overview) - [Storefront setup](/shopify/storefront-setup), for Shopify - [Contract statuses](/contracts/lifecycle) - [Emails your customers receive](/customer-emails/overview) - [Pause or remove SureBright](/platforms/pause-or-remove) **See also:** [Try it on one product or page first](/merchant-portal/widget-options#try-it-on-one-product-or-page-first). --- # Billing Source: https://docs.surebright.com/pos/billing > Add a card or bank account for SureBright to charge, what happens while a bank account is being verified, the default and per-store methods, and your invoices. SureBright invoices you for the plans your stores sell and charges the invoice to a payment method you keep on file. Owners manage this under **Settings → Billing**, which has two tabs: **Payment method** and **Billing history**. The same invoices and payment methods are visible in the merchant portal for accounts that have one; see [Merchant portal billing](/merchant-portal/billing) for the invoice breakdown and billed-order exports. Stores that SureBright invoices manually skip the payment-method requirement. ## Add a payment method Click the add button and pick **Add Credit card/ Debit card** or **Add bank details**. The form is served by Stripe; SureBright never sees the full card or account number. A card needs the cardholder name, number, expiry and CVC. A bank account needs **Account holder name**, **Routing number (ABA- 9 digits)**, **Account number**, **Confirm account number** and **Account type** (**Checking** or **Savings**), for a US or Canadian bank. Click **Save**. A card is usable at once. A bank account is usually confirmed at once too; when the bank needs to verify it, the method shows **Pending verification** and the dialog explains the next step. If a card is declined, or a bank account is rejected, the dialog says so and asks you to try a different one. ## While your bank account is being verified A bank account the bank still has to verify is listed with **Pending verification** and **Awaiting verification from your bank**. Where the bank uses small test deposits, you complete verification by confirming the amounts when they arrive. The portal shows **Bank account verification in progress. Your bank account is being verified. This may take 1-2 business days.** Until you have a verified method: - You can record up to ten sales, and no single sale above $1,000. **Record Sale** shows how many you have left. - Checkout refuses a sale that would go over either limit and asks you to complete payment method verification. - The limits disappear as soon as any method is verified. A new owner with no payment method at all is taken to **Manage stores** on sign-in and asked to add one before continuing. ## Choose which method is charged Your **Default payment method** is the one SureBright charges. To change it, choose **Set as default payment method** on another method and confirm with **Yes, Make default**. ### Use a different method for one store Under **Stores**, each location lists its **Payment method**, and **Edit payment method** lets you assign one. A store with none assigned shows **Payment method not added**. Your invoice is charged to your **Default payment method**, so keep the default set to the account you want to pay from. If you need each store to pay from its own account, ask your SureBright contact. ### Remove a payment method Click **Delete** on the method. If any store is assigned to it, the dialog lists those stores and asks you to pick a replacement for each before you **Reassign & Remove**; otherwise it is **Confirm, Removal**. You cannot remove your only method. ## Billing history One row per invoice with **Date**, **Amount**, **Status** and **Payment method**, sortable by any column. **Download invoice** saves the invoice PDF. | Status | Meaning | |---|---| | **Processed** | Charged successfully. | An invoice whose charge failed is not listed. Its plans are billed again on a later invoice. Check your default payment method and contact SureBright. An empty tab reads **No billing history yet**. ## What you are charged for Each invoice covers the plans your stores sold in the period, less refunds for plans cancelled since. The POS shows the amount and the method charged; the line-by-line breakdown of charges, carryover and refunds is on the invoice PDF and, for accounts with a merchant portal, under [Merchant portal billing](/merchant-portal/billing#see-what-an-invoice-charged-you-for). --- # Bulk upload Source: https://docs.surebright.com/pos/bulk-upload > Record many past sales from a CSV, or upload a scanned invoice and let the portal read the line items, then review before anything is saved. Two shortcuts let you record sales without typing each one into [Record Sale](/pos/recording-a-sale): a CSV upload for a batch of past sales, and an invoice upload that reads a PDF or photo of a customer's receipt. Both end in a review step; nothing is saved until you confirm. ## Upload a CSV of sales Use this when you have a spreadsheet of sales, for example from your till, and want plans recorded for all of them. Open the upload dialog from the **Record Sale** header and download the sample file (one for US sales, one for Canadian sales) and the **Sales Data Upload Guidelines** PDF. Keep the column headings exactly as in the sample. Save as `.csv`; other spreadsheet formats are rejected. Click **Select file**, choose the CSV and click **Upload**. The portal checks every row. Rows are split into **Needs attention** (fix these to include the records in your reports) and **Ready to add** (these records will be added to your reports). Each row shows whether the product is **Eligible** or **Not Eligible** for a plan. Edit a cell inline to fix an error, assign the sale to a team member with **Select team member...**, or **Skip this item** to leave a row out. **Confirm & Save** records the valid and fixed rows and shows a summary. Rows that could not be saved are listed with the reason. **Discard** throws the whole upload away. ### What to put in each column | Column | What to put in it | |---|---| | **Sale date** | The date of the sale. | | **Product**, **SKU/ Model number**, **Manufacturer Name** | The product sold. | | **Manufacturer Warranty Duration** | In months. | | **Product condition** | New, Used, Refurbished or Certified Refurbished. | | **Product price** | What the customer paid for the product. | | **Plan term**, **Coverage type**, **Plan Retail Price** | The plan sold, for example `3 Years`, `Accidental Damage Plan`, and the price the customer paid for it. | | **Quantity** | Units sold. One plan is recorded per unit. | | **Team Member** | The team member who made the sale. | | **First name**, **Last name**, **Email Id**, **Phone Number** | The customer. | | **Street Address**, **Address Line Two**, **City Name**, **State**, **Zip Code**, **Country** | The customer's address. | Imported sales appear in [Sales History](/pos/sales-history) like any other sale, and the dashboard logs a **Bulk sales upload** activity. ## Upload a scanned invoice Use this when a customer hands you a receipt or you have a PDF invoice: the portal reads it and turns the line items into a cart. In **Record Sale**, use the invoice upload button and choose a PDF, PNG, JPG or WebP file. Other types are refused with **Unsupported file. Upload a PDF or image invoice.** An **Extracting** screen follows progress while the invoice is read. Large invoices take a few extra seconds. If the file cannot be read, or reading takes too long, you are told to try again or enter the details manually. The **Review invoice items** step lists every line found, with the file name and **Purchased on** date at the top. Each row shows **Product**, **Price**, **Warranty plan** and **Status**. Under the product title, **Still needed:** names anything missing (**Condition**, **Manufacturer**, **Warranty**). Click **Edit product** to fill them in; a category is suggested automatically where possible. A row that cannot carry a plan says why: the product is not eligible, no plan is available, or the price is outside the plan range. Adjust the price or quantity inline, pick a plan with **Select plan**, or remove the line. Every product needs a unique SKU. You can edit any detail until you submit. Click **Next**. If your cart already has items, **Items already in your cart** asks whether to add to them. The reviewed lines join the cart and you continue to customer details as in [Recording a sale](/pos/recording-a-sale#step-2-enter-the-customers-details). Invoice upload records a single sale for one customer. For many sales at once, use the CSV upload above. --- # Product catalogue Source: https://docs.surebright.com/pos/catalogue > Add, edit and remove the products you sell plans against, change categories in bulk, and import a CSV that you review before anything is saved. The **Product Catalogue** is the list of products your staff pick from in [Record Sale](/pos/recording-a-sale). Each product carries the details SureBright needs to quote a plan: category, condition, manufacturer, manufacturer warranty and price. Keep it current and recording a sale is a two-click job. ## What the catalogue shows Columns: **Sr no**, **SKU**, **Product category**, **Product name**, **Condition**, **Manufacturer name**, **Manufacturer/Seller warranty**, **Product price**, plus a **Warranty eligibility** flag (**Eligible** or **Not eligible**) that tells you whether SureBright has a plan for the product as entered. Filter with the **Category** tabs and the search box. Products you have deactivated are marked **Inactive**. Empty catalogue: **No products in your catalog yet. Add a product or upload your catalog to get started.** ## Add or edit a product Click **Add product**, or the **Edit product** icon on a row. The form: | Field | Required | Notes | |---|---|---| | **SKU / Model Number** | Yes | Unique within your catalogue. Imports match existing products on it. | | **Product Category** | Yes | A SureBright category such as **Electronics**, **Home appliances**, **Furniture**, **Jewellery & watches**, **Medical equipment**, **Fitness & sports**, **HVAC systems**, **Solar products**, **Lawn & garden**, **Musical instrument**, **Outdoor Recreation** and others. | | Product title | Yes | | | Manufacturer name | Yes | | | **Condition** | Yes | **New**, **Used**, **Refurbished** or **Certified Refurbished**. | | **Manufacturer / Seller Warranty** | Yes | A duration from the standard list, or **Custom**. | | Product price | Yes | Must be greater than zero. | **Save** adds the product or keeps your changes. Edits take effect for the next sale; sales already recorded keep the details they were sold with. ## Remove products Use the **Delete product** icon on a row, or tick several rows and remove them together. The confirmation reads **Are you sure you want to remove this product from the catalog?** and notes that **Existing sales records and reports will remain unchanged.** Click **Confirm, Removal**. ## Change the category of several products Tick the products (the bar shows **Selected : N**), click **Change category**, pick the new category and **Confirm & Save**. Every selected product moves to that category. Use this after an import put products in the wrong category. ## Import products from a CSV Click **Upload product catalog**. The file is checked first, then you review and fix rows. Nothing is added to your catalogue until you confirm. Download the template from the upload dialog. Its columns are `productSKU`, `productTitle`, `storeProductType`, `productCondition`, `manufacturerName`, `manufacturerWarrantyDuration` (months) and `price`. A sample file with a few rows is also provided. Click **Select file**, choose a `.csv` and click **Upload**. Up to 5,000 rows per file. Rows are grouped into **Needs attention** (fix these issues to include the products in your catalog) and **Ready to add** (these products will be added to your catalog). Filter by category or **Search**. Each failed row says what is wrong, for example `productSKU is required`, `productCondition must be one of: NEW, USED, REFURBISHED, CERTIFIED_REFURBISHED`, or `price must be greater than zero`. Edit the cell inline; the row is re-checked and moves to **Ready to add** when it passes. **Continue with valid products** takes the valid and fixed rows forward; **Cancel** discards the upload. Confirm with **Confirm & Save**. The summary tells you how many items were skipped due to issues; you can review and fix the skipped products later. ### What the import does with duplicates - A SKU that already exists in your catalogue is updated with the row's values rather than duplicated. - A SKU that appears twice in the file is imported once, using the last occurrence. - A SKU you had deleted earlier is restored with the new values. ### Records kept for an audit SureBright keeps the original file you uploaded and a record of exactly what each import changed, including the rows as they were before each edit you made in the review. These are not shown in the portal. Ask your SureBright contact if you need them for an audit. The dashboard logs a **Bulk product upload** activity when an import is saved, and **Product added**, **Product updated** and **Product deleted** activities for single edits. --- # Locations and team Source: https://docs.surebright.com/pos/locations-and-team > Run several stores under one account, invite staff with a role per store, change roles within the rules, and set each member's commission per store with a change history. One SureBright account can hold any number of **stores** (locations). Team members are invited to specific stores with a role in each. You manage stores under **Settings → Manage stores** and people under **Team Management**. ## Manage your stores ### Add a store and know your default Stores are added during account setup and later from **Settings → Manage stores**. Each store has a **Store name**, **Street address**, city, state or province, postal code, **Country** and a **Store contact number** (your own number or a store-specific one). The first store you create is your default store: it is the one selected when a member signs in and the one sales fall into when no store is picked. ### Switch between stores The **Location** filter in the header switches between **All stores** and a single store. The choice follows you across Record Sale, Sales History and the Dashboard: sales are recorded against the selected store, and history and charts are filtered to it. A sales associate only ever sees their store. ### Change or deactivate a store Store details are not edited directly. From the **Store actions** menu choose **Update store name**, **Update store address**, **Update store phone number**, **Deactivate store** or **Other**, add the new value and a reason, and submit. SureBright reviews the request and applies it. A deactivated store shows **Deactivated**; choose **Reactivate store** to request it back. While a deactivated store is selected, Record Sale, Team Management and Onboarding are disabled. Each store can have its own payment method; see [Billing](/pos/billing#use-a-different-method-for-one-store). ## Manage your team Admins and owners see **Team Management**. It has two tabs, **Active members** and **Removed members**, and lists **Name**, **Email**, **Store name**, **Role**, **Sales commission** and **Last active** for each member. A member with access to several stores appears once, with the stores and a commission range. ### Invite a team member Click **Add team member**. Enter **Full name** and **Email address**. Choose **Owner**, **Admin** or **Sales associate**. Admins and owners can be given **All stores** or a selection (**Select stores**); a sales associate gets exactly one store (**Select a store**). Set the **Sales commission** for a sales associate. Click **Send invite**. The person gets an email with a link to sign up; their access is set from the role you chose. Pending invites can be resent or revoked (**Revoke Invite**). ### A team member cannot sign in Invited team members do not sign up from the login page. They set up their account from the invite email first, then sign in. | What they see | What to do | |---|---| | They never set up their account | Ask them to open the invite email and follow its link. Their name and email address are filled in from the invite. If they cannot find it, check their spam folder, then resend the invite from **Team Management**. | | **Invalid Invite Link** (*This invite link is invalid or has expired.*) | Resend the invite from **Team Management**, or revoke it and invite them again. | | **Invalid email or password. Please try again.** | They must sign in with the exact email address you invited. Use **Forgot password?** on the login page to set a new password. | | **Account not found. Please sign up.** | The address they typed may not be the one you invited, or they have not set up their account from the invite yet. Check the address under **Team Management** and resend the invite if needed. | | They are listed under **Removed members** | Invite them again. | Owners signing up a new store need a work or business email address: the sign-up form answers a free personal address with **Free email not allowed. Please use your work or business email.** If your business has no domain of its own, email [support@surebright.com](mailto:support@surebright.com) with the address you want to use. Team members you invite are signed up through their invite, with the address you entered. ### What each role can do | Role | Can do | |---|---| | **Owner** | Everything: manage owners and admins, billing and subscription, access to all stores. Only an owner can make someone an owner. | | **Admin** | Team management (invite, edit, remove sales associates), access to the stores granted, view financial data and settings. | | **Sales associate** | Record sales and view their own sales and commission for one store. | ### Change a role or store access Open the member's actions menu: **View**, **Edit access**, **Add store access**, **View change history**, **Remove**. **Edit access** shows one row per store with **Store name**, **Role** and **Sales commission**. **Add store access** adds rows. What you can and cannot change: - An owner's role cannot be changed here; their commission can. - Only owners can promote to owner. - Upgrades (sales associate to admin, admin to owner) are always allowed. The dialog lists what the member gains, for example **Team management (invite, edit, remove sales associates)** and **Access to multiple stores**. - Demoting an admin to sales associate is allowed only when they are left with exactly one store. Otherwise you see **Remove extra store access before demoting to sales associate** or **Sales associate must keep at least one store**. - You cannot remove a member's last store. **Remove** takes the member out of your team. You can still view their past performance and other data; they move to **Removed members**. ### Set a member's commission Each member has a **Sales commission** per store: a percentage you choose from a list, used to work out the **Commission earned** figures on the [dashboard](/pos/sales-history#see-how-your-stores-and-team-are-doing), in Sales History and in the monthly challenge. Set it when you invite the member, and change it later in **Edit access** or **Add store access**. Where a member's commission differs between stores, the table shows the range, for example **10 – 30%**. SureBright does not pay commission; the figures are for your own payroll and incentives. ### See a member's change history **View change history** lists every change to a member over time: **Role changed**, **Commission updated**, **Member invited**, **Member joined**, **Member removed**, **Invitation resent** and **Invitation revoked**, each with the before and after values (**Role:**, **Commission:**), who made the change and when. The dashboard's **Recent activities** shows the same events under **Team events**. --- # POS portal overview Source: https://docs.surebright.com/pos/overview > What the SureBright POS portal is, who signs in, what each role can do, and how it connects to the Merchant Portal and the service portal. The SureBright POS portal is the web app your store staff use to sell protection plans at the counter and to record sales made outside your online store. It keeps your product catalogue, your team and locations, your sales history and your billing in one place, and it works on a phone, a tablet or a desktop browser. You need it when a customer buys a product in person, over the phone, or on an invoice, and you want to attach a SureBright plan to that sale. ## Already have a register or POS system? You do not have to replace your till. Pick the row that matches how you sell in person. | Your setup | How plans get recorded | Start here | |---|---|---| | Lightspeed X-Series or R-Series | SureBright connects to Lightspeed. A register sale that includes a SureBright warranty item becomes a plan by itself. | [Lightspeed X-Series](/lightspeed/x-series), [Lightspeed R-Series](/lightspeed/r-series) | | Shopify POS | Staff add the plan in the Shopify POS app, on the same receipt as the product. | [POS extension](/shopify/pos-extension) | | Any other register or POS system | Ring up the product on your till as usual, then record the plan here in **Record Sale**. The portal runs alongside your till and does not connect to it. | [Recording a sale](/pos/recording-a-sale) | | A batch of sales exported from your till or spreadsheet | Upload them as a CSV. | [Bulk upload](/pos/bulk-upload) | | A developer who can connect your POS or ERP | Your system sends each plan sale to SureBright, and cancels it, without anyone typing it in. | [Transaction ingest API](/api-reference/endpoint/partner/transaction-ingest) | | Quotes or proposals made through a partner's quoting tool | The plan reaches SureBright only once it is activated in that tool after the customer accepts. If accepted quotes do not appear in your sales, check that each was activated, then ask your SureBright contact. | Your SureBright contact | If your system is not listed and you want a direct connection, ask your SureBright contact what is available. ### Selling online and in store at the same time Your online store and your point of sale are set up separately and run side by side, so adding one does not change the other. On Lightspeed, SureBright adds its own warranty items to your Lightspeed catalogue; your online store keeps its own setup. Customers get the same confirmation email and claim the same way, in the [customer portal](/customer-portal/overview), wherever they bought. See [Sell protection in store](/platforms/in-store-sales). ## Who signs in and what each role can do Every member of your team gets their own login. Access is decided by a role, and a member can hold a different role in each of your stores. | Role | What the portal lets them do | |---|---| | **Owner** | Everything below, plus billing and payment methods, managing owners and admins, and access to all stores. | | **Admin** | Manage team members and settings, view financial data, record sales and look up sales history for the stores they have access to. | | **Sales associate** | Record sales and view their own sales and commission earnings for one store. | See [Locations and team](/pos/locations-and-team) for how roles are granted and changed. ## Find your way around the portal The left sidebar has one entry per area: | Entry | What it is | Page | |---|---|---| | **Dashboard** | Plans sold, charts, team performance, the monthly challenge and recent activity. | [Sales history and dashboards](/pos/sales-history) | | **Record Sale** | The sale flow: products, customer, confirmation. Also bulk and invoice upload. | [Recording a sale](/pos/recording-a-sale), [Bulk upload](/pos/bulk-upload) | | **Sales History** | Every recorded sale with update, plan change and cancel actions. | [Sales history and dashboards](/pos/sales-history) | | **Product Catalogue** | The products you sell plans against, with CSV import. | [Product catalogue](/pos/catalogue) | | **Team Management** | Invite members, grant store access, change roles and commission. Admins and owners only. | [Locations and team](/pos/locations-and-team) | | **Onboarding** | **Onboarding & Training**: **Common questions**, **Tour the portal** and **Training Videos**. | | | **Settings** | **Account details**, **Manage stores**, **Billing** and **Contact us**. | [Locations and team](/pos/locations-and-team), [Billing](/pos/billing) | The **Location** filter in the header switches between **All stores** and a single store. Whatever you pick applies to Record Sale, Sales History and the dashboard. Deactivated stores are listed under **Deactivated stores**; while one of them is selected, Record Sale, Team Management and Onboarding are greyed out. Products, customer, confirm. What the customer receives. Import a CSV of past sales, or upload a scanned invoice. Update, change plan, cancel with a refund estimate, leaderboard. Add products one by one or import a CSV with a review step. Stores, invitations, roles and per-store commission. Cards and bank accounts, verification, invoices. A chat assistant for store staff. Early access. Send sales from your own POS or ERP instead of typing them in. ## Install the portal like an app You can add the portal to your phone, tablet or computer like an app. Open it in your browser and use the browser's install or **Add to Home Screen** option. It is named **SureBright POS** and then opens full screen, in portrait, with its own icon. Nothing is downloaded from an app store and updates arrive automatically. ## One login across SureBright portals Your POS login is also your login for the other SureBright portals. Open the user menu in the top right: - **Merchant Portal** opens the [merchant portal](/merchant-portal/overview) already signed in. Shown to owners whose account has a merchant portal. - **Sell System Warranties** opens the installer portal already signed in. Shown when your account is set up for the [Whole System Warranty](/installers/overview). - **Logout** signs you out of the POS. Arriving the other way works too: a link from the merchant portal or service portal lands you in the POS without entering your password again. If a portal is not available to you, the menu entry does not appear. ## Get help inside the portal **Onboarding** holds **Common questions**, short **Training Videos** and **Tour the portal**, a guided walkthrough that highlights each part of a page. New accounts see the tour on their first visit to the dashboard; you can start it again from the Onboarding page at any time. **Settings → Contact us** lists SureBright's **Phone** and **Mail** contacts. ## Counter cards, signage and staff training For printed material to help staff offer plans at the counter, such as counter cards or signage, ask your SureBright contact or email [support@surebright.com](mailto:support@surebright.com). Say how many stores you have and what you would like. For what your staff should know about the plans themselves, share [Plan overview for your team](/help/plan-overview) with them. --- # Ray assistant Source: https://docs.surebright.com/pos/ray-assistant > A chat assistant inside the POS that answers staff questions and records, looks up and cancels sales for them, with photo attachments and a confirmation before anything changes. Early access. Ask your SureBright contact to enable this for your store. **Ray** is a chat assistant that lives in the POS. Store staff ask it questions in plain language, and it answers from SureBright's help content or acts on your sales for you: recording a sale, looking one up, checking whether a product can carry a plan, or estimating a refund. It is meant for the moment a customer is at the counter and you do not want to leave the page you are on. ## Turn Ray on Ray is enabled per store by SureBright while it is in early access; nothing is installed on your side. Ray is hidden until your store unlocks it. SureBright gives you an unlock code; type it on any POS page (not inside a text field) and the **Ask Ray** button appears in the corner and opens. The unlock is remembered in that browser. ## What Ray can do The empty chat suggests where to start: - **Record a sale** - **Look up my sales**, for example **Show my sales from this week** - **Cancel a sale and see the refund** - **Is this product eligible for a plan?** - **A customer's product broke, what do you think?** - **How do refunds work?** | You ask | Ray does | |---|---| | To record a sale | Asks for anything missing (**Still needed:** customer, product, plan, quantity, purchase date), shows a **Sale to confirm** card and records it only when you confirm. The card warns that confirming records a real sale that can only be cancelled later with a refund. | | To find sales | Shows a list of matching sales with their status, and the details of one when you pick it. | | To cancel a sale | Shows a **Refund estimate** (plan price paid, what the customer gets back if they cancel today, whether the cancellation would be accepted), then a **Cancellation preview**. You choose to cancel or **Keep the sale**. | | To change a plan | Tells you whether the plan length can be changed on that sale. Plan changes themselves are made in [Sales History](/pos/sales-history#change-warranty-plan). | | For an invoice | Produces the sale's invoice as a file you can open and download. | | Whether a product is eligible | Checks the product and price against your store's categories and tells you which plans, if any, apply. | | About a broken product | Gives **Ray's read**: **What I understood**, **How the plan terms apply** and what it is **Based on**. It is marked **Not a decision**; it helps you set expectations with the customer, and when it cannot assess the case it says **I can't assess this**. Claims are still filed through the customer's own channel. | | A how-to question | Answers from SureBright's help content and says so when it does not know. | Ray works with the store selected in the header **Location** filter and respects the signed-in role: a sales associate sees and changes only their own sales, while admins and owners work across the stores they have access to. The role is shown in the chat header. ## Attach photos Attach up to 6 photos per message (JPEG, PNG, WebP or HEIC, 15 MB each) with **Attach photos** or by dragging them in. Use this for a receipt or a product label when recording a sale, or to show damage when asking about a customer's product. A photo that is too large or the wrong type is marked and left out. ## Chat with Ray Type in **Ask Ray anything…** and press Enter to send. Ray often answers with a card plus a row of quick replies you can tap instead of typing. When it needs a choice from you, for example which of several matching products you mean, it shows a picker. The launcher shows an unread badge when Ray answered while the panel was closed, and the header shows your role (**Owner**, **Admin** or **Sales Associate**) and whether Ray is **Online** or **Offline**. ## Start a new chat or reopen an old one **New chat** starts fresh; **History** lists earlier chats under **Today**, **This week** and **Older**, and lets you reopen or delete them. If you lose connection, a banner reads **You're offline. Ray will reconnect on its own.** While Ray is still working on your last request you can keep typing; it answers when it is done. ## What Ray does not do Ray is a helper for the person at the counter, not a replacement for the portal pages. - It never records or cancels anything without a confirmation card that you accept. - It does not change plan terms, edit the catalogue, manage team members or touch billing. - It does not see other stores' data than the signed-in member is allowed to see. - It does not decide claims. Its read on a broken product is guidance only. If Ray is not available for your store yet, every action it offers is still available from [Record Sale](/pos/recording-a-sale) and [Sales History](/pos/sales-history). --- # Recording a sale Source: https://docs.surebright.com/pos/recording-a-sale > Record a plan sale in three steps: pick the product and plan, enter the customer, confirm. Includes entering the manufacturer warranty and what the customer receives. **Record Sale** is where you attach a SureBright plan to an in-person sale. You pick the product and the plan, enter the customer's details, and confirm. The plan is created on the spot and the customer is emailed their coverage. Use it at the counter while the customer is with you, or afterwards from the receipt. Sales recorded here appear in [Sales History](/pos/sales-history) and on the dashboard straight away. ## Before you start - Pick the right store in the header **Location** filter. The sale is recorded against that store. - Owners must have a payment method on file. Until a method is verified, the page shows how many more sales you can record and a cap on the total; see [Billing](/pos/billing#while-your-bank-account-is-being-verified). - If the selected store is deactivated, Record Sale is disabled. Reactivate it from **Settings → Manage stores**. ## Step 1: choose the product and plan The page opens on your [product catalogue](/pos/catalogue). Find the product with **Search product**, the category tabs (**All**, **Electronics**, **Home appliances**, **Jewelry**, **Automobile**, **Furniture**), the **Eligible Products** / **Non Eligible Products** filter, the price-range filter (**Under $100** up to **$1000+**) and the sort order (**Recently Added**, **Low to High Price**, **High to Low Price**, **Frequently Used**). Switch between grid and list views with the view toggle. Click **Add to cart** on the product. A plan picker opens with every plan available for that product: the term, the coverage type (**Accidental warranty** or **Extended warranty**) and the price the customer pays. **What's covered** opens the plan's coverage details and links to the plan's terms. If the product sold for a different price than the catalogue says, use **Update retail price**. The plan prices update to match the new price. The picker warns when a price looks too high. Set the quantity, then **Add to cart** (or **Update cart** if the product is already in it). The cart lists each product with its plan and a running **Total**. Edit a plan or remove a line from here. Click **Continue to checkout**. ### Sell a plan on a product not in your catalogue You can sell a plan on a product you have not catalogued yet. Choose a category with **Select a product category** and a price band with **Select applicable product price range** to see plans without a product, or click **Add New Product** to save the product first. The form asks for: | Field | Notes | |---|---| | **Product Category** | Picked by SureBright from the title when it can; shows an **Auto** badge. Change it if it is wrong. | | **Product SKU / Model Number** | Required. Must be unique in your catalogue. | | **Product Title** | Required. | | **Manufacturer Name** | Required. | | **Manufacturer / Seller Warranty** | Required. See below. | | **Product Selling Price** | Required. | If the category you pick does not match what SureBright detected, a warning asks you to **Continue & Save** or go back. The product is added to your catalogue, so it is there for the next sale. ### Enter the manufacturer warranty Every product carries a **Manufacturer / Seller Warranty** duration. Pick it from a fixed list (3, 6 and 9 months, then 1 to 7 years). SureBright uses it to work out when its own coverage starts and which plans to offer, so the plan list changes when you change the duration. Products imported without a duration are treated as having a 12-month manufacturer warranty. You can correct the duration for up to 45 days after a sale from Sales History; see [Update product details](/pos/sales-history#update-product-details). ## Step 2: enter the customer's details Fill in **Customer details**: **First name**, **Last name**, **Email address**, phone (with a country code, **+1 (US/CA)** by default), the purchase date, and the address. The address needs a street, city, state or province, postal code and country, unless you tick **Address details will be entered later by the customer via a link.** The **Order summary** on the side lists each line, the plan and the **Total**. For Canadian sales pick the **Province** here: plan prices depend on it, and when the province changes the summary shows **Pricing updated** with the new figures. **Order Documents** opens the terms the customer is agreeing to. Click **Submit**. One plan is recorded for each unit in the cart. ### The customer gave no address Tick **Address details will be entered later by the customer via a link.** The customer then gets an email asking them to add the address in the [customer portal](/customer-portal/overview), straight to the plan. Take the customer's email address in every case, because that is where the plan confirmation and the address request go, and how the customer signs in to claim. You can also correct the address yourself from [Sales History](/pos/sales-history#fix-change-or-cancel-a-sale) with **Update customer details**. ## Step 3: confirmation The confirmation screen tells you the plans are recorded and that the customer has been emailed. From here you can **Print** or **Download** the sale invoice (optional), record another sale, or go to the dashboard. ## What the customer receives - An email at the address you entered with the coverage terms and how to make a claim. - An invoice for the plan, which you can print or download from the confirmation screen and again later from Sales History. The sale shows in [Sales History](/pos/sales-history) with status **Active**, attributed to the signed-in team member and the selected store. Cancellations, plan changes and customer-detail corrections are all made from there. ## Give the customer a printed copy of the terms The customer is emailed the plan's coverage document, but you can also hand them a copy at the counter: - Before you submit, **Order Documents** in the customer step opens the documents for the sale. - In the plan picker, **What's covered** shows the plan's coverage and a **See detailed T&C** link that opens the full terms in a new tab. Open either one and print it with your browser's print option. The sale invoice is printed separately from the confirmation screen with **Print**. ## Installation and project sales For a product that is installed or delivered as part of a project, record the sale once the customer has agreed to the plan, and enter as the purchase date the date the customer bought the product. SureBright works out the coverage dates from that date and from the manufacturer warranty you enter, the same as for any other in-store sale. See [When coverage starts](/contracts/effective-dates#plans-bought-after-the-product-post-purchase). You collect the plan price from your customer with the rest of the project, however you normally take payment. The POS portal does not charge the customer. SureBright invoices you for the plans you record and charges the payment method on file. See [Billing](/pos/billing). If you want cover to start when the installation is finished rather than at purchase, ask your SureBright contact before you record the sale. ## Plans paid for outside your online checkout If a customer paid you for a plan by phone, on an invoice or through a payment link instead of your online checkout, the plan does not exist until it is recorded. Record it here as an in-store sale, or see [Phone, draft and later sales](/learn/phone-and-later-sales) for the options on your online store's platform. SureBright invoices you for the plan in the usual way; the customer's payment stays with you. Have a printed or scanned invoice instead of a product in front of you? Upload it and let the portal read the line items for you. See [Bulk upload](/pos/bulk-upload#upload-a-scanned-invoice). --- # Sales history and dashboards Source: https://docs.surebright.com/pos/sales-history > Find a recorded sale, update the customer or product, change the plan, cancel with a refund estimate, and read the dashboard, team performance and monthly challenge. **Sales History** lists every plan sold through the POS, and the **Dashboard** summarises them. You come here to look up a sale for a customer, fix a detail, change or cancel a plan, and to see how your stores and team are doing. ## Find a sale Search by customer, product or order, narrow by date range, and filter by team member. The header **Location** filter decides which store's sales you see. Admins and owners see every member's sales for the stores they have access to; a sales associate sees only their own. Each row shows **Product purchase date**, **Policy purchase date**, **Store name**, **Order ID**, **Product**, **SKU/Model number**, **Product price**, **Warranty plan details**, **Margin earned**, **Team member**, **Member commission**, **Warranty status**, **Customer details** and **Address details**. Click a row to expand it: **Product Name**, **Warranty Plan**, **Retail Price** and **Line Total** per line. | Status | Meaning | |---|---| | **Active** | The plan is in force. | | **Pending** | Recorded. SureBright is still setting the plan up. | | **Inactive** | Not currently in force. | | **Cancelled** | Cancelled by you, the customer or SureBright. | ### A sale you recorded is not showing Sales recorded in the POS portal are listed here, in **Sales History**, and counted on the **Dashboard**. Sales your online store makes, and sales from Lightspeed or Shopify POS, are listed under **Sales** in the [Merchant Portal](/merchant-portal/sales) instead. See [Sell protection in store](/platforms/in-store-sales#what-changes-when-you-add-in-store-sales). If a POS sale is missing, check these in order: | Check | What to do | |---|---| | The **Location** filter in the header | Sales are recorded against the store selected when the sale was made. Switch to **All stores**, or to that store. | | The date range and team member filter | Widen the dates and clear the team member filter. | | Your role | A sales associate sees only their own sales. Ask an admin or owner to look. | | The sale's status | A sale listed as **Pending** is recorded; SureBright is still setting the plan up. It moves to **Active** by itself. | | Whether the sale finished | A sale is recorded only when the confirmation screen appears after **Submit**. If checkout asked you to complete payment method verification, the sale was not recorded. See [Billing](/pos/billing#while-your-bank-account-is-being-verified). | | A CSV upload | Rows left under **Needs attention**, or skipped, were not saved. See [Bulk upload](/pos/bulk-upload). | Still missing? Email [support@surebright.com](mailto:support@surebright.com) with the store name, the customer's email address and the date of the sale. ## Fix, change or cancel a sale Open the **Sale actions** menu on the sale's row and pick what you need. | You want to | Choose | |---|---| | Correct the customer's name, email, phone or address | **Update customer details** | | Correct the manufacturer warranty recorded at the sale | **Update product details** | | Swap the plan for a different term or coverage type | **Change warranty plan** | | Cancel the plan and see the customer's refund | **Cancel sale** | **Update customer details** changes the customer's name, email, phone and address on the sale. The confirmation email and documents go to the updated address. ### Update product details Shown for sales that are not cancelled. It lets you correct the **Manufacturer / seller warranty** recorded at the time of sale, which moves the start of SureBright coverage. The dialog shows **At sale:** and **Currently:**, and a **No price change** pill when the plan price is unaffected. - You can change it up to 45 days after recording a sale. After that the dialog says **Editing window closed** and gives you the support address to email. - Some products do not allow the change; the dialog says so and asks you to email support. - To confirm, review the **SureBright coverage** dates, tick **I confirm the new duration** and click **Confirm**. You then see **Manufacturer warranty updated**. ### Change warranty plan Swap the plan on a line for a different term or coverage type. **Current plan** and **Available plans** are shown first. The **Order summary** then shows **Whats changing**, the **Used time (prorated)** and **Unused time (prorated)** on the old plan, and either a **Refund to original payment** or a **Balance due**. Tick **I confirm this plan change and refund.** and **Submit**. The sale keeps its history; the new plan replaces the old one. ### Cancel sale Pick a reason (or **Other (Please Specify)** and type one). The **Cancel sale** summary shows **Customer name**, **Product name**, **Warranty plan details**, **Purchase date**, **Amount billed to customer** and **Refund to customer**: the refund estimate SureBright calculates for cancelling today. Confirm to cancel. The customer is emailed, the status becomes **Cancelled**, and the dashboard logs a **Plan canceled** activity. The refund estimate and the final refund are worked out by SureBright from the plan's terms and how long it has run. The POS portal does not move money itself; the refund to the customer is handled through your billing with SureBright. ## See how your stores and team are doing The **Dashboard** summarises your sales. Owners and admins get the full dashboard; sales associates get a personal one. Choose the period with **Last 7 days**, **Last 30 days**, **Last 3 months** or a **Custom range**, and the stores with the **Location** filter (**All stores** or one store). ### What each dashboard card shows | Card | What it shows | Click through | |---|---|---| | **Plans sold** | Plans sold in the period, with a trend chart. | **Plans sold** detail with the chart by day, week or month. | | **Margins earned** | The same period as a value, with a trend chart. | **Margins earned** detail. | | **Associate selling the most warranties** | Your top seller for the period. | | | **Products selling the most warranties** | Your best-selling product. | | | **Plans sold by product category** | Share of plans per category, with **Revenue**. | A table per category, then per product inside it. | | **Team's performance** | **Team member**, **Store name**, **Plans sold**, **Margins earned**, **Commission earned**. | Full table with a team member filter. | | **Sales by store** | **Store name**, **Plans sold**, **Margins earned** per store, when **All stores** is selected. | | | **Recent activities** | The latest events: **Plan sold**, **Plan canceled**, product events, team events, **Top seller**. | Full log with **Plan sold** / **Plan canceled** / **Product events** / **Team events** tabs. | A sales associate sees **Plans sold**, **Total commission**, **Adjustments from cancellations** and **Net earnings** for their own sales, a plans-sold chart and their own recent activity. ### Monthly challenge and leaderboard The **Monthly Challenge** card ranks team members by plans sold in the current month and shows the signed-in member's **Ranking**, **Plans sold** and **Commission earned**. Open it for the full leaderboard, past months and each member's **Total wins**. When a member tops the board, a **Top seller** activity is logged. Commission figures use the per-store commission set in [Team Management](/pos/locations-and-team#set-a-members-commission). --- # Post-purchase offer emails Source: https://docs.surebright.com/post-purchase/offer-emails > Emails SureBright sends for you to customers who did not buy protection at checkout: how to turn them on, when they go out, which orders get them, and what you can change. SureBright can email your customers after they buy, offering protection for products they bought without a plan. You do not need an email platform or any design work: SureBright writes and sends the emails, and the customer buys the plan on your own store. This page explains how to get them, when they go out, which orders are included and what you can change. ## What you can do | You want to | Do this | |---|---| | Start sending offer emails | Ask your SureBright contact to switch them on for your store. See [Turn the emails on](#turn-the-emails-on). | | Send the emails from your own Klaviyo account, in your own design | Run them brand-managed. See [Send them yourself instead](#send-them-yourself-instead). | | Keep the emails from going out before the order arrives | See [Can the emails wait until the order is delivered?](#can-the-emails-wait-until-the-order-is-delivered) | | Leave small accessories out of the emails | Set those products to **Inactive**. See [Leave some products out](#leave-some-products-out). | | Know why a customer did not get an offer | Check [Why a customer did not get an offer](#why-a-customer-did-not-get-an-offer). | | Offer a plan to a customer who bought in store | See [Customers who bought in store](#customers-who-bought-in-store). | ## How the emails work The order contains at least one product that could have carried a SureBright plan, and the customer did not add one. The emails name your store and the product the customer bought, with a button that opens the offer. They come from SureBright, so you send nothing yourself. The button opens your storefront with the customer's order already loaded and the plans still available for each product. This is the same popup as a [post-purchase offer link](/post-purchase/offer-links). The customer pays you for the plan as a separate order on your store, and SureBright invoices you the net amount, as for any other plan. See [How the money works](/merchant-portal/how-billing-works). Once the customer buys a plan for the order, from the email or anywhere else, no more offer emails are sent for it. Coverage for a plan bought this way is counted from the original purchase, so buying later does not push the end date out. See [When coverage starts](/contracts/effective-dates#plans-bought-after-the-product-post-purchase). ## Turn the emails on Offer emails are available on request for Shopify stores. Ask your SureBright contact, or email [support@surebright.com](mailto:support@surebright.com), to switch them on. There is nothing to install and no email platform to connect. Before you ask, check that: - the [SureBright embed is on in your live theme](/shopify/storefront-setup), because the button in the email opens the offer on your storefront; - your products have a SureBright category and their **Warranty status** is **Active** in [Products](/merchant-portal/products). Products without a plan are never offered. On Magento, BigCommerce, WooCommerce and other platforms, ask your SureBright contact what is available for your store. The offer popup the emails open is part of the Shopify embed. ## When the emails go out | Your store | The emails start | |---|---| | Most stores, where coverage is dated from the purchase | When the order is paid. For most orders that is at checkout. An order you create and send as an invoice starts when the customer pays it. | | Stores where coverage is dated from the shipment (often pre-order or made-to-order stores) | When the first product that can carry a plan ships. | Each order gets one series of emails, spread across the time a plan can still be bought after the product. They stop as soon as any of these happens: - the customer buys a plan for the order, from the email, your product page or anywhere else; - the order is cancelled; - every product that could be protected has been refunded or removed from the order; - the window for buying a plan after the product closes. See [Buying a plan after the product](/contracts/what-can-be-covered#buying-a-plan-after-the-product). ### Can the emails wait until the order is delivered? On stores whose coverage is dated from the shipment, the series already starts when the product ships rather than when it is ordered. On other stores it starts from the paid order. Because the emails are spread out, the later ones usually reach customers after their order has arrived. If your products often take a long time to arrive, ask your SureBright contact whether the emails for your store can start from the shipment instead. Tell them roughly how long your deliveries take. ## Which orders get an offer An order gets offer emails only when all of these are true: | Condition | In practice | |---|---| | Offer emails are on for your store | SureBright switched them on, and your store does not run its offer emails through Klaviyo instead | | The order is paid and not cancelled | Unpaid orders wait until they are paid. Orders that never get paid are never emailed | | The order is in US or Canadian dollars | Orders in other currencies are not emailed | | The order has the customer's email address | Without it there is no one to send to | | The order has a shipping or billing address in a country where your plans are sold | An order with no address on it is not emailed | | At least one product on the order can still be protected | It has a SureBright category, its **Warranty status** is **Active**, it is not shipping protection, it has not been refunded, and no plan has been bought for it yet | Each order is emailed once. Editing, fulfilling or partly refunding it later never starts a second series. ### Leave some products out To keep a product out of the offer emails, set its **Warranty status** to **Inactive** in [Products](/merchant-portal/products). An order whose only eligible products are inactive gets no emails. **Inactive** also removes the protection offer from that product on your storefront. If you want a product offered at checkout but not in the emails, ask your SureBright contact what can be done for your store. ### Why a customer did not get an offer | What you find | Why | What you can do | |---|---|---| | The customer bought a plan at checkout, or later | There is nothing left to offer | Nothing | | The products on the order show no plan in [Products](/merchant-portal/products) | No category, **Inactive**, or a category SureBright does not cover | Pick a category or set **Active**. See [What can be covered](/contracts/what-can-be-covered) | | The order has no email address, or no address | SureBright cannot send, or cannot tell where the plan would be sold | Make sure checkout and staff capture both | | The order was cancelled or fully refunded | The series stops | Nothing | | The address is outside the countries your plans are sold in | No plan can be offered there | Nothing | | Your store sends offer emails from Klaviyo | SureBright does not send a second set | Check your own Klaviyo flow | | None of the above | | Email [support@surebright.com](mailto:support@surebright.com) with the order number | ## Customers who bought in store | How the in-store sale was made | Offer emails | |---|---| | Recorded in the [POS portal](/pos/overview), with a plan | Not needed. The plan is already sold and the customer gets the [plan confirmation](/customer-emails/purchase-confirmation) | | [Shopify POS](/shopify/pos-extension), without a plan | Only when the order carries the customer's email and an address. Many in-store orders have no address, so they are not emailed | | Lightspeed or another register | Not covered by the offer emails | To offer protection to an in-store customer after the sale, you can record a plan for them in the [POS portal](/pos/recording-a-sale) when they come back or call, or point them to your [product registration page](/shopify/product-registration) on Shopify. To reach a group of in-store customers who left without a plan, ask your SureBright contact. ## What you can change SureBright writes and designs these emails from its own templates, using your store name and the details of the product and plan. You do not edit them from your store or the Merchant Portal. | You want to | Do this | |---|---| | Show the right store name | Keep your store name accurate in your Shopify settings | | Change the wording, colours or co-branding | Ask your SureBright contact what can be adjusted for your store | | Control the design, copy, logo and sending domain yourself | Send them yourself instead, from Klaviyo | | Stop the emails | Ask your SureBright contact to switch them off | ## Send them yourself instead If you have an email team and a house style, you can run the offer emails from your own Klaviyo account. SureBright sends Klaviyo an event for each order that could have carried protection, with the offer link already built, and your flow sends the email. SureBright reviews the flow before it goes live, and stops sending its own offer emails for your store, so customers never get two. See [Email integrations](/klaviyo-integration/integration-guide) to compare the two ways, and the [Klaviyo brand-managed campaign guide](/klaviyo-integration/brand-managed-campaign-guide) to build the flow. ## Related The link the emails use, and how to put it in your own campaigns. Confirmations and other service emails SureBright always sends. White-glove or brand-managed offer emails. Which products and shoppers can be offered a plan. --- # Post-purchase offer links Source: https://docs.surebright.com/post-purchase/offer-links > Send customers a link that reopens their order on your storefront and offers protection for what they already bought: how to build the link, what the shopper sees, and how to use it in your own campaigns. A **post-purchase offer link** brings a customer back to your storefront to protect something they already bought. You put the link in an email or text message. When the customer opens it, a popup shows the products from that order and the protection plans still available for them. One click adds the plan to the cart. The popup is part of the SureBright app embed on Shopify stores, so you need nothing installed beyond the widget you already run. The SureBright Klaviyo events carry a ready-made link, and any campaign you send yourself can use one. Rather not send anything yourself? SureBright can email the link to your customers for you. See [Post-purchase offer emails](/post-purchase/offer-emails). ## Build the link Take any page of your storefront where the SureBright embed is active and add one parameter naming the order: ```text https://yourstore.com/?quoteLeadId=1234567890 ``` | Parameter | Value | |---|---| | `quoteLeadId` or `careLeadId` | The Shopify order ID of the original purchase (the numeric ID, not the order number shown to the customer) | Either name works, and so do the all-lower-case spellings `quoteleadid` and `careleadid`. Nothing else is needed. The customer does not have to be signed in. ## What the shopper sees when the link opens When the customer opens the link, a popup with your store logo shows the order's products and the plans available for each. | Situation | What the popup shows | |---|---| | A product with plans available | The product, the plan options (term and price, in the store's currency) and **Protect My Purchase** | | Several eligible products | One step per product with **Next** between them, and **Protect My Purchase** on the last | | A product already protected | **Warranty already purchased**, with a note that the purchase is already covered | | A product with no plan on offer | **No warranty plans available** for that product | | Nothing on the order can be protected | A short notice and **Okay**, or no popup at all when there is nothing to say | Pressing **Protect My Purchase** adds the chosen plans to the shopper's cart and sends them on to complete the purchase. The new order contains only the plans, and the customer pays for them as a separate order. Prices match what your product page would show for the same product today. Products already refunded on the original order are not offered. The popup does not open when: - the order is not found on your store; - the customer's address is somewhere SureBright plans are not sold; - the order is on a pre-order store and the window for buying protection after the order has closed; - the SureBright embed is not active on the page. The link opens an offer, not a purchase. Nothing is charged until the customer completes checkout, and a customer who already protected every product on the order sees that and nothing more. ## What happens after the customer buys SureBright links each plan to its product on the original order. You do nothing; see [Plans bought in a later order](/contracts/plans-bought-later) for the rare case where you are asked to choose. The customer receives the [plan confirmation email](/customer-emails/purchase-confirmation) with the covered product and dates. Coverage is counted from the original purchase, so buying later does not push the end date out. See [When coverage starts](/contracts/effective-dates#plans-bought-after-the-product-post-purchase). ## Use the link in your own campaigns Because the link only needs the order ID, you can place it in any message your own tools send after an order. | You send with | Do this | |---|---| | **Klaviyo** | Trigger a flow on the **SureBright: Eligible Order** event, which SureBright sends for every order that could have carried protection and did not. The event carries `post_purchase_url`, the link already built for that order, together with the product title and the plan's coverage bullets, so your flow can send a timed follow-up with a one-click **Protect your purchase** button. Use **SureBright: Policy Purchased** to stop the flow once the customer has bought. See the [Klaviyo brand-managed campaign guide](/klaviyo-integration/brand-managed-campaign-guide). | | **Another tool** | Build the URL from your platform's order ID in the tool's template, for example `https://yourstore.com/?quoteLeadId={{ order.id }}` in whatever syntax the tool uses. Send it only to customers whose order had an eligible product. The popup stays silent otherwise, but the email would promise something it cannot show. | Time the message to the product's arrival rather than the order date. Customers protect things they have in hand, and [Warranty Intelligence](/merchant-portal/warranty-intelligence) reports how many days your late buyers typically take under **Bought at checkout**. ## Related - [Post-purchase offer emails](/post-purchase/offer-emails) - [Plans bought in a later order](/contracts/plans-bought-later) - [Email integrations](/klaviyo-integration/integration-guide) - [Product registration pages](/shopify/product-registration) --- # Business Manager Setup Source: https://docs.surebright.com/salesforce-commerce-cloud/business-manager-setup > Install SureBright in SFCC Business Manager: upload the cartridge, import the metadata, jobs and SureBright product catalogue, then check the installation. On this page you install SureBright in Business Manager: you upload the cartridge, import four files from the SureBright integration package, and check that everything arrived. - **What you get:** the SureBright cartridge on your site, the SureBright jobs ready to schedule, and the warranty products in your catalogue. - **What you do:** the uploads and imports below, in your sandbox first. On the Full Business Manager Access path, SureBright does this configuration for you. **Before you start**: you need administrative access to your SFCC Business Manager instance. Your storefront must follow SFRA guidelines: the integration is built on top of `app_storefront_base` and related modules. --- ## Upload the cartridge and set the 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) **Important**: Always test in your sandbox environment first before deploying to production. Ensure the cartridge is compatible with your SFCC version. --- ## Import the metadata files 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) These files add the custom objects and system extensions the SureBright integration needs. Without them it does not function properly. --- ## Import the SureBright 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. The jobs file adds the jobs that send your products and orders to SureBright. You set their site and schedule in the [Jobs Guide](./jobs). --- ## Import the SureBright product catalogue 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 imports the warranty products as variants, one for each unique warranty tenure and price. We recommend keeping the SureBright products as a separate master catalog for better visibility and management. --- ## Check the installation After all the imports, confirm these three things in Business Manager: | Check | Where | What you should see | |---|---|---| | Cartridge | `Administration → Sites → [Your Site] → Cartridges` | `surebright_sfra` is listed and active, with no compatibility warnings or conflicts. | | Jobs | `Administration → Jobs → Job Definitions` | `SureBrightProductsExport` and `SureBrightOrdersCreation` are imported. | | Warranty products | `Merchant Tools → Products → Product Catalog` | The warranty products are imported with correct SKUs and are assigned to your site's catalogue. | --- ## Troubleshooting | If | Check | |---|---| | The cartridge upload fails | You have administrative permissions, the cartridge is compatible with your SFCC version, and your sandbox has sufficient disk space. | | The metadata import shows errors | The XML file format and structure, any existing custom objects that conflict, and the import logs for the specific error message. | | The product catalogue import has issues | Inventory list and pricebook assignments, product SKU naming conventions, and that your site configuration is complete. | If you are still stuck, check the [FAQs](./faqs), contact your SureBright representative for immediate assistance, or email [support@surebright.com](mailto:support@surebright.com) for technical support. **Next**: go to the [Jobs Guide](./jobs) to schedule the data synchronisation jobs, then run the checks in the [Testing Guide](./testing). --- # Configuration Source: https://docs.surebright.com/salesforce-commerce-cloud/configuration > Create the user account and API client SureBright needs in your SFCC Account Manager, and share the credentials securely, for both the Full Business Manager Access and API-Only Access paths. On this page you give SureBright the access it needs to your SFCC instance. You create a user account and an API client in Account Manager, then share the credentials securely. What you create depends on the path you chose in the [Integration Guide](./integration-guide). | Your path | What you do on this page | What happens next | |---|---|---| | **Full Business Manager Access** (recommended for most stores) | Create a SureBright user account, create an API client, share the credentials. | SureBright handles the technical configuration while you focus on business requirements. | | **API-Only Access** (for teams with SFCC developers) | Create an API client, share the credentials and your site details. | SureBright sends your development team the integration package, and your team deploys it. | **Before you start**: you need Account Manager access that lets you create users and API clients. If you do not have it, see the [FAQs](./faqs). --- ## Set up Full Business Manager Access This path gives SureBright comprehensive access to your SFCC environment, so the SureBright team can handle all technical configuration. This approach requires granting SureBright administrative access to your SFCC Business Manager. All activities will be logged and auditable. ### Create the SureBright user account Create a dedicated SFCC user account for SureBright, with the roles it needs to manage the integration. 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 synchronisation - **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 **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. ### Create the API client for SureBright Create an API client so SureBright can work with your SFCC instance to sync data and manage the integration. 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 synchronisation 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`) **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. ### Share the credentials securely Send SureBright these values so it can connect to your SFCC instance: ``` Client ID: [Your Client ID] Client Secret: [Your Client Secret] Organization ID: [Your Organization ID] Realm: [Your Realm] Short Code: [Your Short Code] ``` When you share them: - 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 These credentials provide access to your SFCC instance. Treat them as sensitive business information and ensure they are shared only with authorised SureBright personnel. --- ## Set up API-Only Access Choose this path if you have a dedicated SFCC development team and prefer to keep full control over your SFCC environment. This approach requires your development team to have experience with SFCC cartridge deployment, job management, and custom object configuration. ### Create an SFCC API client Your development team creates an API client so SureBright can support the integration and guide the data synchronisation. 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 your credentials and site details Send SureBright the credentials and the site configuration details below. ``` 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] ``` Before you send them: - 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 Share this information only through secure, encrypted channels. Verify the recipient's identity before sharing sensitive credentials. ### What SureBright sends your development team On the API-Only Access path, SureBright provides your development team with the integration files and detailed technical documentation for SFCC deployment. The package contains: 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 --- Stuck during configuration? Check the [FAQs Page](./faqs) for detailed solutions, contact your SureBright representative for immediate assistance, or email [support@surebright.com](mailto:support@surebright.com) for technical support. **Next**: go to the [Business Manager Setup](./business-manager-setup). After that, schedule the [Jobs](./jobs), run the [Testing Guide](./testing) checks, then deploy to production and monitor. --- # FAQs Source: https://docs.surebright.com/salesforce-commerce-cloud/faqs > Answers to common questions about setting up SureBright on SFCC: the access SureBright needs, where to find your SFCC details, how plan products and data syncs work, and what to do when plans do not show on the storefront. Answers to the questions SFCC administrators and developers ask most while setting up SureBright. If yours is not here, see [Still have questions?](#still-have-questions) at the end. ## Access and compatibility 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) 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 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 ## Setup, products and data sync 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 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 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 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 **What you control**: - You can modify warranty product descriptions - Product availability can be controlled via inventory lists - Warranty products integrate with your existing product management workflow Products and orders are sent by the two jobs you schedule in the [Jobs Guide](./jobs): **Product Export Job**: - Runs daily (recommended) - Can be configured for different frequencies - Sends all merchandisable products, so SureBright has your current product information **Order Synchronisation**: - Real-time processing (every 15-30 minutes) - Sends your orders to SureBright, where plans sold become contracts **Manual Sync**: - Available for immediate updates - Useful for testing and troubleshooting - Can be triggered from Business Manager ## Plans not showing on the 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 ## Still have questions? If you don't see your question answered here, we're here to help: **Email Support Team** [support@surebright.com](mailto:support@surebright.com) *For detailed technical questions and assistance* **Direct Support** Contact your assigned SureBright representative for immediate assistance. *For urgent issues and business questions* --- # SFCC Integration Guide Source: https://docs.surebright.com/salesforce-commerce-cloud/integration-guide > Add SureBright Product Protection to a Salesforce Commerce Cloud (SFCC) SFRA store: what you get, the two ways to set it up (SureBright with Business Manager access, or your own team with API access), what you need before you start and the steps in order. This guide shows how to offer SureBright warranty and protection plans directly in your Salesforce Commerce Cloud (SFCC) SFRA storefront. Start here to choose who does the setup, check what you need, and follow the steps in order. It is written for your SFCC administrator or development team. **Integration Timeline**: The complete setup typically takes 2-3 business days, depending on your SFCC environment complexity and chosen integration approach. ## What you get on Salesforce Commerce Cloud - Shoppers can pick a protection plan on your product pages, add it to the cart and buy it through your checkout. - Plans are regular products in your SFCC catalogue. - Two scheduled jobs send your products and orders to SureBright. ## Choose who does the setup Pick the path that fits your team's technical capacity and security requirements. | | Full Business Manager Access | API-Only Access | |---|---|---| | **Who configures SFCC** | SureBright handles the complete SFCC configuration, including cartridge deployment, job setup and custom object creation. | Your development team. SureBright provides the integration files and technical guidance. | | **What you do** | Create a user account and an API client for SureBright, then share the credentials securely. | Create an API client, share the credentials and your site details, then deploy and configure with the files SureBright sends. | | **Best for** | You have limited technical resources. Recommended for most stores. | You have a dedicated SFCC development team. | ## Before you start Make sure you have: | You need | Why | |---|---| | Account Manager permissions | To create users and API clients in Account Manager. | | SFCC Business Manager access | Administrative access to your Business Manager instance. | | Product catalogue data | Your complete product catalogue with SKUs, pricing and categories. | | Site configuration details | Your site's inventory list ID and pricebook assignments. | ## Set up SureBright in five steps Use the [Configuration Guide](./configuration) to set up API clients and user accounts. Follow the [Business Manager Setup Guide](./business-manager-setup) to upload cartridges and import metadata. Schedule the product and order jobs using the [Jobs Guide](./jobs). Check the storefront using the [Testing Guide](./testing). Deploy to production and refer to the [FAQs](./faqs) for common questions and answers. ## Get help during setup **Contact Your SureBright Representative** For urgent issues or immediate assistance during integration setup. *Response time: Within 2 hours during business hours* **Email Support Team** [support@surebright.com](mailto:support@surebright.com) *For detailed technical issues and documentation requests* Salesforce's own documentation covers Business Manager and the SFCC APIs: - [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) **Next**: go to the [Configuration Guide](./configuration) to set up user access and API credentials. --- # Jobs Source: https://docs.surebright.com/salesforce-commerce-cloud/jobs > Schedule the two SureBright jobs in SFCC Business Manager, one that sends your products and one that sends your orders, and check that they keep running. Two jobs keep SureBright up to date with your store. On this page you point each one at your site, run it once, and put it on a schedule. | Job | What it gives you | Recommended schedule | |---|---|---| | **SureBright Products Export** | SureBright knows which of your products are online and in stock, so they can be offered with a plan. | Once per day, after your catalogue is updated. | | **SureBright Orders Creation** | Orders reach SureBright, and the plans sold on them become service contracts. | Every hour. | **Before you start**: complete the [Business Manager Setup](./business-manager-setup) and [Configuration](./configuration) phases before configuring jobs. --- ## Schedule the SureBright Products Export job This job goes through your entire storefront catalogue and sends SureBright every Simple and Variant Product that is merchandisable (online and in stock) at the time the job runs. 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. | 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) **Best Practice**: Schedule this job to run during low-traffic hours to minimise impact on storefront performance. --- ## Schedule the SureBright Orders Creation job This job sends your orders to SureBright. For each order, SureBright creates the service contracts for the plans that were sold or, on the Post Purchase flow, what it needs to offer a plan after the purchase. 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), so plans become contracts soon after the order. 4. Configure error handling and retry mechanisms. | 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 | --- ## Check that the jobs are running 1. **Job Status**: Go to `Administration → Jobs → Job Status` to monitor job execution 2. **Job Logs**: Review job logs for errors and performance metrics ## Troubleshooting | If | Check | |---|---| | A job fails to run | The job logs for the specific error message, API connectivity and credentials, and that the system has sufficient resources. | | Products or orders are not reaching SureBright correctly | Product data format and structure, order data completeness, and the contract creation parameters. | If you are still stuck, contact your SureBright representative for immediate assistance or email [support@surebright.com](mailto:support@surebright.com) for technical support. **Next**: go to the [Testing Guide](./testing) to check the integration on your storefront. After go-live, keep monitoring job execution. --- # Testing Source: https://docs.surebright.com/salesforce-commerce-cloud/testing > Check on your SFCC storefront that shoppers see the SureBright offer on product pages, can add a plan to the cart and can check out with it. Once everything is set up, check on your storefront that a shopper can see a plan, add it to the cart and check out with it. - **What you get:** confidence that the offer, cart and checkout work before you go live. - **What you do:** make sure the product catalogue has been exported and SureBright Product Protection is enabled on the product from the Merchant Portal, then run the checks below. **Before you start**: complete the [Business Manager Setup](./business-manager-setup), [Configuration](./configuration), and [Jobs](./jobs) phases before running tests. --- ## See the offer on a product page Go to any SureBright covered Simple or Variant Product and select a variant. The SureBright offering widget appears, with the plan options to choose from. ![SFRA Offering Widget](/images/sfra_offering.png) ## Check the product page, cart and checkout Run these in order on a test order. The expected result is what you should see when the integration works. | Where | What to do | Expected result | |---|---|---| | Merchant Portal | After the **SureBright Products Export** job has run once, ask SureBright to confirm the sync | SureBright confirms your products were received. Only Simple and Variant Products that were online and in stock when the job ran are included | | Product page | Open a covered product that was in the export and pick a variant | The SureBright offer appears with plan options and prices | | Product page | Open a product that is offline, out of stock or not covered | No offer appears | | Product page | Pick a plan and add the product to the cart | The product and the plan reach the cart together | | Cart | Look at the plan line | The plan shows as its own line with its term and price, next to the product it covers | | Checkout | Place the order | Checkout completes with the plan, and the order summary lists the plan line with its price | | Merchant Portal | Wait for the **SureBright Orders Creation** job to run (hourly by default), then open **Sales** | The order and its plan appear, and the plan has become a contract | | Customer email | Check the inbox of the email address on the order | The customer receives the plan confirmation email. See [Emails your customers receive](/customer-emails/overview) | Not yet documented, so confirm with your SureBright contact before go-live: how the plan line is named and priced in the cart, whether a plan follows its product when the shopper changes quantity or removes the product, and how to keep a test order from being billed. If a check fails, contact your SureBright representative for immediate assistance or email [support@surebright.com](mailto:support@surebright.com) for technical support. **Next**: when every check passes, the integration is ready for production deployment. See the [FAQs](./faqs) for any questions. --- # Customer visit links Source: https://docs.surebright.com/service-network/customer-visit-links > How a customer confirms or counters a repair visit from the link in their email, and the three endpoints behind that page. When a provider proposes visit times for an on-site repair, the customer receives an email from SureBright with a link. The page behind it shows the proposed arrival windows and lets the customer pick one or ask for different times. Read this page if you build the customer-facing page yourself, or want to know what the customer sees and why a link stops working. ## What the customer sees The page shows SureBright as the sender, the product, the proposed arrival windows in the job's time zone, and the technician's first name where there is one. It never shows the provider's business or store, a price, or anything about the claim's decision. The customer can: - **Confirm** one of the windows. The visit is booked, the provider is told, and the link is spent. - **Counter** with a note saying what times would work. The proposal is withdrawn, the provider is told to propose again, and the link is spent. A link that has been used, has expired, or whose proposal was withdrawn, superseded or already answered shows **This link is no longer active; SureBright will contact you**. ## The token The link carries a single-use token minted when the email is sent. It expires with the proposal it belongs to, which is when the last proposed window can no longer be held. Sending the customer a newer proposal kills the links sent before it. The token is the only credential. It is sent on every request in the `X-Customer-Link-Token` header, never in the URL path or query, so it does not land in access logs or a `Referer`. Every response carries `Referrer-Policy: no-referrer` and `Cache-Control: no-store`. ## Endpoints Three routes, on the SureBright API host, with the token header on each. | Method and path | What it does | |---|---| | `GET /customer/visit-proposals` | The proposal: product, windows, technician first name, and when the link stops working | | `POST /customer/visit-proposals/confirm` | Book one window | | `POST /customer/visit-proposals/counter` | Decline the windows and say what would work | ### Read the proposal ```bash curl "$SUREBRIGHT_API/customer/visit-proposals" \ -H "X-Customer-Link-Token: $TOKEN" ``` Always `SureBright`. The product being repaired. The technician's first name, or null when the page should say "your technician". The windows still bookable. Each carries `slotHoldId`, `startsAt` and `endsAt` in the job's time zone. A single window can drop out before the link expires. When the link stops working. ### Confirm a window ```bash curl -X POST "$SUREBRIGHT_API/customer/visit-proposals/confirm" \ -H "X-Customer-Link-Token: $TOKEN" \ -H "Content-Type: application/json" \ -d '{"slotHoldId":"..."}' ``` One of the `slotHoldId` values from the proposal. Any other value is `400 SLOT_NOT_IN_PROPOSAL`. ### Counter ```bash curl -X POST "$SUREBRIGHT_API/customer/visit-proposals/counter" \ -H "X-Customer-Link-Token: $TOKEN" \ -H "Content-Type: application/json" \ -d '{"note":"Mornings do not work for me","preferredTimes":"weekday evenings"}' ``` What the customer wants the provider to know. Up to 500 characters. Free text, up to 500 characters. Both bodies are strict: an unknown field is refused rather than ignored, and the token is never accepted in a body. ## Idempotency The two POSTs are idempotent. A retry of a confirm or counter that already succeeded, while the link is still live, returns the first answer rather than acting twice. The idempotency scope is the token, so one customer's retry can never replay another's. A dead link answers `404` or `410` even to a retry of a request that once succeeded. ## Responses the page should handle | Status | Code | Meaning | |---|---|---| | `400` | `VALIDATION_FAILED`, `SLOT_NOT_IN_PROPOSAL` | The body is wrong; field errors are in `details` | | `404` | `LINK_NOT_FOUND` | Not a token this service issued. Show the inactive message | | `410` | `LINK_INACTIVE` | Used, expired, withdrawn or superseded. Show the inactive message | | `409` | `IDEMPOTENCY_IN_PROGRESS` | The first attempt is still running; retry shortly | | `429` | | Too many requests on this link | | `503` | | The schedule is busy; the message is written for the customer. Retry | Anything else the service could say about the job is deliberately answered as `410 LINK_INACTIVE` with no details, so the page has one inactive state and nothing about another job, a provider or a member can leak through it. The mail-in variant of this link (`GET /customer/mail-in`, a label and ship-by page) uses the same token header and the same inactive answers. It is read-only. --- # Service network Source: https://docs.surebright.com/service-network/overview > How repair and installation shops join SureBright's service network, work a repair job from offer to payment, and manage their team in the Service Provider Portal. Early access. Ask your SureBright contact to enable this for your business. SureBright's service network is the set of repair and installation businesses that carry out repairs approved on a claim. A provider signs up in the Service Provider Portal, is reviewed, and then receives job offers that match its service area and capabilities. Read this page if you run a repair or installation business and want to know what joining involves, or if you are a merchant whose claims settle by repair and want to know who does the work. ## Who is in the network A provider is a **business** with one or more **stores** (physical shops or service bases). Jobs are offered to a store, and a store's members work them. SureBright reviews every business before it receives work and verifies each store's documents. ## Roles Roles are assigned per store. A member can be Admin on one store and Technician on another. | Role | Scope | Can | |---|---|---| | **Owner** | The whole business | Everything: onboarding, store changes, billing, documents, accept or decline offers, invite Owners, Admins and Technicians | | **Admin** | Selected stores | Run jobs on their stores, accept or decline offers for them, upload documents, invite and manage Technicians | | **Technician** | One store | Work the jobs assigned to them: visits, inspections, repairs, reports. Never offered a job, and sees only their own | Only a business owner can sign up. Every other member joins by invitation. ## Onboarding An owner enters their email, confirms they are the business owner or an authorised decision-maker, and verifies the address with a one-time code. Then the owner account: name, business name, years of experience, phone and password. Pick the categories of installation, repair and servicing the business offers, down to sub-category or **All**. Offers are matched on these. Upload at least one business document (PDF, JPG or PNG, up to 10 MB each): liability insurance, professional certification, a business or trade licence. Documents can carry an expiry date and are reused across stores. Add the first store (name, phone, address). Set its service area: **Nationwide (US)**, **Select specific states**, **Select specific cities** or **Select specific locations on map** with a radius of 1 to 50 miles around each point. Upload the store's own documents. Add further stores from **Manage stores**. Add the account SureBright pays into. The application goes to SureBright. The dashboard shows **Under review**, then **Approved**, **Rejected** (fix and resubmit) or **Action needed** (one or more stores have a document to re-upload; verified stores keep working). Work pages open once the account is approved or action-needed. Documents live on afterwards in the **Compliance** vault, per store, with status **Active**, **Expires in N days** or **Expired**, and company-wide policies each member acknowledges. A store whose documents lapse stops receiving offers until they are renewed. ## The job A job is one work order from a claim's repair plan, offered to one store. See [Resolutions and payouts](/claims/resolutions-and-payouts) for how the plan is composed. The portal shows it as nine steps. | Step | Label | What the provider does | |---|---|---| | 1 | **Assigned** | The offer. Shows the job's city, state and ZIP, the distance from the store and the pay basis, never the customer. Owner or Admin **Accept** (optionally naming a technician, a start-by date and whether parts are likely), **Reject** with a reason code, or ask Command Center Ops for more time, once. An unanswered offer expires after 24 hours, with a reminder 4 hours before, and goes to the next provider. | | 2 | **Accepted** | The customer's name, address and contact details appear. Assign a technician if not yet done. | | 3 | **Scheduled** | Propose arrival windows to the customer, who confirms or counters through a link (see [Customer visit links](/service-network/customer-visit-links)), or book a slot agreed by phone. Reschedule with a reason. The technician marks **En route**, checks in and checks out. For a mail-in job the customer ships the unit to the store instead. | | 4 | **Inspection** | Scan the unit, record the inspection (root cause, damage, repairability, safety, photographs), report additional faults or that the unit cannot be repaired. | | 5 | **Approval** | Submit the estimate: labour hours and people at the business's locked hourly rate, parts, travel and other lines. SureBright's adjudicator approves or declines; a declined estimate can be revised once. A pre-authorised work order skips this step unless it would overrun its envelope, which is a spend request. | | 6 | **Repair** | Do the work. Order parts and report their arrival, place the job on hold (**Waiting for parts**, **Awaiting customer**, curing or rest time) and resume it, book a return visit, or hand the job back with a reason. | | 7 | **Completed & Invoice** | Record each item's outcome, the service report and the customer's on-device signature, upload photographs and receipts, and **Complete**. A draft invoice is created from the work. Edit its lines with a reason, then submit; an unedited draft is submitted automatically after a few days. | | 8 | **Payment** | The invoice is audited and approved, or flagged for review. | | 9 | **Paid** | Paid in the next payout batch. The repair summary can be downloaded. | Terminal states: **Rejected**, **Offer expired**, **Cancelled**, and a job closed by SureBright, for example when the claim converts to a replacement. A unit still at the store when a job ends becomes a **unit return** the store ships back with a label SureBright provides. ## The portal | Page | What it shows | |---|---| | **Dashboard** | Action center (offers and items needing a reply), earnings and payouts, earnings by store, business insights, performance, recent activity, over a 7-day, 30-day, 3-month or custom range | | **Jobs** | Every job in the member's scope: **All**, **Needs action**, **Active**, **Completed**, **Closed**; search by job ID, product or customer; filter by status, category, service type (on-site, walk-in, mail-in), priority, due date, technician and store | | **Schedule** | A calendar of visits; a Technician sees only their own | | **Invoices** | Every invoice with its status and amount; view, edit lines, submit, download | | **Compliance** | Documents per store and policy acknowledgements | | **Team** | Members, pending invitations, invite, edit access, remove | | **Onboarding & Training** | FAQs, tours and videos | | **Settings** | Account details, manage stores (change requests, deactivate, reactivate), billing history and payout methods (Owner only), contact SureBright | Every action button follows the server's answer for that job: a control the member may not use now is simply not offered. The same jobs can be worked through the [provider API](/service-network/provider-api). --- # Provider API Source: https://docs.surebright.com/service-network/provider-api > The Service Provider Portal's job API for repair and installation businesses: authentication, the request conventions, and what each group of endpoints does. Everything a provider does in the Service Provider Portal can be done against its API: accept an offer, schedule a visit, record an inspection, submit an estimate, complete the job and invoice it. Read this page if you run your own dispatch or field-service system and want to drive SureBright jobs from it. It summarises the surface by capability; the exact bodies are in the portal's own calls and your SureBright contact can share them. ## Base URL and authentication The API is served under the Service Provider Portal's API host, under the prefix `/spp/v1`. Ask your SureBright contact for the host for your environment. Every request carries two headers: | Header | Value | |---|---| | `site-id` | `SPP` | | `Authorization` | `Bearer ` | Sign in with `POST /auth/login` (email and password) to receive an access token and a refresh token. An access token lives for one hour; `POST /auth/token/refresh` exchanges the refresh token for a new pair, and `POST /auth/logout` revokes the session. `GET /me` returns the signed-in member, their business, their role on each store and the permissions the session holds. ```bash curl -X POST "$SPP_API/spp/v1/auth/login" \ -H "site-id: SPP" \ -H "Content-Type: application/json" \ -d '{"email":"owner@example.com","password":"..."}' ``` A member's role is read from SureBright on every request, so a role change, a removal or a deactivated store applies immediately. A revoked session answers `401 SESSION_REVOKED`. ## Conventions - **Envelope.** Every response is `{ "isError": false, "data": ... }` or `{ "isError": true, "errorCode": "...", "message": "...", "details": ... }`. `message` is written to be shown to a person. - **Scope.** Reads return only the member's own jobs, invoices and stores. A job outside the member's reach is `404 JOB_NOT_FOUND`; it is not revealed. What a member may do on a given job comes back on the job read as `allowedActions`, and an action not listed is refused. - **Idempotency.** Mutating calls take an `Idempotency-Key` header, required on the execution routes. The key is scoped to the member, method and path, and the body is hashed with it: a retry with the same key and body replays the first answer (with an `idempotent-replayed` header); the same key with a different body is `409 IDEMPOTENCY_KEY_REUSED`; a retry while the first is still running is `409 IDEMPOTENCY_IN_PROGRESS`. Only a 2xx is stored. - **Money and decimals** are strings. Dates and times are ISO 8601; visit times are in the job's time zone. - **Files** never pass through the API as multipart. Create a file record, PUT the bytes to the signed URL it returns, then confirm it. - **Stage conflicts** answer `409` with a code naming the rule: `INVALID_STAGE`, `OFFER_EXPIRED`, `OFFER_NOT_OPEN`, `STORE_AT_CAPACITY`, `TECHNICIAN_REQUIRED`, `PROPOSAL_ALREADY_OPEN`, `QUOTE_NOT_APPROVED`, `INVOICE_NOT_DRAFT`, `INVOICE_VERSION_CONFLICT`. Refetch the job and re-present. ## Endpoints by capability Paths below are relative to `/spp/v1`. ### Jobs and offers | Method and path | What it does | |---|---| | `GET /jobs` | Held jobs, open offers and recent declines in the member's scope | | `GET /jobs/:jobId` | One job: its items, stage, panels, option lists and `allowedActions` | | `POST /jobs/:jobId/accept` | Accept the offer. Owner or store Admin. Optional technician, start-by date, completion estimate and parts outlook. `409 OFFER_EXPIRED` after the 24-hour window, `409 STORE_AT_CAPACITY` at the store's concurrent limit | | `POST /jobs/:jobId/reject` | Decline with a reason code from the job's option list; a note is required for **Other** | | `POST /jobs/:jobId/offer/extension-request` | Ask for more time on the offer, once. Granted or refused by SureBright; the clock does not pause while it waits | | `PUT /jobs/:jobId/technician` | Set the tentative technician on an offer, or the assignee after acceptance | ### Scheduling and visits | Method and path | What it does | |---|---| | `GET /jobs/:jobId/visit/slots` | The slot picker: the windows a technician could be offered | | `POST /jobs/:jobId/visit/propose` | Propose arrival windows to the customer. A technician must be assigned. The customer confirms or counters through a link | | `DELETE /jobs/:jobId/visit/proposal` | Withdraw the open proposal | | `POST /jobs/:jobId/visit/book` | Book a slot agreed with the customer by phone | | `POST /jobs/:jobId/visit/reschedule` | Reschedule with a reason: propose new windows or book one | | `POST /jobs/:jobId/visit/events` | Record **en route**, **check in** and **check out** | | `GET /schedule` | The member's visits; a Technician sees only their own | ### Execution | Method and path | What it does | |---|---| | `POST /jobs/:jobId/items/:itemId/scan` | Record the unit scan | | `PUT /jobs/:jobId/inspection/draft` | Save the inspection draft | | `POST /jobs/:jobId/faults` | Report an additional fault | | `POST /jobs/:jobId/unrepairable` | Report the unit cannot be repaired | | `POST /jobs/:jobId/parts`, `PATCH`/`DELETE /jobs/:jobId/parts/:partId` | Add, change or remove a part | | `POST /jobs/:jobId/parts/:partId/order`, `/reorder`, `/drop` | Report a part ordered, reorder it, or drop it | | `POST /jobs/:jobId/estimate`, `PUT /jobs/:jobId/estimate` | Submit the estimate; revise it once with a reason | | `POST /jobs/:jobId/spend-requests` | Ask to overrun a pre-authorised envelope | | `POST /jobs/:jobId/holds`, `POST /jobs/:jobId/holds/:holdId/clear` | Place the job on hold (waiting for parts, awaiting customer, cure or rest, other) and lift it | | `POST /jobs/:jobId/extend-timeline` | Ask for more time on the repair | | `POST /jobs/:jobId/report` | Report a problem on the job | | `POST /jobs/:jobId/cancel` | Hand the job back with a reason; blocked while a hold is open | | `POST /jobs/:jobId/mailin/received`, `/mailin/start-repair` | Mail-in jobs: the unit arrived, the bench repair started | ### Files and completion | Method and path | What it does | |---|---| | `POST /jobs/:jobId/files`, `POST /jobs/:jobId/files/:fileId/confirm`, `GET /jobs/:jobId/files/:fileId/url` | Create a file record and get a signed upload URL, confirm the upload, read a signed download URL | | `GET /jobs/:jobId/photos`, `DELETE /jobs/:jobId/photos/:photoId` | The job's photographs | | `PUT /jobs/:jobId/service-report` | Save the service report | | `PUT /jobs/:jobId/items/:itemId/outcome` | Record each item's outcome | | `POST /jobs/:jobId/signature` | The customer's on-device signature | | `GET /jobs/:jobId/completion` | What is still needed before the job can be completed | | `POST /jobs/:jobId/complete` | Complete the job. Checks out an open visit, requires the completion floor to be met (`422 COMPLETION_FLOOR_NOT_MET` lists what is missing) and the labour figures to match the visits, and creates the invoice draft | | `GET /jobs/:jobId/repair-summary` | The repair summary | ### Invoices and billing | Method and path | What it does | |---|---| | `GET /invoices`, `GET /invoices/:invoiceId`, `GET /invoices/:invoiceId/download` | The member's invoices | | `PUT /invoices/:invoiceId/lines` | Edit the draft's lines, with a reason code and the `version` you read | | `POST /invoices/:invoiceId/submit` | Submit the draft. It is audited inline and comes back approved or flagged. `POST /jobs/:jobId/invoice` is an alias for the job's live draft | | `GET /billing/history`, `GET /billing/history/:recordId/invoice` | Payout history and remittances. Owner only | ### Unit returns | Method and path | What it does | |---|---| | `GET /unit-returns`, `GET /unit-returns/:unitReturnId` | Units the store still holds after a job ended and must ship back | | `GET /unit-returns/:unitReturnId/label-url` | The return label | | `POST /unit-returns/:unitReturnId/shipped` | Mark it shipped | | `POST /unit-returns/transfers/:jobShipmentId/received` | Receive a transfer that arrived after the store let the job go | ### Dashboard `GET /dashboard` (the overview), `/dashboard/action-center`, `/dashboard/earnings`, `/dashboard/earnings/stores`, `/dashboard/performance` and `/dashboard/activities`, each over a date range and optionally one store. ## Everything else Onboarding, documents, stores, payout methods, the team and account settings are served by the same API under their own paths (`/onboarding`, `/documents`, `/compliance`, `/stores`, `/team`, `/account`, `/settings`), with the same headers and envelope. They are what the portal's own screens call; ask your SureBright contact if you need to drive them. --- # Shift4Shop Source: https://docs.surebright.com/shift4shop/overview > Connect a Shift4Shop store to SureBright, see what is added to your storefront, know what happens to plans when an order changes, and disconnect. You connect a Shift4Shop store from the SureBright merchant portal by approving SureBright's access in Shift4Shop. After that, offers show on your product pages and in the cart, and each order with a SureBright warranty line becomes a contract. Use this page when you connect a store or want to know why an order did not produce a contract. **What stays in sync.** Orders reach SureBright as they happen. Your product catalogue is copied once, when the store is connected; later product changes are not received automatically, so ask your SureBright contact to refresh the catalogue after a large product update. ## What you get on Shift4Shop - The protection offer on product pages and in the cart. - A contract for each warranty a shopper buys, cancelled for you when the warranty quantity is reduced or the order is fully refunded or cancelled. - Your SureBright store and billing account created when you connect. - Your product catalogue copied to SureBright once, at connection. ## What you need to do | When | What you do | |---|---| | Once | Connect the store from the merchant portal and approve SureBright's access in Shift4Shop. | | Once | Check that your products have a category. | | Always | Leave the two SureBright frontend scripts in place, and do not edit warranty lines on orders. | | After a large product update | Ask your SureBright contact to refresh the catalogue. | ## Connect your store In the portal's [Settings](/merchant-portal/settings#connecting-a-storefront) click **Connect Store**, choose **Shift4Shop** and click **Proceed**. You are sent to Shift4Shop to sign in and approve SureBright's access to your store. SureBright creates your SureBright store and billing account from your store information and currency, adds two frontend scripts to your storefront and copies your products. The portal confirms **Store authorized successfully.** Offers are based on the SureBright category on each product. Check [Products](/merchant-portal/products) for anything without a category. ## Scripts and warranty lines to leave in place Two entries appear under your store's **Frontend Scripts**: | Placement | Shown as | What it is for | |---|---|---| | **BODY** | `window.SureBright = { storeId: '' }` | Tells SureBright which store the page belongs to. | | **HEAD** | SureBright SDK | Shows the protection offer on product pages and in the cart. | Do not remove either script. Offers need both. If one is missing, ask your SureBright contact to recreate it. When a shopper accepts an offer, a warranty line is added to the cart. Its title contains **SureBright** and **Warranty**, and its description records the plan term, the price and the offer the shopper accepted. SureBright uses that description to match the warranty to the right product after checkout, so do not edit warranty lines on orders. ## What happens when an order changes You manage orders in Shift4Shop as usual. SureBright follows new orders and order changes. | What happens in Shift4Shop | What happens to the plan | |---|---| | A new order has warranty lines | The contracts are created, one per warranty unit, each for the product it was offered on, including the product's option selection. | | You change an order and reduce the warranty quantity | The contracts that no longer have a paid warranty unit are cancelled. | | You fully refund or cancel an order | All of the order's contracts are cancelled. | | A warranty line's description cannot be read | No contract is created. The line appears in **Order Resolution** for you or SureBright to resolve. | Three details that affect what you see on a contract: - The covered price is the product's unit price plus its option price. - The contract holder comes from the order's customer and address details. - A plan bought after the original order is matched to the product on the original order. ## Find your contracts in the merchant portal Contracts show under **Recent Sales** on the portal's [Sales](/merchant-portal/sales) page. Warranties that could not be paired with a product, and orders missing customer details, show in **Order Resolution**; see [Why a contract is on hold](/contracts/holds). ## Disconnect your store Ask SureBright to disconnect the store. SureBright then stops receiving your orders. Remove the two frontend scripts yourself if you no longer want the offer shown. Existing contracts stay in force. ## Related - [Products](/merchant-portal/products) - [Sales](/merchant-portal/sales) - [Why a contract is on hold](/contracts/holds) - [Pause or remove SureBright](/platforms/pause-or-remove) --- # Shipping claims Source: https://docs.surebright.com/shipping-protection/claims > What to tell a shopper whose protected shipment was lost, damaged or arrived short: where they file, what they are asked for, when a claim is accepted, and how it is paid, and what SureBright may ask of you. When a protected shipment is lost, damaged or arrives short, the shopper files a claim with SureBright. SureBright checks it, assesses it and settles it. The claim does not go through your store. Use this page to answer a shopper who contacts you about one, and to know what SureBright may ask of you. **What you need to do:** usually nothing. Point a shopper with a lost or damaged protected shipment to `https://customer.surebright.com`. On some claims SureBright asks you for help, for example to dispute the delivery with your shipping carrier, to get a signed proof of delivery, or to ship a replacement. See [When SureBright asks for your help](#when-surebright-asks-for-your-help). ## What shipping protection covers | Covered | Notes | |---|---| | Lost packages | Including packages misrouted that never arrive | | Goods damaged in shipping | | | Theft | | | Items missing from the shipment | Claimed as a shortage | Cover applies to shipments to addresses in the United States. A shopper with a Canadian or other non-US shipping address is not covered, and their fee is refunded. See [Orders that cannot be covered](/shipping-protection/overview#orders-that-cannot-be-covered). Cover is created for a shipment when you fulfil it with a carrier and tracking number. If you ship with a carrier SureBright does not recognise, such as a freight carrier, SureBright's team matches it, or your store can be set to refund the fee instead. Ask your SureBright contact before relying on shipping protection for freight shipments. See [If the shipment has no tracking or an unknown carrier](/shipping-protection/overview#if-the-shipment-has-no-tracking-or-an-unknown-carrier). ## Where a shopper files a shipping claim Shoppers file at the SureBright customer portal, **https://customer.surebright.com**. The link is in the shipping protection email they received when the order shipped. Sign-in is passwordless: the shopper enters the email address used on the order and confirms with a one-time code or magic link. Shoppers who hold shipping protection see **Shipping Warranties** and **Shipping Claims** in the menu. **Shipping Warranties** lists each shipment's cover with its **Order ID** and **Tracking ID**, order date and the items it covers. On active cover the shopper chooses **File a claim**. Cover that has been cancelled cannot be claimed against. ## What the shopper is asked for The claim form has two steps. **Step 1: select items.** The covered items in the shipment are listed with their quantities. The shopper ticks the items that were lost, damaged or missing. **Step 2: say what happened.** | Field | Notes | |---|---| | **Select a Reason** | One of **Loss**, **Damage** or **Shortage** | | **Loss Discovered Date** | The date the shopper found out about the problem | | **More Details** | A free-text description of what happened; required, up to 2,000 characters | The shopper does not enter an amount. SureBright works it out from the claimed items: quantity multiplied by the item price recorded when the shipment was covered. On submit the shopper sees either **Your Shipping Protection Claim is Submitted!**, with a note that the team will review and get back within 48 hours, or a failure message asking them to try again. Trying again retries the same claim; it does not create a second one. ## When a claim is accepted or refused | Rule | What it means for the shopper | |---|---| | A claim is for one shipment | The claim is tied to the cover on a single shipment, not to the whole order, and that cover must be active. | | One open claim per shipment | While a claim is in progress, a second one is refused: the shopper is told a claim has already been filed for the shipment and pointed to **Shipping Claims**. Once the earlier claim has been approved or declined, a new one can be filed if needed. | | Only items in that shipment can be claimed | Items that were not in the shipment, or quantities above what was shipped, are left out. If nothing eligible remains, the claim is refused. | | The same claim sent twice counts once | If an identical claim is already on file, the new submission is treated as that claim. No duplicate is created. | ## How a claim is assessed and paid Once accepted, the claim is assessed using the shipment's carrier and tracking number, the shipment date, what the shopper reported and the calculated amount. The shopper follows it under **Shipping Claims**, which lists each claim with its file date, loss discovered date, claim amount and status (**Under Review**). SureBright then approves or declines the claim. An approved claim is usually settled by paying the shopper directly, using the delivery name and address on the shipment's cover. The payment does not pass through your store or your SureBright account. SureBright may instead ask you to ship a replacement and pay you back for it. See [When SureBright asks for your help](#when-surebright-asks-for-your-help). ### Does your share of the fee reduce what the shopper gets No. Your margin is a share of the shipping protection fee the shopper paid. It has no effect on a claim. The claim amount is worked out from the items claimed and their price when the shipment was covered. ## When SureBright asks for your help Most shipping claims need nothing from you. On some, SureBright asks you for one of these. | SureBright asks you to | Why | What to do | |---|---|---| | Dispute the delivery with your shipping carrier | The tracking shows the package as delivered, or the carrier is responsible for the loss or damage | Open a claim or trace with the carrier on your shipping account, which only you can do, and send SureBright the outcome with the claim reference | | Get a signed proof of delivery | To check whether, and to whom, the package was delivered | Request it from the carrier and send it to SureBright | | Ship a replacement | A replacement suits the shopper better than a payment | Ship it, send SureBright the tracking and your cost. Agree with SureBright before you ship how you will be paid back for the replacement. | Reply to the email SureBright sent you, or write to [support@surebright.com](mailto:support@surebright.com), with the order number and the shipment's tracking number. ## What you see as the merchant Shipping claims are not listed in the Merchant Portal and raise no tasks for you there. A claim does not change the order, the shipping contract or your payout for the shipping protection fee. To ask about a shipping claim, email support with the order number. ## Related How the offer appears, how it is priced and what happens when you ship. Everything else a shopper can do after signing in. --- # Shipping protection Source: https://docs.surebright.com/shipping-protection/overview > Let shoppers pay a small fee to cover their shipment against loss, damage and theft in transit. How to turn it on, choose which products it covers, what it costs the shopper, and what happens when you ship. Shipping protection is a small, optional add-on a shopper buys at checkout. It covers the products in their shipment while they are in transit: lost packages, goods damaged in shipping, packages that are misrouted and never arrive, and theft. If something goes wrong the shopper files a claim with SureBright, not with you, and SureBright settles it. It is separate from product protection (extended warranties). A shopper can buy either, or both, on the same order. Your part is small: ask SureBright to turn it on, choose which products it covers, and add the carrier and tracking number when you fulfil an order. Shipping protection runs on Shopify and BigCommerce stores. On other platforms, ask your SureBright contact. See [Platforms that support shipping protection](#platforms-that-support-shipping-protection). Shipping protection covers shipments to **United States** addresses only. If an order with shipping protection ships anywhere else, no cover is created and the fee is refunded. See [Orders that cannot be covered](#orders-that-cannot-be-covered). ## How shipping protection works On your cart page (and in checkout, on Shopify Plus) the shopper sees **Add Shipping Protection for $X**. The price is worked out from the value of the eligible items in the cart. Ticking the box adds a line item called **Shipping Protection Powered by SureBright** to the cart. It is a product in your catalogue that SureBright created for you, so it goes through your normal checkout and you collect the fee like any other item. When you fulfil the order with a carrier and tracking number, SureBright creates a shipping contract for the covered products in that shipment. The shopper receives an email confirming what is covered. The shopper signs in to the SureBright customer portal, picks the affected items and says what happened. See [Shipping claims](/shipping-protection/claims). ## Turn on shipping protection Your SureBright contact switches shipping protection on for your store. They set up two things: | What | What it means for you | |---|---| | The offer on your storefront | The cart offer appears, and shipments are covered, only once this is on. The checkout offer on Shopify Plus is switched on separately. | | A shipping protection product in your catalogue | One hidden product with one variant per price point. The offer adds the variant that matches the cart's value. Do not delete or edit this product. | You can then decide which of your products are covered from the Merchant Portal. See [Choosing which products are covered](#choosing-which-products-are-covered). ## Where shoppers see the offer ### Cart page widget On the cart page the widget sits next to your checkout button. Depending on the template chosen for your store it is either: - a **checkbox** row: *Add Shipping Protection for $X*, with the line *Protection against package damage, loss, theft, missing items and much more* and a **view coverage** link; or - a **button** row: *Shipping Protection* with an *Add Shipping Protection* button and a **see complete coverage** link. On the checkbox template, protection is pre-selected the first time a shopper sees it on your store. On the button templates the shopper has to opt in. The widget follows the cart. When items are added or removed, or quantities change, the price updates and the protection line is updated or removed. If no eligible items remain, the protection line is removed too. Covered products can also carry a small **shipping protection badge** against their line in the cart, so the shopper can see what the fee applies to. ### Coverage popup The **view coverage** / **see complete coverage** link opens a popup: *Protect your $X worth of items for just $Y!* It lists what is covered, the eligible items in the cart with the total value protected, a **Protect My Purchase** button, a **No, Thanks** button, and a link to the full plan documents. Its colours, icons and copy can be themed for your store. ### Checkout block (Shopify Plus) On Shopify Plus stores the **SureBright Protection Block** checkout extension shows the same offer inside checkout, below the list of cart lines: a checkbox, *Add Shipping Protection for $X*, *Protects against package damage, loss, theft, & more*, and a **see complete coverage** link that opens a list of the eligible items. A matching badge marks covered lines. The price follows the checkout's shipping address and updates if the shopper changes country. Shopify only shows checkout blocks on Plus plans, so on other plans the cart widget is the only place the offer appears. ## Which items are eligible for shipping protection Not every item in a cart counts towards shipping protection. An item is eligible when: - its SureBright product category is one that shipping protection covers; and - you have not switched shipping protection **Off** for that product in the Merchant Portal. Only eligible items are priced and covered. If the eligible value is zero, no offer is shown. If the eligible value is above **$5,000**, no offer is shown either. ## How shipping protection is priced The fee depends on the value of the eligible items in the cart. That value falls into a **price band**, and each band has a fee and your margin on that fee. If your bands change later, an order keeps the fee the shopper saw. Unless your store is set up differently, the default is **$2.50 for every $100 of eligible value**, in $100 bands, up to $5,000. | Eligible cart value | Fee | |---|---| | $0.01 – $100.00 | $2.50 | | $100.01 – $200.00 | $5.00 | | $200.01 – $300.00 | $7.50 | | … (+$2.50 per $100 band) | … | | $4,900.01 – $5,000.00 | $125.00 | Your margin is a percentage of the band fee, agreed with SureBright when the store is set up. Bands and margins differ between stores. The table above is the default and is only a guide; your SureBright contact can tell you what your store uses. ## What happens when you ship the order Cover is created when you **fulfil** the order, not when it is placed, because it applies to a specific shipment with a specific carrier and tracking number. Add the tracking company and tracking number to the fulfillment as you normally would. When you create or update a fulfillment: - SureBright creates one **shipping contract** for the covered items in that shipment. Items the shopper's protection did not cover are ignored. - The carrier is recognised from the tracking company on the fulfillment, for example UPS, USPS, FedEx and DHL and their services. - The *Shipping Protection Powered by SureBright* line is marked as fulfilled on your store, so the order shows as fully fulfilled. - The shopper is emailed **SureBright shipping insurance details of your recent purchase**: the covered items, what is and is not covered, a link to the plan documents, and where to file a claim (`https://customer.surebright.com`). **Partial fulfillments.** If an order ships in several packages, each fulfillment that contains covered items gets its own contract. A fulfillment that contains only uncovered items gets none. One shipping protection purchase can therefore result in more than one contract. ### If the shipment has no tracking or an unknown carrier | Situation | What happens | |---|---| | The fulfillment has no tracking company or tracking number | No contract can be created yet. SureBright's team adds the tracking details and tries again. | | The tracking company is not a carrier SureBright recognises | SureBright's team matches the carrier; you may see the case in your Merchant Portal. Your SureBright contact can instead set your store to refund the shopper's fee automatically when the carrier is unknown. No contract is created in that case. | | The same fulfillment is sent twice | The existing contract is reused. No duplicate is created. | ## Orders that cannot be covered If a shopper has paid for shipping protection but no cover can be created, the fee is refunded in full; shipping protection is never pro-rated. This applies when: - the shipping address is **outside the United States**; - the order contains only the shipping protection line and no products; - none of the products in the order are eligible for the cover; - the shipping protection line did not come from the SureBright offer (for example, it was added to the order by hand). SureBright's team picks these orders up and refunds the shipping protection line through your store. ## If a shipment or order is cancelled If you cancel a fulfillment, SureBright cancels the shipping contract created for it. If the whole order is cancelled, every shipping contract on it is cancelled the same way. The shopper receives an email, **Your SureBright shipping insurance has been cancelled**. Refunding the shipping protection fee on a cancelled order is handled with the rest of the order's refund. ## Choosing which products are covered In the Merchant Portal, open **Products**. When shipping protection is on for your store, the product table has a **Shipping protection** column. - Products in a shipping-eligible category show **On** or **Off**. Open the dropdown and pick the other value to change it; the change saves immediately. Products are **On** unless you turn them off. - Products outside those categories, or with no SureBright category yet, show a static **Not eligible** pill. Give the product a category first if you think it should be covered. - Select several products to change them together: the bulk action bar has a **Shipping protection** dropdown with **On** and **Off**. - The filter panel has a **Shipping protection** group so you can list only **On**, **Off** or **Not eligible** products. Turning a product **Off** removes it from the eligible value: it is not priced into the fee and is not covered if it ships. The column is shown for Shopify and BigCommerce stores and is being rolled out store by store. If shipping protection is on for your store but you do not see the column, ask your SureBright contact. You can see shipping protection sales in the Merchant Portal under **Sales** (**Recent shipping sales**). ## Platforms that support shipping protection | Platform | Shipping protection | |---|---| | Shopify | Cart widget, coverage popup, checkout block on Plus, contracts from fulfillments, per-product toggle in the Merchant Portal | | BigCommerce | Offer at cart, contracts from fulfillments, cancellation, per-product toggle in the Merchant Portal | | Magento | Mentioned in the [Magento install guide](/magento/install-guide); ask your SureBright contact about availability for your store | | Salesforce Commerce Cloud, WooCommerce, Shift4Shop, custom storefronts | Ask your SureBright contact | | Lightspeed and the POS portal | Not available | ## Related How a shopper files a claim and what you need to do. Turn shipping protection on or off per product. Building a custom storefront? See [Shipping protection widgets](/frontend-widget-integration/frontend-widget-kit/shipping-protection-widgets) and the [shipping quote endpoint](/api-reference/endpoint/quote/shipping-quote). **See also:** [What you are billed for shipping protection](/merchant-portal/how-billing-works#what-you-are-billed-for-shipping-protection), [Shipping protection options on your widget](/merchant-portal/widget-options#shipping-protection-options), [Keep shipping protection off some products](/merchant-portal/products#keep-shipping-protection-off-some-products), [Shipping protection on phone and draft orders](/learn/phone-and-later-sales#shipping-protection-on-phone-and-draft-orders), [Where you ship from](/platforms/languages-and-regions#shipping-protection-and-where-you-ship-from). --- # Shopify admin housekeeping Source: https://docs.surebright.com/shopify/admin-housekeeping > The plan products SureBright adds to your Shopify catalogue, and the settings in your Shopify admin that keep the program working: sales channels, discounts, the Cart Validator and keeping plan products out of search and recommendations. Protection plans are products in your Shopify catalogue, sold through your normal checkout. This page explains those plan products and the settings in your Shopify admin that decide whether shoppers can add a plan, whether your discounts cut its price, whether a plan can be bought on its own, and where plan products show up. You change these in Shopify admin, not in the Merchant Portal. | Setting | What it does for you | When to check it | |---|---|---| | [Online Store sales channel](#online-store-sales-channel) | A product that is not on the Online Store channel shows no offer, and its plan cannot be added to the cart | A product shows no offer, or shoppers cannot add a plan | | [Discounts that exclude SureBright products](#discounts-that-exclude-surebright-products) | Keeps a store-wide discount from also cutting the plan price | Before you launch a sale or an automatic discount | | [Cart Validator](#cart-validator) | Blocks a plan from being bought without the product it covers | Once at setup, and again if you change checkout rules | | [Plan products in your catalogue](#the-plan-products-in-your-catalogue) | Explains the products SureBright adds, and what you can and cannot change on them | When you see them for the first time, or set up your ERP or accounts | | [Hide plan products from search and recommendations](#hide-plan-products-from-search-and-recommendations) | Keeps plan products out of search results, "You may also like" and review widgets | At setup, and after every theme change | | [Standalone plan orders](#orders-with-a-plan-and-no-product) | What to do about orders that bought only a plan | When you see such orders | ## Online Store sales channel A product must be available on the **Online Store** sales channel to show an offer and for the plan to be added to the cart from its page. New products and products imported from another system are sometimes published only to other channels. In Shopify admin open the product, find the **Publishing** card and click its three-dot menu. The Publishing card on a Shopify product page Tick **Online Store** in the list of channels and click **Done**. Save the product. The sales channel list with Online Store selected The same applies to the plan products themselves (vendor **Surebright**). If they are unpublished from the Online Store, shoppers cannot add a plan. ### Shopify POS If you sell protection at the counter with the [POS extension](/shopify/pos-extension), the plan products must also be available on the **Point of Sale** sales channel. If Shopify POS says the warranty product does not exist, publish the plan products to **Point of Sale** the same way. Add warranties in POS from the SureBright tile. A plan product rung up any other way, for example by searching for it in POS, is not linked to the product it covers, and the sale does not become a contract. If that happened, email [support@surebright.com](mailto:support@surebright.com) with the order number. ## Discounts that exclude SureBright products Plan prices are set in [Warranty Pricing](/merchant-portal/warranty-pricing). A store-wide discount code or automatic discount would also apply to the plan line in the cart, so build discounts on a collection that leaves SureBright products out. In **Products → Collections** create a collection, for example **All products except Surebright**, with the automated condition **Product vendor** is not equal to **Surebright**. Smart collection condition excluding the Surebright vendor Go to **Discounts → Create discount → Amount off products**. Creating an amount-off-products discount Under **Applies to** choose **Specific collections** and pick the collection you just made. Applies to set to the collection that excludes Surebright Set the value, dates and limits as usual and save. Repeat the **Applies to** step for every discount you create while the program runs. To offer a discount on the plan itself, use [Abandoned Cart Recovery](/abandoned-cart-guide/abandoned-cart), which issues single-use codes scoped to the plan. ## Cart Validator The SureBright Cart Validator is a Shopify checkout rule that comes with the **SUREBRIGHT - EXTENDED WARRANTY** app. Switch it on and a plan cannot be bought on its own: checkout is blocked unless every plan in the cart goes with an eligible product in the same cart. This stops plans being bought by mistake, through a shared cart link or through a channel where the SureBright offer does not show. You switch it on once under **Settings > Checkout > Checkout rules**. [Enable the SureBright Cart Validator](/shopify/enable-surebright-cart-validator) has the steps, the test and what to do if it misbehaves. ## The plan products in your catalogue When your store is set up, SureBright adds products to your Shopify catalogue so that a plan can be added to the cart and paid for at your checkout like any other item. They can appear before you have switched anything on, because they are created at setup, before your offer goes live. | What you see | What it means | |---|---| | Products titled **Product Warranty Powered by SureBright**, vendor **Surebright** | The plan products. There is one for each category and price band, with a variant for each term, so a store with several categories has several. That is expected, not a duplicate. | | Variants named **SureBright Protection**, with a coverage ID | Each variant is one plan term at one price. Variants on the same product share its coverage ID; your contracts still record the right term. | | No stock tracking, and no shipping | A plan has nothing to ship or count. | | An empty **Cost per item** | SureBright does not fill it in. What SureBright bills you for each plan is on your invoices. See [How billing works](/merchant-portal/how-billing-works). | Do not edit, rename, delete, unpublish from the Online Store, or archive the plan products or their variants. The offer adds these exact variants to the cart, so a changed or missing variant means shoppers cannot buy that plan. You can safely fill in **Cost per item** for your own reporting, and mark the products **Unlisted** (see below). Need the list of plan SKUs for an ERP or your accounts? Download it from the Merchant Portal: [Download your plan SKUs](/erp/download-plan-skus). For step-by-step ERP guides (Acumatica, NetSuite, Dynamics 365, SAP Business One, Odoo), see [Supported platforms](/platforms/overview#erp). ## Hide plan products from search and recommendations SureBright hides the plan products from your collection pages and hides the add-to-cart form on a plan product's own page. Your theme and other apps can still show them elsewhere: in storefront search, in "You may also like" recommendations, or in a review app's widgets. In Shopify admin open each plan product (vendor **Surebright**) and set its status to **Unlisted**. Unlisted products stay buyable, so the offer keeps working, but Shopify leaves them out of search, recommendations and collections. If a review, search or recommendation app still shows them, exclude the vendor **Surebright** in that app's settings. A new theme can bring its own search and recommendation sections. After you publish one, search your storefront for "warranty" and look at the recommendations on a product page. If a plan product still shows somewhere, tell [support@surebright.com](mailto:support@surebright.com) which page and which part of it. ## Orders with a plan and no product An order that bought only a SureBright plan, often the cheapest one, with no product, is usually one of these: a shopper reaching the plan product through search or a shared link, or bots testing stolen cards on a low-priced item. | You want to | Do this | |---|---| | Stop standalone plan purchases | Switch on the [Cart Validator](#cart-validator). Checkout is then blocked unless the plan goes with an eligible product, and the shopper sees **Warranty purchases are permitted only when accompanied by an eligible product.** | | Keep plans bought later working | Nothing. The Cart Validator lets through plans bought from [post-purchase offer links](/post-purchase/offer-links) and from your [product registration page](/shopify/product-registration), which are meant to be bought on their own. | | Not pay for fraudulent or mistaken orders | Cancel or refund them in Shopify, including the plan line. A plan cancelled before it is billed is never charged. See [Refunds and your credit](/learn/refunds-and-credits). | | Make the plan products harder to find | See [Hide plan products from search and recommendations](#hide-plan-products-from-search-and-recommendations). | | Get help on another platform | Email [support@surebright.com](mailto:support@surebright.com) with example order numbers. | ### Can someone buy a plan for a product they do not own? On your registration page the shopper must enter a purchase date within your store's registration window, 30 days by default, and the plan is priced for that date. See [Product registration](/shopify/product-registration). Every claim is then reviewed by SureBright before it is approved. See [Claims overview](/claims/overview). If you see registration purchases you do not recognise, send SureBright the order numbers. ## Related Turning the app embed on and confirming it from the Merchant Portal. App permissions, collaborator requests and SureBright staff accounts. What each contract status means and how a contract moves between them. **See also:** [Checkouts with only a plan in them](/learn/plans-in-your-order-tools#checkouts-with-only-a-plan-in-them). --- # Bundles Source: https://docs.surebright.com/shopify/bundles > Which Shopify bundles can carry a protection plan, what the shopper sees, what the cart and order look like, and how to get bundle support for your store. A bundle is one product on your storefront that becomes several items on the order. SureBright protects the components, because a claim is about the dehumidifier or the pump, not about the kit. The shopper sees one plan price for the bundle, and you get one contract for each covered component. ## Which bundles are offered a plan | Bundle | Offered? | | --- | --- | | Shopify fixed bundle whose protectable components are all in one SureBright category | Yes. One plan price covering every protectable component. | | Fixed bundle with some components that cannot be protected (a filter, a cable) | Yes. Those components are left out of the plan and never get a contract. | | Fixed bundle whose protectable components fall into different categories | Not as standard. If you sell bundles like these regularly, SureBright can set up custom handling so they carry a plan. This is available to stores that meet a minimum order volume: ask your SureBright contact. | | Bundle built by a bundle app as a single "bundle as product" page | Supported for specific apps, switched on per store. See [Bundle app pages](#bundle-app-pages-the-warranty-bar-and-pop-up). | | Bundle from an app that splits the bundle into its components on the order, such as Simple Bundles | Supported. SureBright recognises the components and spreads the plan price across them. Ask SureBright to check your set-up before launch. | | Product built with a product options or configurator app | Ask SureBright. See [Product options and configurator apps](#product-options-and-configurator-apps). | | Furniture or other products sold as separate pieces that make one set | See [Sets sold as separate pieces](#sets-sold-as-separate-pieces). | What the shopper is offered is final. A bundle that shows no plan never produces a contract. ## What the shopper sees on a bundle For a fixed bundle the product page shows the standard SureBright plan cards. The price on each card is the total for the bundle: the component plan prices for that term, added up. If your theme has a bundle quantity picker (for example a "2x" option drawn by a bundle app), ask SureBright to make the plan price follow it. ## What the cart and the order look like When the shopper adds a bundle with a plan, the cart gets one protection line for each protectable component, not one line for the bundle. This is the same whether the plan is added from the product page, the cart offer or the cart toggle. | On each protection line | What you see | | --- | --- | | Title | The bundle title, a dash, and the component title, for example **In-Wall Dehumidifier Kit - Pump**. This tells a component plan apart from a plan on the same product bought on its own. | | Quantity | The bundle quantity times the number of that component in the bundle. | The lines stay together. When the shopper changes the bundle quantity the plan lines follow, and when the bundle leaves the cart they all go with it. In Shopify checkout, removing a bundle's plan with the Protection Badge removes the component plans as a set. See [Checkout extensions](/shopify/checkout-extensions). On the order you get one contract for each covered component. A plan on a bundle is refunded or cancelled component by component, following the order's line items. See [Contract statuses](/contracts/lifecycle). ## Bundle app pages: the warranty bar and pop-up Some stores sell bundles through an app that draws a "build your bundle" box on a single product page. The shopper picks a variant for each component and the app adds the components to the cart. On these pages SureBright replaces the standard plan cards with a compact bar and a pop-up, so the bundle app's own add-to-cart button keeps working as it does today. SureBright switches this on per store, and it currently supports the Fast Bundle app. **The warranty bar** sits where the plan cards normally would. Before a choice it reads **Add extended warranty**, with the line **Covers breakdowns, wear & tear, power surges, and more - What's covered?** and an **Add warranty** button. After the shopper confirms, it reads **SureBright protection added**, summarises what was chosen, and offers **Change plan**. **The pop-up** opens from the bar. It is headed **Add Product Warranty for the following items from your cart:** and lists one row per bundle unit, each with the component's image, title, variant and a plan dropdown. The footer shows **Selected Products** and **Total**, with **No, thanks** and **Protect my purchase** buttons, and the strip **Let us handle the worries, and you enjoy your purchase!** When the shopper changes a component's variant in the bundle box, that row's plans update. When the shopper then adds the bundle with the app's own button, the plans they confirmed go into the cart with the components. ## Claims on a bundle Each covered component has its own contract, so a claim is made on the component that failed, not on the whole bundle. If the pump in a dehumidifier kit breaks, the customer claims on the pump's contract and the other components stay covered. In the customer portal the customer opens that component under **Protection plans** and clicks **File a claim**. See [Filing a claim](/claims/filing-a-claim). ## Product options and configurator apps Some apps build a product from options the shopper picks, such as size, finish or add-ons, and change the price as they go. Whether the plan price can follow those choices depends on how the app adds the product to the cart. Send SureBright the URL of a product built with the app, name the app, and say which options change the price. SureBright checks it and tells you what works, before you launch it. ## Sets sold as separate pieces When a set, such as a sectional sofa, is sold as separate products that the shopper picks one by one, each piece is its own product and gets its own plan offer. To sell one plan for the whole set, talk to your SureBright contact. One way stores do this is to record the sale in the [SureBright POS portal](/pos/overview). Whichever way you sell it, the shopper pays you for the plan at your checkout, and SureBright bills you through your payment method. SureBright never invoices your customer. ## Get bundle support for your store Shopify fixed bundles are recognised from your catalogue. Make sure the components are categorised. As standard, a bundle offers a plan when its protectable components share a category. For bundles that mix categories, custom handling is available to stores that meet a minimum order volume. Tell SureBright which bundle app you use and share a bundle product page. SureBright switches on the bar and pop-up for your store. If your cart drawer needs a refresh to show the added plans, SureBright sets that up too. Place a test order with a plan on a bundle and check in the Merchant Portal that one contract per protectable component was created. ## Troubleshooting | What you see | Why | What to do | | --- | --- | --- | | No plan offered on a bundle, but its components get one on their own pages | The protectable components are in different SureBright categories, so the bundle cannot carry a plan. | Nothing to fix on the storefront. If you believe the components belong to one category, ask SureBright to review their categorisation. | | No plan offered, and the components have no plan either | The components are not categorised yet. | Allow time for categorisation after adding the products, or ask SureBright. | | Bundle app page shows neither the bar nor the plan cards | The bundle app took more than 10 seconds to load its bundle, so the page was left as the app drew it. | Reload the page. If it persists, send SureBright the URL. | | Several protection lines in the cart for one bundle | Expected. One line per protectable component, each titled with the bundle and the component. | Nothing. They change and leave the cart together with the bundle. | | Only some components got a contract | Components that cannot be protected are left out of the plan. | Compare against the plan rows shown in the pop-up or the cart. Those are the covered components. | ## Related - [What can be covered](/contracts/what-can-be-covered) - [Checkout extensions (Shopify Plus)](/shopify/checkout-extensions) - [Contract statuses](/contracts/lifecycle) Building a custom storefront or cart? Each component plan line carries hidden line properties that must reach the order unchanged. They are listed under [Cart line-item properties](/frontend-widget-integration/frontend-widget-kit/javascript-injection#cart-line-item-properties), and the quantity rules are in [Client-side cart sync](/frontend-widget-integration/frontend-widget-kit/cart-sync). --- # Checkout extensions (Shopify Plus) Source: https://docs.surebright.com/shopify/checkout-extensions > Offer SureBright shipping and product protection inside Shopify checkout with the Protection Block and Protection Badge On a Shopify Plus store you can offer protection inside checkout itself, after the shopper has left the cart. You add two blocks in Shopify's checkout editor. They come with the **SureBright - Extended Warranty** app and are listed together in the editor as **SureBright - Product & Shipping Protection**: A box below the list of cart items that offers **shipping protection** for the whole order with one checkbox. A small addition under each cart line: a **Protected** label for covered items and an **Add Warranty** link for eligible items that lets the shopper add a product warranty without leaving checkout. ## Requirements - Your store is on **Shopify Plus**. Shopify shows these checkout blocks on Plus stores only, so the Merchant Portal shows the checkout steps only to Plus stores. - Your checkout uses **checkout extensibility** (the checkout editor with an **Apps** panel). - The **SureBright - Extended Warranty** app is installed and your storefront is set up (see [Storefront setup](/shopify/storefront-setup)). ## Add the blocks to your checkout Go to **Settings → Storefront setup**. Under **Protection in checkout**, click **Open checkout editor ↗**. It opens your live checkout on the **Apps** panel. Opening it from this link also switches on the checkout offering in your live SureBright design. Under **SureBright - Extended Warranty**, click **+** next to **SureBright Protection Block** and **SureBright Protection Badge**. In the checkout behavior controls, turn on **Include app in Shop Pay**. Click **Save**. To check that it works, preview your checkout in the checkout editor. You should see the SureBright protection offer below your cart items. The Merchant Portal shows no on or off status for checkout, because Shopify does not report where the blocks are placed. Use the checkout editor preview to confirm. The checkout editor preview always shows **sample content**: the Protection Block shows a sample shipping protection price and the badge shows an **Add Warranty** link with sample 1, 2 and 3 year plans on every item. This lets you see the layout before a real shopper reaches checkout. Place a real test checkout to see real prices. ## What the shopper sees in checkout ### Protection Block: shipping protection for the order Once the shopper has entered a shipping address, and shipping protection is available for the items in the cart, a bordered box appears below the cart items: - A checkbox with the heading **Add Shipping Protection for $X.XX** (in the checkout currency). - The line **Protects against package damage, loss, theft, & more**, followed by a **see complete coverage** link that opens a coverage pop-up. Ticking the checkbox adds shipping protection to the order as one line. Unticking removes it. The price updates by itself when the shipping country changes or when products are added or removed. If shipping protection is not available for the cart, nothing is shown. ### Protection Badge: warranty on each cart line Under each cart line the badge shows what applies to that item: | Situation | What appears | | --- | --- | | Item is eligible for a product warranty and not yet covered | An **Add Warranty** link | | Item has a product warranty in the cart | A **Protected** label with the product protection icon | | Shipping protection is on and covers the item | A **Protected** label with the shipping protection icon (plus **Add Warranty** if a product warranty is also available) | | Both product and shipping protection apply | Both icons with an info tooltip reading **Product warranty and Shipping Protection** | | Warranty was added in checkout | A trash icon with the tooltip **Remove warranty from cart** on the warranty line | Clicking **Add Warranty** opens a pop-up for that product: - The product title and image. - The plan heading (your configured offering title, or **Add Extended Warranty** by default) and the available terms as selectable options, with a plan pre-selected. - The coverage bullets for the plan and a **Trusted by 100K+ customers** strip with your store logo and SureBright's. - **Protect My Purchase** and **No, Thanks** buttons. - A footer link to the plan's documents. **Protect My Purchase** adds the chosen warranty to the order with the same quantity as the product. If the shopper later changes the product quantity, the warranty quantity follows. The trash icon removes only warranties added in checkout. A warranty the shopper added earlier, on the product or cart page, is left alone. ## Troubleshooting That card only appears when your store is on a Shopify Plus plan. On other plans, SureBright protection is offered on the product and cart pages instead. - The shipping protection box appears only after a shipping address is entered, and only when shipping protection is available for the items in the cart. - The **Add Warranty** link appears only on items that are eligible for a warranty. Items that already have one show **Protected** instead. - The checkout editor preview always shows sample content. Test with a real checkout to see real offers. The message **We couldn't turn on checkout protection. Open the checkout editor again to try once more.** means the portal could not switch on the checkout offering in your live design. Click **Open checkout editor ↗** again. ## Related - [Storefront setup](/shopify/storefront-setup): turn SureBright on in your theme first. - [Bundles](/shopify/bundles): how plans on a bundle behave, including in checkout. The two blocks are Shopify checkout UI extensions: | Extension | Handle | Target | | --- | --- | --- | | SureBright Protection Block | `sb-checkout-protection-block` | `purchase.checkout.cart-line-list.render-after` | | SureBright Protection Badge | `sb-checkout-protection-badge` | `purchase.checkout.cart-line-item.render-after` | Lines added in checkout carry the same properties as lines added on the storefront, listed under [Cart line-item properties](/frontend-widget-integration/frontend-widget-kit/javascript-injection#cart-line-item-properties), with `_sbWarrantySource` set to `CHECKOUT_EXTENSION`. If your own code reads or changes cart lines in checkout, note that: - The badge is drawn from the line attributes `_isSBProductProtected`, `_isSBEligibleProduct` and `_isSBShippingProtected`, so lines protected on the storefront before checkout also show as protected. - The trash icon is offered only on a warranty line that carries both `_sbQuoteItemId` and `_sbWarrantySource = CHECKOUT_EXTENSION`. Warranties on bundle components (`_isBundleComponentPolicy = "true"`) are removed together. - Post-purchase and registration warranties (`_quotePlatform` of `PLATFORM_POST_PURCHASE` or `REGISTRATION_POST_PURCHASE`) are never removed or quantity-matched in checkout, because the product they cover is not in the cart. - The order holds one shipping protection line with quantity 1. Extra lines or a higher quantity are corrected. --- # Offer two kinds of protection on one product Source: https://docs.surebright.com/shopify/dual-coverage > Show two kinds of protection plan on the same product page. Shoppers use two tabs to choose between a plan for breakdowns and a plan that also covers accidents. Some shoppers only worry about a product breaking down. Others also worry about drops and spills. With two kinds of protection on the same page, each shopper can pick the cover they care about. SureBright calls this **dual coverage**. The offer on your product page gets two tabs. The shopper first picks the kind of cover, then how long it lasts. SureBright switches dual coverage on for your store. It only works for some kinds of products. Ask your SureBright contact whether yours qualify. | You want to | Go to | | --- | --- | | See what shoppers see | [What shoppers see on the product page](#what-shoppers-see-on-the-product-page) | | Know why some products have no tabs | [Products with only one kind of cover](#products-with-only-one-kind-of-cover) | | Know what happens in the cart | [In the cart and at checkout](#in-the-cart-and-at-checkout) | | Sell plans over the phone or in your shop | [Phone orders and Shopify POS](#phone-orders-and-shopify-pos) | | Get it switched on | [Get dual coverage switched on](#get-dual-coverage-switched-on) | | Fix something that looks wrong | [If something looks wrong](#if-something-looks-wrong) | ## What shoppers see on the product page The offer has a title and two tabs: | Tab | Plans shown | | --- | --- | | **Extended Warranty** | Plans that cover breakdowns. | | **Accidental + Extended Warranty** | Plans that cover accidents, like drops and spills, and also breakdowns. | Each tab has its own plans. The **Extended Warranty** tab opens first. Shoppers can switch tabs without losing their choice. Say a shopper picks a 2-year plan, looks at the other tab, then comes back. The 2-year plan is still picked. On a tab the shopper has not used yet, no plan is picked. The title changes with the tab: - On the first tab it says **Add premium product protection**. - On the second tab it says **Add Accidental and Breakdown Warranty**. SureBright can change both titles to your own words. ### In the pop-up A pop-up with the plans opens when the shopper clicks "what's covered". It also opens if they click add to cart without picking a plan. The pop-up has the heading **Select a coverage plan** and the same two tabs. What the pop-up says is covered, and for how long, changes with the open tab. A plan picked in the pop-up is also picked on the page. ## Products with only one kind of cover Tabs only show on products that have both kinds of plan. - A product with one kind of plan shows the normal offer, with no tabs. - A product with no plans shows no offer. ## In the cart and at checkout The plan goes into the cart like any other plan. Your cart and checkout do not change. A product can have only one plan in the cart. If the shopper adds a plan from the other tab, it replaces the first one. ## Phone orders and Shopify POS **Phone orders.** In Shopify admin you can make an order for a customer yourself (a draft order), for example when they call you. The **SureBright - Product Protection Draft Order** pop-up lists both kinds of plan together in the plan dropdown for each product. See [Over the Phone Sales using Draft Order Extension](/draft-order-guide/shopify-draft-order). **In your shop.** Shopify POS is Shopify's app for selling in person. There, plans that cover accidents are called **Accidental Protection**, not **Extended Warranty**. See [POS Extension](/shopify/pos-extension). ## Get dual coverage switched on Both kinds of plan must be available for the kinds of product you want to offer them on. SureBright checks this against your products. SureBright turns it on for your store. They set your own titles if you want them. They also check the tabs work with your store's design (your theme). SureBright can show the accidental tab first to half of your shoppers. This shows which order sells more plans. Each shopper sees the same order for their whole visit. If SureBright is moving your store to a newer version of the offer, ask them to check the tabs are in your new design before it goes live. ## If something looks wrong | What you see | What to do | | --- | --- | | No tabs, only one set of plans | That product has only one kind of plan, or dual coverage is not on for your store. Look at another product that should have both. If no product shows tabs, ask SureBright whether it is on. | | Tabs on the page but not in the pop-up | Something in your store's design (your theme) is getting in the way. Send SureBright the link to the product page. | | The wrong title above the tabs | Your own titles have not been set yet. Send SureBright the two titles you want, one for each tab. | | Two plans for the same product in the cart, one of each kind | The older plan is taken out of the cart on its own. See [Client-side cart sync](/frontend-widget-integration/frontend-widget-kit/cart-sync). | ## Related Ready-made designs for the offer on your product page. Sell plans in person with Shopify POS. **See also:** [Offer only one kind of cover on some products](/merchant-portal/onboarding#can-i-offer-only-one-kind-of-cover-on-some-products). The selected plan's `coverageType` is `BREAKDOWN` on the warranty tab and `ACCIDENTAL_BREAKDOWN` on the accidental tab. Your code can read it from `window.SureBright.onSelectionChange`; see the [JavaScript API Reference](/frontend-widget-integration/frontend-widget-kit/javascript-injection#selectionchange-payload). The plan is added to the cart with the same line-item properties as any other plan. --- # Enable the SureBright Cart Validator Source: https://docs.surebright.com/shopify/enable-surebright-cart-validator > Switch on the SureBright Cart Validator, a Shopify checkout rule that stops a protection plan being bought without the product it covers. The SureBright Cart Validator is a Shopify checkout rule that stops a protection plan being bought on its own. With it switched on, checkout is blocked unless every plan in the cart goes with an eligible product in the same cart. It comes with the **SUREBRIGHT - EXTENDED WARRANTY** app, so there is nothing to install. You switch it on once in Shopify admin, and it takes about two minutes. ## Why switch it on Without the validator, a plan can reach checkout without its product: through a shared cart link, a saved cart, or a sales channel where the SureBright offer does not show. That leaves you with a contract that has nothing to cover. The validator blocks those carts at checkout, and shoppers buying a product with its plan are not affected. ## Switch it on In Shopify admin click **Settings** at the bottom left of the sidebar. Settings in the Shopify admin sidebar Click **Checkout** in the settings menu and scroll to **Checkout rules** at the bottom of the page. The Checkout rules section Click **Add rule**. Under **SUREBRIGHT - EXTENDED WARRANTY** choose **sb-cart-validator**. Selecting sb-cart-validator from the list of checkout rules The rule opens as **Inactive**. Give it a **Title**. Leave **Block checkout if app experiences a problem** unchecked, so an outage of the validator never stops a shopper paying. Checkout rule configuration with the title field and fallback option Change the status from **Inactive** to **Active** and click **Save changes**. The header shows the rule title with an **Active** badge. Setting the rule status to Active The rule saved and shown as Active Back under **Checkout rules** the rule is listed as **Active**. Test it: add a SureBright plan product to a cart without its product and go to checkout. The validator should block the purchase. The Surebright rule listed as Active under Checkout rules With **Block checkout if app experiences a problem** unchecked, checkout continues normally if the validator ever fails to respond. Only the validation is skipped. ## If something goes wrong | What you see | Why | What to do | |---|---|---| | **sb-cart-validator** is not in the **Add rule** list | The SureBright app is not installed on this store, or your Shopify plan does not offer checkout rules | Check the app is installed under **Apps**. Ask your SureBright contact if it is | | A shopper with a product and its plan is blocked | The plan in the cart is not linked to that product | Ask the shopper to remove the plan and add it again from the product page. Tell your SureBright contact if it keeps happening | | Checkout is never blocked in your test | The rule is still **Inactive**, or the cart holds the product as well as the plan | Check the rule shows **Active**, then test with a cart that holds only the plan | ## Related - [Shopify admin housekeeping](/shopify/admin-housekeeping): the other Shopify settings that keep the program working. - [Plans in your order tools](/learn/plans-in-your-order-tools) --- # GDPR webhooks Source: https://docs.surebright.com/shopify/gdpr > What happens when a customer of your Shopify store asks for their data or its erasure, what SureBright holds about them, and what you need to do. When a customer asks you for the data held about them, or asks for it to be erased, you pass the request on from Shopify and SureBright receives it. This page says what SureBright holds about a customer, what you need to do, and what happens next, so you can answer a customer or a regulator accurately. SureBright holds customer data because a protection plan is issued to a person. That is what these requests concern. ## What SureBright holds about a customer | Data | Why it is held | | --- | --- | | Name, email, phone | Printed on the plan and used to send the confirmation email and to identify the customer when they claim. | | Street address, city, state or province, ZIP or postal code | Required to issue the plan. A plan without a complete address is held; see [Why a contract is on hold](/contracts/holds). | | The product covered, its price and the order reference | Defines what the plan covers. | | Coverage start and end dates | Define when the plan is in force. | Payment details are never held. The plan is paid for through your checkout. ## Handle a customer data or erasure request In Shopify admin open the customer, choose **Request customer data** or **Erase personal data**, and include SureBright in the request. Shopify passes it to SureBright. There is nothing to set up for this: it comes with the **SureBright - Extended Warranty** app on every store. Email [support@surebright.com](mailto:support@surebright.com) with the Shopify customer id or order number and the date you sent the Shopify request. SureBright matches it to the request it received and tells you what it holds and what it has done. SureBright records the request when it arrives. Nothing is exported or erased on the spot. The data, or confirmation of erasure, comes to you from SureBright separately. A protection plan that is still in force carries the customer details needed to honour a claim; see the customer details listed in [Why a contract is on hold](/contracts/holds). Raise the plan itself with support if the customer also wants it cancelled. ## When each request reaches SureBright | What happens | When SureBright receives the request | | --- | --- | | A customer asks for their data | When you request it from the app in Shopify admin. | | A customer asks for erasure | After you pass the request to apps. Shopify delays it while the customer has recent orders. | | You uninstall the SureBright app | Shopify sends a request to erase your store's data 48 hours after the uninstall. You do not send anything. | In each case SureBright records the request and works from that record to fulfil it. ## Related - [Why a contract is on hold](/contracts/holds): the customer details a plan needs and what happens when one is missing. - [Helping a customer](/help/helping-a-customer): other things customers ask you about their plan. - [Pause or remove SureBright](/platforms/pause-or-remove): what happens when you uninstall. These requests arrive through Shopify's three mandatory privacy webhooks (`customers/data_request`, `customers/redact` and `shop/redact`). They are delivered to the SureBright app, not to your store's own endpoints, so you will not see them in your store's webhook list. See [Platform webhooks SureBright receives](/api-reference/endpoint/webhooks/platform-receivers). --- # Headless Shopify: Hydrogen Source: https://docs.surebright.com/shopify/headless-hydrogen > SureBright works on Shopify Hydrogen and other headless Shopify storefronts. What you get, what is different from a theme store, and what your developer needs to do. Yes, SureBright works on a headless Shopify storefront. Shopify Hydrogen has its own built-in support, and so does Shopyflow, which runs Shopify on Webflow. This page tells you what you get, what is different from a store on a Shopify theme, and what to hand your developer. | Your storefront | Supported | What it takes | | --- | --- | --- | | Shopify theme (Online Store) | Yes | Switch on the app embed. See [Storefront setup](/shopify/storefront-setup). | | Shopify Hydrogen | Yes | Your developer adds the SureBright script and keeps Hydrogen's standard cart and product conventions. | | Shopyflow (Shopify on Webflow) | Yes | Your developer adds the SureBright script. | | Another headless Shopify front end | Ask first | Talk to SureBright before you build. Support depends on how your storefront handles its cart. | ## What you get on Hydrogen - The protection offer on your product pages, in your design. - The plan added to the cart as its own line when a shopper chooses one. - The plan kept in step with the product in the cart: the same quantity, and removed when the product is removed. - Orders with a plan turned into plans for your customers, the same way as on any Shopify store, because your orders still go through Shopify. - Sales, attach rate and billing in the [Merchant Portal](/merchant-portal/overview). ## What is different from a theme store | On a Shopify theme | On Hydrogen | | --- | --- | | You switch on the SureBright app embed in the theme editor. | There is no theme, so there is nothing to switch on. Your developer adds one script to the storefront. | | **Settings → Storefront setup** in the Merchant Portal shows whether the embed is on. | That check does not apply. Your developer confirms the offer on the storefront, and SureBright confirms the first test order. | | The offer finds its place on the page by itself. | SureBright sets the placement for your storefront once it is ready. Tell SureBright when it is. | | A design can be [targeted](/merchant-portal/design-targeting) at a theme or template with no extra work. | Your developer has to tell the widget which theme or template a page stands for. | | Shopper consent follows Shopify's consent banner. | If your storefront has its own consent manager, tell SureBright. | ## What to hand your developer Send your developer this list and the two developer pages below. In plain words, they need to: It carries your store's address, so SureBright knows which store the storefront belongs to. One line of configuration. It saves the script from guessing. The widget reads the selected variant and the cart the way the Hydrogen starter template provides them, and adds the plan through the storefront's own cart. Each plan line carries hidden details that tie it to the product it covers. If the storefront drops them, the order arrives with a plan SureBright cannot set up. Place one test order with a plan and ask SureBright to confirm the plan was created. See [Test your setup](/platforms/test-your-setup). The script tag and the Hydrogen requirements, step by step. How the pieces fit together, what breaks when one is missing, and how to verify. ## If the offer does not show | What you see | Usual cause | | --- | --- | | No offer on any page | The script is missing your store's address, or the storefront was not declared as Hydrogen. | | The offer shows the wrong plan or none on some variants | The product form no longer exposes the selected variant in the standard way. | | A plan is in the cart but the customer gets no plan after ordering | The storefront dropped the plan's details between the cart and the order. | | The offer is missing on product or cart pages only | Those pages do not use the usual `/products/` and `/cart` addresses. | Your developer can confirm each of these with the checks in [Headless and custom storefronts](/frontend-widget-integration/frontend-widget-kit/headless-and-custom-storefronts#what-breaks-when-a-step-is-skipped). ## Before you start Tell your SureBright contact that your storefront is headless before your developer begins. Placement, design and which offers are switched on are finished on SureBright's side before the offer goes live for your shoppers. ## Related - [Supported platforms](/platforms/overview) - [Storefront setup](/shopify/storefront-setup) for stores on a Shopify theme - [Shopify Markets pricing](/shopify/markets) - [Offer not showing?](/help/offer-not-showing) --- # Shopify Markets pricing Source: https://docs.surebright.com/shopify/markets > Which price a shopper in each Shopify Market sees for a protection plan, what you need to have in place, and what happens when a plan is offered in one currency and paid in another. If you use Shopify Markets to show shoppers in different countries different prices or currencies, SureBright prices each plan against the price that shopper is actually charged, not against your base price. This page says which price is used, what you need in place, and how to check a market. This applies to Shopify stores only. Ask your SureBright contact to switch it on once your markets are set up. There is nothing to set in the SureBright app. ## Which price a shopper's plan is based on The plan follows the shopper's country, the same country Shopify's own country selector sets. | The shopper is in | The plan is priced against | | --- | --- | | A country assigned to one of your markets | The product's price in that market. | | A country not assigned to any market | The product's price in your primary market. | | A market where the product has no price | The product's price in that market's currency, if it has one in another market. Otherwise your base price. | Stores priced only through market price lists, where the base price is zero, still get plans: the market price is used. Until your markets have been set up with SureBright, plans are priced against your base price, as on a store without Markets. Plans are sold to shoppers in the United States and Canada. Shoppers in a market that serves other countries are not offered a plan. See [Languages and regions](/platforms/languages-and-regions). ## When you change a market or a price You do not need to tell SureBright. - **You add, change or delete a market.** SureBright picks up the change and re-reads the market prices of your whole catalogue. - **You change a product's price in a market.** The new price reaches SureBright the next time the product is updated in Shopify. Saving the product in Shopify is enough. ## What you need to have in place - Markets set up in Shopify, with every country you sell to assigned to a market. - A storefront that switches country with the shopper. On an Online Store theme, Shopify's country selector does this for you. On a headless storefront, ask your developer to check the note at the end of this page. - Markets pricing switched on for your store by SureBright. ## When the plan and order currencies differ A plan is offered for one country and, with it, one currency. If the order is then paid in a different currency, or its shipping or billing address is not in that country, the plan stays on the order but its contract is put on hold. An example is a plan offered to a US shopper in USD on an order paid in CAD. You see a **Currency mismatch** hold, and a case appears in **Order Resolution**. There is nothing for you to do: SureBright matches the amounts to the order currency and the hold clears. See [Why a contract is on hold](/contracts/holds). This happens when a shopper changes country between viewing the product and paying, or when a storefront shows one country on the product page and another at checkout. Keeping the storefront's country consistent, as above, avoids it. ## Check that a market is priced correctly - In Shopify admin, **Settings → Markets** lists the markets SureBright follows. - Open a product page as a shopper in a market other than your primary one. The plan prices in the SureBright offer should follow the market price, not the base price. If they follow the base price, save the product in Shopify and look again. - If plans are missing in one market but present in another, confirm the country is one SureBright sells in before you contact support. ## Related - [Why a contract is on hold](/contracts/holds): the currency mismatch hold and the others. - [Languages and regions](/platforms/languages-and-regions): where plans are sold and in which currency. - [What can be covered](/contracts/what-can-be-covered): which shoppers and products get an offer. SureBright keeps your markets and per-market prices current through Shopify's market and product webhooks, listed in [Platform webhooks SureBright receives](/api-reference/endpoint/webhooks/platform-receivers). On a headless storefront, the localisation you pass to the Storefront API must match the country the SureBright SDK reports for the shopper. On an Online Store theme that country is `Shopify.country`. To see what the SDK resolves on a page, add `?sb_debug` to the URL; see [Debugging](/frontend-widget-integration/frontend-widget-kit/javascript-injection#debugging). --- # POS Extension Source: https://docs.surebright.com/shopify/pos-extension > Sell SureBright warranties in your physical store from the Shopify POS app With the SureBright POS extension your store staff can add a SureBright warranty to a Shopify POS cart in a few taps, and sell it on the same receipt as the product. It comes with the **SureBright - Extended Warranty** app and appears inside the Shopify POS app once you have granted permissions and added the tile. ## What the extension adds to Shopify POS A smart grid tile labelled **SureBright App** with the subtitle **Protect Your Purchase**. Tapping it opens the cart warranty screen. A full-screen page titled **SureBright Warranty** that lists every item in the current cart that can be protected, with its plan options. A SureBright action on a product's details page that opens the warranty options for that product's variants, before anything is in the cart. ## Set up the POS extension The SureBright app must be allowed in POS. Grant the permissions by following [these steps](https://app.storylane.io/share/lrt9aeyhnw9i). Add the tile on each device by following [these steps](https://app.storylane.io/share/qukutyegdyab). Make sure the Shopify POS app on each device is updated to the latest version from the App Store or Google Play. If the tile is not visible after these steps, update the Shopify POS app to the latest version. If it is still missing, email [support@surebright.com](mailto:support@surebright.com) with the version of the Shopify POS app installed on the device. ## Add a warranty to a POS cart Add the customer's products to the POS cart. Tap the **SureBright App** tile on the smart grid. The **SureBright Warranty** screen opens and shows a spinner while it loads warranty options. Each eligible cart item gets its own section headed with the product title. Under it are the available plans, written as, for example, **2 Year Extended Warranty - $49**. For accidental damage plans the label reads **Accidental Protection** instead of **Extended Warranty**. Tap a plan to add it. The screen shows **Adding warranty to cart...** for a few seconds, then a toast **Warranty Added To Cart** appears and the screen closes. The warranty is now a line in the cart, with the same quantity as the product it covers. Complete the sale in POS as normal. The warranty is sold on the same receipt as the product. You can also start from a product instead of the cart: open the product's details page in POS, choose the SureBright action, and the same warranty options appear for each variant of that product. Warranties added from here have quantity 1. ### What staff see when nothing is eligible - From the tile: **No Eligible Cart Item found for Warranty**. The cart is empty, or none of its items has a SureBright plan. - From a product's details page: **No Eligible Product for Warranty**. An item that already has a SureBright warranty in the cart is not offered again. ## Show the customer what is covered Each item's section has a **What's Covered** button. It opens a screen headed with the product title that reads **Use your purchase worry-free for years to come.** and lists two sections: **Your Warranty Plan Provides** and **Why Surebright?**. A button at the bottom opens the plan's documents inside POS. On iOS a PDF shows on that screen; on Android it opens in a separate viewer. ## Related - [Storefront setup](/shopify/storefront-setup): offer protection on your online store. - [Checkout extensions (Shopify Plus)](/shopify/checkout-extensions): offer protection inside online checkout. The extension is a Shopify POS UI extension with four targets: | Target | Purpose | | --- | --- | | `pos.home.tile.render` | Smart grid tile | | `pos.home.modal.render` | Cart warranty screen | | `pos.product-details.action.menu-item.render` | Product details action | | `pos.product-details.action.render` | Product details warranty screen | A warranty line added in POS carries the line properties `_sbQuoteId`, `_sbQuoteItemId` and `_variantId` (the covered product variant). Keep them on the line through to the order; see [Cart line-item properties](/frontend-widget-integration/frontend-widget-kit/javascript-injection#cart-line-item-properties). Prices show a `$` prefix for US stores and a `CAD` suffix for Canadian stores. **See also:** [Shopify POS setup](/shopify/admin-housekeeping#shopify-pos). --- # Product registration pages Source: https://docs.surebright.com/shopify/product-registration > Let shoppers who already own one of your products buy SureBright protection for it from a page on your Shopify store: what each page offers, what the shopper does, and what you set up. Not every protection plan is sold at checkout. A shopper may have bought the product last week, be registering it for the manufacturer's warranty, or have received a follow-up email from you. You can give those shoppers a page on your Shopify store where they buy protection for a product they already own. | Page | Address on your store | What it lets you offer | | --- | --- | --- | | **Extended product protection** | `/pages/extended-product-protection` | A shopper who owns one of your products looks it up, says when they bought it and picks a plan. | | **Product registration** | `/pages/product-registration` | A shopper fills in your product registration form. After they submit it, SureBright offers protection for the product they registered. | Both are ordinary Shopify pages that you create under **Online Store → Pages**. SureBright adds its part once the page exists and you have told us about it. They work even if SureBright is otherwise limited to certain page types on your store (see [Storefront setup](/shopify/storefront-setup)). A plan sold from these pages is priced for the purchase date the shopper enters and is tied to the product they already own, not to a new item in the cart. In the Merchant Portal, **Sales → Recent sales** lists them under the **Platform** filter as **Registration Post Purchase**. ## Extended product protection page ### What the shopper does on the protection page The page shows a **Product Title** field with the placeholder **Search by product title** and a **Search** button. As the shopper types, matching products from your store appear in a dropdown with their image and title. They pick one. If the product has several variants, a variant selector appears. The shopper enters a **Product purchase date** from today back to the end of your store's registration window, which is 30 days by default. On stores whose coverage starts when the order ships, the field reads **Product delivery date** and the window is 37 days. Leaving it empty shows **Please select a date of purchase** (or **Please select a delivery date**). The shopper clicks **See Warranty Offers**. After a **Loading warranty options...** message, the SureBright plan pop-up opens with the terms available for that product and purchase date. If there is no plan, the page shows **No warranty options available**. Choosing a plan and confirming adds it to the Shopify cart and sends the shopper to the cart page to check out. Only the plan is in the cart. The product itself is not added again. ### Create the protection page in Shopify In Shopify admin go to **Online Store → Pages → Add page**. Give it a title such as "Extended Product Protection". In the page's search engine listing, set the URL handle to `extended-product-protection` so the page is served at `/pages/extended-product-protection`. (`/pages/product-extended-warranty` also works.) In the page content, switch to the HTML editor and add an empty container where you want the lookup to appear: ```html
``` Without it, the lookup appears in a spot SureBright sets for your store, or straight after the page heading.
Email [support@surebright.com](mailto:support@surebright.com) with the page URL. SureBright sets the page heading, the search box helper text, the co-branding logo and the widget styling for your store. These are not set in Shopify.
Link to the page from your site footer, your warranty or support page, and your post-purchase emails, so shoppers who bought without protection can find it. ## Product registration page This page is for stores that collect product registrations from customers. You keep your own registration form. SureBright adds a protection offer after it is submitted. ### What the shopper does after registering 1. The shopper fills in your registration form on `/pages/product-registration` (name, email, the product and its purchase date, plus any fields your form has) and submits it. Your form works exactly as before: its validation, CAPTCHA and any redirect you have set up are untouched. 2. SureBright matches the product name on the form to a product in your store and looks for protection plans for it. 3. If plans exist, the SureBright plan pop-up opens on top of the page with the product's offers. The shopper can pick a plan and add it to the cart, or close the pop-up with the "no thanks" option and stay on the page. ### Set up the registration page In Shopify admin, create a page with the handle `product-registration` and embed your registration form on it. Email [support@surebright.com](mailto:support@surebright.com) with the page URL and a description of the form's fields. Because every registration form is different, SureBright sets up the connection for your store: which form to follow, which of its fields hold the first name, last name, email, product name and purchase date, and where the registration should be passed on (for example to your existing form provider). ## Keeping these pages from being misused Anyone with the link or QR code can open these pages, so it is fair to ask what stops a plan being bought for an old unit, or for a unit the shopper does not own. These limits apply on every store: | Concern | What limits it | |---|---| | A plan for a product bought long ago | The purchase date can only be picked from today back to the end of your store's registration window. Older products are not offered a plan. | | Buying late to get a full term | Cover is counted from the purchase date entered, not from the day the plan is bought, so buying later never adds time. See [When coverage starts](/contracts/effective-dates#plans-bought-after-the-product-post-purchase). | | A claim for damage that happened before the plan | Every claim is reviewed by SureBright, including whether the incident falls inside the plan's cover dates. | | A purchase you do not recognise | The plan is bought through your own checkout, so it is an order on your store. Refund the plan line to cancel it. See [Helping a customer](/help/helping-a-customer#i-want-to-cancel-my-plan). | On the product registration page, your own form keeps its validation and CAPTCHA. If a registration looks wrong to you, email [support@surebright.com](mailto:support@surebright.com) with the order number before or after you refund it. ## Shoppers arriving from a post-purchase link Your post-purchase emails can send a customer to your storefront with their order in the link, such as `https://yourstore.com/?quoteLeadId=1234567890`. When they land: 1. A pop-up opens with the heading **Keep it protected with an extended warranty.**, your store logo, the eligible products from the order and their plan options, with offers that are still available listed first. Products that are already protected show **Warranty already purchased**. Nothing is shown if the order has no eligible items. 2. The shopper picks a plan and clicks **Protect My Purchase**, or dismisses with **No, thanks**. Choosing a plan adds it to the cart and sends them to the cart page. How to build the link and use it in your campaigns is on [Post-purchase offer links](/post-purchase/offer-links). The link can point at any page of your store. The home page (`/?quoteLeadId=...`) is the simplest. Make sure the SureBright Offering embed is on in your live theme, otherwise the pop-up cannot open. ## Related Build the link and use it in your own campaigns. How a plan bought later is linked to the product it covers. Turn on the SureBright Offering embed in your theme. Send the post-purchase link from your own Klaviyo flow. - **Page addresses.** The lookup appears on `/pages/extended-product-protection` or `/pages/product-extended-warranty`. The registration offer runs on `/pages/product-registration`. Other addresses are set up by SureBright on request. - **Placement.** Put `
` where the lookup should render. - **Cart behaviour.** A plan bought from these pages is its own cart line. It is not removed or quantity-matched when the cart has no matching product. If your theme edits cart lines, leave these alone. See [Cart sync](/frontend-widget-integration/frontend-widget-kit/cart-sync) and the line-item properties in the [JavaScript API reference](/frontend-widget-integration/frontend-widget-kit/javascript-injection).
**See also:** [Can someone buy a plan for a product they do not own](/shopify/admin-housekeeping#can-someone-buy-a-plan-for-a-product-they-do-not-own), [Tell your customers](/platforms/switching-to-surebright#tell-your-customers). --- # Storefront setup Source: https://docs.surebright.com/shopify/storefront-setup > Turn on the SureBright Offering app embed in your Shopify theme, confirm it is on from the Merchant Portal, and fix an offer that is not showing Shoppers see SureBright protection offers on your Shopify storefront once you switch on **SureBright Offering** in your theme. It is an app embed that comes with the **SureBright - Extended Warranty** app you installed. With it on in your live theme, the offer shows near **Add to cart** on product pages, in the cart, and in the other places you have set up with SureBright. The easy way is from the Merchant Portal. Under **Settings → Storefront setup**, the **Turn on in Shopify ↗** link next to each theme opens Shopify's theme editor on the right panel with SureBright already switched on, so all you do is click **Save**. The portal also tells you, theme by theme, whether it is on. Is your storefront headless, for example built on Hydrogen? There is no theme embed to switch on. See [Headless and Hydrogen](/shopify/headless-hydrogen). ## Turn SureBright on in your theme Go to **Settings** and find the **Storefront setup** section. It only appears for Shopify stores. Under **Protection on product pages**, every theme in your store is listed with its role (**Live theme**, **Not published** or **Development theme**) and a status badge. Click **Turn on in Shopify ↗** next to the theme you want. The Shopify theme editor opens with the SureBright Offering embed already selected. Make sure the **SureBright Offering** switch is on, then click **Save** in the top-right corner of the theme editor. Return to the Merchant Portal tab. It checks your themes again when you return (Shopify can report the save a few seconds late). You can also click **Check again**. Your **live theme** is the one shoppers see. Turning the embed on in an unpublished or development theme only affects previews of that theme. To confirm it works, open a product page in the theme editor preview. You should see the SureBright protection offer near the **Add to cart** button. ## What the status badges mean | Badge | Meaning | What you can do | | --- | --- | --- | | **Turned on** | SureBright Offering is on in that theme. | Nothing. To switch it off, click **Turn off in Shopify ↗**, which opens the theme editor's App embeds panel. | | **Not turned on** | The embed is available but off. | Click **Turn on in Shopify ↗**. The theme editor opens with the embed selected. | | **Can't check right now** | The portal could not read the theme from Shopify. | Click **Open in Shopify ↗** to look in the theme editor yourself, or try **Check again** in a moment. | Each theme has its own badge. There is no single on or off status for the whole store. ## Custom themes and page builders There is no separate SureBright block or snippet to add, whatever your theme is built with. The same steps work on a custom theme, a heavily edited theme, and product pages built in a page builder app: Follow [Turn SureBright on in your theme](#turn-surebright-on-in-your-theme) for the theme the pages belong to. Page builder pages use your theme's embed too. Email [support@surebright.com](mailto:support@surebright.com) with the URL of a product page built the new way, and say where the offer should sit, for example above **Add to cart**. Include bundle or landing pages if they are built differently. SureBright sets the offer's position for those pages on its side. Open the page, pick a different variant or option, and add the product with a plan. Check that the plan in the cart is for the product you picked. If it is not, send SureBright the URL and what you did. Do this again when you redesign a product page or move it to a page builder, because the offer's position was matched to the old page. See [After a theme or platform change](/platforms/after-a-theme-or-platform-change). ## Add protection to checkout (Shopify Plus) If your store is on Shopify Plus, the same **Storefront setup** section shows a second card, **Protection in checkout**, with one row: **SureBright Protection Block and Badge**. Click **Open checkout editor ↗** to add them. This row shows no status, because Shopify does not tell the portal whether the blocks are placed in your checkout. See [Checkout extensions](/shopify/checkout-extensions) for the full steps. ## Troubleshooting - In **Settings → Storefront setup**, check the badge next to your **Live theme**. If it says **Not turned on**, click **Turn on in Shopify ↗**, switch the embed on and **Save**. - If the embed is **Turned on** only in a theme marked **Not published** or **Development theme**, shoppers will not see it. Turn it on in the live theme as well. - If you recently saved in the theme editor, click **Check again**. Shopify can take a few seconds to report the change. - If the badge is right and the offer is still missing, work through [Offer not showing?](/help/offer-not-showing). The portal could not read your themes from Shopify. Click **Open in Shopify ↗** to see the App embeds panel directly, or try **Check again** later. If it persists, contact [support@surebright.com](mailto:support@surebright.com). Depending on how your store is set up, SureBright may run only on product, cart, collection and home pages, plus the page types SureBright has added for your store. Ask [support@surebright.com](mailto:support@surebright.com) to add the page type you need. The embed setting belongs to each theme. When you publish a new theme, check its badge in **Storefront setup** and turn the embed on there if needed. Stores set up before the app embed existed may have a SureBright script added to the theme. Load SureBright once: the **SureBright Offering** embed is the current way. Before you remove an older script or turn the embed on alongside it, ask [support@surebright.com](mailto:support@surebright.com) to check your store, so the offer does not disappear in between. See [Analytics and page speed](/merchant-portal/analytics-and-page-speed). Next to a theme with the **Turned on** badge, click **Turn off in Shopify ↗**. The theme editor's App embeds panel opens. Switch **SureBright Offering** off and **Save**. ## Related - [Checkout extensions (Shopify Plus)](/shopify/checkout-extensions): offer protection inside checkout. - [Shopify admin housekeeping](/shopify/admin-housekeeping): three Shopify settings that keep plans working. - [Shopify Help: App embeds](https://help.shopify.com/en/manual/online-store/themes/theme-structure/extend/apps#app-embeds): Shopify's own description of app embeds. The embed adds one script tag that loads the SureBright storefront SDK. Which SDK file loads, and on which page types, is set by SureBright for each store and is not something you set yourself. The SDK files and the page rules are listed in [SDK Installation](/frontend-widget-integration/frontend-widget-kit/sdk-installation). Three details that page does not carry: the script loads with `defer`; a page-type list applies only to the `v0`, `v1` and `v2` SDK files, and when no list is set for the store the SDK loads on every page; the Merchant Portal's default SDK version for a store is `v2`. --- # SureBright on Wix: FAQs Source: https://docs.surebright.com/wix/faq > Answers to common questions about SureBright on Wix: where the offer shows, plans in the cart, contracts, refunds, billing and claims. Answers to the questions Wix merchants ask most about the offer, the cart, orders, billing and claims. For setup, see [Install SureBright on Wix](/wix/install-guide). ## Your product page Wix places the SureBright offer just above **Add to Cart** on your product page when you install the app. To move it, open your site in the Wix Editor, go to the product page and drag the SureBright box. To remove it, select the box and delete it. Publish your site afterwards so shoppers see the change. Removing the box stops new plans being offered. Contracts already sold are not affected. Check that: - the product is set to **Active** in the merchant portal (**Products**) and has a SureBright category - the offer is turned on for your store - you published your site in the Wix Editor after installing SureBright - your store currency is USD or CAD No. **Buy Now** goes straight to checkout with the product alone. When your product page has Buy Now, the offer shows a short note: *Protection plans are added with Add to Cart (not with Buy Now).* SureBright offer above Add to Cart and Buy Now, with the note Protection plans are added with Add to Cart (not with Buy Now) No. Plans are not products in your Wix store, so there is nothing to add to your product list or inventory. ## The cart As its own line, for example *2 Year Protection Powered by SureBright*, at the price shown in the offer. The plan line has no **+** or **−** buttons: its quantity follows the product. To drop protection, the shopper removes the plan line with its bin. Wix side cart with 3 monitors and 2 Year Protection Powered by SureBright, quantity 3, $26.00 each, with no +/- buttons on the plan line The plan follows the product within a few seconds: more units get more plans, fewer units get fewer, and removing the product removes its plan. If the shopper clicks **Checkout** straight after a change, the button dims for a moment until the plan has caught up. Checkout also stops an order that has more plans than products, or a plan without its product. ## Orders and contracts When the order is paid. For a manual or offline payment, that is when you mark the order as paid in Wix. Each plan unit gets its own contract, so 2 tablets with 2 plans give 2 contracts. You don't need to do anything. Wix can take a few minutes to tell SureBright about an order. If SureBright can't finish an order straight away, it tries again on its own. Nothing is lost and no contract is created twice. Do it in your Wix dashboard as usual, and SureBright follows: | In Wix | Contracts | |---|---| | Refund a plan (all or some units) | That many contracts are cancelled | | Cancel the order | All of the order's contracts are cancelled | SureBright can't refund a Wix order for you. Refunds are always made in Wix. The price the customer actually paid for the product, after any sale price or coupon. SureBright charges the payment method you add in the merchant portal (**Billing**) for the plans sold on your store: each plan's price minus your margin. Plans that are refunded or cancelled are credited against your next charge. There is no setup fee or minimum, and every charge is under **Billing > Billing History**. See [Pricing, margins and invoices](/merchant-portal/how-billing-works). Directly with SureBright. You don't handle claims. After buying a plan, your customer receives the plan details from SureBright, including how to make a claim. They can claim any time through the SureBright customer portal, or by phone, email or chat. A paid plan always gets a contract. If something on the order needs a check, the contract is created but held, for example when the plan's price doesn't match the price offered, the order ships outside the US or Canada, or the covered product can't be found on the order. Held contracts show the reason in the merchant portal. --- # Install SureBright on Wix Source: https://docs.surebright.com/wix/install-guide > Install the SureBright app on your Wix store, sign in to the SureBright merchant portal, switch your products on and get protection plans showing on your product pages. SureBright for Wix is a single app. Install it, switch your products on in the Merchant Portal and publish your site, and shoppers see protection plans on your product pages. Installing it connects your Wix store to SureBright, copies your products so they can be quoted, and places the SureBright offer just above **Add to Cart**. Shoppers buy a plan together with the product, and every plan sold becomes a SureBright contract. The SureBright app for Wix is not listed in the Wix App Market yet. To install it now, ask your SureBright contact or [support@surebright.com](mailto:support@surebright.com) for the install link. The steps after the install are the same. ## Before you start | Requirement | Why | |---|---| | **Wix Stores** on your site | SureBright reads your products and orders from Wix Stores. A site without it stays in setup until Wix Stores is added. | | **Store currency in USD or CAD** | Plans are priced in US or Canadian dollars. Stores whose currency is anything else do not show the offer. If your store also sells in other currencies, shoppers see plan prices converted into the currency they pay in. | | **Customers in the US or Canada** | Plans cover products delivered to US and Canadian addresses. A plan on an order shipped anywhere else is held for review instead of becoming an active contract. | ## Install the app Install the **SureBright** app on your Wix site with the link from your SureBright contact. It is a single click, and there is nothing to configure in Wix. SureBright then creates your store, copies your products and places the protection offer on your product page. After the install, Wix opens your site in the Editor on the product page. The SureBright box sits just above **Add to Cart** and shows a preview of the offer with **sample plans and prices**. Real plans and prices only appear on your live site. The box also tells you how to finish setup: **click the box, then click Manage**. The Wix Editor on the product page with the SureBright box selected and its Manage button highlighted In the Editor, click the SureBright box, then **Manage**. The SureBright page opens in your Wix dashboard. Click **Open SureBright**: the SureBright merchant portal opens in a new tab, already signed in to your store. **Click here to activate products** on the same page opens the portal straight on Products. The SureBright page in the Wix dashboard with the Open SureBright button highlighted In the portal, open **Products** (1) and set **Warranty status** to **Active** (2) for each product you want to protect. Every product starts as **Inactive**. The merchant portal's Products page with Products in the menu and the Warranty status dropdown highlighted, numbered 1 and 2 You can reopen the SureBright page any time from **Apps** in your Wix dashboard, or with [this link](https://manage.wix.com/account/site-selector?actionUrl=https%3A%2F%2Fmanage.wix.com%2Fdashboard%2F%7BmetaSiteId%7D%2Fapp%2F34437ddf-6008-4e38-9988-395394e32b82). If it says **We're finishing setting up SureBright**, wait a moment. It refreshes on its own. Once you have signed in to the merchant portal, go back to the Editor tab and click **Publish** at the top right. Wix adds the SureBright offer to your site's design, and the design only goes live when you publish. Until you do, the offer does not appear on your live site. The Wix Editor with the Publish button at the top right highlighted The first person who opens SureBright from the Wix dashboard becomes the store's **Owner** in the merchant portal, so ask the site owner to open it first. Anyone else who opens it later gets their own access: **Admin** if they own the Wix site, otherwise a more limited role. ## Complete onboarding In the merchant portal, open **Billing** and click **Add Payment Method**. SureBright charges you for the protection plans sold on your store. The merchant portal's Billing page with the Add Payment Method button highlighted Make sure each product you switched on has a SureBright category. A product needs one to be quoted. New products and changes you make in Wix reach SureBright on their own, so you never need to re-sync. To change the offer's layout, colours or wording, open **Studio** in the portal and click **Open the studio**. The merchant portal's Studio page with the Open the studio button highlighted In SureBright, publish your design in **Studio** to turn the offer on (this is separate from publishing your site in the Wix Editor). If you can't open Studio yet, ask your SureBright account manager to turn it on. Then open an active product on your live site: the offer shows just above **Add to Cart**. If it does not, check that you published your site in the Wix Editor after installing SureBright. A live Wix product page with the SureBright Add Extended Warranty offer, 1, 2 and 3 year plans, highlighted above the Add to Cart button ## Next steps Your Wix store is connected to SureBright. Then: Where the offer shows, plans in the cart, contracts, refunds and cancellations. How to remove SureBright from your site, and what is kept. --- # Uninstall or reinstall SureBright on Wix Source: https://docs.surebright.com/wix/uninstall-and-reinstall > What happens when you remove the SureBright app from your Wix site, what is kept, and how a reinstall picks up where you left off. Removing the SureBright app stops new plans being offered and sold on your Wix site. Plans already sold stay in force, and SureBright keeps your store, settings and contracts, so a reinstall picks up where you left off. ## Removing the app SureBright has an element on your site (the offer on your product page), so Wix removes it from the **Editor**. If you start from **Apps > Manage Apps** in your Wix dashboard, Wix sends you to the Editor to finish. Open your site in the Wix Editor and click **Add Apps** in the left panel. The Wix Editor with the Add Apps button in the left panel highlighted In the panel that opens, click **Manage Apps** (1). Next to **SureBright Product Protection**, click the arrow (2), then **Delete app** (3). The Editor's Manage Apps panel: Manage Apps, the arrow next to SureBright Product Protection, and Delete app, highlighted and numbered 1 to 3 In the window that opens, choose a reason (1) and click **Delete App** (2). Wix's Delete SureBright Product Protection window with the reason list and the Delete App button highlighted, numbered 1 and 2 Click **Publish** so the removal goes live. When the app is removed: - **The offer stops showing** on your product pages, and shoppers can no longer add plans to their carts. - **Contracts already sold stay in force.** Your customers keep their cover and can still make claims. - **Your SureBright records are kept**: your store, products, settings, contracts and billing details. Nothing is deleted. - **SureBright stops reading your store.** It no longer receives your product changes or new orders. Orders placed after the app is removed are not sent to SureBright, so no contracts are created for them. If you only want to stop offering plans for a while, you do not need to remove the app. Ask your SureBright contact to switch the offer off for your store instead, or turn individual products off in the merchant portal. See [Pause or remove SureBright](/platforms/pause-or-remove). ## Reinstalling Install **SureBright** on the same Wix site again. SureBright recognises the site and picks up your existing store instead of creating a new one: Install **SureBright** on your site again, as you did the first time. SureBright reconnects your existing store, keeps your offer design and settings (including which products are switched on), and copies your products again so any changes you made while the app was removed are picked up. In the Editor, click the SureBright box, then **Manage** (or [open SureBright in your Wix dashboard](https://manage.wix.com/account/site-selector?actionUrl=https%3A%2F%2Fmanage.wix.com%2Fdashboard%2F%7BmetaSiteId%7D%2Fapp%2F34437ddf-6008-4e38-9988-395394e32b82)), and click **Open SureBright**. The first sign-in after a reinstall takes you through onboarding again, so you can check your payment method and products. Click **Publish** in the Editor. The offer only appears on your live site again once you publish. Your past contracts and reports are still in the merchant portal after a reinstall. --- # WooCommerce Source: https://docs.surebright.com/woocommerce/overview > Install the Surebright Product Protection Plan plugin for WordPress, see what shoppers get, set up the four order webhooks, and know what happens when you refund or delete an order. SureBright for WooCommerce is a WordPress plugin, **Surebright Product Protection Plan**, plus four order webhooks that you create in WooCommerce. The plugin shows the offer on your product and cart pages and adds the chosen plan to the cart. The webhooks are what turn the plans you sell into contracts. Use this page when you install the plugin or set up the webhooks with your SureBright contact. **Availability.** The WooCommerce plugin is in limited release. It is installed with help from your SureBright contact rather than from the WordPress plugin directory. Talk to us before planning a launch on WooCommerce. ## What you get on WooCommerce - A protection offer on product pages and on the cart page. - The chosen plan added to the WooCommerce cart and bought through checkout with the rest of the order. - A **Merchant Portal** page in your WordPress admin that signs you in to SureBright without separate credentials. - A contract for each plan sold, kept in step when you refund, delete or restore the order. ## What you need to do | Step | What you do | |---|---| | 1 | Install and activate the plugin, with help from your SureBright contact. | | 2 | Open the merchant portal from WordPress and complete the onboarding journey. | | 3 | Check that your products have a category. | | 4 | Create four order webhooks in WooCommerce. Until they exist, plans sold on your store do not become contracts. | ## Requirements | | | |---|---| | WordPress | 5.6 or later | | PHP | 7.2 or later | | WooCommerce | tested up to 5.6.0 | | Plugin version | 3.7.1 | ## Install the plugin Install the **Surebright Product Protection Plan** plugin in WordPress and activate it. Activation registers your store with SureBright. The plugin adds a **Merchant Portal** page to the WordPress admin menu with a **Login** button. It opens the SureBright [merchant portal](/merchant-portal/overview) signed in as your store, so you do not need separate credentials. Complete the onboarding journey there. Offers are based on the SureBright category on each product. Check [Products](/merchant-portal/products) and set the category on anything that is missing one. Create the four webhooks described under [Set up the four order webhooks](#set-up-the-four-order-webhooks). Until they exist, plans sold on your store do not become contracts. During onboarding SureBright creates the plan products in your WooCommerce catalogue, one per category you sell, so that a plan can be added to the cart and paid for like any other item. Leave these products as they are. ## What shoppers see on product and cart pages **Product pages.** Above the **Add to cart** button the shopper sees an **Add 2-Year Warranty** block with one tile per available term showing the added years and the price, with **Powered By SureBright** underneath. The information icon opens a popup headed **Don't want to spend extra on this product for the next few years?**, with the list of what the plan covers under **Your Warranty Plan Provides**, an **Add Warranty** button, **No Thanks**, and a link to the plan's terms. **Cart page.** Each cart item that qualifies gets an **Add Warranty for $price** link next to its name. Clicking it opens the **Add Extended Warranty** popup with the available plans and **Add Protection** / **No Thanks** buttons. Choosing a plan adds it to the WooCommerce cart without reloading the page. The plan then goes through checkout with the rest of the order. ## Set up the four order webhooks Create the webhooks in **WooCommerce > Settings > Advanced > Webhooks**, one per topic. For each one: - Choose the topic from the table. - Enter the delivery URL: the host your SureBright contact gives you, followed by the path from the table. - Enter the **Secret** your SureBright contact provides, exactly as given. With any other secret, plans do not become contracts. - Set it to **Active** and to the WP REST API v3 payload. | Topic | Delivery URL path | What it does for you | |---|---|---| | **Order created** (`order.created`) | `/partner/api/v1/webhook/woocommerce/order/create` | The plans on a new order become contracts, each for the product it covers. | | **Order updated** (`order.updated`) | `/partner/api/v1/webhook/woocommerce/order/update` | Refunded plan quantities cancel the matching contracts, and changed customer details reach the contract. | | **Order deleted** (`order.deleted`) | `/partner/api/v1/webhook/woocommerce/order/delete` | The order's contracts are cancelled. | | **Order restored** (`order.restored`) | `/partner/api/v1/webhook/woocommerce/order/restore` | Contracts cancelled by the delete are reinstated. | WooCommerce disables a webhook after repeated delivery failures. If plans stop turning into contracts, open **WooCommerce > Settings > Advanced > Webhooks** and check that all four are still **Active**. Two things to know once the webhooks are running: - **Keep your site URL the same.** SureBright recognises your store by the URL of your WordPress site, which must match the store SureBright registered. If you move domains, tell your SureBright contact before the webhooks start failing. - **A successful delivery is not always a contract.** If an order is missing something SureBright needs (for example a line price that is not a number), WooCommerce still shows the delivery as successful. SureBright reviews the gap itself. ## Questions about the webhooks | Question | Answer | |---|---| | Which orders become contracts? | Orders whose status is **Processing** or **Completed**. An order that is **Pending payment**, **On hold** or **Failed** is noted, and its contracts are created when the order moves to **Processing** or **Completed**. That move arrives through **Order updated**, so keep that webhook on even if most of your orders are created already paid. | | Do partial refunds count? | Yes. A refund on an order arrives through **Order updated**, and the refunded plan quantities are cancelled. | | Can a repeated delivery create a second contract? | No. WooCommerce sometimes delivers the same webhook twice, or you may redeliver one by hand. SureBright recognises an order it has already handled and does not create its contracts again. | | Can I delete **Order deleted** and **Order restored** because they never fire? | Keep them. They only fire when you delete or restore an order, which may be rare. Without them, plans on a deleted order stay active and you are billed for them. | | Can I change the payload or API version? | Keep the WP REST API v3 payload on all four. | ## Refund, delete or restore an order | You do this in WooCommerce | What happens to the plan | |---|---| | Refund a plan line | The contracts for the refunded quantity are cancelled. | | Refund the covered product but leave the plan on the order | The sale shows in **Order Resolution** as a product-refunded case. See [Why a contract is on hold](/contracts/holds). | | Change the customer's details on the order | The contract is updated. | | Delete the order | The order's contracts are cancelled. | | Restore a deleted order | The contracts cancelled by the delete are reinstated. | ## Find your contracts in the merchant portal Contracts show under **Recent Sales** on the portal's [Sales](/merchant-portal/sales) page. A contract can appear a short while after the order. Plans SureBright could not pair with a product appear in **Order Resolution**. ## Related - [Products](/merchant-portal/products) - [Sales](/merchant-portal/sales) - [Why a contract is on hold](/contracts/holds) - [Test your setup](/platforms/test-your-setup) ---