Skip to main content
API docs by Redocly

KNISTR Loyalty Storefront API (1.0.0)

Download OpenAPI specification:Download

Read and change the loyalty data of the customer who is logged in to the shop.

Use it to build your own loyalty UI instead of the ready-made theme blocks the app ships with. Those blocks call these same endpoints, so you lose nothing by replacing them.

The loyalty data that the app syncs into Shopify (customer metafields, shop metaobjects) is an internal detail of those blocks and may change without notice — build against this API instead.

Storefront

Loyalty endpoints a storefront may call on behalf of the logged-in customer.

Two supported ways to reach them:

  • Shopify App Proxy (recommended for themes) — call /apps/loyalty-proxy/... on the shop domain. Shopify signs the request and appends logged_in_customer_id; no credentials of your own.
  • Session token (checkout and customer-account UI extensions) — call the API host directly and send the Shopify session token in the X-Shopify-Session-Token header. The customer is taken from the token, never from the query string.

Every endpoint except GET /config acts on the logged-in customer and answers 401 without one.

List the member's activity history

Points earned, points spent and rewards redeemed, newest first.

Authorizations:
NoneShopifySessionToken
query Parameters
logged_in_customer_id
string

Appended by the Shopify App Proxy. Ignored when a session token is used.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Set the member's birthday

Month and day only, as --MM-DD. It can be set once; afterwards the stored date is returned with 409.

Authorizations:
NoneShopifySessionToken
query Parameters
logged_in_customer_id
string

Appended by the Shopify App Proxy. Ignored when a session token is used.

Request Body schema: application/json
required
birthdate
required
string^--\d{2}-\d{2}$

Day and month of birth as an ISO-8601 MonthDay, --MM-DD. The year is deliberately not collected. Any other format is rejected with 400.

Responses

Request samples

Content type
application/json
{
  • "birthdate": "--08-24"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "birthdate": "--08-24"
}

Get the shop's program configuration

Branding, earning rules and the reward options a member can redeem. Shop-scoped: this is the one endpoint that needs no logged-in customer.

Authorizations:
NoneShopifySessionToken
query Parameters
logged_in_customer_id
string

Appended by the Shopify App Proxy. Ignored when a session token is used.

Responses

Response samples

Content type
application/json
{
  • "branding": {
    },
  • "earning": {
    },
  • "rewardOptions": [
    ]
}

Leave the loyalty program

Ends the membership. Points and coupons are no longer usable.

Authorizations:
NoneShopifySessionToken
query Parameters
logged_in_customer_id
string

Appended by the Shopify App Proxy. Ignored when a session token is used.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "You have successfully left the loyalty program."
}

Get the member's balance and coupons

Points balance, pending points and the coupons the customer currently holds.

Authorizations:
NoneShopifySessionToken
query Parameters
logged_in_customer_id
string

Appended by the Shopify App Proxy. Ignored when a session token is used.

Responses

Response samples

Content type
application/json
{
  • "memberId": "3f1a7c02-95d1-4a2e-8f0b-1c6de2a9b410",
  • "email": "ada@example.com",
  • "firstName": "Ada",
  • "lastName": "Lovelace",
  • "birthdate": "--08-24",
  • "activePoints": 420,
  • "pendingPoints": 50,
  • "totalPoints": 470,
  • "coupons": [
    ]
}

Redeem points for a reward

Exchanges the member's points for the reward option and returns the coupon to show the customer. Option ids come from GET /config.

Authorizations:
NoneShopifySessionToken
query Parameters
logged_in_customer_id
string

Appended by the Shopify App Proxy. Ignored when a session token is used.

Request Body schema: application/json
required
optionId
required
string

optionId of the reward to redeem, taken from rewardOptions in GET /config.

Responses

Request samples

Content type
application/json
{
  • "optionId": "6b1f0f4c-2f3a-4a1e-9a7c-0d2f8e5b1c33"
}

Response samples

Content type
application/json
{
  • "couponId": "c81d4e2f-6a90-4b13-9f77-2b0c5e6a8d41",
  • "memberId": "3f1a7c02-95d1-4a2e-8f0b-1c6de2a9b410",
  • "code": "LOYALTY-5EUR-A7K2",
  • "title": "€5 off your order",
  • "description": "Applies to any order over €20.",
  • "discountType": "PERCENTAGE",
  • "discountValue": 5,
  • "minOrderValue": 20,
  • "status": "AVAILABLE",
  • "validFrom": "2022-03-10T12:15:50",
  • "validUntil": "2022-03-10T12:15:50",
  • "redeemedAt": "2022-03-10T12:15:50",
  • "pointsCost": 500,
  • "isValid": true
}

Join the loyalty program

Creates a membership for the logged-in customer. Calling it again for a customer who is already a member returns that membership instead of failing.

Authorizations:
NoneShopifySessionToken
query Parameters
logged_in_customer_id
string

Appended by the Shopify App Proxy. Ignored when a session token is used.

Request Body schema: application/json
required
registrationSource
string

Where the customer joined from, stored for reporting. Defaults to WIDGET when omitted.

consentGiven
required
boolean

Whether the customer agreed to the loyalty terms. Must be true; the request is rejected with 400 otherwise.

Responses

Request samples

Content type
application/json
{
  • "registrationSource": "STOREFRONT",
  • "consentGiven": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "memberId": "3f1a7c02-95d1-4a2e-8f0b-1c6de2a9b410",
  • "email": "ada@example.com",
  • "firstName": "Ada",
  • "lastName": "Lovelace",
  • "activePoints": 100,
  • "pendingPoints": 0,
  • "totalRewardPoints": 100
}