Configuration

Get the earning rules, rewards and VIP tiers that the shop offers.

GET /v1/configuration

Guests and signed-in shoppers receive the same catalogue. The request takes no parameters or body.

GET /apps/nasp-rewards/v1/configuration
Accept: application/json

Response

200 OK. This shop offers a 25-point welcome gift and USD 1.00 of store credit for every 100 points.

{
	"earning_rules": [
		{
			"activity": "welcome_gift",
			"title": "Welcome gift",
			"points": "25",
			"benefit": {
				"type": "points",
				"points": 25
			},
			"vip_dependent": false,
			"paused": false,
			"tier_benefits": [],
			"condition": "Earn once when you first sign in to your new account."
		}
	],
	"rewards": [
		{
			"rule_id": "41",
			"title": "Store credit",
			"redemption_type": "store_credit",
			"distribution": "points",
			"currency": "USD",
			"points_amount": "100",
			"vip_audience": "everyone",
			"tier_terms": [],
			"terms_version": "00fb41de36c3274e1608196fb3e86ffb9640a66488da220c0ab97cf46297a1a6",
			"terms": {
				"unit_credit_amount": "1.00",
				"expires_after_days": null
			}
		}
	]
}

Full example with VIP tiers, a free product and eligible collections

Earning rules

Each entry in earning_rules has an activity identifier, a display title, a condition and a points amount (null for birthday and welcome gifts that give a code). An empty array means the shop has no active earning rules.

Activity Additional fields
purchase points per full spend_amount in currency on a qualifying payment. Each tier_rates entry gives the tier_id and points for that tier.
welcome_gift A new customer receives this once, automatically, when their account is enabled, usually at first sign-in. It can’t be claimed. benefit, tier_benefits, vip_dependent and paused work as for birthday. Show the welcome gift
visit_… profile_url is the destination for a visit claim. It can be null.
email_subscription Points for a qualifying email subscription.
birthday collect_birth_year indicates whether the shop asks for a year. benefit describes the default reward. tier_benefits lists each active tier’s tier_id, mode (default, custom or none) and resolved benefit. vip_dependent is true if any active tier uses custom or none; paused means the whole birthday reward is currently stopped by VIP status.

Birthday benefit uses the same shape as the signed birthday form. The public catalogue describes the configuration for everyone; use the signed form to show a particular shopper’s applicable birthday benefit.

Rewards

Each entry in rewards describes one offer. Merchant wording uses the shop’s default language.

Field Meaning
rule_id, title The reward ID and its display name.
redemption_type, terms, currency The type of benefit, its conditions and the currency for its amounts.
distribution points for rewards a shopper can redeem. tier_entry_gift and vip_checkout are automatic tier benefits.
points_amount Standard price in points. For store credit, this is the price of one unit of credit.
tier_terms Each entry contains a tier_id and the price that tier pays in points_amount. Automatic benefits have null prices.
vip_audience For points rewards, everyone allows all shoppers and selected_tiers allows only the listed tiers.
terms_version Identifies the offer the shopper saw, including its price and eligible merchandise. A redemption uses this value exactly as returned.

Reward terms by type

redemption_type Fields in terms
store_credit unit_credit_amount gives the value of one unit. expires_after_days is the number of days until expiry, or null.
amount_off_order discount gives the type and its percentage or fixed amount. minimum_purchase has a type of none, quantity or subtotal, with a quantity or amount when applicable.
amount_off_products The discount and minimum purchase, plus entitlement_scope and the complete list of targets. For a fixed discount, applies_once_per_order distinguishes one discount per order from one per eligible item.
free_shipping minimum_purchase, destination_scope (all or countries), country_codes, include_rest_of_world and maximum_shipping_price. A null maximum means there is no price cap.
buy_x_get_y customer_buys lists the qualifying targets, their scope and the required quantity or amount. customer_gets separately lists its scope, eligible targets, quantity and discount. The discount can be free. uses_per_order_limit is the maximum number of uses, or null.
free_product variant_id, label, storefront_url and quantity identify the exact item. The shopper adds that variant to the cart and applies the issued code.

Each merchandise target has a kind (product, variant or collection), an id, a label and a storefront_url. A variant also has a product_id. Links and parent IDs can be null. All targets are included in this response.

Discount terms include combines_with and expires_after_days. The order, product, Buy X Get Y and free product discounts also include purchase_type: "one_time".

VIP tiers

vip_program appears after the shop launches VIP. It includes status, qualification_period (lifetime, calendar_year or rolling), rolling_months, time_zone and currency. Each entry in tiers gives its tier_id, name, threshold and keep_threshold, in ascending order of threshold. threshold is the spend to reach the tier. keep_threshold is the spend a shopper already in the tier needs to stay. It equals threshold when the merchant sets no spend to keep, including the base tier ("0.00") and every tier of a lifetime programme, so themes need no fallback.

When the programme is active, match the shopper’s current tier to the reward’s tier_terms. An unlisted tier pays the standard price on an everyone reward. When the programme is paused, everyone pays the standard price and selected-tier rewards are unavailable.

Errors

400 invalid_request indicates an unexpected parameter. 403 upgrade_required means the shop needs NASP Rewards Plus. 503 service_unavailable means the catalogue could not be returned. Display an unavailable message and try again later. All shared errors