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

ECRS® Third Party Price Computing Scale API Client (5.8.180)

Purpose

This document's purpose is to provide an introduction to the Third Party Price Computing Scale API Client, define the requirements that must be met in order to use the API client, and define the schema of the API client.

Intended Audience

The scale management provider is the intended audience for this document, as they will be using the Third Party Price Computing Scale API Client to send data between the CATAPULT system and in-store price computing scales. CATAPULT merchants (i.e., those retailers who use the CATAPULT® software suite) may also use this documentation as needed.

Overview

Capabilities of the Third Party Price Computing Scale API Client

  • The Third Party Price Computing Scale API Client - available from ECRS - is a RESTful API client that allows scale management providers to automatically receive updated inventory item data from merchants who use the CATAPULT software suite, so they can in turn send that data to connected, price computing scales.

  • The Third Party Price Computing Scale API Client truly is that; an API client. As such, the following is true:

    • The scale management provider is responsible for the development work necessary for integrating to and receiving data from the API client.
    • Query parameters and HTTP headers can be specified - if desired/required - and provided to the CATAPULT merchant for application and use.

  • To provide inventory data, the Third Party Price Computing Scale API Client will submit a POST request to the endpoint/server specified by the scale management provider.

  • Inventory data that is store-specific can be obtained from the merchant's CATAPULT database using the Third Party Price Computing Scale API Client. In a multi-store system, this allows for merchants to send item data that is only relevant at that store to the associated scales.

  • Should a request fail, the Third Party Price Computing Scale API Client will reattempt - up to 10 times - to send the request if any of HTTP error codes listed below are returned. Note that the reattempt will not be immediate; it will occur when the event runs (every five minutes) that initiates the request to send the updated data.

    • 404 (Not Found)
    • 408 (Request Timeout)
    • 500 (Internal Error)
    • 502 (Bad Gateway)
    • 503 (Service Unavailable)
    • 504 (Gateway Timeout)

Limitations of the Third Party Price Computing Scale API Client

  • The API client does not accept or help facilitate queries to the CATAPULT merchant's database. Only requests to the endpoint/server specified by the third-party scale management provider are possible.

  • The API client does not currently have a message/activity log that can be queried. However, an audit trail - which must be obtained by ECRS - is available upon request.

  • The API client can only be used with merchants who use the ECRS CATAPULT software suite.

  • The API client does not send new or updated item data immediately after the updates have been made (i.e., real-time updates); there is an event that runs every five (5) minutes that sends the updated data.

Requirements

API Client Communication Requirements

  • Communication with the Third Party Price Computing Scale API Client must occur using Transport Layer Security (TLS).

  • Where the Third Party Price Computing Scale API Client is the entity that submits a request, the server specified by the third-party scale management provider must accept POST requests.

  • For each request submitted by the Third Party Price Computing Scale API Client, the entity that receives that request (i.e., the scale management provider) must provide a true or false response. An optional message can be included with each response that provides any details about the response.

Requirements of the Third-Party Scale Management Provider

Provide Integration Data Points to CATAPULT Merchant

To allow the merchant to set up the Third Party Price Computing Scale API Client and correctly establish the communication between their database and the database of the scale management provider, the following must be provided to them:

  • URL - The desired web location where the API client will send item updates to. This field is required.

  • HEADER - The header will contain any desired parameters that are to be included in the header of the API client's request. The desired parameters must be in a JSON object and formatted as a string. Multiple key/value pairs must be separated by commas.

    EXAMPLE HEADER

    {"header1":"header1value","header2":"header2value"}

  • QUERY PARAMETERS - The query parameters are those that can be included with the request each time one is performed by the API client. The desired parameters must be a key=value pair and separated by an ampersand (&). The specified query parameters will automatically be added onto the URL specified each time the API client performs a request.

    EXAMPLE QUERY PARAMETERS

    parameter1=value1&parameter2=value2

Requirements of the CATAPULT Merchant

  • Have CATAPULT 5.8.167+ - The merchant must be running CATAPULT version 5.8.167 or newer at the store(s) where the Third Party Price Computing Scale API Client is to send data from. The API client is not compatible - and cannot be used - with any older versions of CATAPULT.

  • Set Up Integration Using Provided Data Points - Once the merchant is provided the URL and any optional HEADER and/or QUERY PARAMETER strings, they must use these data points to set up the integration between their system and the scale management provider. Instructions on how to set up this integration are detailed in this article.

Document Revision History

Current Revision: 5.8.180

Revision Date

  • 02/09/2025

New

  • N / A

Fixes & Improvements

  • Clarified that the required CATAPULT version is 5.8.167+, not 5.8.168+.

Older Revisions

5.8.168

Revision Date

  • 8/18/2025

New

  • Document Established

Fixes & Improvements

  • N / A

Endpoints

Scale-Eligible Items

  • This endpoint provides data for items that are sent to scales located in the deli, bakery, or otherwise. This data consists of general information about the item, nutritional information, ingredients, and store-specific information.

  • Unless otherwise noted, all item data is managed by the merchant in CATAPULT Web Office.

  • Unless otherwise noted, all store-specific item information will override any item-level (i.e., "global") information.

  • The first request from the Third Party Price Computing Scale API Client will contain all eligible inventory items (and their associated data). This initial set of data is determined by the merchant specifying the items in CATAPULT Web Office. Due to the amount of data, the item data will be paginated and potentially result in multiple requests. By default, there will be up to 100 items on a single page with each request. If a page does not contain 100 items, then it will only display the amount of data available on the page.

  • Once the initial set of item data has been sent, any updated data will be automatically included in different requests every five (5) minutes thereafter. This updated data can include new items altogether, or updates to existing items.

Request Body schema: application/json
deleted
required
boolean

Indicates if the item has been deleted.

  • true: Item has been deleted
  • false: Item has NOT been deleted
itemId
required
string [ 1 .. 16 ] characters

The Item ID (i.e., UPC, PLU, or SKU) of the item, as set in CATAPULT Web Office.

barcode
required
string

The code of a Type 2 formatted barcode of the itemId field. This format is controlled by the Barcode Format field in Scale Settings within CATAPULT Web Office. The Barcode Format field has the following options:

  • Match Item ID
  • 13 Digit Type 2 with leading zero
  • 13 Digit Type 2 with leading zeroes
required
Array of objects (Store)
  • An array of all store-specific data for the item.
  • Note that while this field is "required", no store-specific data for an item may be present, in which case null would be included in the request.
Array
deleted
required
boolean

Indicates if the item has been deleted from the associated store.

  • true: Item has been deleted
  • false: Item has NOT been deleted
storeId
required
string
  • The unique identifier of a store that was optionally provided to the CATAPULT merchant by the scale management provider.
  • This is NOT the Store ID entered into the Store Record in CATAPULT Web Office.
active
required
boolean

Indicates if the item is active at the scale (at the associated store).

  • true - or null - Item is active
  • false - Item is inactive
unitPrice
required
number <decimal(16,4)>
  • The item's price at the associated store. This price will be from Price Level 1 on the item's Inventory Record in CATAPULT Web Office.
  • For weighted items, this is the price per unit of measurement (e.g., $2.99 / lb)
  • For "by count" and "fixed weight" items, this is the price for the entire package.
divider
integer <= 999999999 characters

The pricing divider for the item, which will be the integer that the item's unitPrice is divided by.

unit
string

If an item is sold by weight, this is the item's unit of measure.

tare
number

The item's tare value at the store.

forceTare
boolean

Indicates whether or not the item is forced to have a tare at the store.

  • true - Tare will be forced.
  • false - Tare will NOT be forced.
descLine1
string <= 64 characters
  • The store-specific value entered for Deli Scale Attribute Description Line 1 for the item.
  • If an item does not have a store-specific Description Line 1, the general item level Description Line 1 will be used.
  • If no item or store-specific Description Line 1 values are present, the default Description Line 1 value - as entered in the Scale Settings of CATAPULT Web Office - will be used (if present).
descLine2
string <= 64 characters
  • The store-specific value entered for Deli Scale Attribute Description Line 2 for the item.
  • If an item does not have a store-specific Description Line 2, the general item level Description Line 2 will be used.
  • If no item or store-specific Description Line 2 values are present, the default Description Line 2 value - as entered in the Scale Settings of CATAPULT Web Office - will be used (if present).
descLine3
string <= 64 characters
  • The store-specific value entered for Deli Scale Attribute Description Line 3 for the item.
  • If an item does not have a store-specific Description Line 3, the general item level Description Line 3 will be used.
  • If no item or store-specific Description Line 3 values are present, the default Description Line 3 value - as entered in the Scale Settings of CATAPULT Web Office - will be used (if present).
descLine4
string <= 64 characters
  • The store-specific value entered for Deli Scale Attribute Description Line 4 for the item.
  • If an item does not have a store-specific Description Line 4, the general item level Description Line 4 will be used.
  • If no item or store-specific Description Line 4 values are present, the default Description Line 4 value - as entered in the Scale Settings of CATAPULT Web Office - will be used (if present).
byCountQty
integer <= 999 characters
  • The integer entered for Deli Scale Attribute By count quantity on the item.
  • If no store-specific byCountQty is entered, the item-level value will be used.
fixedWeight
integer <= 9999 characters
  • The integer entered for Deli Scale Attribute Fixed weight amount on the item.
  • If no store-specific Fixed weight amount is entered, the item-level value will be used.
shelfLife
integer <= 9999 characters
  • The store-specific Shelf Life of the item. Note that the value entered here will be associated with the option chosen for the store-specific shelfLifeByHours field.
shelfLifeByHours
boolean
  • Indicates if the item's store-specific shelfLife value is by days or by hours.
    • true = Hours
    • false = Days
useBy
integer <= 9999 characters

The number of days that an item is best by and should be used within, as entered in the Use Within X Days field on the Inventory Record in Web Office for a specific store.

ingredients
string <= 6000 characters

The entered list of ingredients for the item.

customerPrice
number

The price of the item if a customer is associated to the transaction.

customerDivider
integer <= 999999999 characters

The pricing divider for the item if a customer is associated to the transaction.

promoPrice
number

The promotional price of the item (if it is on promotion).

promoEnd
string

The date and time at which the promotional pricing for the item ends.

promptPrice
boolean

Indicates if the scale operator should be prompted to enter item's price when weighed/processed.

  • true - The scale operator will be prompted to enter the item's price.
  • false - The scale operator will NOT be prompted to enter the item's price.
Array of objects (NutritionData)

The item's store-specific nutritional data.

Array
servingSize
string

The item's recommended Serving Size.

servingsPerContainer
string

The number of servings - based on the servingSize - in the item's container.

Array of objects (NutrientTypes)
required
Array of objects (NutritionData)
  • An array of all nutritional data for the item.
  • Note that while this field is "required", no nutritional data for an item may be present, in which case null would be included in the request.
Array
servingSize
string

The item's recommended Serving Size.

servingsPerContainer
string

The number of servings - based on the servingSize - in the item's container.

Array of objects (NutrientTypes)
Array
type
required
string

The nutrients in the item. The following nutrient types can be specified:

  • VITAMIN_A
  • VITAMIN_C
  • THIAMIN
  • RIBOFLAVIN
  • NIACIN
  • CALCIUM
  • IRON
  • VITAMIN_D
  • VITAMIN_E
  • VITAMIN_B6
  • FOLIC_ACID
  • VITAMIN_B12
  • PHOSPHORUS
  • IODINE
  • MAGNESIUM
  • ZINC
  • COPPER
  • BIOTIN
  • PANTOTHENIC_ACID
  • BETA_CAROTENE
  • CHLORIDE
  • CHROMIUM
  • MANGANESE
  • MOLYBDENUM
  • SELENIUM
  • VITAMIN_K
  • CALORIES
  • CALORIES_FROM_FAT
  • TOTAL_FAT
  • SATURATED_FAT
  • CHOLESTEROL
  • TOTAL_CARBOHYDRATES
  • DIETARY_FIBER
  • SODIUM
  • SUGARS
  • PROTEIN
  • POTASSIUM
  • TRANS_FATTY_ACID
  • CALS_FROM_SAT_FAT
  • OTHER_CARBS
  • MONSAT_FAT
  • POLYSAT_FAT
  • INSOLUBLE_FIBER
  • SOLUBLE_FIBER
  • SUGAR_ALCOHOL
  • SAT_FAT_TRANS_FAT
  • CALS_FROM_SAT_TRANS
  • ENERGY
  • OMEGA_6_POLY
  • OMEGA_3_POLY
  • STARCH
  • ADDED_SUGAR
value
required
number

The amount of each nutrient. Note that each nutrient's associated unit (e.g., g for grams) is automatically implied by the nutrient itself.

deptNum
required
integer

The ID/Number of the Department that the item is assigned to.

descLine1
required
string <= 64 characters

The value entered for Deli Scale Attribute Description Line 1 for the item. Note that if an item does not have an assigned Description Line 1, the default Description Line 1 - as entered in the Scale Settings of CATAPULT Web Office - will be used (if present).

active
boolean

Indicates if the item is active at the scale.

  • true - or null - Item is active
  • false - Item is inactive
cool
string <= 100 characters

The item's entered Country of Origin Label.

descLine2
string <= 64 characters

The value entered for Deli Scale Attribute Description Line 2 for the item. Note that if an item does not have an assigned Description Line 2, the default Description Line 2 - as entered in the Scale Settings of CATAPULT Web Office - will be used (if present).

descLine3
string <= 64 characters

The value entered for Deli Scale Attribute Description Line 3 for the item. Note that if an item does not have an assigned Description Line 3, the default Description Line 3 - as entered in the Scale Settings of CATAPULT Web Office - will be used (if present).

descLine4
string <= 64 characters

The value entered for Deli Scale Attribute Description Line 4 for the item. Note that if an item does not have an assigned Description Line 4, the default Description Line 4 - as entered in the Scale Settings of CATAPULT Web Office - will be used (if present).

byCountQty
integer <= 999 characters

The integer entered for Deli Scale Attribute By count quantity on the item.

fixedWeight
integer <= 999 characters

The integer entered for Deli Scale Attribute Fixed weight amount on the item.

shelfLife
integer <= 999 characters

The entered Shelf Life of the item. Note that the value entered here will be associated with the option chosen for shelfLifeByHours.

shelfLifeByHours
boolean

Indicates if the item's entered shelfLife value is by days or by hours.

  • true = Hours
  • false = Days
useBy
integer <= 9999 characters

The number of days that an item is best by and should be used within, as entered in the Use Within X Days field on the Inventory Record in Web Office.

ingredients
string <= 6000 characters

The entered list of ingredients for the item.

Responses

Response Schema: application/json
success
required
boolean

When requests are sent from the "Scale-Eligible Items" endpoint, a true or false response must be provided to allow the API client to know that the request was received - or not received - successfully.

  • true: The request was received successfully.
  • false: The request was NOT received successfully.
message
string

Allows you to specify and include any desired text with the provided true or false response.

Request samples

Content type
application/json
{
  • "deleted": "false",
  • "itemId": "123456789",
  • "barcode": "0200123456789",
  • "stores": [
    • {
      • "deleted": "false",
      • "storeId": "27",
      • "active": "true",
      • "unitPrice": "4.9900",
      • "divider": "3",
      • "unit": "lb",
      • "tare": "0.25000",
      • "forceTare": "true",
      • "descLine1": "string",
      • "descLine2": "string",
      • "descLine3": "string",
      • "descLine4": "string",
      • "byCountQty": "6",
      • "fixedWeight": "3",
      • "shelfLife": "4",
      • "shelfLifeByHours": "false",
      • "useBy": "9",
      • "ingredients": "Yukon Gold Potatoes, Dill, Sour Cream, Mayonnaise, Salt, Pepper, Sugar, Onion Powder",
      • "customerPrice": "8.9900",
      • "customerDivider": "2",
      • "promoPrice": "6.9900",
      • "promoEnd": "2025-07-21 14:30:00",
      • "promptPrice": "true",
      • "nutrition": [
        • {
          • "servingSize": "3 OZ",
          • "servingsPerContainer": "2.5",
          • "values": [
            • {
              • "type": "VITAMIN_D",
              • "value": "30"
              }
            ]
          }
        ]
      }
    ],
  • "nutrition": [
    • {
      • "servingSize": "3 OZ",
      • "servingsPerContainer": "2.5",
      • "values": [
        • {
          • "type": "VITAMIN_D",
          • "value": "30"
          }
        ]
      }
    ],
  • "deptNum": 4,
  • "descLine1": "string",
  • "active": "true",
  • "cool": "Germany",
  • "descLine2": "string",
  • "descLine3": "string",
  • "descLine4": "string",
  • "byCountQty": "5",
  • "fixedWeight": "3",
  • "shelfLife": "5",
  • "shelfLifeByHours": "false",
  • "useBy": "10",
  • "ingredients": "Red Potatoes, Dill, Sour Cream, Mayonnaise, Salt, Pepper, Sugar"
}

Response samples

Content type
application/json
{
  • "success": "true",
  • "message": "string"
}