ECRS Logo - Dark Blue Letters with Golden E
API docs by Redocly

ECRS® Loyalty Points Provider API (5.8.187)

ECRS Support: support@ecrs.com URL: https://www.ecrs.com

Description

This document describes the REST / JSON API which can be exposed to allow ECRS® CATAPULT® to use a third party as the system of record for loyalty point balances.

These calls are made from a central ECRS server hosted by by the retailer to a server provided by the 3rd party provider. The 3rd party server should host an endpoint "/points" which supports the GET, PUT, and DELETE requests documented below. All requests expect to receive a response within a default of 6 seconds or the request will be aborted and the response ignored unless otherwise noted.

The third-party loyalty server must be configured to use the secure HTTPS protocol and must support TLS 1.2 or higher. Cipher suites must be compatible with the current version of the Java Runtime Environment deployed with Transaction Server POS; as of this publication, that version is OpenJDK Temurin 11.0.15+10.

Configuration of the POS to make calls to an implementation of this server is done through advanced settings defined within WebOffice.

Document Revision History

Current Revision = 5.8.187

Revision Date

  • 05/15/2026

New:

Fixes & Improvements:

  • Expanded documentation of existing functionality
  • Clarified example responses
  • Removed deprecated "store" field from LoyaltyUpdate schema

Older Revisions

1.0.0
  • Initial publication of specification

Retrieve Loyalty Balances

Retrieves a list of all loyalty point balances belonging to the current customer. Any balance configured within ECRS CATAPULT but not returned by the 3rd party server is considered to have a zero balance.

This request would be utilized any time the POS needs to obtain the loyalty points balance for a specific customer; for example, when the customer is associated to a new transaction or when their balance is checked by a cashier.

ECRS CATAPULT POS supports the use of multiple loyalty programs simultaneously, if the merchant has configured more than just the default program. If multiple programs are in use, balances for all programs must be returned in this data set; customers will be assumed to have 0 loyalty value available in any loyalty program which is excluded.

path Parameters
customer
required
string
Example: 400000000123

The account number (Customer ID) of the customer whose loyalty balances are being queried

Responses

Response Schema: application/json
customer
string [ 1 .. 16 ] characters

The id of the customer

Array of objects (LoyaltyBalance)

An array of loyalty balances associated to this customer

Array
name
required
string [ 1 .. 32 ] characters

The name of the loyalty point program

balance
required
number <decimal>

The current balance of this loyalty program.

Note: When a program is configured to display as 'points' in ECRS CATAPULT then a single point is equivalent to 0.01 in this field. When program is configured to display as a dollar value then this field is displayed rounded to 2-decimal places.

dailyAccrual
number <decimal>

The number of points the customer has accrued on the current business day.

Response samples

Content type
application/json
{
  • "customer": "400000000123",
  • "balances": [
    • {
      • "name": "Default Program",
      • "balance": "1.3300",
      • "dailyAccrual": "0.8500"
      }
    ]
}

Loyalty Balance Log Insert/Update

The PUT request will be sent when a customer's loyalty balance needs to be updated as a result of an accrual (for example, a purchase was made and the customer earned points), a redemption (the customer spent points to make a purchase), or an adjustment submitted through CATAPULT Web Office.

path Parameters
customer
required
string
Example: 400000000123

The customer ID of the customer whose points need to be updated.

id
required
string <uuid>
Example: 9df9f9bf-2984-4dee-909b-5af63c734054

The unique identity of the log entry to be inserted or updated in the loyalty balance log for a customer.

Request Body schema: application/json
required
name
required
string [ 1 .. 32 ] characters

The name of the loyalty program to update.

adjustment
required
number <decimal>

The amount to adjust the loyalty program balance by.

time
required
string <date-time>

The time at which accrual originated.

allowNegative
boolean

Indicates if this adjustment should be allowed to take the customers balance into the negative. If false an adjustment which would take an adjustment negative

reason
string <= 12 characters

A type description for this adjustment. Values include, but are not limited to:

  • Redemption - A loyalty redemption
  • Accrual - Addition of new loyalty points caused by the completion of a transaction.
  • Adjustment - This is an adjustment of loyalty points for administrative reasons.
terminalNumber
integer <int32>

The number of the terminal at which this adjustment originated.

receiptNumber
integer <int32>

An receipt number indicating the transaction at which this adjustment originated.

cashierName
string <= 64 characters

The name of the cashier responsible for this adjustment.

Responses

Response Schema: application/json
message
string

A human readable description of the response(Error details or other information useful for debugging).

object (LoyaltyBalance)

The balance of a single loyalty points program.

name
required
string [ 1 .. 32 ] characters

The name of the loyalty point program

balance
required
number <decimal>

The current balance of this loyalty program.

Note: When a program is configured to display as 'points' in ECRS CATAPULT then a single point is equivalent to 0.01 in this field. When program is configured to display as a dollar value then this field is displayed rounded to 2-decimal places.

dailyAccrual
number <decimal>

The number of points the customer has accrued on the current business day.

Response Schema: application/json
message
string

A human readable description of the response(Error details or other information useful for debugging).

object (LoyaltyBalance)

The balance of a single loyalty points program.

name
required
string [ 1 .. 32 ] characters

The name of the loyalty point program

balance
required
number <decimal>

The current balance of this loyalty program.

Note: When a program is configured to display as 'points' in ECRS CATAPULT then a single point is equivalent to 0.01 in this field. When program is configured to display as a dollar value then this field is displayed rounded to 2-decimal places.

dailyAccrual
number <decimal>

The number of points the customer has accrued on the current business day.

Request samples

Content type
application/json
{
  • "name": "Default Program",
  • "adjustment": "0.8500",
  • "time": "2026-05-15T07:38:22.939Z",
  • "allowNegative": true,
  • "reason": "ACCRUAL",
  • "terminalNumber": 1,
  • "receiptNumber": 1538,
  • "cashierName": "Doe, John"
}

Response samples

Content type
application/json
{
  • "message": "OK",
  • "program": {
    • "name": "Default Program",
    • "balance": "1.3300",
    • "dailyAccrual": "0.8500"
    }
}

Loyalty Balance Log Deletion

Deletes a change from the loyalty balance log for a customer. For example, this will occur if a customer begins to redeem points in a transaction but the transaction is subsequently voided before completion.

path Parameters
customer
required
string
Example: 400000000123

The customer account number (Customer ID) of the customer record from which a loyalty record is to be deleted

id
required
string <uuid>
Example: 9df9f9bf-2984-4dee-909b-5af63c734054

The unique identity of the log entry to be deleted from the loyalty balance log for a customer.

Responses

Response Schema: application/json
message
string

A human readable description of the response(Error details or other information useful for debugging).

object (LoyaltyBalance)

The balance of a single loyalty points program.

name
required
string [ 1 .. 32 ] characters

The name of the loyalty point program

balance
required
number <decimal>

The current balance of this loyalty program.

Note: When a program is configured to display as 'points' in ECRS CATAPULT then a single point is equivalent to 0.01 in this field. When program is configured to display as a dollar value then this field is displayed rounded to 2-decimal places.

dailyAccrual
number <decimal>

The number of points the customer has accrued on the current business day.

Response samples

Content type
application/json
{
  • "message": "OK",
  • "program": {
    • "name": "Default Program",
    • "balance": "1.3300",
    • "dailyAccrual": "0.8500"
    }
}