All three endpoints require a signed-in shopper. Shopify identifies the shopper from the storefront session.
GET /v1/customer
Returns the current shopper’s loyalty summary. The request takes no parameters or body.
GET /apps/nasp-rewards/v1/customer
Accept: application/json
200 OK. A shopper with no points or activity can receive this response:
{
"points_balance": "0",
"vip_status": null,
"purchase_earning": null,
"earning_state": [],
"birthday_saved": false,
"upcoming_points_expiries": [],
"non_expiring_points": "0",
"expiry_breakdown_complete": true,
"point_history": []
}
Complete response for a Gold shopper with 550 points
| Field | Meaning |
|---|---|
points_balance |
The shopper’s recorded balance as a whole-number string. |
vip_status |
Null before the VIP programme launches. Otherwise includes tier_id, current_tier_name, manual, valid_through (inclusive date or null), progress_spend and currency. A paused programme still shows the shopper’s tier. |
| Next tier | Inside vip_status, next_tier_id, next_tier_name, next_tier_required_spend and amount_to_next_tier describe the next tier. They are null for a manually assigned tier or the highest tier. amount_to_keep_tier is the spend needed to keep the current tier, when applicable. It is measured against that tier’s spend to keep, the keep_threshold in Configuration, so it can be smaller than the tier’s threshold. |
purchase_earning |
The shopper earns points_amount points per spend_amount in currency. Null when purchase earning is inactive. |
earning_state |
Each entry has an activity identifier and a state of available or completed. Email subscription can also be ineligible. The welcome gift is completed once it has been awarded, as points or a code, and ineligible if the customer’s account was enabled while no welcome reward applied. |
birthday_saved |
True when the shopper has a saved month and day. |
upcoming_points_expiries |
Groups of points with the same expires_at timestamp in UTC. non_expiring_points gives the total with no expiry. |
expiry_breakdown_complete |
False when the expiry groups and non-expiring points explain only part of the balance. |
point_history |
Up to 20 entries, newest first. Each has an id, title, signed points amount and UTC created_at timestamp. For past rewards, use redemption history. |
Balance freshness
The summary can show an earlier balance, including points that have just expired.
For example, the page shows 550 points and a successful 100-point redemption returns points_balance: "450". Display 450 from that response. A separate summary request is optional and can still show the earlier 550.
GET /v1/customer/birthday
Returns the birthday fields the shop collects and any saved date. The request takes no parameters or body.
GET /apps/nasp-rewards/v1/customer/birthday
Accept: application/json
200 OK. This shop collects a month and day and offers 40 points on the shopper’s birthday.
{
"enabled": true,
"collect_birth_year": false,
"points": "40",
"benefit": { "type": "points", "points": 40 },
"birthday": {
"month": 3,
"day": 4,
"year": null
},
"awarded_this_year": false,
"awarded_points_this_year": null,
"gift_accepted_this_year": false
}
When the rule is off, the response contains only "enabled": false. With no saved date, the date fields are null. The API hides the year when the shop does not collect it. awarded_points_this_year gives the points awarded for the current UTC birthday year, or null. gift_accepted_this_year reports a gift awarded for that birthday year, including one whose code is still being prepared.
The benefit describes the reward applicable to this shopper’s birthday tier and the current settings. Use it for the offer text:
benefit.type |
Detail |
|---|---|
points |
points is an integer. The top-level points field remains a string. |
free_product |
product_title can identify the selected variant. Top-level points is null. |
amount_off_order |
percentage is a decimal string, such as "20". Top-level points is null. |
none |
No reward currently applies. Top-level points is null. Keep birthday entry and recorded award status available. |
Tier exclusions, missing gift defaults and a paused VIP-dependent birthday rule can produce none. This response never includes a gift code. Codes belong to the shopper’s reward receipts.
PUT /v1/customer/birthday
Saves a date for the signed-in shopper. The last valid save wins, even when it comes from an older form.
PUT /apps/nasp-rewards/v1/customer/birthday
Content-Type: application/json
{
"customer_id": "729001",
"birthday": {
"month": 6,
"day": 10,
"year": null
}
}
Both top-level fields are required. month and day must be integers that form a valid date. If the shop collects the year, year must be a positive integer and the date cannot be in the future (UTC). Otherwise, omit year or send null to preserve any year already saved.
200 OK. The response includes the saved form and the shopper’s current points balance. Saving the date does not itself award points or a gift.
{
"enabled": true,
"collect_birth_year": false,
"points": "40",
"benefit": { "type": "points", "points": 40 },
"birthday": {
"month": 6,
"day": 10,
"year": null
},
"awarded_this_year": false,
"awarded_points_this_year": null,
"gift_accepted_this_year": false,
"points_balance": "550"
}
Errors
| Response | Meaning and recovery |
|---|---|
401 customer_login_required |
Offer sign-in and clear private details. |
400 invalid_request |
Check the shopper ID and the shape of the birthday object. |
404 birthday_points_unavailable |
The shop disabled the rule. Close the form. |
409 shopper_changed |
The account changed. Reload before showing a new form. |
422 invalid_birthday |
Check the date and whether the shop collects a year. |
Shared access requirements and errors
Request handling
Send the documented JSON fields. Extra fields are ignored; required values and business rules are still validated. Handle other failures using the generic fallback described in Requests and errors. An unclear redemption result must retain the original idempotency key for recovery.