ECRS Logo
API docs by Redocly

Digital Coupon and External Loyalty API Client (5.8.189)

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 Transaction Server and CATAPULT WebCart™ sites to interact with external digital coupon and loyalty providers.

This is not a generic RESTful API. It is an API Client that sends requests from CATAPULT Transaction Server/WebCart to a third-party-hosted service. The third-party provider is responsible for implementing and hosting endpoints that respond to these requests within 5 seconds. If the response is not received within 5 seconds, the request will be aborted and the response ignored unless otherwise noted.

Use Cases

Use Case 1: Digital Coupon Redemption: A retailer integrates with a third-party coupon provider. When a customer scans their loyalty card, the Point of Sale (Transaction Server) sends a transaction update to the provider. The provider responds with applicable digital coupons, which are applied to the transaction.

Use Case 2: Loyalty Points Redemption: A customer with a loyalty account adds items to their cart. The Point of Sale (Transaction Server) sends a transaction update to the loyalty provider. The provider returns optional coupons that can be redeemed using loyalty points. The cashier is prompted to apply the coupon if the customer has sufficient balance.

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.

Requirements

There are certain prerequisites and configuration details that are required to successfully implement and operate the Digital Coupon and External Loyalty API Client. Review the requirements in this section thoroughly to ensure secure, compatible integration with CATAPULT Transaction Server and WebCart systems.

Advanced Settings for Set Up & Configuration

These settings are configured in CATAPULT Web Office and control how Transaction Server interacts with the third-party service. They may be applied at the enterprise, store, or terminal level.

Required Advanced Settings

  • com.ecrsoft.tserver.genericcoup.url - Specifies the URL and path that Transaction Server will use to communicate with the defined service (e.g., https://your.domain.com/). This value may be shared across the enterprise or configured uniquely for each location or instance.
    • Security Requirements: Must use HTTPS protocol with TLS 1.2 or higher for secure communication.
  • com.ecrsoft.tserver.genericcoup.siteid - The site ID to be provided in requests. This value may be shared across the enterprise or configured uniquely for each location or instance.
  • com.ecrsoft.tserver.genericcoup.name - The name of the digital coupon service as it is displayed at the Point of Sale (Transaction Server). For example, on a busy dialogue for slow responses.
  • com.ecrsoft.tserver.genericcoup.username - The username to be provided as part of the basic auth credentials.
  • com.ecrsoft.tserver.genericcoup.password - The password to be provided as part of the basic auth credentials.

Conditional Advanced Settings

  • com.ecrsoft.tserver.genericcoup.sharedkey (default = EMPTY): A shared key can optionally be provided as a field on some requests.
  • com.ecrsoft.tserver.genericcoup.sharedsecret (default = EMPTY): A shared secret can optionally be provided as field on some requests.
  • com.ecrsoft.tserver.genericcoup.cancelPost (default = FALSE): If true, the cancel request is sent as a POST instead of as a GET.
  • com.ecrsoft.tserver.genericcoup.selfStacking (default = FALSE): If true, multiple coupons/discounts can be applied to an item. If false, only the best provided coupon/discount will be applied to the item.
  • com.ecrsoft.tserver.genericcoup.commitEmpty (default = FALSE): If true, a commit is sent when the transaction ends even if no coupons/discounts were applied to the transaction.
  • com.ecrsoft.tserver.genericcoup.abortWithoutCustomer (default = TRUE): If true, transaction updates will not be sent when there is no customer linked to the transaction. Additionally, if a customer is removed from the transaction, a cancellation request will be triggered. This is typcially used to exchange all transaction data with a third party.
  • com.ecrsoft.tserver.genericcoup.sendTransientUpdates (default = FALSE): If true, transaction update requests are sent anytime an item is added/removed/updated or when a customer is associated to the transaction. This is typically used for real-time data exchange before the transaction is finalized with a tender.
  • com.ecrsoft.tserver.genericcoup.sendPhones (default = FALSE): If true, transaction update requests will include the list of phone numbers associated with the customer. This enables all customer phone numbers from CATAPULT to be posted to the third party.
  • com.ecrsoft.tserver.genericcoup.sendEmails (default = FALSE): If true, transaction update requests will include the list of email addresses associated with the customer. This enables all customer email addresses from CATAPULT to be posted to the third party.
  • com.ecrsoft.tserver.genericcoup.demographics (default = FALSE): If true, a POST request will be sent to the demographics method whenever there is an attempt to associate an unidentified customer. This can be used to allow for customer association from the PIN pad (e.g., phone number lookup) not found within CATAPULT, to request or query the third party for customer information.
  • com.ecrsoft.tserver.genericcoup.stackingMode: Determines how coupons/discounts from this service stack with physical (paper) coupons. The available options are:
    • NONE (default): No stacking rules are enforced. Both digital and physical coupons can be applied to the same item without restriction.
    • DIGITAL_FIRST: Digital coupons are applied first. If a paper coupon conflicts with a digital one, the paper coupon will be removed.
    • PHYSICAL_FIRST: Paper coupons are applied first. If a digital coupon conflicts with a paper one, the digital coupon will be removed.
    • NATURAL: If a coupon (digital or physical) is already applied to the transaction, it will remain. No additional stacking logic is enforced.
  • com.ecrsoft.tserver.genericcoup.useExternalImages (default = FALSE): If true, the API will expect and use the imageUrl exactly as proided in the response to the /coupons endpoint. If false, or not applied at all, the API will append the path speified 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.
    • Available with CATAPULT 5.7.158.16+ and 5.8.165+
    • Version Restriction: This feature is disabled and cannot be enabled on prior versions of CATAPULT for security reasons.
    • 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).

Security Requirements

Image URL Security (CATAPULT Transaction Server 5.7.158.9+ and 5.8.165+)

All image URLs provided in coupon responses are subject to the following security 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.189

Revision Date

  • 06/15/2026

New

  • N / A

Fixes & Improvements

Endpoint: /transaction/cancel (Redemption > GET Cancel Transaction)

  • If a transaction is completely voided, and a /transaction/cancel endpoint fails due to the terminal experiencing a network outage, then the "Cancel" request will be reattempted later when a stable connection is restored.

Older Revisions

5.8.167

Revision Date

  • 08/14/2025

New

Enhanced Overview Section

  • Added a description of the API Client and outlined its responsibilities.
  • Added two use cases to illustrate how the documentation supports coupons and loyalty scenarios.

New Requirements Section

  • Moved and organized Advanced Settings into this section by required or conditional.
  • Clarified Advanced Settings with additional context where needed.
  • Included the Requirements section in the Table Of Contents for easier navigation.

Fixes & Improvements

Endpoint: /coupons (Clipping > GET Retrieve Coupons)

  • Added a brief description for the coupons array.
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.
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 Transaction Server 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 Transaction Server 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 Transaction Server 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

This endpoint is used to retrieve the display data for all coupons available to a site/retailer. This data is cached in Transaction Server/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 retailer's 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)

List of digital coupons with display and eligibility details.

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.

endDate
string <date>

The last date that the coupon is available for redemption.

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.16+ and 5.8.165+, 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

This endpoint is 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 retailer's 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

This endpoint is used to associate/clip a coupon to a customer's card and/or unclip a coupon from the card. Typically, this endpoint is 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 retailer's coupon portal is needed. Otherwise only a stub needs to be implemented which returns an empty response.

query Parameters
site
required
string

The site ID where coupon data should be modified.

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

This endpoint is used to 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 at the Point of Sale (Transaction Server) 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 Transaction Server.

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

This endpoint is used to create or update the transaction in the coupon provider's system so that Transaction Server can be informed which coupons should be applied to the transaction with the 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 Transaction Server 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 Transaction Server. However, the customer field on the result can still be used to trigger a customer association at the Point of Sale.

Non-transient updates will always be sent when the cashier totals the transaction at Transaction Server 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, Point of Sale (Transaction Server) will provide the value as GTIN-14 with check digit. Otherwise TS 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 Transaction Server.

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

This endpoint is used to cancel a transaction that 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 Point of Sale (Transaction Server). The transaction ID could be re-used if a cashier later resumes the transaction.

If the server cannot be contacted (i.e., a network outage), and the transaction was completely voided, then the "Cancel" action will be delayed and tried periodically in the background until the action is successful.

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

This endpoint is used to 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.

If the server cannot be contacted (i.e., a network outage) during the "Commit" action, the action will be delayed and tried periodically in the background until successful.

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 Transaction Server (Point of Sale).

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. "
      }
    ]
}