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
• For multi-currency please include a separate entry per currency, and map your currency to the loyaltyCurrencyId provided in the snag admin.

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

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

// no pagination
Status code: 2**
Response body:
{
  "data": [{
    "id": string // optional, only if pagination is required
    walletAddress: string
    amount: string // important: amount must be a string
    loyaltyCurrencyId: 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.
• For multi-currency please specify a separate path for each currency.
• 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.