Integrate Loyalty with a custom or headless store

Use this guide when your store runs on a custom-built platform, or on one without a Yotpo Loyalty integration. Every step runs on your server and uses your GUID and API key (see Authentication). Never call the API from the browser.

📘
Before you start

Set up your earning campaigns and redemption options in the Loyalty admin.

Test on a separate store first. See Testing your integration.

Step 1: Send customers

Send customers with Create/Update Customer Records when they create an account or their details change. Use your platform's customer ID as id; the other endpoints take the same value as customer_id.

Set opted_in to true when a customer joins the program.
Send tags if campaigns include or exclude customers by tag.
Sending customers is also what rewards account creation.

Step 2: Load coupon codes for your rewards

Without a platform integration, Loyalty can't create discount codes in your store. Create the codes in your platform instead, then load them into each coupon redemption option, either in the Loyalty admin or with Upload Coupon Codes. Each time a customer redeems that option, they get the next unused code.

Create a separate set of codes for each reward, such as $5 off and $10 off. Upload enough to cover your expected redemptions, and add more before they run out.

Step 3: Send orders

After each purchase, send the order from your server with Create Order. Points are awarded asynchronously against your active campaigns.

What earns points: points are based on total_amount_cents. Send the total with or without shipping and taxes, depending on what you want customers to earn on.
Product rules: include items if any campaign is limited to certain products or collections.
Customer rules: include the customer object (with tags) if campaigns include or exclude customers by tag.
Discounts: send the codes used on the order in coupon_code.

Customers can redeem points in two ways:

Explicitly: redeem with Create Redemption and show the customer the coupon code. Points are deducted right away.
At checkout: redeem with delay_points_deduction: true and apply the code to the cart for the customer. Points are deducted only when the code is used, so a customer who changes their mind or abandons the cart keeps their points.

You can also use the order status to separate deducting the points used for a discount (for example when the order is paid) from awarding points for the purchase (for example after it ships). Set which statuses do what in your Loyalty admin settings.

Step 4: Send refunds

When an order is refunded, send it with Create Refund, using the order_id you sent in step 3. The points the refund amount earned are deducted. Include items if campaigns depend on specific products.

Step 5: Show points and rewards in your storefront

Fetch the data on your server and render it in your own UI:

Balance, tier and history: Fetch Customer Details, with with_history=true for point history.
Ways to earn: Get Active Campaigns, with with_status=true and the customer for their progress on each campaign.
Rewards they can redeem: Fetch Active Redemption Options with the customer's email.
Points a product earns: Product Potential Points (v3.0).

Next steps

Pick the features you want to build in What you can build.
Handle errors and retries safely with Errors. A retried redemption or point adjustment deducts or awards points twice.
Run the go-live checklist in Testing your integration.