API Reference

The Ploints REST API gives you programmatic access to points, customers, badges, and webhooks. All endpoints are scoped to your business via your API key.

Authentication

Every request must include your API key in the Authorization header:

Authorization: Bearer <api_key>

// Equivalent alternative:
X-API-Key: <api_key>

Response Format

All endpoints return JSON with a consistent envelope:

{
  "success": true,
  "data": { ... }
}

// Error response
{
  "success": false,
  "error": "Description of what went wrong"
}

Points

Award, redeem, and check point balances for your customers.

POST/api/v1/points/award

Award Points

Award points to a customer. The customer will be auto-enrolled if they do not already exist.

Parameter	Type	Required	Description
`customerEmail`	string	Yes	Email address of the customer
`amount`	number	Yes	Number of points to award (must be a positive integer)
`description`	string	No	Reason for awarding points (e.g. 'Purchase #1234')
`idempotencyKey`	string	No	Unique key (e.g. booking or order ID). Sending the same key twice returns the original transaction instead of double-awarding.
`referenceId`	string	No	Alias for idempotencyKey — either field deduplicates awards for the same business.
`skipMultiplier`	boolean	No	Set true if your system pre-calculates points (tier multipliers will not be applied again)

curl -X POST https://ploints.space/api/v1/points/award \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerEmail": "jane@example.com",
    "amount": 50,
    "description": "Purchase #1234",
    "idempotencyKey": "order-1234"
  }'

POST/api/v1/points/redeem

Redeem Points

Redeem points from a customer's balance. Fails if the customer does not have enough points.

Parameter	Type	Required	Description
`customerEmail`	string	Yes	Email address of the customer
`amount`	number	Yes	Number of points to redeem (must be a positive integer)
`description`	string	No	Reason for redemption (e.g. 'Reward: Free Coffee')
`idempotencyKey`	string	No	Unique key — a retried request with the same key will not deduct twice

curl -X POST https://ploints.space/api/v1/points/redeem \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerEmail": "jane@example.com",
    "amount": 25,
    "description": "Reward: Free Coffee"
  }'

GET/api/v1/points/balance?email=...

Get Balance

Retrieve the current point balance for a customer. Only customers enrolled at your business are visible — others return 404.

Parameter	Type	Required	Description
`email`	string	Yes	Customer email address (query parameter)

curl https://ploints.space/api/v1/points/balance?email=jane@example.com \
  -H "Authorization: Bearer <api_key>"

Customers

List and create customers enrolled in your loyalty program.

GET/api/v1/customers?page=1

List Customers

Retrieve a paginated list of customers for your business.

Parameter	Type	Required	Description
`page`	number	No	Page number (defaults to 1)

curl https://ploints.space/api/v1/customers?page=1 \
  -H "Authorization: Bearer <api_key>"

POST/api/v1/customers

Create / Enroll Customer

Create a new customer or enroll an existing one in your loyalty program.

Parameter	Type	Required	Description
`email`	string	Yes	Customer email address
`name`	string	Yes	Customer full name
`phone`	string	No	Customer phone number

curl -X POST https://ploints.space/api/v1/customers \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "name": "Jane Doe",
    "phone": "+1234567890"
  }'

Badges

Issue digital badges to customers for achievements and milestones.

POST/api/v1/badges

Issue Badge

Issue a badge to a customer. Badges are unique per customer; re-issuing has no effect.

Parameter	Type	Required	Description
`customerEmail`	string	Yes	Email address of the customer
`badgeSlug`	string	Yes	Unique identifier of the badge to issue

curl -X POST https://ploints.space/api/v1/badges \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerEmail": "jane@example.com",
    "badgeSlug": "first-purchase"
  }'

Webhooks

POST/api/v1/webhooks

Register Webhook

Parameter	Type	Required	Description
`url`	string	Yes	The HTTPS URL that will receive POST requests
`events`	string[]	Yes	Array of event types to subscribe to (e.g. ['points.earned', 'customer.created'])

curl -X POST https://ploints.space/api/v1/webhooks \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yoursite.com/webhooks/ploints",
    "events": ["points.earned", "points.redeemed"]
  }'

GET/api/v1/webhooks

List Webhooks

Retrieve all registered webhook endpoints for your business.

curl https://ploints.space/api/v1/webhooks \
  -H "Authorization: Bearer <api_key>"

Error Codes

The API uses standard HTTP status codes. Common responses include:

Status	Meaning
`200`	Success
`201`	Resource created
`400`	Bad request (validation failed)
`401`	Unauthorized (invalid or missing API key)
`404`	Resource not found
`422`	Unprocessable entity (insufficient points, etc.)
`429`	Rate limit exceeded
`500`	Internal server error