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.