The following two APIs are standards we expect for interacting with a client’s loyalty point system.

Configuration

In our self-serve dashboard we will ask for the following:

• Get balance URL
• Update balance URL
• API key

Authentication

Please build your APIs with API key access. Allow us to pass in the API key as a header

# we will send the following header on all requests
x-api-key: YOUR_API_KEY

Get loyalty point balance

• This endpoint will be called many times from our frontend, so make sure it is performant and can handle the load
• For non-existence wallet addresses please don’t include in the array or pass back a “0” balance

GET <URL can be specified, e.g. https://api.domain.com/api/balances>

Request parameters:
{
  walletAddress: string | string[],  // case-insensitive
  startingAfter?: string // optional, only if pagination is required.
}

// no pagination
Response body:
Status code: 2**

{
  "data": [{
    "id": string // optional, only if pagination is required
    walletAddress: string
    amount: string // important: amount must be a string
  }],
  hasNextPage: boolean // if pagination is required
}

Update loyalty point balance

• This endpoint should process all updates transactionally (all succeed, or all fail), or return a 400 error.
• It is the APIs responsibility to balance check.
• Example: if one wallet has insufficient balance, then return a 400 and a proper error message. We will surface the error message to the frontend.

POST <URL can be specified, e.g. https://api.domain.com/api/balances>

Body parameters:
{
  entries: [
		{
		  walletAddress: string // case-insensitive
		  direction: 'debit' | 'credit'
		  amount: string // important: amount must be string.
		  idempotencyKey: string | undefined // external client responsible for saving only once
		}
	],
	description: "description of event",
}

Response:

Success:
Status code: 2**

Failure:
Satus code: 4** or 5**
Response body:
{
  message: string
}