Reward redemption

Spend points on a reward, check its receipt and list a shopper’s past rewards.

All endpoints on this page require a signed-in shopper. A receipt records the reward and price the shopper accepted. The shopper can read only their own receipts.

POST /v1/redemptions

Spends points on a reward from Configuration. The API checks the shopper’s current tier, the offer terms and the points available to spend. The balance displayed on the page can be older.

Request

A Gold shopper chooses a blanket for 100 points.

POST /apps/nasp-rewards/v1/redemptions
Content-Type: application/json
{
	"customer_id": "729001",
	"rule_id": "42",
	"points": "100",
	"terms_version": "323e38674305165817edfa6dda9fc6f2cce80cb3fc53af4c480b19b64b4c3740",
	"idempotency_key": "8ed48195-91a3-4f8a-acd4-9372090fc8ab"
}
Field Required Meaning
customer_id Yes Shopify customer ID that the theme rendered for this shopper.
rule_id Yes ID from the selected reward.
points Yes Total price the shopper confirmed, as a positive whole-number string. A fixed-price reward costs one unit.
terms_version Yes Value returned by Configuration for the displayed reward. Copy it from the response.
idempotency_key Yes One UUID per confirmed spend, for example from crypto.randomUUID(). Sending the same key and selection again recovers the same receipt.
unit_points Store credit only Price in points for one unit of credit at the shopper’s tier. The total points must be a whole multiple of this price.

For example, exchanging 300 points at 100 points per USD 1.00 requires points: "300" and unit_points: "100". That purchase buys USD 3.00 of store credit. Example store credit response

Response

202 Accepted. The shopper started with 550 points. The spend has reduced their balance to 450. The shopper can see the code once Shopify issues the discount.

{
	"points_balance": "450",
	"redemption": {
		"id": "7306",
		"rule_id": "42",
		"origin": "points_redemption",
		"redemption_type": "free_product",
		"title": "Birthday blanket",
		"terms_text": null,
		"points": "100",
		"currency": "USD",
		"status": "pending",
		"created_at": "2026-11-06T10:05:10Z",
		"reward_issued_at": null,
		"expires_at": null,
		"benefit": {
			"selected_variant": {
				"variant_id": "123",
				"label": "Red Blanket · Small",
				"storefront_url": "/products/red-blanket?variant=123"
			},
			"quantity": 1,
			"purchase_type": "one_time"
		},
		"code_status": null,
		"reward_code": null
	}
}

A repeat request with the same key and selection returns the original receipt and the current balance. The status is 202 while the shopper is waiting for the reward, then 200 once the reward succeeds or fails.

GET /v1/redemptions/{id}

Returns one receipt in any status. The path requires the receipt ID returned by the spend. The request takes no body or query parameters.

GET /apps/nasp-rewards/v1/redemptions/7306
Accept: application/json

200 OK. The same blanket now has an issued code.

{
	"redemption": {
		"id": "7306",
		"rule_id": "42",
		"origin": "points_redemption",
		"redemption_type": "free_product",
		"title": "Birthday blanket",
		"terms_text": null,
		"points": "100",
		"currency": "USD",
		"status": "succeeded",
		"created_at": "2026-11-06T10:05:10Z",
		"reward_issued_at": "2026-11-06T10:05:13Z",
		"expires_at": null,
		"benefit": {
			"selected_variant": {
				"variant_id": "123",
				"label": "Red Blanket · Small",
				"storefront_url": "/products/red-blanket?variant=123"
			},
			"quantity": 1,
			"purchase_type": "one_time"
		},
		"code_status": "available",
		"reward_code": "7GC2HX9PL4KQ"
	}
}

A missing receipt or one that belongs to another shopper returns 404 reward_unavailable.

GET /v1/redemptions

Returns successful receipts, newest first. The default page includes up to 20 receipts. A pending redemption appears in the receipt detail before it appears in history.

GET /apps/nasp-rewards/v1/redemptions
Accept: application/json
Query parameter Meaning
filter Omit to list past rewards, including store credit, tier gifts and birthday gifts. available lists up to five currently available discount codes per page.
cursor The next_cursor from the previous response for the same shopper and filter. A null cursor marks the last page.

200 OK. Each entry in redemptions has the same fields as a single receipt. has_redemptions is true if the shopper has any successful receipt, including one outside the selected filter. For example, a shopper with only store credit receives this response to GET /v1/redemptions?filter=available:

{
	"redemptions": [],
	"has_redemptions": true,
	"next_cursor": null
}

Complete response with an available code

Receipt fields

Field Meaning
id, rule_id Receipt ID and original reward rule ID. rule_id can be null on older receipts.
origin points_redemption for a spend, tier_entry_gift for a tier gift, or birthday_gift for a birthday gift.
redemption_type, title, terms_text Reward type and wording saved with the receipt. Older receipts can have a null title. terms_text is null on new receipts.
points, currency, benefit Points spent, currency and benefit accepted at the time. A gift costs zero points. A store credit receipt includes the credit amount. Older receipts can have fewer benefit details.
status pending, issuing, reconciling or reversal_pending while the spend is in progress. succeeded and failed are final.
created_at, reward_issued_at, expires_at UTC timestamps. Issue and expiry dates can be null.
code_status, reward_code Display a code when status is succeeded, code_status is available and reward_code contains a value. Other code statuses are used, expired or unavailable. Both fields are null for store credit and for a reward that has yet to succeed.

Recover a lost response

Keep the original key, shopper ID and confirmed selection if the connection drops after a spend. Sending the original POST again returns the accepted receipt or accepts the spend once. A new key represents a new spend.

POST /v1/redemptions/lookup

Finds a storefront receipt by idempotency key without spending points. The JSON body requires one field.

{
	"idempotency_key": "8ed48195-91a3-4f8a-acd4-9372090fc8ab"
}

200 OK returns the same redemption object as a receipt detail request. A 404 reward_unavailable can mean the original spend has not finished being accepted. Retry the original POST with the original key and selection. Example lookup response

GET /v1/redemptions/current

Returns the shopper’s current points spend if it is still in progress, including a spend started outside the theme. This read takes no parameters or body. 200 OK returns a redemption object, or the following response when there is no current spend:

{
	"redemption": null
}

Use the receipt ID or key when available. A completed spend is no longer current.

Errors

Response Meaning and recovery
400 invalid_request Check field names, types and UUID format.
400 invalid_cursor Start history again from the first page with the intended filter.
404 redemption_unavailable The shopper cannot redeem this offer. Refresh Configuration.
409 redemption_offer_changed Fetch the offer and shopper’s tier again. Show the new terms and ask the shopper to confirm.
409 idempotency_conflict The key was already used with different details. Look up the original spend.
409 redemption_in_progress Check the current receipt before accepting another spend.
409 shopper_changed Clear the previous shopper’s details and reload.
422 insufficient_points The shopper lacks spendable points for this selection.
422 invalid_points Check the reward’s price or the number of store credit units.
429, server error or timeout Keep the original request. After a 429, wait for Retry-After before resending it.

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.