Skip to main content

Setting up Cashback Offers on a headless storefront

Connect cashback opt-ins and cart attribution on a Hydrogen or custom storefront, and understand checkout estimation requirements.

Written by Stuart Chaney

Introduction

You can connect Cashback Offers to a Hydrogen or custom storefront by capturing the customer’s opt-in and carrying the offer details through the cart to the order. You create and manage the offer in Rivo as usual.
​

Your custom storefront needs to handle the steps normally performed by Rivo’s theme integration. Cashback estimation is a separate checkout operation: its endpoint requires a Shopify checkout session token, so you cannot call it with the storefront token used for opt-ins.


​
​

Before You Begin

  • Have Rivo Plus with Developer Toolkit access. In Settings > Developer Toolkit, set up your REST API key and enable the JavaScript API and Metafields for your wider headless integration. Keep REST API keys on your server.

  • Ask your Rivo account manager or support to confirm Cashback availability for your store and enable headless storefront API access.

  • Request a storefront API token and have your store’s myshopify.com domain allowlisted for headless authentication. The opt-in endpoint uses this storefront token, not the Merchant REST API key generated in Developer Toolkit.

  • Give support your custom storefront URL as well as your myshopify.com domain so they can confirm your setup.

For general integration setup, see Guide to using Rivo with Shopify Hydrogen Headless setups. For key management, see Manage API keys.


​
​

1. Create and Activate Your Offer

  1. In Rivo, go to Programs > Cashback > Offers and select New Cashback Offer.

  2. Set the offer name, identifier, Shopify customer segment, and holding period.

  3. Configure the offer’s earning rule to set the cashback amount.

  4. Set the offer to Active for an end-to-end test and launch. Make sure Cashback Program Status is enabled under Programs > Cashback > Settings.

Use the offer’s Identifier in your API request and cart attributes. This is the value in the Cashback URL, not the offer’s name or numeric ID. A campaign URL on its own does not implement opt-in handling in your custom storefront.
​

See Cashback Offers for the standard offer settings and approval flow.


​
​

2. Capture the Customer’s Opt-In

Send a JSON request to:
​

POST https://loyalty-api.rivo.io/api/cashback_opt_ins?shop=example.myshopify.com
​

Use these headers:

  • Authorization: Bearer YOUR_STOREFRONT_API_TOKEN

  • Content-Type: application/json

Example request body:

{  "visitor_token": "YOUR_VISITOR_TOKEN",  "visit_token": "YOUR_VISIT_TOKEN",  "cashback_offer": "YOUR_OFFER_IDENTIFIER",  "email": "[email protected]"}

  • visitor_token: Use a distinct token for this visitor and keep it consistent when retrying their opt-in.

  • visit_token: The token for this visit. Carry the same value into the cart.

  • cashback_offer: The offer’s identifier from Rivo.

  • email: The customer’s email, if available.

  • logged_in_customer_id: You can also supply the authenticated customer’s numeric Shopify customer ID. Only supply an ID verified through your own customer sign-in flow.

A captured opt-in returns an id and success: true. Save that returned ID for the cart attribution step. Retrying the same visitor and offer can return the existing opt-in ID.
​

Check for the returned id, not just HTTP 200 or success: true. If the cashback program is disabled or the offer identifier is missing or unknown, the endpoint can return success: true without an ID. Do not treat that response as a completed opt-in.


​
​

3. Carry Cashback Attribution Through the Cart

After receiving the opt-in ID, save these attributes on the Shopify cart that the customer will use for checkout. Preserve any existing cart attributes.

Cart attribute

Value

_rivo_visitor_token

The same visitor_token sent with the opt-in

_rivo_visit_token

The same visit_token sent with the opt-in

_rivo_cashback_offer

The offer identifier sent as cashback_offer

_rivo_cashback_opt_in_id

The id returned by the opt-in endpoint

Use your headless cart integration to write these values. Wait for the cart update to succeed before sending the customer to checkout, and verify that the completed order retains the attribution.
​

On a theme storefront, Rivo’s storefront script captures the opt-in and adds these attributes automatically. Your custom storefront must provide this behavior. The checkout cashback display reads the cart attribution; it does not replace this step.
​

Saving the opt-in alone is not enough. Rivo uses the order’s offer attribution when selecting the cashback offer, and the customer must meet the offer’s eligibility rules. An opt-in is not a promise of credit.


​
​

4. Handle Cashback Estimates in the Correct Context

The checkout estimation endpoint is:
​

POST https://loyalty-api.rivo.io/api/checkout/cashback_estimation
​

This endpoint requires a valid Shopify checkout session token in the Bearer header. A storefront API token or Merchant REST API key does not authenticate it. Rivo’s checkout cashback extension obtains that session token within Shopify checkout.
​

For a custom integration running inside Shopify checkout, the request includes:

  • order: Checkout totals using subtotal_price, total_discounts, total_tax, and total_shipping.

  • order.cart_attributes: An array of { "key": "...", "value": "..." } entries, including _rivo_cashback_offer with the offer identifier.

  • order.checkout_line_items: Checkout lines, including quantity, merchandise.product.id, and cost.totalAmount.amount, for product-aware calculations.

  • cart_currency_code: The checkout currency code.

  • customer_email: The checkout customer’s email, when available.

A calculated response includes success, cashback, cashback_formatted, and cashback_offer_identifier. Some responses return zero cashback or success: false without the formatted fields, so handle those cases before displaying an amount. Estimates do not guarantee final eligibility or credit approval.
​

If you need to show an estimate on the headless storefront before Shopify checkout, contact your account manager or support to confirm the supported approach for your build. Do not use the checkout endpoint with your storefront token or present an unverified calculation as guaranteed cashback.
​

A headless storefront and Shopify checkout are separate integration surfaces. Confirm your checkout extension setup with support rather than assuming that using Hydrogen makes checkout extensions unavailable.


​
​

5. Test Before Launch

Use a test customer and a qualifying order to check the complete journey:

  1. The opt-in request returns an id.

  2. The checkout cart contains all four attribution attributes with matching values.

  3. The completed order retains the cashback attribution.

  4. The customer meets the configured Shopify segment and offer conditions.

  5. The opt-in and order appear in Rivo’s cashback activity, and credit follows the configured approval and holding-period rules.


​

Troubleshooting

The opt-in request returns 401 or 403.
​

Confirm that you are using a storefront API token for the correct store, that shop is the matching myshopify.com domain, and that support has enabled and allowlisted headless access.
​

The opt-in request succeeds but returns no ID.
​

Check that the cashback program is enabled and that cashback_offer exactly matches an existing offer identifier.
​

The opt-in exists, but cashback is missing from the order.
​

Check the cart-to-order attribution first, then the offer’s customer segment, earning rule, and approval conditions. Keep the opt-in response ID and test order details when contacting support.
​

The estimate request fails with my storefront token.
​

The estimation endpoint requires a Shopify checkout session token. Contact support for guidance on estimates outside Shopify checkout.

Related Articles
Did this answer your question?