Requests and errors

Access requirements, request format and HTTP responses for the Storefront Loyalty API v1.

Base path

The API is available on the NASP Rewards Plus plan. The default base path is /apps/nasp-rewards/v1 on your client’s storefront. The merchant can change the app proxy path in the NASP Rewards app settings in Shopify admin. For example, if they chose /tools/loyalty, the Configuration URL is /tools/loyalty/v1/configuration.

Access

Configuration is public. Every other endpoint requires a shopper signed in to the store. Shopify forwards the request with the shop and shopper identity. The theme needs no API key.

A claim, birthday save or redemption includes customer_id. Its value is the Shopify customer ID from Liquid’s customer.id, written as a string. If the shopper changes accounts between opening the page and submitting the request, the API returns 409 shopper_changed.

Send requests from the theme using a relative URL on the shop’s HTTPS storefront. The browser sets the origin headers.

If the shopper switches accounts in another tab, clear their private details and reload before showing a balance, birthday or reward code.

Request and response format

Item Format
Response JSON. Send Accept: application/json.
GET No request body. Each GET also supports HEAD, which returns headers only.
POST and PUT A JSON object with Content-Type: application/json. Each endpoint lists the fields it accepts. Extra fields are ignored. Use unique JSON keys.
IDs and point amounts Decimal strings, such as "729001" and "550". A submitted ID or points selection must be a positive whole number without leading zeros.
Money A decimal string, such as "10.00", with a currency code such as USD.
Private responses Cache-Control: private, no-store.

Errors

API errors include a code. Other failures can return HTML, an empty body or unrecognised JSON. If the storefront returns a password page or the request fails before you receive JSON, display that rewards are unavailable. A failed balance request gives you no balance to display.

HTTP status Code What the theme can do
400 invalid_request Check the field names, types and query parameters against the endpoint reference.
401 customer_login_required Clear the previous shopper’s details. Offer sign-in using Liquid’s routes.storefront_login_url.
403 invalid_proxy Check the app proxy path. On a custom storefront domain, check that the browser sends Sec-Fetch-Site: same-origin when the theme submits a change.
403 upgrade_required, plan_required Check the shop’s NASP Rewards subscription.
404 Depends on the endpoint The resource is unavailable to this shopper. See the endpoint reference.
415 unsupported_media_type Send the required JSON content type. Unmatched paths or methods use normal routing errors; do not rely on a specific 405 body.
409 shopper_changed Clear the previous shopper’s details and reload the page.
409, 422 Depends on the endpoint See the endpoint reference for changes to an offer, an invalid date or insufficient points.
429 rate_limited Wait for the number of seconds in Retry-After or retry_after before the next request.
500, 503 rate_limit_unavailable, entitlement_unavailable, service_unavailable Try again later. For a lost redemption response, recover the original spend.

The shop normally has a shared allowance of 60 requests per 60 seconds. A rate limit response looks like this:

{
	"code": "rate_limited",
	"retry_after": 60
}

For an unclear redemption response, keep the original idempotency key and selection. HTML, an empty body or unrecognised JSON must never cause a new spend automatically.