Third Party Checkout Provider Integration Guide

IMPORTANT: This guide is only applicable for checkout providers in Shopify platform

Overview

When a customer reaches your checkout, this integration lets you show them three things from Yuko — in real time:

What the customer sees / does	API endpoint
Their current points balance	`GET /customers/rewards/redeemable`
Rewards available to redeem right now	`GET /customers/rewards/redeemable`
Spend their points to get a discount code or store credit	`POST /customers/rewards/redeem`
Points they will earn on this purchase	`POST /points/estimate`

Three API calls. One seamless checkout experience.

How it works

Customer reaches checkout
        │
        ▼
Your checkout identifies the customer
(Shopify Customer ID is required for Endpoints 1 & 3)
        │
        ├─────────────────────────────────────────────┐
        ▼                                             ▼
  API Call #1                                  API Call #2
  GET /customers/rewards/redeemable            POST /points/estimate
  Requires Shopify Customer ID                 No customer ID needed       
  Only for logged-in customers                 Works for guests too
        │                                             │
        ▼                                             ▼
  Returns:                                     Returns:
  · Points balance                             · Points earned on this cart
  · Rewards available to redeem
  · Rewards already issued (codes)
        │                                             │
        └────────────────┬────────────────────────────┘
                         ▼
          Your checkout UI renders:
          "You have 650 points"
          "Redeem: $5 off (costs 500 pts)"   ← customer clicks this
          "Unused coupon: YUKO-TVJ-BL1"
          "You'll earn 120 points on this order"
                         │
          Customer clicks "Redeem" on a reward
                         │
                         ▼
                   API Call #3
                   POST /customers/rewards/redeem
                   Sends: customer_id + reward_id
                         │
                         ▼
                   Returns:
                   · New discount code (e.g. YUKO-ABC-123)
                   · Points deducted
                   · Expiry date
                         │
                         ▼
          Your checkout applies the discount code
          Customer completes purchase

All Yuko API calls must be made from your backend server — never directly from the customer’s browser. See Security Rules for details.

Before you start

What the merchant needs to do

The merchant must have Yuko installed on their Shopify store. Once installed:

Open Shopify Admin

Go to the merchant’s Shopify Admin Dashboard.

Open Yuko

Click Apps → Yuko Loyalty.

Go to API settings

Navigate to Integrations → REST API and click Create new key.

Create an API token

Choose Custom Key and give the key Read/Write Access on Rewards (write:rewards, needed to redeem) and Read Access on Points (read:points, needed for the estimate).

Share the API key

Copy the API key and share it securely with your team. It looks like this:

py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Each merchant generates their own API key. If you are integrating across multiple merchants, each one will have a different key.

What your team needs

The customer’s Shopify Customer ID at checkout time — required for Endpoint 1, only available when the customer is logged in
Shopify Product IDs and Variant IDs for every item in the cart — required for Endpoint 2

Authentication

Yuko uses Bearer Token Authentication. Every API request must include the merchant’s API key in the Authorization header.

Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

This header is required on every single request — no exceptions.

Full authentication details are in the Authentication reference.

Base URL

All Yuko API requests start with:

https://api.yukoapp.com/api/v1/public

General rules

Always use HTTPS
Always set Content-Type: application/json on POST requests
All responses are JSON
Successful responses wrap data inside a "data" key
Error responses include an "error" object with code and message

See the API Introduction for a full overview of request and response formats.

Endpoint 1: Get points balance and redeemable rewards

This is the primary endpoint for your checkout loyalty panel. One call returns everything:

The customer’s current points balance
All rewards they can redeem (with a flag showing if they have enough points for each)
Rewards already issued to the customer (with their discount codes and status)

/customers/rewards/redeemable is a single endpoint that covers both the points balance and the full rewards list. You do not need a separate “get balance” call.

Full API reference → GET /customers/rewards/redeemable

Request

GET https://api.yukoapp.com/api/v1/public/customers/rewards/redeemable

Requires the read:rewards scope (or write:rewards). The merchant configures this in Shopify Admin → Apps → Yuko Loyalty → Integrations → REST API. See Scopes.

Query parameters

string

required

The Shopify Customer ID of the logged-in customer, for example 9049402769586. This is mandatory — do not call this endpoint for guest checkouts.

Example request

curl --request GET \
  --url "https://api.yukoapp.com/api/v1/public/customers/rewards/redeemable?customer_id=9049402769586" \
  --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Example response

200

{
  "data": {
    "points_balance": 650,
    "rewards": [
      {
        "id": "90424fa7-e8a9-4ef4-b43a-72c9b2028db5",
        "name": "$5 off your next order",
        "description": "Redeem 500 points for a $5 discount.",
        "reward_type": "fixed",
        "points_cost": 500,
        "reward_rule": {
          "points_required": 500,
          "value": 5
        },
        "icon": null,
        "can_redeem": true,
        "points_needed": 0
      },
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "10% off your next order",
        "description": "Redeem 1000 points for 10% off.",
        "reward_type": "percentage",
        "points_cost": 1000,
        "reward_rule": {
          "points_required": 1000,
          "value": 10
        },
        "icon": null,
        "can_redeem": false,
        "points_needed": 350
      }
    ],
    "customer_rewards": [
      {
        "id": "1fd80ced-326f-4082-951b-21a38632a603",
        "customer_id": "63a2c89a-9936-4bc0-9d5f-93db46110b76",
        "reward_id": "90424fa7-e8a9-4ef4-b43a-72c9b2028db5",
        "reward_type": "fixed",
        "status": "active",
        "discount_code": "YUKO-TVJ-BL1",
        "points_used": 500,
        "expires_at": "2026-06-01T00:00:00+00:00",
        "used_at": null,
        "created_at": "2026-02-15T08:30:00+00:00"
      }
    ]
  }
}

Response fields

object

Show data properties

integer

The customer’s current redeemable points balance. Always 0 for customers who are excluded (banned) from the loyalty program. Display this prominently at the top of your loyalty panel.

object[]

All active rewards for the online store (point-of-sale rewards are excluded), enriched with affordability data for this specific customer.

Show reward properties

string<uuid>

Unique ID of the reward.

string

The reward name to display to the customer.

string | null

Optional longer description of the reward.

enum<string>

The type of reward. One of fixed, percentage, free_shipping, free_product, store_credit.

integer

How many points the customer must spend to redeem this reward (taken from reward_rule.points_required).

object

The reward configuration, returned as stored. Structure varies by reward_type. Every reward includes points_required; fixed, percentage and store_credit rewards include value (the amount, percentage or credit amount).

object | null

The reward’s icon, or null if none is set. Contains source (default or custom), slug, id and url.

boolean

true if the customer has enough points. false if not.

integer

How many more points the customer needs. Always 0 when can_redeem is true.

object[]

Every reward already issued to the customer, newest first, in any status (including used and expired ones) and from any source (points redemptions as well as VIP tier, referral and membership rewards, so reward_id isn’t always a catalogue reward ID). Filter on status === "active" to find codes the customer can still apply. Each item is a Customer Reward Object.

Show customer reward properties

string | null

The actual coupon code (e.g. YUKO-TVJ-BL1). This is a standard Shopify discount code — pass it directly through your checkout discount flow.

enum<string>

Current status. Only show coupons where status === "active". One of active, used, inactive, expired, deleted, revert.

string<date-time> | null

When this coupon expires. null means no expiry.

string<date-time> | null

null if the coupon has not been used yet.

integer

How many points were spent to create this coupon.

Display logic

If points_balance > 0:
  Show: "You have {points_balance} points"

For each reward in rewards[]:
  If can_redeem === true  → Show active "Redeem" button: "{name} — {points_cost} pts"
  If can_redeem === false → Show greyed out: "{name} — earn {points_needed} more points"

For each item in customer_rewards[] where status === "active":
  Show: "You have an unused reward: {discount_code}"

Endpoint 2: Points estimate at checkout

This endpoint tells the customer how many loyalty points they will earn when they complete this purchase. No Shopify Customer ID is required (you still need the API key), so it works for both logged-in customers and guests.

The request carries product and variant IDs only, with no prices or quantities, so the cart amount Yuko calculates with is always 0. As a result the endpoint currently returns points_earned: 0 for every request. With the display logic below, the earn message stays hidden. Confirm it returns non-zero values for the merchant’s earn rules before you rely on it.

Full API reference → POST /points/estimate

Requires the read:points scope. See Scopes.

Request

POST https://api.yukoapp.com/api/v1/public/points/estimate

Request body

object

Optional. Include only if the customer is logged in. Omit entirely for guest checkouts. If you send it, include at least id or email.

Show customer properties

string

Shopify Customer ID. Used to look up the customer if email is not provided.

string

Customer email address. Takes priority over id when both are provided; if no customer matches the email, id isn’t tried.

object[]

required

The line items in the cart. Must contain at least one item.

Show item properties

string

required

The Shopify Product ID.

string

required

The Shopify Variant/SKU ID.

Example request: logged-in customer

curl --request POST \
  --url "https://api.yukoapp.com/api/v1/public/points/estimate" \
  --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{
    "customer": {
      "id": "9049402769586",
      "email": "rahul.sharma@example.com"
    },
    "items": [
      {
        "product_id": "prod_1001",
        "variant_id": "var_1001_red_m"
      },
      {
        "product_id": "prod_2044",
        "variant_id": "var_2044_black_42"
      }
    ]
  }'

Example request: guest checkout

curl --request POST \
  --url "https://api.yukoapp.com/api/v1/public/points/estimate" \
  --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{
    "items": [
      {
        "product_id": "prod_1001",
        "variant_id": "var_1001_red_m"
      }
    ]
  }'

Example response

200

{
  "data": {
    "points_earned": 0,
    "message": "You will earn 0 points after completing this purchase"
  }
}

Response fields

object

Show data properties

integer

The number of loyalty points the customer will earn after completing the purchase. Currently always 0 (see the warning above).

string

A ready-to-display string. You can show this directly in your UI without additional formatting. The message is always returned, even when points_earned is 0, so check points_earned before showing it.

Display logic

If points_earned > 0:
  Show the message field directly in your UI

If points_earned === 0:
  Hide this section entirely — never show "You will earn 0 points"

Endpoint 3: Redeem a reward (burn points)

This is the endpoint your checkout calls when a customer actively chooses to spend their points on a reward. When the customer clicks “Redeem” on an available reward, call this endpoint. Yuko will:

Deduct the required points from the customer’s balance
Generate a fresh Shopify discount code for that reward
Return the discount code so you can apply it to the order

This endpoint is triggered by a customer action — not automatically at checkout load. Only call it when the customer explicitly clicks “Redeem” on a reward option.

The request has no points amount, so only rewards with a fixed points cost can be redeemed here. A reward whose reward_rule.method is increment (customer chooses how many points to spend) always fails with Insufficient points balance, even when can_redeem is true. Hide the Redeem button for those rewards.

Full API reference → POST /customers/rewards/redeem

Requires the write:rewards scope. Read-only keys can’t redeem. See Scopes.

Request

POST https://api.yukoapp.com/api/v1/public/customers/rewards/redeem

Required headers

Header	Value
`Authorization`	`Bearer YOUR_API_KEY`
`Content-Type`	`application/json`

Request body

string

required

The Shopify Customer ID of the logged-in customer.

string<uuid>

required

The UUID of the reward the customer wants to redeem. Get this from the rewards[].id field in the Endpoint 1 response (GET /customers/rewards/redeemable).

Example request

curl --request POST \
  --url "https://api.yukoapp.com/api/v1/public/customers/rewards/redeem" \
  --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{
    "customer_id": "9049402769586",
    "reward_id": "90424fa7-e8a9-4ef4-b43a-72c9b2028db5"
  }'

The reward_id comes directly from the rewards[].id field in the Endpoint 1 response. Store these IDs when you render the rewards list so you have them ready when the customer clicks “Redeem”.

Example response

A 201 Created status means the redemption was successful and a new coupon code has been generated.

201

{
  "data": {
    "coupon_code": "YUKO-TVJ-BL1",
    "points_spent": 500,
    "reward_type": "fixed",
    "discount_value": 5,
    "expires_at": "2026-06-01T00:00:00+00:00"
  }
}

Response fields

object

Show data properties

string | null

The newly generated Shopify discount code (e.g. YUKO-TVJ-BL1). Apply this directly through your checkout’s discount flow. null for store_credit reward types — the credit is added to the customer’s account automatically.

integer

The number of points deducted from the customer’s balance.

enum<string>

The type of reward that was redeemed. One of fixed, percentage, free_shipping, free_product, store_credit.

number

The discount amount or percentage associated with the coupon.

For fixed: this is the amount in the store’s currency (e.g. 5 means 5 off)
For percentage: this is the percentage (e.g. 10 means 10% off)
For free_product: the free product’s price, or 0 if it isn’t known
0 for free_shipping and store_credit reward types

string<date-time> | null

When the generated coupon expires. null if the reward has no expiry, and always null for store_credit rewards.

Errors

Code	Scenario	What to do
`422`	Customer doesn’t have enough points (`redemption_failed`, `Insufficient points balance`)	This shouldn’t happen if you used `can_redeem` from Endpoint 1 correctly. Show the customer a message: “You don’t have enough points for this reward.”
`422`	Reward not found or is inactive (`redemption_failed`, `Reward not found or inactive`)	The reward may have been deactivated by the merchant. Refresh the rewards list by calling Endpoint 1 again.
`422`	Customer is excluded from the loyalty program (`Customer banned`), or loyalty is turned off (`Loyalty not enabled`) (`redemption_failed`)	Hide the loyalty panel.
`422`	The discount or store credit couldn’t be created on Shopify (`redemption_failed`, e.g. `Failed to generate platform coupon`)	Show a generic error and let the customer retry or continue without the reward.
`422`	`customer_id` or `reward_id` missing, or `reward_id` isn’t a UUID (`validation_error`)	Fix the request body.
`404`	Customer not found	The `customer_id` is not in Yuko.
`401`	Invalid API key	Check the `Authorization` header.

Display logic after a successful redemption

On successful 201 response:

1. Show the customer their new discount code:
   "Your reward is ready! Code: {coupon_code}"

2. Auto-apply the discount code to the order if your checkout supports it

3. Update the displayed points balance:
   New balance = old points_balance - points_spent

4. Remove the redeemed reward from the "available rewards" list in your UI

After a successful redemption, the customer’s points balance has decreased. If you have the old balance cached, subtract points_spent from it to show the updated balance without making another API call.

Full checkout flow

Collect what you need at checkout

Shopify Customer ID — only if the customer is logged in (needed for Endpoint 1)
Product IDs and Variant IDs for every item in the cart (needed for Endpoint 2)

Decide which endpoints to call

Customer state	Call Endpoint 1?	Call Endpoint 2?	Call Endpoint 3?
Logged in, Shopify Customer ID available	✅ Yes	✅ Yes — include `customer` field	✅ Yes — when customer clicks “Redeem”
Guest checkout	❌ No — skip	✅ Yes — omit `customer` field	❌ No — guests can’t redeem points

Fire both calls in parallel

Do not wait for one to finish before starting the other. Running them in parallel keeps checkout fast.

# Call 1 — Only if the customer is logged in
curl --request GET \
  --url "https://api.yukoapp.com/api/v1/public/customers/rewards/redeemable?customer_id=9049402769586" \
  --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Call 2 — Always run this, for both logged-in and guest customers
curl --request POST \
  --url "https://api.yukoapp.com/api/v1/public/points/estimate" \
  --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{
    "customer": {
      "id": "9049402769586"
    },
    "items": [
      {
        "product_id": "prod_1001",
        "variant_id": "var_1001_red_m"
      }
    ]
  }'

Render the loyalty panel

Combine both responses to display the loyalty section. This is only an example; adapt it to your UI.

┌──────────────────────────────────────────────┐
│  🏆  Your Rewards                            │
│                                              │
│  Points Balance: 650 pts                     │
│                                              │
│  ✅  $5 off your next order                 │
│      Costs 500 pts              [Redeem →]  │
│                                              │
│  🔒  10% off your next order                │
│      Earn 350 more points to unlock          │
│                                              │
│  🎟️  You have an unused coupon              │
│      YUKO-TVJ-BL1          [Apply to order] │
│                                              │
│  💰  You'll earn 120 points on this order!  │
└──────────────────────────────────────────────┘

Handle the Redeem button click

When a customer clicks “Redeem” on an available reward, call Endpoint 3 with their customer_id and the reward_id of the reward they selected.

curl --request POST \
  --url "https://api.yukoapp.com/api/v1/public/customers/rewards/redeem" \
  --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{
    "customer_id": "9049402769586",
    "reward_id": "90424fa7-e8a9-4ef4-b43a-72c9b2028db5"
  }'

On a 201 response:

Take the coupon_code from the response and apply it to the checkout order
Update the displayed points balance: new_balance = old_balance - points_spent
Remove the redeemed reward from the UI rewards list

The reward_id is the id field from the rewards[] array in the Endpoint 1 response. You should store these IDs when you render the rewards list so they’re ready when the customer clicks.

Error handling

The loyalty panel is an enhancement to checkout — it must never block or break the purchase. If any Yuko API call fails, hide the loyalty panel silently and let checkout continue.

Full list of error codes → Errors reference

HTTP status codes

Code	Meaning	What to do
`200`	Success	Use the response data
`401`	Unauthorized — API key missing or incorrect	Check the `Authorization` header and key value
`403`	Forbidden — token missing the right scope (`insufficient_scope`)	Ask the merchant to create a key with `write:rewards` and `read:points`
`404`	Customer not found	The `customer_id` doesn’t exist in Yuko — hide the panel silently
`422`	Validation error (`validation_error`) or failed redemption (`redemption_failed`)	Check the `message` field in the response
`429`	Rate limit exceeded	Wait 1 second and retry once — see Rate Limits
`500`	Yuko internal error	Retry once. If it persists, hide the panel and let checkout continue.

Error response format

All error responses from Yuko return an error object with a code and a message:

{
  "error": {
    "code": "not_found",
    "message": "Customer not found"
  }
}

Recommended handling pattern

401 → Log the error. Hide the loyalty panel.
404 → Customer has no Yuko account yet (common for new customers). Hide silently.
429 → Wait 1 second. Retry the same request once.
5xx → Retry once after a short delay. If it fails again, hide the panel.
Any other error → Hide the loyalty panel. Never block checkout.

Rate limits

See full details → Rate Limits reference

Limit	Value
Requests per second (per API token)	10
Error when exceeded	HTTP `429 Too Many Requests`
Reset interval	1 second

Cache the rewards list. The rewards[] catalogue changes infrequently — you can cache it for 5–15 minutes. The points_balance and customer_rewards[] are customer-specific and should be fetched fresh each checkout session.

Don’t poll. Call both endpoints once when the customer arrives at checkout.
Retry with a delay. On a 429, wait 1 second and retry once. Never retry immediately.

Security rules

These rules are not optional. Violating them exposes the merchant’s API key and puts their store at risk.

Rule 1: Never expose the API key on the frontend

The key is a secret. It must only ever live on your backend server.

❌ Never put it in browser-side JavaScript
❌ Never put it in a mobile app binary
❌ Never commit it to a public code repository
✅ Make all Yuko API calls from your backend — pass only the results to your frontend

Rule 2: Use HTTPS everywhere

Always send requests to the https:// base URL so the API key is never sent unencrypted.

Authentication setup options

Choose whichever approach fits your architecture.

Token-Based (Easy Quick Start)
OAuth-Based (Recommended)

This is the simplest approach. No OAuth flow required.How it works:

Merchant generates a token

The merchant goes to Shopify Admin → Apps → Yuko Loyalty → Integrations → REST API and creates a Custom Key with write:rewards and read:points.

Merchant shares the token

The merchant copies the token and pastes it into your checkout platform’s merchant settings.

Your backend uses the token

Your backend reads the token from your settings and includes it in every Yuko API request for that merchant.

Pros: Fast to set up. No OAuth flow required.
Cons: The merchant must manually copy-paste the token. If they regenerate it, it needs to be updated on your side.

This gives merchants a one-click Connect Yuko button inside your checkout dashboard — no manual copy-pasting.How it works:

Add a Connect button

Add a “Connect Yuko” button in your merchant dashboard settings.

Redirect to Yuko

When the merchant clicks it, redirect them to Yuko’s OAuth authorization page.

Merchant approves

The merchant reviews and approves the connection inside Yuko.

Exchange the code

Yuko redirects back to your platform with an authorization code. Your backend exchanges this code for an access token.

Store and use

Store the token securely. Use it for all Yuko API calls for that merchant going forward.

Integration can be initiated from either side:

Initiated by	Description
Your checkout platform	You add the “Connect to Yuko” button. The merchant clicks it from your dashboard.
Yuko	Yuko lists your platform as an option. The merchant connects from inside their Yuko settings.

To get started with OAuth, contact the Yuko team to receive your OAuth client credentials (client ID and client secret) and configure your redirect URI → Book a call

Testing

Get a test API key

Contact the Yuko team for a test key, or use a real merchant’s key on a development Shopify store.

Verify authentication

curl --request GET \
  --url "https://api.yukoapp.com/api/v1/public/customers/rewards/redeemable?customer_id=9049402769586" \
  --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Expected: HTTP 200 with data.points_balance in the response body.
If you get HTTP 401, the API key is wrong — check for extra spaces or incorrect values.

Test Endpoint 1 with a real customer

curl --request GET \
  --url "https://api.yukoapp.com/api/v1/public/customers/rewards/redeemable?customer_id=REAL_CUSTOMER_ID" \
  --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Verify:

points_balance returns a number
rewards[] is populated with the merchant’s reward options
can_redeem correctly reflects the customer’s balance
customer_rewards[] returns any existing coupons

Test Endpoint 2 with real cart items

curl --request POST \
  --url "https://api.yukoapp.com/api/v1/public/points/estimate" \
  --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{
    "customer": {
      "id": "REAL_SHOPIFY_CUSTOMER_ID"
    },
    "items": [
      {
        "product_id": "REAL_PRODUCT_ID",
        "variant_id": "REAL_VARIANT_ID"
      }
    ]
  }'

Verify: the request returns HTTP 200 with points_earned and message. points_earned is currently always 0 (see the warning in Endpoint 2).

Test Endpoint 3: redeem a reward

Use a reward_id from the Endpoint 1 response (choose one where can_redeem === true).

curl --request POST \
  --url "https://api.yukoapp.com/api/v1/public/customers/rewards/redeem" \
  --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{
    "customer_id": "REAL_SHOPIFY_CUSTOMER_ID",
    "reward_id": "REWARD_ID_FROM_ENDPOINT_1_RESPONSE"
  }'

Verify:

Response is HTTP 201 (not 200)
coupon_code is returned and is a valid Shopify discount code
points_spent matches the points_cost of the reward you redeemed
expires_at is present (or null if the reward has no expiry or is store credit)

Test Endpoint 2 for guest checkout

curl --request POST \
  --url "https://api.yukoapp.com/api/v1/public/points/estimate" \
  --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{
    "items": [
      {
        "product_id": "REAL_PRODUCT_ID",
        "variant_id": "REAL_VARIANT_ID"
      }
    ]
  }'

Verify: Returns HTTP 200 with no customer field in the request body.

Test error cases

Test	How to trigger	Expected result
Wrong API key	Use `Bearer wrong_key`	HTTP 401
Unknown customer	Use `customer_id=0000000`	HTTP 404
Missing items	Send `"items": []`	HTTP 422
Guest checkout	Omit `customer` entirely	HTTP 200
Redeem with insufficient points	Use a `reward_id` where `can_redeem === false`	HTTP 422
Redeem with invalid reward ID	Use a made-up UUID as `reward_id`	HTTP 422

Test UI edge cases

Customer with 0 points — panel shows rewards, all greyed out
Customer with no prior redemptions — customer_rewards[] is an empty array — handle without crashing
Guest customer — Endpoint 1 and Endpoint 3 are not called; only show earn estimate from Endpoint 2
points_earned === 0 — hide the earn message; do not show “0 points”
After a successful redemption — UI updates the balance and removes the redeemed reward from the list

Go-live checklist

Security

API key stored as an environment variable — not hardcoded anywhere
All Yuko API calls made from the backend server — not the browser
HTTPS used for all requests

API integration

GET /customers/rewards/redeemable working and returning correct data
POST /points/estimate working for both logged-in and guest customers
POST /customers/rewards/redeem working — returns 201 with a valid coupon_code
Endpoints 1 and 2 fire in parallel at checkout load — not sequentially
Endpoint 3 is only called on an explicit customer “Redeem” click — not at page load
If any call fails, checkout continues without breaking

UI

Points balance displayed clearly
Redeemable rewards shown with a “Redeem” button for rewards where can_redeem === true
Rewards with insufficient points shown as greyed-out with “X more points needed”
Unused coupon codes from customer_rewards[] surfaced with an apply action
Points earn estimate shown when points_earned > 0
After a successful redemption: balance updates, redeemed reward is removed from list, new coupon code is surfaced or auto-applied
No loyalty UI shown for guest checkouts
Empty customer_rewards[] handled gracefully — no crash, no blank space

Rate limiting

Retry logic in place for HTTP 429 — wait 1 second, retry once
No polling within a single checkout session

Authentication

Plan in place for token rotation if the merchant regenerates their API key

API reference links

Get Redeemable Rewards

Points balance, available rewards, and unused coupons for a customer.

Redeem a Reward

Burn a customer’s points and generate a discount code.

Points Estimate

How many points a customer earns on a given cart.

Authentication

How Bearer Token authentication works in the Yuko API.

Errors

Full list of HTTP error codes and what they mean.

Rate Limits

Request limits and how to handle 429 errors.

Support

Book a call with Ramesh

For integration questions, OAuth setup, and onboarding support.

API Documentation

Full Yuko API reference.

​Overview

​How it works

​Before you start

​What the merchant needs to do

​What your team needs

​Authentication

​Base URL

​General rules

​Endpoint 1: Get points balance and redeemable rewards

​Request

​Query parameters

​Example request

​Example response

​Response fields

​Display logic

​Endpoint 2: Points estimate at checkout

​Request

​Request body

​Example request: logged-in customer

​Example request: guest checkout

​Example response

​Response fields

​Display logic

​Endpoint 3: Redeem a reward (burn points)

​Request

​Required headers

​Request body

​Example request

​Example response

​Response fields

​Errors

​Display logic after a successful redemption

​Full checkout flow

​Error handling

​HTTP status codes

​Error response format

​Recommended handling pattern

​Rate limits

​Security rules

​Rule 1: Never expose the API key on the frontend

​Rule 2: Use HTTPS everywhere

​Authentication setup options

​Testing

​Go-live checklist

​Security

​API integration

​UI

​Rate limiting

​Authentication

​API reference links

Get Redeemable Rewards

Redeem a Reward

Points Estimate

Authentication

Errors

Rate Limits

​Support

Book a call with Ramesh

API Documentation

Overview

How it works

Before you start

What the merchant needs to do

What your team needs

Authentication

Base URL

General rules

Endpoint 1: Get points balance and redeemable rewards

Request

Query parameters

Example request

Example response

Response fields

Display logic

Endpoint 2: Points estimate at checkout

Request

Request body

Example request: logged-in customer

Example request: guest checkout

Example response

Response fields

Display logic

Endpoint 3: Redeem a reward (burn points)

Request

Required headers

Request body

Example request

Example response

Response fields

Errors

Display logic after a successful redemption

Full checkout flow

Error handling

HTTP status codes

Error response format

Recommended handling pattern

Rate limits

Security rules

Rule 1: Never expose the API key on the frontend

Rule 2: Use HTTPS everywhere

Authentication setup options

Testing

Go-live checklist

Security

API integration

UI

Rate limiting

Authentication

API reference links

Support