REST API endpoints reference

All REST API endpoints are under https://example.com/wp-json/spar/v1. The API must be switched on first at Points & Rewards › API, Webhooks & AI › REST API. Each endpoint can also be switched off on that tab. To test the API without writing code, import the /openapi description into Postman, Insomnia or a custom GPT.

Who can call each endpoint

• Store managers are users with the manage_woocommerce capability, such as administrators and shop managers.
• Customers can call some endpoints, but only for their own account. Asking for another customer returns “Customer not found.”
• Scope is the scope an API key needs. Application passwords skip scope checks and use the WordPress user’s permissions.

Customer endpoints

Method	Endpoint	What it does	Who	Scope
GET	/me	The signed-in user, how they signed in, and their points account	Any signed-in user	read
GET	/customers	Lists customers. Filter with search, has_points or min_balance. Sort by balance, lifetime, name or registered. 20 per page, up to 100.	Store managers	read
GET	/customers/{id}	Balance, lifetime points, status, level, next level and referral link	Store managers, the customer	read
GET	/customers/{id}/history	Points history, newest first	Store managers, the customer	read
POST	/customers/{id}/points	Adds or removes points. Send points, action (add or remove) and an optional note.	Store managers	write
POST	/customers/{id}/balance	Sets an exact balance. Lifetime points do not change.	Store managers	write
POST	/customers/{id}/status	Sets the status to active or banned	Store managers	write

Rewards, levels and referrals

Method	Endpoint	What it does	Who	Scope
GET	/levels	Levels, and whether they are based on lifetime points or balance	Any signed-in user	read
GET	/rewards	Rewards with their points cost, and whether the customer can afford each one	Any signed-in user	read
POST	/rewards/{id}/claim	Claims a reward and spends the points. Voucher, custom and store credit rewards only.	The customer, or store managers for any customer	write
GET	/vouchers	Reward vouchers, and whether each is unused, used, expired or inactive	Any signed-in user (own vouchers)	read
GET	/referrals/stats	Clicks, conversions, conversion rate and points earned. Store managers also get store-wide figures.	Any signed-in user	read

Rewards that add a product to the cart cannot be claimed through the API. The customer has to claim them on your site.

Reports and events

Method	Endpoint	What it does	Who	Scope
GET	/events	A feed of points changes. Pass after with the last event ID you received to get only newer changes.	Store managers	read
GET	/reports/summary	Program totals, points liability, outstanding vouchers, top customers and levels. Cached for up to 5 minutes.	Store managers	read

API management

Method	Endpoint	What it does	Who	Scope
GET, POST	/keys	Lists or creates API keys. A new key is only returned once.	Store managers	manage
DELETE	/keys/{id}	Revokes a key	Store managers	manage
GET	/openapi	The OpenAPI 3.1 description of every endpoint	Anyone	none

Pro endpoints

Method	Endpoint	What it does	Who	Scope
GET	/guests	Guest points by email, pending or migrated	Store managers	read
GET	/pending-points	Points waiting out the points delay	Store managers, the customer	read
GET, POST	/webhooks	Lists or adds webhooks	Store managers	manage
PATCH, DELETE	/webhooks/{id}	Switches a webhook on or off, changes its events, or deletes it	Store managers	manage
POST	/webhooks/{id}/test	Sends a test delivery	Store managers	manage
GET	/webhooks/events	Lists the events a webhook can send	Store managers	read

Example: give a customer points

curl -X POST https://example.com/wp-json/spar/v1/customers/42/points 
  -H "Authorization: Bearer spar_your_api_key" 
  -H "Content-Type: application/json" 
  -d '{"points": 100, "action": "add", "note": "In-store purchase"}'

The response status is applied, or delayed when the points delay (Pro) holds the points back. When you remove points, the amount is capped at the customer’s balance.

Related

• Set up the REST API and API keys
• Send webhooks to other services (Pro)
• Actions & Filters Reference