ECRS® Instant Item Detail API Client (5.8.180)

Purpose

This document's purpose is to provide an introduction to the Instant Item Detail API Client, define the requirements that must be met in order to use the API Client, and define the schema of the API Client.
This API Client was previously offered as the Third Party Label API Client, as its original purpose was to allow third party label service providers with inventory data to update physical or electronic labels. However, due to the data and capabilities that the API Client provides, it was renamed in revision 5.8.180 to the Instant Item Detail API Client. Any previous integrations previously established with the Third Party Label API Client will still be honored and function without issue. Likewise, the original use cases of the API Client are still possible.

Intended Audience

This document's intended audience is any user who intends to integrate with, or is interested in integrating with, the Instant Item Detail API Client to obtain inventory data from a CATAPULT system.

Overview

Capabilities of the Instant Item Detail API Client

The Instant Item Detail API Client - available from ECRS - is a RESTful API Client that allows users to automatically receive updated inventory item data from a CATAPULT system. Specifically, the data will be obtained from the headquarters CATAPULT database.
The Instant Item Detail API Client truly is that; an API Client. As such, the following is true:
- Any party who intends to use the API Client is responsible for the development required to integrate with and receive data from the API Client.
- Query parameters and HTTP headers can be specified if desired and/or required. These must be applied by the merchant in CATAPULT Web Office.
To provide the inventory data, the Instant Item Detail API Client will submit a POST request to the specified endpoint/server.
To provide images associated with inventory items, the Instant Item Detail Client will submit a POST request to the specified endpoint/server.
Store-specific inventory data can be obtained from the CATAPULT database using the Instant Item Detail API Client. In a multi-store system, this allows merchants to take advantage of inventory data that is relevant to any desired store, not just generic information.
In CATAPULT Web Office, both the Send items to 3rd party service function (in Inventory Maintenance) and the Export All function (in Third Party Service profiles) allow for data to be resent to the specified endpoint/server. The API Client itself, however, does not have a function or property to resend data.

Limitations of the Instant Item Detail API Client

The Instant Item Detail API Client does not accept or help facilitate queries to the CATAPULT database. Only requests to the specified endpoint/server are possible.
The Instant Item Detail API Client does not currently have a message/activity log that can be queried.
The Instant Item Detail API Client does not send updates to inventory 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.
The Instant Item Detail API Client can only be used with merchants who use the ECRS CATAPULT software suite.

Requirements

API Client Communication Requirements

Communication with the Instant Item Detail API Client must occur using Transport Layer Security (TLS).
- Where the Instant Item Detail API Client is the entity that submits a request, the server specified by the service provider (i.e., the entity receiving the data from the API Client) must accept POST requests.
- For each request submitted by the Instant Item Detail API Client, the endpoint or server that receives that request must provide a true or false response. An optional message can be included with each response that details any noteworthy events or experiences.

Merchant Must Have CATAPULT 5.7.155+

The merchant must be running CATAPULT version 5.7.155 or newer at the store(s) where the Instant Item Detail API Client is to pull and send inventory data from. The API Client is not compatible - and cannot be used - with any older versions of CATAPULT.

Required Actions by the Merchant

The merchant must take certain actions within CATAPULT Web Office to set up the Instant Item Detail API Client to facilitate communication with the specified server/endpoint. These actions are detailed in this page of ECRS Docs. While performing these actions, the following data points must be configured:

URL
Image URL
Price Label Settings URL
Header
Query Parameters
Inventory Fields

Additional details on these data points are provided below.

URL

The desired web location where the API Client will send updates to inventory item data. This field is required.

Image URL

The desired web location where the API Client will send updates to inventory item images. This field is required if images are to be used.

Price Label Settings URL

The desired web location where the API Client will send settings (i.e., unique identifier & key/value data) about the Price Label Type(s) assigned to inventory items included in the request. This field is required if the settings for Price Label Types need to be obtained.

The header will contain the desired parameters that are to be included in the header of the API Client's request, each time one is made. The desired parameters must be in a JSON object and formatted as a string.

EXAMPLE: If an API Key needed to be included in the header, the associated JSON object string would be: {"apikey":"BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0"}

Query Parameters

The query parameters are those that should be included with the request each time one is performed by the API Client. The desired query parameters must be entered in CATAPULT Web Office in the following format:

param1=val1&param2=val2&param3=val3

Each specified query parameter will automatically be added onto the URL specified each time the API Client performs a request.

Inventory Fields

By default, the Instant Item Detail API Client will only send the required fields, which are:

Item Record ID
Item ID
Item Receipt Alias
Store Record ID
Store Name
Store Number
Deleted from Store = true/false
Supplier Information Record ID*
Supplier Unit ID*
Supplier Name*
Supplier Unit ID Deleted* = true/false

*Only required when the item's Ordering Information is included in the data sent.

Additional inventory fields can be sent in the Instant Item Detail API Client request, but they must be specified - by code - and provided to the merchant. The available inventory fields that can be sent are detailed in Table 1 below.

Code	Inventory Field
1	Item Name
2	Size
3	Size Quantity
4	Size Unit
5	Memo
6	Suggested Retail
7	Country of Origin
8	Department Name
9	Department ID
10	Sub-Department ID
11	Sub-Department Name
12	Category ID
13	Category Name
14	Sub-Category ID
15	Sub-Category Name
17	Variety ID
18	Variety Name
19	Brand
20	Global Power Field 1
21	Global Power Field 2
22	Global Power Field 3
23	Global Power Field 4
24	Global Power Field 5
25	Global Power Field 6
26	Global Power Field 7
27	Global Power Field 8
28	Store Power Field 1
29	Store Power Field 2
30	Store Power Field 3
31	Store Power Field 4
32	Store Power Field 5
33	Store Power Field 6
34	Store Power Field 7
35	Store Power Field 8
36	Local
37	DSD
38	Discontinued
39	Location
40	Shelf Information
41	Alternate ID Quantity
42	Regional Descriptor
43	Production Method
44	Supplier Name
45	Supplier Unit ID
46	Supplier ID
47	Order Quantity
48	Order Unit
49	Weight
50	Fixed Tare
51	Percent Tare
52	Unit of Measure
53	Tare Type
54	Zone
55	Store Street Address
56	Store City
57	Store State
58	Store Postal Code
59	Additional Receipt Alias
60	Ingredients
61	Shelf Life
62	Description Line 1
63	Description Line 2
64	Description Line 3
65	Description Line 4
66	Description Size 1
67	Description Size 2
68	Description Size 3
69	Description Size 4
70	Fixed Weight Amount
71	By Count Quantity
72	Force Shelf Life Entry
73	Deli Scale Attribute 1
74	Deli Scale Attribute 2
75	Deli Scale Attribute 3
76	Deli Scale Attribute 4
77	Deli Scale Attribute 5
78	Deli Scale Attribute 6
79	Deli Scale Attribute 7
80	Health Attribute 1
81	Health Attribute 2
82	Health Attribute 3
83	Health Attribute 4
84	Health Attribute 5
85	Health Attribute 6
86	Marketing Attribute 1
87	Marketing Attribute 2
88	Marketing Attribute 3
89	Marketing Attribute 4
90	Marketing Attribute 5
91	Marketing Attribute 6
92	Price / Price & Cost Change Worksheet Name
93	Name of Price Label Type Assigned to Price Level 1 on Price Change or Price & Cost Change Worksheet
94	Name of Price Label Type Assigned to Price Level 2 on Price Change or Price & Cost Change Worksheet
95	Name of Price Label Type Assigned to Price Level 3 on Price Change or Price & Cost Change Worksheet
96	Name of Price Label Type Assigned to Price Level 4 on Price Change or Price & Cost Change Worksheet
97	Price / Price & Cost Change Start Date
98	Price / Price & Cost Change End Date
99	Price / Price & Cost Change Price 1
100	Price / Price & Cost Change Price 2
101	Price / Price & Cost Change Price 3
102	Price / Price & Cost Change Price 4
103	Price / Price & Cost Change Price Divider 1
104	Price / Price & Cost Change Price Divider 2
105	Price / Price & Cost Change Price Divider 3
106	Price / Price & Cost Change Price Divider 4
107	Price / Price & Cost Change Discount 1
108	Price / Price & Cost Change Discount 2
109	Price / Price & Cost Change Discount 3
110	Price / Price & Cost Change Discount 4
111	Price Level 1 Price
112	Price Level 2 Price
113	Price Level 3 Price
114	Price Level 4 Price
115	Price Level 1 Pricing Divider
116	Price Level 2 Pricing Divider
117	Price Level 3 Pricing Divider
118	Price Level 4 Pricing Divider
119	Price Level 1 Auto Discount
120	Price Level 2 Auto Discount
121	Price Level 3 Auto Discount
122	Price Level 4 Auto Discount
123	WebCart Enabled
124	Weighted Net Sales Grade
125	Weighted Velocity Grade
126	Weighted Profit Grade
127	Weighted Department Grade
128	Weighted Basket Grade
129	Percent Net Sales Grade
130	Percent Velocity Grade
131	Percent Profit Grade
132	Percent Department Grade
133	Percent Basket Grade
134	Image
135	Health Attribute Image 1
136	Health Attribute Image 2
137	Health Attribute Image 3
138	Health Attribute Image 4
139	Health Attribute Image 5
140	Health Attribute Image 6
141	Name of Price Label Type Assigned to Price Level 1 of Item
142	Name of Price Label Type Assigned to Price Level 2 of Item
143	Name of Price Label Type Assigned to Price Level 3 of Item
144	Name of Price Label Type Assigned to Price Level 4 of Item
145	Option to Include Keys & Values of Price Label Types in Request
146	Unique ID of Price Label Type Assigned to Price Level 1
147	Unique ID of Price Label Type Assigned to Price Level 2
148	Unique ID of Price Label Type Assigned to Price Level 3
149	Unique ID of Price Label Type Assigned to Price Level 4
150	Unique ID of Price Label Type Assigned to Price Level 1 on Price Change or Price & Cost Change Worksheet
151	Unique ID of Price Label Type Assigned to Price Level 2 on Price Change or Price & Cost Change Worksheet
152	Unique ID of Price Label Type Assigned to Price Level 3 on Price Change or Price & Cost Change Worksheet
153	Unique ID of Price Label Type Assigned to Price Level 4 on Price Change or Price & Cost Change Worksheet

Table 1

Note: The Instant Item Detail API Client will send null for any inventory field that is not populated on the associated item.

Document Revision History

Current Revision: 5.8.180

5.8.180 Revision

Revision Date

02/10/2026

New

Revised name of the API Client from "Third Party Label API Client" to Instant Item Detail API Client to better reflect and represent the purpose of the API Client.
The Item Price Label Type Settings endpoint is now available with this API Client. This endpoint provides details (i.e., unique identifier & key/value data) about the Price Label type(s) assigned to inventory items included in the request.
The following properties are now available to be included in the request sent by the API Client:
- The name of the Price Label Type assigned to an item on Price Levels 1-4
- The settings associated with the item's assigned Price Label Type for Price Levels 1-4
- The unique identifiers (assigned by the CATAPULT database) of Price Label Types assigned to items for Price Levels 1-4
- The unique identifiers (assigned by the CATAPULT database) of Price Label Types assigned to items when they are on a Price Change or Price & Cost Change worksheet for Price Levels 1-4

Fixes and Improvements

N / A

Older Revisions

5.7.155 Revision

Revision Date

02/18/2025

New

Document Established

Fixes and Improvements

N / A

Endpoints

Items

Endpoint Purpose

This endpoint provides item data. This data consists of general information about the item, as well as store-specific information.
Unless otherwise noted, all item data is managed by the merchant in CATAPULT Web Office.

Using this Endpoint

The first request from the Instant Item Detail 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 5,000 items on a single page with each request. If a page does not contain 5,000 items, then it will only display the amount of data available on the page.
- The default page size can be adjusted, if desired. To do so, the CATAPULT merchant must apply an Advanced Setting in CATAPULT Web Office. Details and instructions on how to apply this Advanced Setting can be found in this page of ECRS Docs.
Once the initial inventory data has been sent, any updated inventory item data will be automatically included in different requests every five (5) minutes thereafter. This updated inventory data can include new items altogether, or updates to existing items.

Request Body schema: application/json

Array

recordID

required

string

The unique identifier for the item, which will vary in format depending on if the item is a Base Item, or an Alternate ID of the Base Item.

Base Item: The recordID will be a unique value that represents the item (e.g., 4294967296001).
Alternate ID of Base Item: The recordID will be a unique, hyphenated value that is comprised of the Base Item's ID along with a unique value that represents the Alternate ID (e.g., 4294967296001-4887254236902).

itemId

required

string [ 1 .. 16 ] characters

The Item ID (i.e., UPC, PLU, or SKU) of the item.

receiptAlias

required

string <= 32 characters

The Receipt Alias of the item, which is the text that displays on the customer's receipt when the item is purchased.

itemName

string <= 254 characters

The Name of the item, as entered in CATAPULT Web Office.

size

string <= 20 characters

The size of the item, as entered in the Size field on the item's inventory record in CATAPULT Web Office.

sizeQty

number

If the Size field is populated correctly on an item's inventory record, this field is the numeric portion of the item's size.

sizeUnit

string <= 20 characters

If the Size field is populated correctly on an item's inventory record, this field is the unit of measure for the item's size.

memo

string <= 254 characters

The text entered into the item's Memo field.

suggestedRetail

number <= 999999999999 characters

The entered Suggested Retail price of the item.

coolText

string <= 100 characters

The item's entered Country of Origin Label.

deptName

string <= 30 characters

The name of the Department that the item is assigned to.

deptNumber

integer

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

subDeptName

string <= 30 characters

The name of the Sub-Department that the item is assigned to.

subDeptNumber

integer

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

categoryName

string <= 30 characters

The name of the Category that the item is assigned to.

categoryNumber

integer

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

subCategoryName

string <= 30 characters

The name of the Sub-Category that the item is assigned to.

subCategoryNumber

integer

The ID/Number of the Sub-Category that the item is assigned to.

varietyName

string <= 30 characters

The name of the Variety that the item is assigned to.

varietyNumber

integer

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

brand

string <= 30 characters

The Brand associated with the item.

powerField1

string <= 30 characters

The value selected for Power Field 1 on the item.

powerField2

string <= 30 characters

The value selected for Power Field 2 on the item.

powerField3

string <= 30 characters

The value selected for Power Field 3 on the item.

powerField4

string <= 30 characters

The value selected for Power Field 4 on the item.

powerField5

string <= 30 characters

The value entered for Power Field 5 on the item.

powerField6

string <= 30 characters

The value entered for Power Field 6 on the item.

powerField7

string <= 30 characters

The value entered for Power Field 7 on the item.

powerField8

string <= 30 characters

The value entered for Power Field 8 on the item.

packageQty

number

The Alternate ID Quantity of the item (if present).

regionalDescriptor

string <= 30 characters

The item's entered Regional Descriptor (i.e., what region of a country or province an item came from).

productionMethod

string <= 30 characters

The name of the Production Method selected for the item.

localReceiptAlias

string <= 32 characters

The item's Additional Receipt Alias. The Additional Receipt Alias can be for one of the following languages:

English
French
Chinese (Simplified)
Spanish
Russian
Japanese

healthAttr1

string <= 2 characters

The two character Symbol of the first Health Attribute selected for the item.

healthAttr2

string <= 2 characters

The two character Symbol of the second Health Attribute selected for the item.

healthAttr3

string <= 2 characters

The two character Symbol of the third Health Attribute selected for the item.

healthAttr4

string <= 2 characters

The two character Symbol of the fourth Health Attribute selected for the item.

healthAttr5

string <= 2 characters

The two character Symbol of the fifth Health Attribute selected for the item.

healthAttr6

string <= 2 characters

The two character Symbol of the sixth Health Attribute selected for the item.

marketingAttr1

string <= 30 characters

The name/description of the first Marketing Attribute selected for the item.

marketingAttr2

string <= 30 characters

The name/description of the second Marketing Attribute selected for the item.

marketingAttr3

string <= 30 characters

The name/description of the third Marketing Attribute selected for the item.

marketingAttr4

string <= 30 characters

The name/description of the fourth Marketing Attribute selected for the item.

marketingAttr5

string <= 30 characters

The name/description of the fifth Marketing Attribute selected for the item.

marketingAttr6

string <= 30 characters

The name/description of the sixth Marketing Attribute selected for the item.

image

string

The name of the image assocated with the item.

heathAttrImg1

string

The name of the image assocated with the first Health Attribute selected for the item.

heathAttrImg2

string

The name of the image assocated with the second Health Attribute selected for the item.

heathAttrImg3

string

The name of the image assocated with the third Health Attribute selected for the item.

heathAttrImg4

string

The name of the image assocated with the fourth Health Attribute selected for the item.

heathAttrImg5

string

The name of the image assocated with the fifth Health Attribute selected for the item.

heathAttrImg6

string

The name of the image assocated with the sixth Health Attribute selected for the item.

Array of objects (OrderData)

List of all supplier information for this item. An item can have multiple suppliers.

Array

recordID required	string The unique indentifier associated with the item's Supplier Unit ID and Supplier.
supplierID required	string <= 15 characters The Supplier's ID, as entered on the Supplier Record in CATAPULT Web Office.
supplierName required	string <= 25 characters The name of the Supplier, as entered on the Supplier Record in CATAPULT Web Office. Note that this field is only required if ordering information for the item is included in the request.
deleted required	boolean Indicates if the corresponding Supplier Unit ID (SUID) has been deleted from the associated item. `true`: SUID has been deleted `false`: SUID has NOT been deleted
supplierCode	string <= 10 characters The Supplier Unit ID of the item for the associated Supplier. Note that this field is only required if ordering information for the item is included in the request.
orderQty	number <= null characters The number of items in a single order unit for the associated Supplier.
orderUnit	string <= 30 characters The order unit assigned to the item for the associated Supplier.

Array of objects (Store)

List of all store-specific data for this item.

Array

recordID required	string The unique identifier for the item's associated store.
storeName required	string <= 60 characters The name of the store that the item is associated with (i.e., where the item is sold).
storeNumber required	string <= 10 characters The number/ID of the store that the item is associated with (i.e., where the item is sold).
deleted required	boolean Indicates if this item has been deleted from the associated store. `true`: Item has been deleted `false`: Item has NOT been deleted
localPowerField1	string <= 30 characters The value selected for Store Level PowerField 1 for the item.
localPowerField2	string <= 30 characters The value selected for Store Level PowerField 2 for the item.
localPowerField3	string <= 30 characters The value selected for Store Level PowerField 3 for the item.
localPowerField4	string <= 30 characters The value selected for Store Level PowerField 4 for the item.
localPowerField5	string <= 30 characters The value entered in Store Level PowerField 5 for the item.
localPowerField6	string <= 30 characters The value entered in Store Level PowerField 6 for the item.
localPowerField7	string <= 30 characters The value entered in Store Level PowerField 7 for the item.
localPowerField8	string <= 30 characters The value entered in Store Level PowerField 8 for the item.
local	boolean Indicates if the item is set as geographically "local" to the associated store. `true`: The item is local to the store `false`: The item is NOT local to the store
dsd	boolean Indicates if the item is set as a "Direct Store Delivery" (DSD) item for the associated store. `true`: Item is set as DSD `false`: Item is NOT set as DSD
discontinued	boolean Indicates if the item is set as "Discontinued" for the associated store. `true`: Item has been discontinued `false`: Item has NOT been discontinued
location	string <= 30 characters The item's location within the associated store.
sequenceNumber	string The item's shelf sequence within the associated store.
weight	string <= 30 characters The name of the item's assigned Weight profile for the associated store. The Weight profile determines the unit of measure (e.g., pounds) the item is sold by, any tare options, and more.
fixedTare	number The entered Fixed Tare Weight for the item, but only if the item has an assigned Weight profile that contains a Fixed tare type.
percentTare	number The entered tare percentage for the item, but only if the item has an assigned Weight profile that contains a Percent tare type.
unitOfMeasure	integer Enum: 1 2 3 4 5 The item's unit of measure - as determined by the assigned Weight profile - for the associated store. `1`: Grams `2`: Kilograms `3`: Pounds `4`: Ounces `5`: Hundred Grams
tareType	integer Enum: 0 1 2 3 4 5 The item's tare type - as determined by the assigned Weight profile - for the associated store. `0`: None `1`: Percent `2`: Fixed `3`: Percent and Fixed `4`: Prompt `5`: Select
zone	string <= 30 characters The name of the Zone that the store is a part of. The store will be the one that the item is associated with.
storeStreetAddress	string <= 50 characters The street address of the store where the item is sold at.
storeCity	string <= 20 characters The city where the item's associated store resides in.
storeState	string <= 2 characters The state abbreviation where the item's associated store resides in.
storePostalCode	string <= 15 characters The ZIP/Postal Code where the item's associated store resides in.
ingredients	string The entered ingredients for the item.
shelfLife	integer <= 999 characters The entered Shelf Life of the item.
descLine1	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).
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).
descSize1	integer <= 2 characters The integer entered for Deli Scale Attribute Description Size 1 on the item.
descSize2	integer <= 2 characters The integer entered for Deli Scale Attribute Description Size 2 on the item.
descSize3	integer <= 2 characters The integer entered for Deli Scale Attribute Description Size 3 on the item.
descSize4	integer <= 2 characters The integer entered for Deli Scale Attribute Description Size 4 on the item.
fixedWeightAmt	integer <= 9999 characters The integer entered for Deli Scale Attribute Fixed weight amount on the item.
byCountQty	integer <= 999 characters The integer entered for Deli Scale Attribute By count quantity on the item.
forceShelfLife	boolean Indicates if the item must have a shelf life entry, as determined by the Force shelf life entry Deli Scale Attribute on the item. `Yes`: Shelf life entry will be forced. `No`: Shelf life entry will NOT be forced.
userAssigned1	string <= 30 characters The value entered for Deli Scale Attribute User assigned field 1 on the item.
userAssigned2	string <= 30 characters The value entered for Deli Scale Attribute User assigned field 2 on the item.
userAssigned3	string <= 30 characters The value entered for Deli Scale Attribute User assigned field 3 on the item.
userAssigned4	string <= 30 characters The value entered for Deli Scale Attribute User assigned field 4 on the item.
userAssigned5	integer <= 99999999 characters The integer entered for Deli Scale Attribute User assigned field 5 on the item.
userAssigned6	integer <= 99999999 characters The integer entered for Deli Scale Attribute User assigned field 6 on the item.
userAssigned7	integer <= 99999999 characters The integer entered for Deli Scale Attribute User assigned field 7 on the item.
wrkName	string <= 40 characters The name of the active (and temporary) Price Change or Price & Cost Change worksheet that the item is on at the time of the request. If the item is on multiple worksheets, the worksheet with the highest priority and the one that was most recently activated will be used.
pclPromoName1	string <= 30 characters The name of the Price Label Type profile assigned to the item - on the temporary Price Change or Price & Cost Change worksheet - for Price Level 1.
pclPromoName2	string <= 30 characters The name of the Price Label Type profile assigned to the item - on the temporary Price Change or Price & Cost Change worksheet - for Price Level 2.
pclPromoName3	string <= 30 characters The name of the Price Label Type profile assigned to the item - on the temporary Price Change or Price & Cost Change worksheet - for Price Level 3.
pclPromoName4	string <= 30 characters The name of the Price Label Type profile assigned to the item - on the temporary Price Change or Price & Cost Change worksheet - for Price Level 4.
promoStart	string The start date of the temporary Price Change or Price & Cost Change worksheet that the item is on (i.e., the date when the item's promotional price first takes effect).
promoEnd	string The end date of the temporary Price Change or Price & Cost Change worksheet that the item is on (i.e., the date when the item's promotional price ends).
promoPrice1	number The item's promotional price for Price Level 1, as determined by the active + temporary Price Change or Price & Cost Change worksheet that the item is on at the time of the request.
promoPrice2	number The item's promotional price for Price Level 2, as determined by the active + temporary Price Change or Price & Cost Change worksheet that the item is on at the time of the request.
promoPrice3	number The item's promotional price for Price Level 3, as determined by the active + temporary Price Change or Price & Cost Change worksheet that the item is on at the time of the request.
promoPrice4	number The item's promotional price for Price Level 4, as determined by the active + temporary Price Change or Price & Cost Change worksheet that the item is on at the time of the request.
promoDivider1	integer The item's promotional Pricing Divider for Price Level 1, as determined by the active + temporary Price Change or Price & Cost Change worksheet that the item is on at the time of the request.
promoDivider2	integer The item's promotional Pricing Divider for Price Level 2, as determined by the active + temporary Price Change or Price & Cost Change worksheet that the item is on at the time of the request.
promoDivider3	integer The item's promotional Pricing Divider for Price Level 3, as determined by the active + temporary Price Change or Price & Cost Change worksheet that the item is on at the time of the request.
promoDivider4	integer The item's promotional Pricing Divider for Price Level 4, as determined by the active + temporary Price Change or Price & Cost Change worksheet that the item is on at the time of the request.
promoDiscount1	string <= 30 characters The name of the item's promotional Auto Discount for Price Level 1, as determined by the active + temporary Price Change or Price & Cost Change worksheet that the item is on at the time of the request.
promoDiscount2	string <= 30 characters The name of the item's promotional Auto Discount for Price Level 2, as determined by the active + temporary Price Change or Price & Cost Change worksheet that the item is on at the time of the request.
promoDiscount3	string <= 30 characters The name of the item's promotional Auto Discount for Price Level 3, as determined by the active + temporary Price Change or Price & Cost Change worksheet that the item is on at the time of the request.
promoDiscount4	string <= 30 characters The name of the item's promotional Auto Discount for Price Level 4, as determined by the active + temporary Price Change or Price & Cost Change worksheet that the item is on at the time of the request.
price1	number <= 10000000000000000 characters The price of the item for Price Level 1. Note that the pricing will be specific to the Zone that the item's associated store is a part of.
price2	number <= 10000000000000000 characters The price of the item for Price Level 2. Note that the pricing will be specific to the Zone that the item's associated store is a part of.
price3	number <= 10000000000000000 characters The price of the item for Price Level 3. Note that the pricing will be specific to the Zone that the item's associated store is a part of.
price4	number <= 10000000000000000 characters The price of the item for Price Level 4. Note that the pricing will be specific to the Zone that the item's associated store is a part of.
divider1	integer <= 99 characters The Pricing Divider for the item on Price Level 1. Note that the Pricing Divider will be specific to the Zone that the item's associated store is a part of.
divider2	integer <= 99 characters The Pricing Divider for the item on Price Level 2. Note that the Pricing Divider will be specific to the Zone that the item's associated store is a part of.
divider3	integer <= 99 characters The Pricing Divider for the item on Price Level 3. Note that the Pricing Divider will be specific to the Zone that the item's associated store is a part of.
divider4	integer <= 99 characters The Pricing Divider for the item on Price Level 4. Note that the Pricing Divider will be specific to the Zone that the item's associated store is a part of.
discount1	string <= 30 characters The name of the Auto Discount assigned to the item for Price Level 1. Note that the Auto Discount will be specific to the Zone that the item's associated store is a part of.
discount2	string <= 30 characters The name of the Auto Discount assigned to the item for Price Level 2. Note that the Auto Discount will be specific to the Zone that the item's associated store is a part of.
discount3	string <= 30 characters The name of the Auto Discount assigned to the item for Price Level 3. Note that the Auto Discount will be specific to the Zone that the item's associated store is a part of.
discount4	string <= 30 characters The name of the Auto Discount assigned to the item for Price Level 4. Note that the Auto Discount will be specific to the Zone that the item's associated store is a part of.
webCartEnabled	boolean Indicates whether or not the item is enabled (i.e., allowed to be sold) in CATAPULT WebCart™ for the associated store. `true`: The item is enabled for WebCart. `false`: The item is NOT enabled for WebCart.
weightedNetSalesGrade	number The weighted Revenue (i.e., Net Sales) Grade for the item at the associated store.
weightedVelocityGrade	number The weighted Velocity Grade for the item at the associated store.
weightedProfitGrade	number The weighted Contribution (i.e., Profit) Grade for the item at the associated store.
weightedDeptGrade	number The weighted Department Grade for the item at the associated store.
weightedBasketGrade	number The weighted Basket Grade for the item at the associated store.
percentNetSalesGrade	number The percent Revenue (i.e., Net Sales) Grade for the item at the associated store.
percentVelocityGrade	number The percent Velocity Grade for the item at the associated store.
percentProfitGrade	number The percent Contribution (i.e., Profit) Grade for the item at the assocated store.
percentDeptGrade	number The percent Department Grade for the item at the associated store.
percentBasketGrade	number The percent Basket Grade for the item at the associated store.
pclName1	string <= 30 characters Available with CATAPULT 5.8.180+ The name of the Price Label Type assigned to the item for Price Level 1.
pclName2	string <= 30 characters Available with CATAPULT 5.8.180+ The name of the Price Label Type assigned to the item for Price Level 2.
pclName3	string <= 30 characters Available with CATAPULT 5.8.180+ The name of the Price Label Type assigned to the item for Price Level 3.
pclName4	string Available with CATAPULT 5.8.180+ The name of the Price Label Type assigned to the item for Price Level 4.
pl1SettingsID	integer Available with CATAPULT 5.8.180+ A unique identifier, automatically assigned by the CATAPULT database, for the Price Label Type that is assigned to the item for Price Level 1. In order for this ID to be included in the API Client's request, the `value` property (i.e., Code 145) must also be included in the list of "fields" specified by the merchant in the Third Party Service profile.
pl2SettingsID	integer Available with CATAPULT 5.8.180+ A unique identifier, automatically assigned by the CATAPULT database, for the Price Label Type that is assigned to the item for Price Level 2. In order for this ID to be included in the API Client's request, the `value` property (i.e., Code 145) must also be included in the list of "fields" specified by the merchant in the Third Party Service profile.
pl3SettingsID	integer Available with CATAPULT 5.8.180+ A unique identifier, automatically assigned by the CATAPULT database, for the Price Label Type that is assigned to the item for Price Level 3. In order for this ID to be included in the API Client's request, the `value` property (i.e., Code 145) must also be included in the list of "fields" specified by the merchant in the Third Party Service profile.
pl4SettingsID	integer Available with CATAPULT 5.8.180+ A unique identifier, automatically assigned by the CATAPULT database, for the Price Label Type that is assigned to the item for Price Level 4. In order for this ID to be included in the API Client's request, the `value` property (i.e., Code 145) must also be included in the list of "fields" specified by the merchant in the Third Party Service profile.
pl1PromoSettingsID	integer Available with CATAPULT 5.8.180+ A unique identifier, automatically assigned by the CATAPULT database, for the Price Label Type that is assigned to Price Level 1 for an item on an active - and temporary - Price Change or Price & Cost Change worksheet. Notes This ID will only be included in the API Client's request when the associated worksheet is active. Meaning, the current date is within the specified Start Date and End Date of the worksheet. In order for this ID to be included in the API Client's request, the `value` property (i.e., Code = 145) must also be included in the list of "fields" specified by the merchant in the Third Party Service profile.
pl2PromoSettingsID	integer Available with CATAPULT 5.8.180+ A unique identifier, automatically assigned by the CATAPULT database, for the Price Label Type that is assigned to Price Level 2 for an item on an active - and temporary - Price Change or Price & Cost Change worksheet. Notes This ID will only be included in the API Client's request when the associated worksheet is active. Meaning, the current date is within the specified Start Date and End Date of the worksheet. In order for this ID to be included in the API Client's request, the `value` property (i.e., Code = 145) must also be included in the list of "fields" specified by the merchant in the Third Party Service profile.
pl3PromoSettingsID	integer Available with CATAPULT 5.8.180+ A unique identifier, automatically assigned by the CATAPULT database, for the Price Label Type that is assigned to Price Level 3 for an item on an active - and temporary - Price Change or Price & Cost Change worksheet. Notes This ID will only be included in the API Client's request when the associated worksheet is active. Meaning, the current date is within the specified Start Date and End Date of the worksheet. In order for this ID to be included in the API Client's request, the `value` property (i.e., Code = 145) must also be included in the list of "fields" specified by the merchant in the Third Party Service profile.
pl4PromoSettingsID	integer Available with CATAPULT 5.8.180+ A unique identifier, automatically assigned by the CATAPULT database, for the Price Label Type that is assigned to Price Level 4 for an item on an active - and temporary - Price Change or Price & Cost Change worksheet. Notes This ID will only be included in the API Client's request when the associated worksheet is active. Meaning, the current date is within the specified Start Date and End Date of the worksheet. In order for this ID to be included in the API Client's request, the `value` property (i.e., Code = 145) must also be included in the list of "fields" specified by the merchant in the Third Party Service profile.

Responses

Response Schema: application/json

success required	boolean When requests are sent from either the "Items" or "Images" 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

Payload

Content type

application/json

[{"recordID": "4294967296001",
"itemId": "94011",
"receiptAlias": "Org Bananas",
"itemName": "Organic Yellow Bananas",
"size": "16 OZ",
"sizeQty": "16",
"sizeUnit": "OZ",
"memo": "These bananas are perfect for Banana Bread!",
"suggestedRetail": 5.99,
"coolText": "France",
"deptName": "Produce",
"deptNumber": "4",
"subDeptName": "Fruits",
"subDeptNumber": "8",
"categoryName": "International Fruits",
"categoryNumber": "12",
"subCategoryName": "Shelf-Stable Fruits",
"subCategoryNumber": "16",
"varietyName": "Organic Shelf-Stable Fruits",
"varietyNumber": "20",
"brand": "Urban Market Deli",
"powerField1": "string",
"powerField2": "string",
"powerField3": "string",
"powerField4": "string",
"powerField5": "string",
"powerField6": "string",
"powerField7": "string",
"powerField8": "string",
"packageQty": "2",
"regionalDescriptor": "Napa Valley",
"productionMethod": "Hand Made in Boone NC",
"localReceiptAlias": "Fromage de chèvre",
"healthAttr1": "O1",
"healthAttr2": "GF",
"healthAttr3": "NG",
"healthAttr4": "DF",
"healthAttr5": "K",
"healthAttr6": "CF",
"marketingAttr1": "USDA Prime",
"marketingAttr2": "USDA Choice",
"marketingAttr3": "USDA Select",
"marketingAttr4": "Wine Taster Gold Medal",
"marketingAttr5": "Wine Taster Silver Medal",
"marketingAttr6": "Wine Taster Bronze Medal",
"image": "4494967296001.jpg",
"heathAttrImg1": "4494967296101.png",
"heathAttrImg2": "4494967296201.jpg",
"heathAttrImg3": "4494967296301.png",
"heathAttrImg4": "4494967296401.jpg",
"heathAttrImg5": "4494967296501.png",
"heathAttrImg6": "4494967296601.jpg",
"ordering": [{"recordID": "4294967298581",
"supplierID": "33",
"supplierName": "ECRS Food Supply",
"deleted": "false",
"supplierCode": "11060",
"orderQty": "12",
"orderUnit": "Case"
}
],
"stores": [{"recordID": "4294967297054",
"storeName": "Urban Market",
"storeNumber": "27",
"deleted": "false",
"localPowerField1": "string",
"localPowerField2": "string",
"localPowerField3": "string",
"localPowerField4": "string",
"localPowerField5": "string",
"localPowerField6": "string",
"localPowerField7": "string",
"localPowerField8": "string",
"local": true,
"dsd": true,
"discontinued": true,
"location": "Aisle 9",
"sequenceNumber": "32",
"weight": "By Pound",
"fixedTare": "0.250",
"percentTare": "5",
"unitOfMeasure": 1,
"tareType": 0,
"zone": "Rural Zone",
"storeStreetAddress": "150 Market Hills Drive",
"storeCity": "Boone",
"storeState": "NC",
"storePostalCode": "28607",
"ingredients": "Red Potatoes, Dill, Sour Cream, Mayonnaise, Salt, Pepper, Sugar",
"shelfLife": "5",
"descLine1": "string",
"descLine2": "string",
"descLine3": "string",
"descLine4": "string",
"descSize1": 0,
"descSize2": 0,
"descSize3": 0,
"descSize4": 0,
"fixedWeightAmt": "3",
"byCountQty": "5",
"forceShelfLife": "Yes",
"userAssigned1": "string",
"userAssigned2": "string",
"userAssigned3": "string",
"userAssigned4": "string",
"userAssigned5": 0,
"userAssigned6": 0,
"userAssigned7": 0,
"wrkName": "string",
"pclPromoName1": "string",
"pclPromoName2": "string",
"pclPromoName3": "string",
"pclPromoName4": "string",
"promoStart": "string",
"promoEnd": "string",
"promoPrice1": 0,
"promoPrice2": 0,
"promoPrice3": 0,
"promoPrice4": 0,
"promoDivider1": 0,
"promoDivider2": 0,
"promoDivider3": 0,
"promoDivider4": 0,
"promoDiscount1": "string",
"promoDiscount2": "string",
"promoDiscount3": "string",
"promoDiscount4": "string",
"price1": 4.99,
"price2": 3.99,
"price3": 2.99,
"price4": 1.99,
"divider1": "3",
"divider2": "3",
"divider3": "3",
"divider4": "3",
"discount1": "string",
"discount2": "string",
"discount3": "string",
"discount4": "string",
"webCartEnabled": true,
"weightedNetSalesGrade": 0,
"weightedVelocityGrade": 0,
"weightedProfitGrade": 0,
"weightedDeptGrade": 0,
"weightedBasketGrade": 0,
"percentNetSalesGrade": 0,
"percentVelocityGrade": 0,
"percentProfitGrade": 0,
"percentDeptGrade": 0,
"percentBasketGrade": 0,
"pclName1": "string",
"pclName2": "string",
"pclName3": "string",
"pclName4": "string",
"pl1SettingsID": 0,
"pl2SettingsID": 0,
"pl3SettingsID": 0,
"pl4SettingsID": 0,
"pl1PromoSettingsID": 0,
"pl2PromoSettingsID": 0,
"pl3PromoSettingsID": 0,
"pl4PromoSettingsID": 0
}
]
}
]

Response samples

Content type

application/json

{"success": "true",
"message": "string"
}

Item Images

Context

When a CATAPULT merchant uploads an image for an item in CATAPULT Web Office, CATAPULT automatically assigns the image a name. The image name will be comprised of two unique numerical values, separated by a hyphen. In addition, the image file's type will be included as well, resulting in a name that would look similar to: 4494967296501.jpg

Endpoint Purpose

This endpoint provides the associated images for items, and they are provided in a standalone request from the Instant Item Detail API Client.
All item images are managed by the merchant - for each item - in CATAPULT Web Office. These images can be item images or Health Attribute images (i.e., icons).
If any new items have images, or if any existing items have updated images, those qualifications will cause the Instant Item Detail API Client to send the associated images in a request. This request will occur prior to the associated item data being sent, which is done in a separate request. Due to the size of the images, the image data will be paginated and potentially result in multiple requests. There will be up to 10 images included in each request (i.e., on each page); this amount cannot be adjusted.
Each image's name - as it appears in the CATAPULT database - will be included in the request from the "Images" endpoint. As such, if item images are needed for each item, the image field must be included in the list of query parameters for the "Items" endpoint request. The image field is required because it specifies the name of the item's associated image (e.g., 4494967296501.jpg).

Managing Images from the API Client

The following are responsibilities of the service provider regarding item images:

The images must be stored on a server or resource that can be referenced.
Logic must be created/developed that will evaluate the name of an item's associated image, obtain the corresponding image from the stored location, and use or display the image as needed.
While it is not required, it is highly recommended to create/develop logic that removes old image files that are no longer used or referenced by items.

Request Body schema: multipart/form-data

file	Array of any <binary> [ items <binary > ] An image that will be referenced by an item. This image can either be a product photograph, or an item's Health Attribute icon.

Item Price Label Type Settings

Context

In CATAPULT, items can be assigned Price Label Types, which are reusable components that contain various settings and data points. Price Label Types can be used to indicate the type of label stock that price labels should be printed on, if the labels can be grayscale or color, and more.
Price Label Types can be assigned to items on any of the four base CATAPULT Price Levels, or on any of the four promotional Price Levels.

Endpoint Purpose

This endpoint provides the unique identifier and all associated key/value pairs (i.e., settings) of one or more specified Price Label Types assigned to items.

Using this Endpoint

To use this endpoint, the "Value" field (i.e., Code = 145) must be included in the list of fields that the merchant enables/applies in CATAPULT Web Office. In addition to the "Value" field, at least one of the fields listed below must also be enabled/applied in CATAPULT Web Office. If at least one of the fields are not applied, no useful data will be included in the request from this endpoint.
- Unique ID of Price Label Type Assigned to Price Level 1 (Code = 146)
- Unique ID of Price Label Type Assigned to Price Level 2 (Code = 147)
- Unique ID of Price Label Type Assigned to Price Level 3 (Code = 148)
- Unique ID of Price Label Type Assigned to Price Level 4 (Code = 149)
- Unique ID of Price Label Type Assigned to Price Level 1 on Price Change or Price & Cost Change Worksheet (Code = 150)
- Unique ID of Price Label Type Assigned to Price Level 2 on Price Change or Price & Cost Change Worksheet (Code = 151)
- Unique ID of Price Label Type Assigned to Price Level 3 on Price Change or Price & Cost Change Worksheet (Code = 152)
- Unique ID of Price Label Type Assigned to Price Level 4 on Price Change or Price & Cost Change Worksheet (Code = 153)
The data from this endpoint is formatted as a JSON array, with the subsequent data for each Price Label Type formatted as a JSON object within the array.
The settings for each Price Label Type (assigned to an item) will not be included with each item in the request from the Items endpoint. Instead, a reference to the settings of each Price Label Type (included with this endpoint) will be in each applicable item in the Items request. This avoids duplicate data and reduces the overhead for processing the request.

Request Body schema: application/json

recordId

number

The unique identifier of the specified Price Label Type profile(s). This identifier is automatically assigned to the Price Label Type profile by the CATAPULT database (when the profile is created).

Array of objects (Value-Settings)

The key and value pairs entered for the Price Label Type profile in CATAPULT Web Office.

Array

key	string The text entered as a "Key" for the Price Label Type profile.
value	string The text entered with the associated "Key" for the Price Label Type profile.

Responses

Response Schema: application/json

success required	boolean When requests are sent from either the "Items" or "Images" 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

Payload

Content type

application/json

{"recordId": 4294697302026,
"settings": [{"key": "45",
"value": "string"
}
]
}

Response samples

Content type

application/json

{"success": "true",
"message": "string"
}

ECRS® Instant Item Detail API Client (5.8.180)

Purpose

Intended Audience

Overview

Capabilities of the Instant Item Detail API Client

Limitations of the Instant Item Detail API Client

Requirements

API Client Communication Requirements

Merchant Must Have CATAPULT 5.7.155+

Required Actions by the Merchant

URL

Image URL

Price Label Settings URL

Header

Query Parameters

Inventory Fields

Document Revision History

Current Revision: 5.8.180

5.8.180 Revision

Revision Date

New

Fixes and Improvements

Older Revisions

Revision Date

New

Fixes and Improvements

Endpoints

Items

Endpoint Purpose

Using this Endpoint

Request Body schema: application/json

Responses

Response Schema: application/json

Request samples

Response samples

Item Images

Context

Endpoint Purpose

Managing Images from the API Client

Request Body schema: multipart/form-data

Item Price Label Type Settings

Context

Endpoint Purpose

Using this Endpoint

Request Body schema: application/json

Responses

Response Schema: application/json

Request samples

Response samples