Customer and birthday

Read a shopper’s points, VIP tier and recent activity. Read or update their birthday.

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.