Get loyalty program configuration

Retrieves the shop's active loyalty campaign configuration: its tiers (ordered by starting points) and milestones (ordered by points needed). Returns NOT_FOUND when the shop has no active loyalty campaign.

GET
/sdk/studio/{shopId}/loyalty
x-stash-hmac-signature<token>

Versioned HMAC-SHA256 signature authenticating server-to-server SDK requests (your backend calling Stash), as opposed to client-side SDK operations. Recommended over the deprecated X-Stash-Api-Key for the best security. Header format: v1;{appId};{unixMillisTimestamp};{base64Signature} (semicolon-delimited). {base64Signature} is the base64-encoded HMAC-SHA256 of the string {unixMillisTimestamp}.{requestBody} using your app ingress secret (the ingress secret is shown base64-encoded in Studio; base64-decode it to the raw bytes used as the HMAC key), where {requestBody} is the request body exactly as you send it for POST and PUT requests (the compact canonical request JSON is also accepted) and empty for GET requests. A signature over the exact bytes verifies for bodies of up to 18 KiB (18,432 bytes); a larger body may be refused with 401 even when correctly signed. The timestamp must be within 5 minutes of Stash server time. Your appId is your immutable app identifier, shown in Stash Studio under Project Settings > App details; your ingress secret is under Project Settings > API Secrets.

In: header

Path Parameters

shopId*string

Shop identifier from Stash Studio

Response Body

application/json

application/json

curl -X GET "https://example.com/sdk/studio/string/loyalty"
{  "activeCampaign": {    "campaignId": "string",    "tiers": [      {        "tierId": "string",        "name": "string",        "startPoints": 0,        "pointsPerDollar": 0,        "pointsMultiplierPermille": 0,        "iconUrl": "string",        "milestones": [          {            "milestoneId": "string",            "name": "string",            "pointsNeeded": 0,            "rewards": [              {                "itemId": "string",                "quantity": 0,                "type": "LOYALTY_REWARD_TYPE_UNSPECIFIED"              }            ]          }        ]      }    ]  }}

How is this guide?

Refresh localizations POST

Asks Stash to refresh the shop's localizations from its enabled localization source, for example after the source file changes. The request body is the empty JSON object {}. This method accepts only the versioned x-stash-hmac-signature header, signed over the request body exactly as sent ({}); the legacy stash-hmac-signature header is rejected with HTTP 401 (UNAUTHENTICATED), because it carries no timestamp and a captured request could be replayed. The shop in the signature header must equal the shop_id in the path. A successful response means the refresh is durably queued, not that the import has completed or that the storefront shows the result. Repeated calls are safe, so retry after a 500, a 503 or a timeout with a fresh timestamp and signature. Errors, by the HTTP status a REST caller receives and its gRPC status. Two of them share HTTP 400; a REST caller tells them apart by the code in the error body, 3 for INVALID_ARGUMENT and 9 for FAILED_PRECONDITION. 400 INVALID_ARGUMENT (code 3) when the request is malformed, for example a body that is not valid JSON; fix the request, because resending it unchanged does not help. 400 FAILED_PRECONDITION (code 9) when the shop has no enabled localization source; retrying does not help until the source is set up and enabled. 401 UNAUTHENTICATED when the signature is missing, invalid, outside the time window, sent in the legacy header, or names a different shop or one Stash does not know; fix the signing, because resending it unchanged does not help. 500 INTERNAL when Stash hits an internal error, for example reading the shop's localization settings; retry with backoff. 503 UNAVAILABLE when the refresh could not be queued; retry with backoff.

Get loyalty configuration GET

Retrieves the shop's loyalty configuration in the shape UpdateLoyaltyConfig accepts: display settings, bonus definitions, reward products with their status, every campaign (season) with its status, and the spend conversion table with the rate derived per currency. Product rewards are returned by SKU. Use it to verify a sync. This method accepts only the versioned x-stash-hmac-signature header, signed over an empty body; the legacy stash-hmac-signature header is rejected with HTTP 401 (UNAUTHENTICATED), because it carries no timestamp and a captured request could be replayed. Errors, by the HTTP status a REST caller receives and its gRPC status: 401 UNAUTHENTICATED when the signature is missing, invalid, outside the time window, sent in the legacy header, or names a different shop; fix the signing, because resending it unchanged does not help. 404 NOT_FOUND for an unknown shop or a shop with no loyalty program; it does not change on a retry. 501 UNIMPLEMENTED when the loyalty configuration API is not available; it does not change on a retry. 500 INTERNAL when Stash hits an internal error, for example reading the shop's loyalty configuration; reading is safe to repeat, so retry with backoff.