Third-Party Loyalty API (5.8.195)

Overview

What is the Third-Party Loyalty API?

This RESTful API provides third parties with the capability to check, decrement, and accrue a customer's loyalty balance for a specified Loyalty Program within the CATAPULT database. With CATAPULT, loyalty point amounts and balances are represented as integer loyalty points/cents. Examples:

Loyalty Points	Corresponding Dollar Value
1	$0.01
5	$0.05
10	$0.10
50	$0.50
100	$1.00
1000	$10.00
10000	$100.00

Requirements

Property Requirements

Across all of the endpoints within this API, specific properties are shared and used which require a specific standard/format. These requirements are detailed below:

Time - For any endpoint that uses the time property, the RFC-3339 date-time format must be used. Unix epoch values, including epoch milliseconds, are not supported. Example RFC-3339 date-time formats:
- 2026-09-03T09:30:00Z
- 2026-09-04T09:30:00-05:00
- 2026-09-05T09:30:00-06:00
- 2026-09-06T09:30:00-07:00
- 2026-09-07T09:30:00-08:00
- 2026-09-08T09:30:00-09:00
- 2026-09-09T09:30:00-10:00
Loyalty Program IDs - When using any of the endpoints in this API to check, decrement, or accrue loyalty points for a customer, the associated Loyalty Program must be specified by including a Loyalty Program ID. The Loyalty Program ID - programId - is a unique identifier assigned to the desired Loyalty Program by the CATAPULT database. The CATAPULT merchant must work with ECRS to obtain this ID for their desired Loyalty Program(s) so that it can be used in the requests to each endpoint.
Request Identifier - When making a request through any of the endpoints in this API, each request must include a unique identifier. The unique identifier for each request must follow Universally Unique Identifier (UUID) format. Example: "identifier": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
Requestor - When using any of the endpoints in this API, the requestor property must be included in the request. This property is used to record who made the request to update the customer's loyalty balance, and is not automatically derived from the API-key employee identity. The text entered for this property will appear as the "Cashier Name" for the corresponding loyalty update on the Loyalty Points Activity report.

Best Practices for requestor Property

Because the text entered in requestor property will appear as the "Cashier Name" on the Loyalty Points Activity report, it's a best practice to enter text that is descriptive and indicative (e.g., API Loyalty Adjustment, ECRS Loyalty API, etc.).

Each endpoint has an associated requestor property. This, in turn, allows for the requestor property to be unique for each endpoint. However, for reporting consistency, it's recommended to use the same text for the requestor property across all endpoints.

In addition, the requestor property for each endpoint does not allow you to enter store-specific contents. Meaning, if you have multiple stores in your operation, or even multiple store banners in your operation (under the same Headquarters), the property will be the same for each store using the endpoint(s). As a result, it is a best practice to enter text for the requestor property that is universally understood across your operation.

Guidance for Invalid Requests

Adjusting a customer's loyalty point balance is an action that is not to be taken lightly, as these points often determine what rewards a customer is eligible to receive and their overall experience with the store. As a result, the requests through each endpoint to update or act on a customer's loyalty balance must adhere to the requirements outlined in this document. However, should an invalid request be sent, the API will provide an error code and specific guidance (i.e., description) on why the request was invalid. These error codes, and corresponding descriptions, can be seen in the table below.

Error Code	Description
1	Not Authorized
2	Invalid Customer
3	Invalid Loyalty Program
4	Data Access Error
5	Insufficient Balance
6	Pre-Authorization Already Complete
7	Pre-Authorization Identifier Duplicated with Differing Values
8	Completion Identifier Duplicated with Differing Values
9	Cannot Authorize 0-points
10	No Corresponding Pre-Authorization
11	Missing Identifier
12	Accrual Amount Must Be Greater Than Zero
999	Unknown Error

Document Revision History

Current Revision: 5.8.195

5.8.195 Revision

Revision Date

09/08/2026

New

Added the Accrue Loyalty Balance endpoint. This endpoint allows for the Point of Sale system processing the transaction (not CATAPULT) to post updates to the CATAPULT database and update the loyalty balance of the customer associated with the transaction.

Fixes & Improvements

The definitions and examples of many endpoint properties have been enhanced and clarified throughout the documentation.

Older Revisions

5.8.183

Revision Date

03/11/2026

New

Added Revision History to this document.

Fixes & Improvements

No fixes or improvements were made with this revision.

5.8.182 and Older

Revision History for this document started with Revision 5.8.183. As such, revision history for older versions is not included here. However, any new features or functions added previously are noted - by version - throughout the documentation.

Endpoints

Balance-Check

Gets a customer's current loyalty balance, in loyalty points/cents, which can be used for providing discounts. If a loyalty program is not specified, the default loyalty program is used.

Authorizations:

PreSharedKey

query Parameters

customer required	string [ 1 .. 16 ] characters Example: customer=40100637000240 The customer's account or card number.
requestor	string [ 1 .. 62 ] characters Example: requestor=ECRS Loyalty API Identifier for the entity making the request. Once entered, the identifier is echoed in the response and recorded as the "Cashier Name" on the Loyalty Points Activity report in CATAPULT Web Office.
time	string <date-time> Example: time=2018-03-20T09:12:28Z The date and time, in RFC-3339 format, for the request. Once entered, the date-time is echoed in the response. Unix epoch values are not supported.
programId	string [ 1 .. 32 ] characters Example: programId=0-1 The unique identifier of the CATAPULT Loyalty Program, as assigned by the CATAPULT Database. If no value is entered for this property, a default value of "0-1" will be used. If you do not know the programId of the desired Loyalty Program, work with the merchant to obtain it, as ECRS must assist in providing the ID from the database.

Responses

Response Schema: application/json

customer required	string [ 1 .. 16 ] characters The customer's account or card number, echoed from the request.
requestor required	string [ 1 .. 62 ] characters The identifier for the entity requesting the balance, echoed from the request.
time required	string <date-time> The requestor's RFC-3339 date-time value, echoed from the request.
programId required	string The unique identifier for the CATAPULT Loyalty Program, as assigned by the CATAPULT Database. This identifier will be echoed from the request.
balance required	integer The current available balance of the loyalty program, in loyalty points/cents.

Response Schema: application/json

code required	integer A code that is representative of why the request failed. The provided code should be paired with the associated `description` for failure details. See the Guidance for Invalid Requests section above for the complete list of codes.
description required	string A description that provides details on why the request failed. The description is paired with a `code` to represent the complete failure details. See the Guidance for Invalid Requests section above for the complete list of descriptions.

Response samples

Content type

application/json

{"customer": "40100637000240",
"requestor": "ECRS Loyalty API",
"time": "2018-03-20T09:12:28Z",
"programId": "0-1",
"balance": 163
}

Pre-Authorization

Preauthorizes an amount for a customer. This locks the requested cents from being used by another transaction until a corresponding completion call is made or the preauthorization timeout elapses. If amount is omitted, the customer's entire available balance for the selected program is requested; at least 1 cent is required.

Authorizations:

PreSharedKey

Request Body schema: application/json

customer required	string [ 1 .. 16 ] characters The customer's account or card number.
requestor required	string [ 1 .. 62 ] characters Identifier for the entity making the request. Once entered, the identifier is echoed in the response and recorded as the "Cashier Name" on the Loyalty Points Activity report in CATAPULT Web Office.
time required	string <date-time> The date and time, in RFC-3339 format, for the request. Once entered, the date-time is echoed in the response. Unix epoch values are not supported.
programId	string [ 1 .. 32 ] characters The unique identifier of the CATAPULT Loyalty Program, as assigned by the CATAPULT Database. If no value is entered for this property, a default value of "0-1" will be used. If you do not know the programId of the desired Loyalty Program, work with the merchant to obtain it, as ECRS must assist in providing the ID from the database.
discount	string <= 128 characters The optional description of the discount for which the pre-authorized points are being used.
amount	integer >= 1 The amount to preauthorize, in cents. If omitted, the entire available balance for the selected program is preauthorized. The amount must be at least 1, and an error is returned if the customer does not have sufficient balance.
identifier required	string <uuid> A UUID used for tracking the request and preventing duplicates when retrying a failed request. If the same UUID is repeated in an identical request, the request succeeds without changing the customer's available balance. This allows a request to be retried after a timeout without duplicating the deduction. The response sets `dupe` to true. If the request has already been completed then an error will be returned.

Responses

Response Schema: application/json

customer required	string [ 1 .. 16 ] characters The customer's account or card number, echoed from the request.
requestor required	string [ 1 .. 62 ] characters An identifier for the entity making the request. Echoed from the request and recorded as the "Cashier Name" on the Loyalty Points Activity report in CATAPULT Web Office.
time required	string <date-time> The date and time of when the request took place.
programId required	string [ 1 .. 32 ] characters The unique identifier for the CATAPULT Loyalty Program, as assigned by the CATAPULT Database. This identifier will be echoed from the request.
discount	string <= 128 characters An optional description of the discount for which the pre-authorized points are being used.
amount required	integer The amount preauthorized from the customer's loyalty balance, in loyalty points/cents.
identifier required	string <uuid> The unique identifier of the discount for which the pre-authorized points are being used.
balance required	integer The available remaining balance for the current program, in loyalty points/cents.
dupe	boolean Default: false True if this response is a duplicate of a prior response with the same identifier.

Response Schema: application/json

code required	integer A code that is representative of why the request failed. The provided code should be paired with the associated `description` for failure details. See the Guidance for Invalid Requests section above for the complete list of codes.
description required	string A description that provides details on why the request failed. The description is paired with a `code` to represent the complete failure details. See the Guidance for Invalid Requests section above for the complete list of descriptions.
identifier	string <uuid> The identifier for the request, if available.
balance	integer If the authentication, customer, balance, and loyalty program were valid. The balance of the customer will be returned.

Request samples

Payload

Content type

application/json

Example

Pre-Auth Entire Balance of Default Program

{"customer": "40100637000240",
"requestor": "ECRS Loyalty API",
"time": "2019-08-24T14:15:22Z",
"discount": "15c",
"identifier": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Response samples

Content type

application/json

{"customer": "40100637000240",
"requestor": "Third-Party",
"time": "2019-08-24T14:15:22Z",
"programId": "0-1",
"discount": "15c",
"amount": 100,
"identifier": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"balance": 63,
"dupe": false
}

Completion

Called when a transaction is complete. This can complete a matching preauthorization or apply a direct deduction. If amount is omitted, the matching preauthorization amount is used; if no matching preauthorization exists, the customer's full available balance is used. A zero amount cancels a matching preauthorization and is otherwise rejected.

Authorizations:

PreSharedKey

Request Body schema: application/json

customer required	string [ 1 .. 16 ] characters The customer's account or card number.
requestor required	string [ 1 .. 64 ] characters Identifier for the entity making the request. Once entered, the identifier is echoed in the response and recorded as the "Cashier Name" on the Loyalty Points Activity report in CATAPULT Web Office.
time required	string <date-time> The date and time, in RFC-3339 format, for the request. Once entered, the date-time is echoed in the response. Unix epoch values are not supported.
programId	string [ 1 .. 32 ] characters The unique identifier of the CATAPULT Loyalty Program, as assigned by the CATAPULT Database. If no value is entered for this property, the loyalty program from the matching preauthorization is used when available. Otherwise, a default value of "0-1" will be used. If you do not know the programId of the desired Loyalty Program, work with the merchant to obtain it, as ECRS must assist in providing the ID from the database.
discount	string <= 128 characters The optional description of the discount for which the pre-authorized points are being used.
amount	integer >= 0 The amount to deduct, in cents. If omitted and there is no corresponding preauthorization, the customer's full available balance will be deducted. If omitted and there is a corresponding preauthorization, its amount will be used. An error is returned if the customer does not have sufficient balance.
identifier required	string <uuid> A UUID used for tracking the request and preventing duplicates when retrying a failed request. If the same UUID is repeated in an identical request, the request succeeds without changing the customer's available balance. This allows a request to be retried after a timeout without duplicating the deduction. The response sets `dupe` to true. If the identifier matches the identifier for a preceding pre-auth request then that pre-auth will be updated with the completed amount and made permanent. If the amount on a completion request is 0 then any matching pre-auth will be cancelled. Otherwise a zero amount will result in an error.

Responses

Response Schema: application/json

customer required	string [ 1 .. 16 ] characters The customer's account or card number, echoed from the request.
requestor required	string [ 1 .. 62 ] characters An identifier for the entity making the request. Echoed from the request and recorded as the "Cashier Name" on the Loyalty Points Activity report in CATAPULT Web Office.
time required	string <date-time> The date and time when the request took place.
programId required	string [ 1 .. 32 ] characters The unique identifier of the CATAPULT Loyalty Program, as assigned by the CATAPULT Database. This identifier will be echoed from the request.
discount	string <= 128 characters The optional description of the discount for which the pre-authorized points are being used.
amount required	integer The amount deducted from the customer's loyalty balance, in loyalty points/cents.
identifier required	string <uuid> The unique identifier of the request, which is echoed from the corresponding property in the request.
balance required	integer The available remaining balance for the selected program, in loyalty points/cents.
dupe	boolean Default: false True if this response is a duplicate of a prior response with the same identifier.

Response Schema: application/json

code required	integer A code that is representative of why the request failed. The provided code should be paired with the associated `description` for failure details. See the Guidance for Invalid Requests section above for the complete list of codes.
description required	string A description that provides details on why the request failed. The description is paired with a `code` to represent the complete failure details. See the Guidance for Invalid Requests section above for the complete list of descriptions.
identifier	string <uuid> The identifier of the request, if available.
balance	integer If the authentication, customer, balance, and loyalty program were valid. The balance of the customer will be returned.

Request samples

Payload

Content type

application/json

Example

100 Cents from Default Program

{"customer": "40100637000240",
"requestor": "ECRS Loyalty API",
"time": "2019-08-24T14:15:22Z",
"discount": "15c",
"amount": 100,
"identifier": "14d3030c-3b61-4070-b902-342f80e99364"
}

Response samples

Content type

application/json

{"customer": "40100637000240",
"requestor": "Third-Party",
"time": "2019-08-24T14:15:22Z",
"programId": "0-1",
"discount": "15c",
"amount": 100,
"identifier": "14d3030c-3b61-4070-b902-342f80e99364",
"balance": 63,
"dupe": false
}

Accrue Loyalty Balance

Context

If a CATAPULT merchant opts to do so, their customers can earn loyalty points based on the items they purchase in a transaction. Once a transaction completes, the point of sale system is responsible for updating the customer's loyalty account balance (based on the items purchased in the transaction).

Requirements

The merchant must be running CATAPULT 5.8.195 or newer in their store to use this endpoint.
The Employee Record (in CATAPULT) associated with the API Key must have the Adjust Loyalty Points checkpoint enabled in their assigned Authorization Security profile. Note that the "API Key Employee" is used for authorization only; the requestor property with the endpoint is used to record the "Cashier Name" on the Loyalty Points Activity report (i.e., record who performed the loyalty points adjustment).

Endpoint Purpose

This endpoint allows for a specified amount to be added directly to a customer's loyalty balance. The amount and resulting balance are represented as integer cents.

Authorizations:

PreSharedKey

Request Body schema: application/json

customer required	string [ 1 .. 16 ] characters The customer's account or card number.
requestor required	string [ 1 .. 62 ] characters Identifier for the entity making the request. Once entered, the identifier is echoed in the response and recorded as the "Cashier Name" on the Loyalty Points Activity report in CATAPULT Web Office.
time required	string <date-time> The date and time, in RFC-3339 format, for the request. Once entered, the date-time is echoed in the response. Unix epoch values are not supported.
programId	string [ 1 .. 32 ] characters The unique identifier of the CATAPULT Loyalty Program, as assigned by the CATAPULT Database. If no value is entered for this property, a default value of "0-1" will be used. If you do not know the programId of the desired Loyalty Program, work with the merchant to obtain it, as ECRS must assist in providing the ID from the database.
amount required	integer >= 1 The positive amount to add to the associated customer's loyalty balance, in loyalty points/cents. For example, entering 125 for this property adds 125 points (i.e., $1.25).
identifier required	string <uuid> A Universally Unique Identifier (UUID) used to identify this accrual request and prevent a retry from adding the amount again. The identifier is an idempotency key. Repeating the same identifier returns a successful result with `dupe` set to `true` and does not add the amount again.

Responses

Response Schema: application/json

amount required	integer The accrued amount, in loyalty points/cents.
balance required	integer The customer's current loyalty balance, in loyalty points/cents.
customer required	string The customer's account or card number.
dupe required	boolean Default: false True when the request repeats a prior successful accrual with the same identifier.
identifier required	string <uuid> The UUID identifier for the request.
programId required	string The unique identifier for the CATAPULT Loyalty Program, as assigned by the CATAPULT Database. This identifier will be echoed from the request.
requestor required	string An identifier for the entity making the request. Echoed from the request and recorded as the "Cashier Name" on the Loyalty Points Activity report in CATAPULT Web Office.
time required	string <date-time> The requestor's date and time, echoed from the request.

Response Schema: application/json

balance	integer The customer's current loyalty balance, in cents, when available.
code required	integer A code that is representative of why the request failed. The provided code should be paired with the associated `description` for failure details. See the Guidance for Invalid Requests section above for the complete list of codes.
description required	string A description that provides details on why the request failed. The description is paired with a `code` to represent the complete failure details. See the Guidance for Invalid Requests section above for the complete list of descriptions.

Response Schema: application/json

code required	integer A code that is representative of why the request failed. The provided code should be paired with the associated `description` for details on why the request failed.
description required	string A description that provides details on why the request failed. The description is paired with a `code` to represent the complete failure details.

Request samples

Payload

Content type

application/json

{"amount": 125,
"customer": "40100637000240",
"programId": "0-1",
"identifier": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"requestor": "ECRS Loyalty API",
"time": "2026-08-07T14:15:22Z"
}

Response samples

Content type

application/json

Example

Successful Accrual

{"amount": 125,
"balance": 4800,
"customer": "40100637000240",
"dupe": false,
"identifier": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"programId": "0-1",
"requestor": "ECRS Loyalty API",
"time": "2026-08-07T14:15:22Z"
}