ECRS Logo
API docs by Redocly

Digital Coupon and External Loyalty API Client (5.8.165)

Overview

The Digital Coupon and External Loyalty API Client is a RESTful API Client that can be leveraged by a third party to allow CATAPULT Point of Sale (POS) terminals and CATAPULT WebCart™ sites to interact with external digital coupon and loyalty providers.

The requests are made directly from the individual POS or WebCart terminals to a server provided by the Third-Party provider. All requests expect to receive a response within a default of 5 seconds or the request will be aborted and the response ignored unless otherwise noted.

Advanced Settings for Set Up & Configuration

Configuration of the POS to make calls to an implementation of this server is controlled by Advanced Settings defined within CATAPULT Web Office. These Advanced Settings can be any combination of enterprise, store, or terminal specific.

  • com.ecrsoft.tserver.genericcoup.url - Indicates the URL and path the POS will attempt to use to communicate with the defined service (e.g., https://your.domain.com/). Required

    • Security Requirements: Must use HTTPS protocol with TLS 1.2 or higher for secure communication.

  • com.ecrsoft.tserver.genericcoup.useExternalImages

    • Available with CATAPULT Transaction Server 5.7.158.9+ and 5.8.165+ | Defaults to false
    • Version Restriction: This feature is disabled and cannot be enabled on prior versions of CATAPULT Transaction Server for security reasons.
    • Applying and setting the value of this Advanced Setting to true will cause the API to expect and use the imageUrl exactly as provided in the response to the /coupons endpoint.
    • If the value of this Advanced Setting is set to false, or is not applied at all, then the API will append the path specified in the imageUrl - as provided in the response to the /coupons endpoint - to the URL entered with the com.ecrsoft.tserver.genericcoup.url Advanced Setting.
    • This Advanced Setting should be applied (i.e., value = true) if the coupon images are hosted on a different domain than the one specified with the com.ecrsoft.tserver.genericcoup.url Advanced Setting.
    • This Advanced Setting should NOT be applied if the coupon images are hosted on the same domain as specified with the com.ecrsoft.tserver.genericcoup.url Advanced Setting.
    • For external images to display correctly on WebCart, ensure your Content Security Policy (CSP) is configured appropriately. For guidance, refer to Maintaining a Secure Content Security Policy (CSP).

  • com.ecrsoft.tserver.genericcoup.siteid - The site ID to be provided in requests. Required

  • com.ecrsoft.tserver.genericcoup.name - The name of the digital coupon service as it is displayed in the Point of Sale (ie on a busy dialogue for slow responses.). Required

  • com.ecrsoft.tserver.genericcoup.username - The username to be provided as part of the basic auth credentials. Required

  • com.ecrsoft.tserver.genericcoup.password - The password to be provided as part of the basic auth credentials. Required

  • com.ecrsoft.tserver.genericcoup.sharedkey - A shared key which can optionally be provided as as field on some requests. Defaults to empty.

  • com.ecrsoft.tserver.genericcoup.sharedsecret - A shared secret which can optionally be provided as field on some requests. Defaults to empty.

  • com.ecrsoft.tserver.genericcoup.cancelPost - If true the the cancel request is sent as a POST instead of as a GET. Defaults to false

  • com.ecrsoft.tserver.genericcoup.selfStacking - If true then the this service allows applying multiple provided coupons/discounts to the same item, if false then the POS will apply only the best provided coupon/discount to each individual item. Defaults to false.

  • com.ecrsoft.tserver.genericcoup.stackingMode - Determines how coupons/discounts provided by this service stack with physical coupons. Possible options include:

    • NONE: There are no stacking rules, both digital and physical coupons can apply to the same item. This is the default.
    • DIGITAL_FIRST: Digital coupons apply first, removing paper coupons as needed.
    • PHYSICAL_FIRST: Paper coupons apply first, removing digital coupons as needed.
    • NATURAL: If a coupon is already on the transaction then allow it to remain.

  • com.ecrsoft.tserver.genericcoup.commitEmpty - If true then a commit is sent when the transaction ends even if no coupons/discounts were applied to the transaction. Defaults to false.

  • com.ecrsoft.tserver.genericcoup.abortWithoutCustomer - If true then transaction updates are not sent when no customer is associated with the transaction, and if a customer is dissociated from the transaction then a cancel request is sent. Defaults to true.

  • com.ecrsoft.tserver.genericcoup.sendTransientUpdates - If true then transaction update requests are sent anytime an item is added/removed/updated or a customer is associated to the transaction. Defaults to false.

  • com.ecrsoft.tserver.genericcoup.sendPhones - If true then transaction update requests are sent with the list of phone numbers associated with the customer. Defaults to false.

  • com.ecrsoft.tserver.genericcoup.sendEmails - If true then transaction update requests are requests are sent with the list of email addresses associated with the customer. Defaults to false.

  • com.ecrsoft.tserver.genericcoup.demographics - If true then a POST will be made to the demographics method when an attempt is made to associate an unidentified customer. Defaults to false

Backwards Compatibility

  • While ECRS attempts to maintain backwards compatibility whenever possible this API is subject to change without notice.
  • Providers are encouraged to ignore unrecognized fields in requests in order to improve compatibility across versions.
  • ECRS will attempt to add only optional fields to responses and assume a backwards compatible default when not present.

Security Requirements

Image URL Security (CATAPULT 5.7.158.9+ and 5.8.165+)

All image URLs provided in coupon responses are subject to the following seurity validations:

  • Protocol: Must use HTTPS with TLS 1.2 or higher
  • Content-Type: Must be one of the following allowed image types:
    • image/jpeg
    • image/png
    • image/gif
  • Content-Length: Must not exceed 50MB (52,428,800 bytes)
  • Validation: URLs are validated via HTTP HEAD request before image retrieval
  • Failure Handling: Images that fail validation are rejected and not displayed

Base URL Security

The base URL configured in com.ecrsoft.tserver.genericcoup.url must use HTTPS with TLS 1.2 or higher for secure API communication.

Minimum CATAPULT Transaction Server Version

  • 5.5.6.90 or Newer

Document Revision History

Current Revision

  • 5.8.165

Revision Date

  • 07/11/2025

New

Enhanced Security Requirements (Added comprehensive validation for image URLs and base URLs)

  • Image URLs must use HTTPS with TLS 1.2 or higher
  • Image content-length limited to 50MB maximum
  • Image content-type restricted to: image/jpeg, image/png, and image/gif
  • Base URL must use HTTPS with TLS 1.2 or higher
  • Version restriction added to com.ecrsoft.tserver.genericcoup.useExternalImages setting to prevent enabling on prior versions

Fixes & Improvements

General

  • Added guidance to the Overview on configuring Content Security Policy (CSP) for external coupon images when using com.ecrsoft.tserver.genericcoup.useExternalImages.

Endpoint: /coupons (Clipping > GET Retrieve Coupons)

  • Added support for absolute imageUrl paths for images on different domains. Specifically, if coupon images are hosted at a different domain than defined in the com.ecrsoft.tserver.genericcoup.url Advanced Setting, applying this Advanced Setting (and having the Value be true) allows the API to correctly process and use the absolute URL of the image.

Older Revisions

1.0.8
  • Added com.ecrsoft.tserver.genericcoup.useExternalImages advanced setting to support external image sources. When enabled, this setting prevents the system from prepending the com.ecrsoft.tserver.genericcoup.url value to coupon images, allowing retailers to use images hosted at different base URLs.
1.0.7
  • Added option to send receipt lines as part of the transaction commit, these will be applied to the transaction on a best-effort basis.
  • Added ability to provide optional coupons which can be applied based on availability of points from supplied buckets.
1.0.6
  • Clarified settings required to enable and configure the POS to use this service.
  • Added option to send the transaction update request anytime an item is added/removed/updated on a transaction or when a customer is associated.
  • Added ability to send a customer field on TransactionUpdateResult that instructs the POS to associate a customer with the given ID to the transaction.
  • Added ability to send a type field on AppliedCoupon to aid in classifying coupons/discounts in reports.
  • Added ability to send receipt lines that should be placed on the receipt printed and/or emailed to the customer to TransactionUpdateResult. Note that customers can opt-out of receiving receipts if allowed by the retailer.
  • Added optional '/customer/demographics' path to return customer demographics when the POS attempts to associate an unknown phone number to a transaction.
1.0.5
  • Added ability to flag an AppliedCoupon to reduce the tax liability of the items to which it applies, by default coupons do not reduce tax.
1.0.4
  • Added site,customer,transaction fields to the UpdateTransactionRequest and CommitTransactionRequest.
  • /transaction/commit was erroneously defined as a GET method even though it had a request body defined.
1.0.3
  • Added cashier,terminal,time,subTotal,taxTotal,grossTotal fields to TransactionUpdateRequest.
  • Added receiptAlias to AppliedCoupon.
1.0.2
  • Added tenders field to the CommitTransactionRequest.
  • Added the dept field to Item.
1.0.1
  • Added the discountPrice field to Item.

Clipping

Retrieve Coupons

Used for retrieving the display data for all coupons available to a site/retailer.

This is cached in the POS/Webcart for quick search by and display to the consumer.

This method only needs to be implemented if the ability to clip coupons/discounts via the retailers coupon portal is needed. Otherwise only a stub needs to be implemented which returns an empty response.

query Parameters
site
required
string

The ID of the site to retrieve coupons for

Responses

Response Schema: application/json
Array of objects (Coupon)
Array
id
required
string [ 1 .. 16 ] characters

A unique ID for a coupon, used to identify the coupon in all other requests.

shortDescription
required
string <= 128 characters

Headline or name for the coupon.

requirementDescription
string <= 1024 characters

Describes what must be purchased to receive the discount.

longDescription
string <= 1024 characters

Additional information about the coupon. Typically display in a popup or more information area.

category
string <= 128 characters

A category to which the coupon belongs, ie Health and Beauty, Frozen Foods, Meat and Seafood

brand
string <= 128 characters

The brand name of the product to which the coupon applies.

startDate
string <date>

The first date that the coupon is available for redemption at the POS.

endDate
string <date>

The last date that the coupon is available for redemption at the POS.

imageUrl
string <= 1024 characters
  • If coupon images are hosted on the same domain defined in the com.ecrsoft.tserver.genericcoup.url Advanced Setting, this field represents the relative path of each image on that domain (e.g., /CouponImage24.jpg). This is the only option supported with CATAPULT 5.8.162 or older.
  • If coupon images are hosted at a different domain than defined in the com.ecrsoft.tserver.genericcoup.url Advanced Setting, this field represents the absolute URL of each image (e.g., https://image.domain.com/CouponImage25.jpg). With CATAPULT 5.7.158.13+ and 5.8.163+, this option is supported when the com.ecrsoft.tserver.genericcoup.useExternalImages Advanced Setting is applied and the Value is set to true.
targeted
boolean

Flag which indicates that the coupon should only be shown to specific customers.

enabled
boolean

Indicates if clipping is currently allowed for this coupon.

featured
boolean

Indicates that the coupons should be highlighted and/or brought to the top of search results.

requirementUpcs
Array of strings[ items = 14 characters ]

One or more of these UPCs must be purchased to receive the discount.

rewardUpcs
Array of strings[ items = 14 characters ]

One or more of these upcs will receive the discount, if not present the required upcs will receive the discount.

Response Schema: application/json
Array of objects (ErrorCode)

Error Code data if an error occurred, otherwise should not be present

Array
id
string
Enum: "REQUIRED_FIELDS_MISSING" "INVALID_SITE" "INVALID_CUSTOMER" "INVALID_COUPON_ID" "ALREADY_CLIPPED"

A short machine readable error message. The list provided is not all-inclusive.

details
string

A detailed human readable error message suitable for use debugging the application.

Response samples

Content type
application/json
{
  • "coupons": [
    • {
      • "id": "C2222",
      • "shortDescription": "10% Off A Certain Soft Drink",
      • "requirementDescription": "Buy One X Brand Soft Drink and get 10% Off. Valid between 7/28/16 and 7/28/17",
      • "longDescription": "Buy One X Brand Soft Drink and get 10% Off. Offer not valid in certain states and provinces.",
      • "category": "Beverages",
      • "brand": "Brand X",
      • "startDate": "2016-07-28",
      • "endDate": "2017-07-28",
      • "imageUrl": "/CouponImage24.jpg",
      • "targeted": false,
      • "enabled": true,
      • "featured": false,
      • "requirementUpcs": [
        • 894773001193,
        • 894773001049
        ],
      • "rewardUpcs": [ ]
      }
    ]
}

Customer Coupons

Used to determine the coupons which a particular customer can or has clipped.

This method only needs to be implemented if the ability to clip coupons/discounts via the retailers coupon portal is needed. Otherwise only a stub needs to be implemented which returns an empty response.

query Parameters
site
required
string

The ID of the site to retrieve coupons for.

customer
required
string

The ID of the customer to retrieve coupon metadata for. Typically a barcode from the customers card, however, it can be any arbitrary string that uniquely identifies the customer.

Responses

Response Schema: application/json
available
Array of strings[ items [ 1 .. 16 ] characters ]

The list of coupon ID's that are currently available to be clipped by the customer.

clipped
Array of strings[ items [ 1 .. 16 ] characters ]

The list of coupon ID's that are clipped by the customer and available to be used

redeemed
Array of strings[ items [ 1 .. 16 ] characters ]

The list of coupon ID's that have been redeemed by the customer. History should be limited to coupons redeemed at most 30 days ago.

expired
Array of strings[ items [ 1 .. 16 ] characters ]

The list of coupons ID's that were clipped by the customer but not used before expiration. History should be limited to coupons that expired at most 30 days ago.

pending
Array of strings[ items [ 1 .. 16 ] characters ]

The list of coupons that were clipped and are currently allocated to a transaction.

Response Schema: application/json
Array of objects (ErrorCode)

Error Code data if an error occurred, otherwise should not be present

Array
id
string
Enum: "REQUIRED_FIELDS_MISSING" "INVALID_SITE" "INVALID_CUSTOMER" "INVALID_COUPON_ID" "ALREADY_CLIPPED"

A short machine readable error message. The list provided is not all-inclusive.

details
string

A detailed human readable error message suitable for use debugging the application.

Response samples

Content type
application/json
{
  • "available": [
    • "2222"
    ],
  • "clipped": [
    • "1",
    • "2",
    • "3456",
    • "7890"
    ],
  • "redeemed": [
    • "C3"
    ],
  • "expired": [
    • "B2"
    ],
  • "pending": [
    • "A1"
    ]
}

Update Customer

Used to associate/clip a coupon to a customers card and/or unclip the coupon from the card.

Usually used for a single coupon at a time but could be used for batches of coupons.

This method only needs to be implemented if the ability to clip coupons/discounts via the retailers coupon portal is needed. Otherwise only a stub needs to be implemented which returns an empty response.

query Parameters
site
required
string

The ID of the site to edit coupons for

customer
required
string

The ID of the customer to edit coupons for.

Request Body schema: application/json

The ids of the coupons to be added and/or removed from the transaction.

add
Array of strings[ items [ 1 .. 16 ] characters ]

The list of coupons ID's to add to the customers card.

remove
Array of strings[ items [ 1 .. 16 ] characters ]

The list of coupon ID's to remove from the customers card.

Responses

Response Schema: application/json
added
Array of strings[ items [ 1 .. 16 ] characters ]

The list of coupon ID's added to the customer.

removed
Array of strings[ items [ 1 .. 16 ] characters ]

The list of coupon ID's removed from the customer.

Response Schema: application/json
Array of objects (ErrorCode)

Error Code data if an error occurred, otherwise should not be present

Array
id
string
Enum: "REQUIRED_FIELDS_MISSING" "INVALID_SITE" "INVALID_CUSTOMER" "INVALID_COUPON_ID" "ALREADY_CLIPPED"

A short machine readable error message. The list provided is not all-inclusive.

details
string

A detailed human readable error message suitable for use debugging the application.

Request samples

Content type
application/json
{
  • "add": [
    • "A123456",
    • "B654321"
    ],
  • "remove": [
    • "C2222"
    ]
}

Response samples

Content type
application/json
{
  • "added": [
    • "A123456",
    • "B654321"
    ],
  • "removed": [
    • "C2222"
    ]
}

Demographics

Get Demographics

Look up demographic data of a customer using Phone Numbers and/or Email Addresses.

This may be used if customer association via phone number or email address is performed in the Catapult POS and no matching customer is found. A request can be made to this method to pre-populate the fields used to create a local copy of the customer within Catapult.

This method will only be called if the 'com.ecrsoft.tserver.genericcoup.demographics' advanced setting is enabled.

query Parameters
site
required
string

The ID of the site to edit coupons for

Request Body schema: application/json

Information known about the customer to be looked up.

phones
Array of strings[ items <= 10 characters ]

A list of numeric phone numbers associated with the current customer. These are typically 10 digits.

emails
Array of strings[ items [ 1 .. 254 ] characters ]

A list of email addresses associated with the current customer.

Responses

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

The account number or ID of a customer

firstName
string <= 25 characters

The first name of the customer if available. This field is optional and may be used to add or update records in the Catapult customer database to keep it synchronized with the provider.

lastName
string <= 25 characters

The last name of the customer if available. This field is optional and may be used to add or update records in the Catapult customer database to keep it synchronized with the provider.

email
string <= 254 characters

The email address of the customer if available. This field is optional and may be used to add or update records in the Catapult customer database to keep it synchronized with the provider. It may also be used to send eReceipts to the customer.

phone
string <= 14 characters

The phone number of the customer if available. This field is optional and may be used to add or update records in the Catapult customer database to keep it synchronized with the provider. This is typically provided as 10 digits, however, common formatting and 1-digit country codes are acceptable but ignored by the POS.

Response Schema: application/json
Array of objects (ErrorCode)

Error Code data if an error occurred, otherwise should not be present

Array
id
string
Enum: "REQUIRED_FIELDS_MISSING" "INVALID_SITE" "INVALID_CUSTOMER" "INVALID_COUPON_ID" "ALREADY_CLIPPED"

A short machine readable error message. The list provided is not all-inclusive.

details
string

A detailed human readable error message suitable for use debugging the application.

Response Schema: application/json
Array of objects (ErrorCode)

Error Code data if an error occurred, otherwise should not be present

Array
id
string
Enum: "REQUIRED_FIELDS_MISSING" "INVALID_SITE" "INVALID_CUSTOMER" "INVALID_COUPON_ID" "ALREADY_CLIPPED"

A short machine readable error message. The list provided is not all-inclusive.

details
string

A detailed human readable error message suitable for use debugging the application.

Request samples

Content type
application/json
{
  • "phones": [
    • "8282652907"
    ],
  • "emails": [
    • "support@ecrs.com"
    ]
}

Response samples

Content type
application/json
{
  • "id": "12345678901234",
  • "firstName": "John",
  • "lastName": "Smith",
  • "email": "support@ecrs.com",
  • "phone": "(123)456-7890"
}

Redemption

Update Transaction

Creates or updates the transaction in the coupon providers system so that they can tell the POS which coupons should be applied to the transaction with it's current items.

Coupons used should enter a pending state with the transaction's ID preventing their use on any other transaction unless the current transaction is cancelled or later updated to a state where the coupon would not be used. This prevents over-redemption if the same card is used at multiple locations simultaneously.

If the POS is configured to send transient updates(disabled by default), then updates will be sent with the transient field set to true any time an item is added/removed/changed or the associated customer is changed. Any AppliedCoupons returned in the response to a transient update will be ignored by the POS. However, the customer field on the result can still be used to trigger a customer association at the POS.

Non-transient updates will always be sent when the cashier totals the transaction at the POS or immediately prior to the first tender. It is possible for the cashier to make modifications to the sale following a total or partial tender, in this case a new non-transient update will be sent to the digital coupon provider before it is committed.

query Parameters
site
required
string

The ID of the site at which the transaction occurred

customer
required
string

The ID of the customer performing the transaction

transaction
required
string

The ID of the transaction being applied

Request Body schema: application/json

The new content of the transaction to be updated.

site
string

The ID of the site at which the transaction was performed.

customer
string

The ID of the customer to which the transaction belongs

phones
Array of strings[ items <= 10 characters ]

A list of numeric phone numbers associated with the current customer. These are typically 10 digits. Must be explicitly enabled via advanced setting.

emails
Array of strings[ items [ 1 .. 254 ] characters ]

A list of email addresses associated with the current customer. Must be explicitly enabled via advanced settings.

transaction
string

The ID of the transaction being committed.

cashier
integer <int32>

The number of the cashier ringing up this transaction as defined in CATAPULT.

terminal
integer <int32>

The number of the terminal/register at which this transaction is being rung up as defined in CATAPULT.

time
string <date>

The time at which the transaction update request was made on the terminal in ISO-8601 date and time format.

transientRequest
boolean

A true value in this field indicates that the transaction is expected to change before the final transaction update is transmitted and this update is meant to be informational. If false then further changes to the transaction may or may not occur(the last update prior to a commit will always be false). If true any AppliedCoupon objects in the result returned for the request will be ignored. Customer responses will still be handled.

Array of objects (Item)

The list of items currently on the transaction.

Array
id
integer <int32>

An unique ID for this line item within the transaction. Note that these values may not be sequential in the case of an item correct.

quantity
number

The quantity of this line item within the transaction.

upc
string [ 1 .. 14 ] characters

The UPC of this transaction within the transaction.

If the value stored in the catapult database is a valid UPC-A, UPC-E, or EAN-13 the POS will provide the value as GTIN-14 with check digit. Otherwise the POS will provide the barcode as it is defined.

price
number

The extended price of this line item.

discountPrice
number

The price of this line item after any store/system discounts have been applied.

dept
number

The department number to which this item belongs as defined in Catapult.

subTotal
number

The total price of all items on the transaction.

taxTotal
number

The total amount of taxes applied to the transaction.

grossTotal
number

The total price of all items on the transaction including taxes.

Responses

Response Schema: application/json
Array of objects (AppliedCoupon)

A list of all coupon applications that should be applied to this transaction.

Array
couponId
required
string [ 1 .. 15 ] characters

The ID of the coupon that was applied.

externalId
required
string <= 100 characters

An ID of the coupon in a Third-Party system to be stored with the redemption.

receiptAlias
string <= 33 characters

A description for the coupon to be shown to the customer on receipts and/or invoices. If field is not present a description will be generated based on the coupon id.

reducesTax
boolean

When true then this coupon will reduce the tax liability of the items to which it applies. If absent or false then the tax liability is not reduced by the coupon / discount applied.

type
string <= 30 characters

A string which describes the type of this coupon/discount. Only used for reporting purposes.

Array of objects (ItemDiscount)

The items to which the coupon applies. If not present or empty then total discount will be applied to the subtotal of the transaction.

Array
lineId
required
integer <int32>

The unique ID of the line item to which this discount should apply as provided on the ID field of Item.

discount
number

The portion of the discount that should apply to this item

totalDiscount
required
number

The total discount of this coupon.

object (OptionalCouponInfo)

Information describing an optional coupon, the cashier will be prompted to ask the cashier if they wish to apply this coupon based on the optional details.

prompt
string <= 1024 characters

The textual content of the question to present the cashier.

loyaltyId
string [ 1 .. 16 ] characters

If the optional coupon has a loyalty cost, then the ID of the loyalty program from which it should consume points must be provided. If no matching loyalty program is found in the balance list then a balance of 0 will be assumed and the coupon will not be offered.

loyaltyCost
integer <int32>

The cost of the coupon to be deducted from any available loyalty balance. The coupon will not be offered if an insufficient balance is available from the list of loyalty balances.

Array of objects (ReceiptLine)

A list of receipt lines to be placed on the receipt.

Array
type
required
string
Enum: "IMAGE" "TEXT" "C128" "CUT"

The type of coupon line

content
string

The content to be printed on the receipt.

For the IMAGE type this is the BASE64 Encoded content of an image. Not all receipt printer hardware supports all image formats, for best compatibility images should be 1-bit bitmap files no larger than 250x250 pixels.

For the TEXT type this is the content of the line. Receipt printers vary in the number of allowed columns per line, however, 40 is the most common receipt width.

For the C128 type this is the content of a Code 128 barcode to be printed on the receipt.

For the CUT type this field will be ignored.

object (CustomerDemographics)

A description of a customer

id
required
string [ 1 .. 16 ] characters

The account number or ID of a customer

firstName
string <= 25 characters

The first name of the customer if available. This field is optional and may be used to add or update records in the Catapult customer database to keep it synchronized with the provider.

lastName
string <= 25 characters

The last name of the customer if available. This field is optional and may be used to add or update records in the Catapult customer database to keep it synchronized with the provider.

email
string <= 254 characters

The email address of the customer if available. This field is optional and may be used to add or update records in the Catapult customer database to keep it synchronized with the provider. It may also be used to send eReceipts to the customer.

phone
string <= 14 characters

The phone number of the customer if available. This field is optional and may be used to add or update records in the Catapult customer database to keep it synchronized with the provider. This is typically provided as 10 digits, however, common formatting and 1-digit country codes are acceptable but ignored by the POS.

Array of objects (LoyaltyBalance)

An optional list of loyalty balances which are available to optional coupons within the transaction.

Array
id
required
string [ 1 .. 16 ] characters

A unique ID or name describing the loyalty program.

balance
integer <int32>

The available value for the loyalty program.

Response Schema: application/json
Array of objects (ErrorCode)

Error Code data if an error occurred, otherwise should not be present

Array
id
string
Enum: "REQUIRED_FIELDS_MISSING" "INVALID_SITE" "INVALID_CUSTOMER" "INVALID_COUPON_ID" "ALREADY_CLIPPED"

A short machine readable error message. The list provided is not all-inclusive.

details
string

A detailed human readable error message suitable for use debugging the application.

Request samples

Content type
application/json
{
  • "site": "STO1",
  • "customer": "412345",
  • "phones": [
    • "8282652907"
    ],
  • "emails": [
    • "support@ecrs.com"
    ],
  • "transaction": "1234-5678-1234",
  • "cashier": 99,
  • "terminal": 6,
  • "time": "2018-08-13T10:15:30",
  • "transientRequest": false,
  • "items": [
    • {
      • "id": 1,
      • "quantity": 2,
      • "upc": 894773001193,
      • "price": 1.99,
      • "discountPrice": 1.49,
      • "dept": 3
      }
    ],
  • "subTotal": 1.49,
  • "taxTotal": 0.2,
  • "grossTotal": 1.69
}

Response samples

Content type
application/json
{
  • "applied": [
    • {
      • "couponId": "A123456",
      • "externalId": "51112456789",
      • "receiptAlias": "Buy One Get One Free Dog Food",
      • "reducesTax": true,
      • "type": "Mfr Discount",
      • "items": [
        • {
          • "lineId": 4,
          • "discount": 1.5
          }
        ],
      • "totalDiscount": 1.5,
      • "optional": {
        • "prompt": "Would you like to use your ABCDEFG coupon for 100 points?",
        • "loyaltyId": "12345678901234",
        • "loyaltyCost": 100
        }
      }
    ],
  • "receiptLines": [
    • {
      • "type": "TEXT",
      • "content": " I'm a line to print on a receipt. "
      }
    ],
  • "customer": {
    • "id": "12345678901234",
    • "firstName": "John",
    • "lastName": "Smith",
    • "email": "support@ecrs.com",
    • "phone": "(123)456-7890"
    },
  • "loyaltyBalances": [
    • {
      • "id": "12345678901234",
      • "balance": 400
      }
    ]
}

Cancel Transaction

Cancels a transaction which was previously created. This changes the status of all coupons associated with the customer back to a clipped state so that they can be used on a future transaction.

This is typically done when a transaction is either voided or suspended at the POS. The transaction ID could be re-used if a cashier later resumes the transaction.

query Parameters
site
required
string

The ID of the site at which the transaction is being cancelled

customer
required
string

The ID of the customer cancelling the transaction

transaction
required
string

The ID of the transaction to be cancelled

Responses

Response Schema: application/json
Array of objects (ErrorCode)

Error Code data if an error occurred, otherwise should not be present

Array
id
string
Enum: "REQUIRED_FIELDS_MISSING" "INVALID_SITE" "INVALID_CUSTOMER" "INVALID_COUPON_ID" "ALREADY_CLIPPED"

A short machine readable error message. The list provided is not all-inclusive.

details
string

A detailed human readable error message suitable for use debugging the application.

Response samples

Content type
application/json
{
  • "errors": [
    • {
      • "id": "INVALID_SITE",
      • "details": "My Detailed Error Message."
      }
    ]
}

Commit Transaction

Mark all coupons in the provided list as having been redeemed.

Any coupons not in the list but marked pending for the given transaction are moved back to the clipped state.

If the coupon list is empty then all coupons currently marked as pending for the transaction should be redeemed.

query Parameters
site
required
string

The ID of the site at which the transaction is being committed

customer
required
string

The ID of the customer committing the transaction

transaction
required
string

The ID of the transaction to be committed

Request Body schema: application/json

The ID's of the coupons which were used on the transaction by the POS

site
string

The ID of the site at which the transaction was performed.

customer
string

The ID of the customer to which the transaction belongs

transaction
string

The ID of the transaction being committed.

coupons
Array of strings[ items [ 1 .. 15 ] characters ]

The list of coupons to be committed for a transaction.

Array of objects (CommitTender)

The list of tenders used to close this transaction. Tenders paid into the cash drawer will be negative.

Array
type
string
Enum: "CASH" "CHECK" "CREDIT" "DEBIT" "SNAP" "EBT_SNAP" "WIC" "WIC_EBT" "FSA_CREDIT" "FSA_DEBIT" "EBT_CASH_BENEFITS" "GIFT_CARD"

The type of this tender. The list provided is not all-inclusive.

amount
number

The amount tendered with this tender type.

Responses

Response Schema: application/json
Array of objects (ReceiptLine)

A list of receipt lines to be placed on the receipt. Note: When included on the commit response instead of the transaction update response the receipt lines are not guaranteed to be applied. If the server cannot be contacted(i.e., a network outage), then the commit will be delayed and tried periodically in the background. This would result in the commit receipt lines not being available when the customers receipt is initially printed.

Array
type
required
string
Enum: "IMAGE" "TEXT" "C128" "CUT"

The type of coupon line

content
string

The content to be printed on the receipt.

For the IMAGE type this is the BASE64 Encoded content of an image. Not all receipt printer hardware supports all image formats, for best compatibility images should be 1-bit bitmap files no larger than 250x250 pixels.

For the TEXT type this is the content of the line. Receipt printers vary in the number of allowed columns per line, however, 40 is the most common receipt width.

For the C128 type this is the content of a Code 128 barcode to be printed on the receipt.

For the CUT type this field will be ignored.

Response Schema: application/json
Array of objects (ErrorCode)

Error Code data if an error occurred, otherwise should not be present

Array
id
string
Enum: "REQUIRED_FIELDS_MISSING" "INVALID_SITE" "INVALID_CUSTOMER" "INVALID_COUPON_ID" "ALREADY_CLIPPED"

A short machine readable error message. The list provided is not all-inclusive.

details
string

A detailed human readable error message suitable for use debugging the application.

Request samples

Content type
application/json
{
  • "site": "STO1",
  • "customer": "412345",
  • "transaction": "1234-5678-1234",
  • "coupons": [
    • "A123456",
    • "B654321"
    ],
  • "tenders": [
    • {
      • "type": "CASH",
      • "amount": 5.21
      }
    ]
}

Response samples

Content type
application/json
{
  • "receiptLines": [
    • {
      • "type": "TEXT",
      • "content": " I'm a line to print on a receipt. "
      }
    ]
}