logo
API docs by Redocly

CATAPULT Passport API Suite (5.8.165)

Download OpenAPI specification:Download

ECRS Support: support@ecrs.com URL: https://www.ecrs.com

The Catapult Passport API Suite describes REST-like endpoints for adding, updating, or deleting data from a CATAPULT® system.

Overview

Authentication

  • Endpoint authentication is managed by API Keys. Keys are acquired in CATAPULT Web Office and assigned to individual Employee Records.
  • For security Best Practices, it is recommended to include the API Key value in the X-ECRS-APIKEY request header, instead of the query string, wherever possible.
  • As an additional security measure, employee API Keys do not replicate between stores. This means API Keys created in a Web Office interface apply to that specific store location only.
  • In addition, any Employee Record marked as Inactive, Locked, or terminated (Termination Date is populated) will not be able to use their associated API Key with any endpoint in Passport API suite; no action will be taken through the endpoints in these scenarios.

While it is recommended that calls be made to the HQ and filtered with available parameters, authentication for calls to non-HQ Web Office addresses are possible. These require the creation of separate API Keys on employee records in the respective Web Office interface. For example:

  • Employee 142 has an API Key created on their maintenance record in the HQ Web Office. This can be used to authenticate requests sent to the HQ Web Office and will only display on the employee record when viewed in the HQ Web Office interface.
  • Employee 142 has another API Key created on their maintenance record in the RS1 Web Office. This will be used to authenticate requests sent to the RS1 Web Office and will only display on the employee record when viewed in the RS1 Web Office interface.

The API Key visible in the HQ Web Office interface is used to authenticate HQ requests, while the API Key from the RS1 Web Office interface is used for RS1 requests.

Content Negotiation & Media Types
Catapult Passport API operations support these response content-types in the request accept: header:

  • application/xml
  • application/json
  • text/csv

API response content-type is determined by agent-driven, or client-based, content negotiation. Response content-type will default to XML data format if the incoming request header does not describe a specific accept value. If Accept header text/csv is passed, the resulting CSV will be single quote (') qualified.

CSV Request Body Formatting Requirements
XML and JSON data formats are unconditionally accepted by all Catapult Passport API endpoints. The CSV data format is likewise accepted by all endpoints, provided the incoming request satisfies the necessary formatting criteria:

  • IMPORTANT: Request header Content-Type with value "text/csv" must be included in the request.
  • The CSV file must always start with a header row that names each column.
  • The file data may be qualified with a single quote or nothing (not qualified).
  • Each column must be delimited by a comma ,.
  • Each row must be delimited by 1 or more carriage return and/or newline characters.
  • Quoting rules:
    • A single-quote ' character placed after a row or column delimiter will start the next row or column as quoted.
    • Quoted columns do not terminate until the next quote character is encountered.
    • Single-quotes within an quoted column (or vice-versa) can be escaped by a back-slash \ character.
    • A row or column delimiter must be placed immediately after each single-quote termination (after closing a quoted row or column).

Data Type Requirements
Certain data types allow for more leeway with accepted values, while others expect a strict input format. For consistency, unless where otherwise noted and when present in a query parameter, the data types listed here will accept:

  • Boolean - Standard true or false values or binary 0, 1 numeric values.
  • Date Time - Time-zone optional, separator-agnostic YYYY-MM-DDThh:mm:ss or YYYY-MM-DD hh:mm:ss ISO8601/RFC3339 format.
  • Empty String - Pair of double-quotes without a space separator, such as parameter="".
  • Currency - Standard decimal-separated USD format, such as 12.50

Network Connectivity Requirements
Performing requests or updates via the Passport Services API is not possible over Wide-Area-Network (WAN) connections without an active VPN. Requests are only accepted from the same environment where cardholder data is located. More specifically, requests are only accepted from non-routable RFC1918 private network addresses; communication is not possible with any cloud-based platforms or applications.

Licensing Requirements
In order for a CATAPULT merchant - or their chosen third party - to perform requests through the Passport Services API, the CATAPULT store that contains the database where requests will be sent must have one of the following "Passport API" licenses enabled:

  • Passport API Read Only - This license allows authorized personnel to submit requests to endpoints that only support GET methods (e.g., Transaction Journal, Items, Dynamic Promotions, etc.). Endpoints that support a variety of methods - such as Customers and Maintenance Profiles - cannot be sent requests with this license, even though they support one or more GET methods. In turn, this means that no updates to the merchant's CATAPULT database can be made via Passport Services API with this license. Please note, responses like "Passport APIs are not licensed for this server" and "The requested service is not valid" will be returned should a request be made to an ineligible endpoint.
  • Passport API Read & Write - This license allows authorized personnel to use all Passport Services API endpoints to the fullest by submitting GET requests and/or performing PUT, POST, or DEL updates.

Please note that unique licenses cannot be assigned to individual users of the Passport Services API for each store. Meaning, if User 1 and User 2 both needed to submit requests via the Passport Services API to a store, both users would have the same level of access (i.e., Read Only or Read/Write); User 1 could not have Read Only access while User 2 had Read/Write.

Troubleshooting

  • All Passport API endpoints do not use an employee's assigned Authorization Security checkpoints to determine access. Instead, an employee's Inactive status is used.
  • If an employee with a valid API Key is NOT marked as "Inactive" (on their record in CATAPULT Web Office), then that employee will have access to query all Passport API endpoints.
  • If an employee with a valid API Key IS marked as "Inactive", then that employee will not be able to query any Passport API endpoint.
  • Endpoint operations are only accessible to requests that originate from the same local, non-routing private network or VPN as the HQ.
  • API events are output to the CATAPULT web server and can be found in the \Tomcat X.X\logs\ directory, for example: api.YYYY-MM-DD.log
  • Use a unique batch number for different batch procedures. This will make it easier to identify related batch events in the batch_importMessages table and filter for a specific batch number.
  • Passport includes XML v1.1 formatting. Most browsers do not currently support XML v1.1 formatting and should therefore not be relied on, if used at all, for accurate troubleshooting. A dedicated API testing platform is recommended.

Document Revision History

Current Revision = 5.8.165

Revision Date

  • 07/11/2025

New

  • None

Fixes & Improvements

Endpoint: /batch/PriceCost (Batch Updates > POST Batch Price and Cost)

  • Added the appendExistingWorksheets query parameter to the endpoint, which determines if Passport API adds data included in the request to a new worksheet or an existing worksheet (if one exists).

  • Added the autoCommit query parameter to the endpoint, which determines if Passport API automatically commits any worksheet created within the batch or not.

Endpoint: /batch/PermanentPriceCost (Batch Updates > POST Batch Permanent Price and Cost)

  • Added the appendExistingWorksheets query parameter to the endpoint, which determines if Passport API adds data included in the request to a new worksheet or an existing worksheet (if one exists).

  • Added the autoCommit query parameter to the endpoint, which determines if Passport API automatically commits any worksheet created within the batch or not.

Older Revisions

5.8.164 Revision

Revision Date

  • 06/30/2025

New

Endpoint: /giftCardUpdate (Gift Cards > PUT Update Gift Cards in Bulk)

  • Added the /giftCardUpdate endpoint to allow for the dollar amount of existing CATAPULT gift cards to be updated via an adjustment amount or set to a specific value.

Endpoint: /summaryItemData (Summary Item Data > GET Summary Item Data)

  • Added the omitFromSales field to the endpoint's response to identify if the associated Inventory Item or Department is omitted from summarized sales data. This field returns 0 or 1.
    • 0: The record is NOT omitted from sales.
    • 1: The record is omitted from sales.

Fixes & Improvements

General

  • Clarified that only single quotes or no quotes are supported for encapsulating values in CSV files.

Endpoint: /Customer (Customers > PUT Edit & Update)

  • Clarified that the checkAcceptanceProfile field is only included in the endpoint's response; it is not a query parameter.

Endpoint: /batch/PermanentPriceCost (Batch Updates > POST Batch Permanent Price and Cost)

  • Clarified the date and time format for the startDate field.

Endpoint: /batch/PriceCost (Batch Updates > POST Batch Price and Cost)

  • Clarified the date and time format for the startDate field.

Endpoint: /batch/removePriceCost (Batch Updates > POST Batch Remove Temporary Price Change)

  • Clarified the date and time format for the startDate and endDate fields.
5.8.163 Revision

Revision Date

  • 06/12/2025

New

Endpoint: /batch/itemMaintenance (Batch Updates > POST Batch Item Maintenance)

  • Added the the replaceItemID field to the endpoint's request body to allow for an item's existing Item ID to be replaced with another. Prior to using this field, this article in the ECRS Online manual should be referenced.

Fixes & Improvements

Endpoint: /batch/X (Batch Updates > All POST Type Batch Update Endpoints)

  • Clarified that all Batch Update endpoints should only contain fields in the request that truly need to be updated. If fields need to be preserved/unchanged, then those fields should NOT be included in the request for any Batch Update endpoint.
5.8.162 Revision

Revision Date

  • 05/26/2025

New

Endpoint: /inventoryAdjustmentDetail (Inventory Adjustments > GET Inventory Adjustments)

Added the following fields to the endpoint's response to allow for easier and clearer identification of the associated data:

  • Worksheet ID
  • Store Name
  • Store Number
  • Store ID

Fixes & Improvements

  • None
5.8.161 Revision

Revision Date

  • 05/12/2025

New

Endpoint: /batch/itemOrderingInformation (Batch Updates > POST Batch Item Ordering Information)

  • Added logic so that if the orderUnitName field is included in the request, but the specified name does not match an existing Order Unit in the CATAPULT database, then a new Order Unit will be created with that same name and have a default orderQty of 0.

Fixes & Improvements

Endpoint: /giftCardBulk (Gift Cards > POST Create Gift Cards in Bulk)

  • Clarified that the endpoint can be used to create and order physical CATAPULT Self-Hosted Gift Cards; the endpoint is not limited to just creating electronic Gift Cards (i.e., "E-Gift Cards").
5.8.160 Revision

Revision Date

  • 04/24/2025

New

Endpoint: /Customer (Customers > PUT Edit & Update)

  • Added logic so that the following billToAddress fields can be cleared/emptied from an existing customer record if NONE is entered in the corresponding query parameter:
    • Address Line 1
    • Address Line 2
    • City
    • State / Province
    • Postal (ZIP) Code
    • Email Address
    • Phone Number

Fixes & Improvements

  • None
5.7.158 Revision

Revision Date

  • 03/25/2025

New

  • None

Fixes & Improvements

Endpoint: /TransactionJournal (Transaction Journal > GET View & Search)

  • Updated the TransactionStatus query parameter to clarify the available transaction statuses.
  • Updated the TRN_Type field description in the response to include all recorded terminal types.
  • Updated the TRN_Status field description in the response to include all available transaction statuses.

Endpoint: /batch/itemOrderingInformation (Batch Updates > POST Batch Item Ordering Information)

  • Updated the orderUnitName field description to note that the field is only required when new records are being inserted; the field is NOT required when updates are being made.
  • Removed the 'E' Action (Un-Discontinue), as this action is unsupported.

Endpoint: /batch/storePromotions (Batch Updates > POST Batch Store Promotions)

  • Updated the Overview and Notes section of the endpoint's introduction for accuracy, clarity, and conciseness.
  • Updated the REQUEST BODY SCHEMA of the endpoint to reflect the supported fields.
  • Removed the 'E' Action (Un-Discontinue), as this action is unsupported.

Endpoint: /batch/itemPromotions (Batch Updates > POST Batch Item Promotions)

  • Updated the Overview and Notes section of the endpoint's introduction for accuracy, clarity, and conciseness.
  • Updated the REQUEST BODY SCHEMA of the endpoint to reflect the supported fields.
  • Removed the 'E' Action (Un-Discontinue), as this action is unsupported.
5.7.156 Revision

Revision Date

  • 03/07/2025

New

  • None

Fixes & Improvements

Endpoint: /itemDetail (Items > GET Detailed Search)

  • Noted that the storeNumber query parameter is required. Without this parameter, no data will be returned.
  • Added a best practice that the itemSearch query parameter should always be populated with an Item ID or Receipt Alias value.

Endpoint: /allItems (Items > GET View All)

  • Clarified the overview and purpose of this endpoint.

Endpoint: /batch/shelfInformation (Batch Updates > POST Batch Item Shelf Information)

  • Improved the context that introduces the endpoint.
  • Added cautionary note that the endpoint was designed to delete the Shelf Information value from inventory records not specified in a batch. As such, performing batch updates to individual items is not possible without otherwise deleting the Shelf Information previously specified on other inventory records.
5.7.155 Revision

Revision Date

  • 02/21/2025

New

Endpoint: /purchaseOrderItems (Purchase Orders > PUT Purchase Order Items)

  • Added logic to the Request Body Schema to allow for items with the same SUID to be processed in the request without failure.

Fixes & Improvements

Endpoint: /Customers (Customers > PUT Edit & Update)

  • Removed membershipAccountJoined as a Query Parameter, as it is a read-only field.
  • Clarified the scope and intended purpose of the membershipInactive Query Parameter.
  • Expanded the JSON, XML, and CSV response samples.
5.7.154 and Older
  • Revision History for this document started with Revision 5.7.155. As such, revision history for older versions is not included here. However, any new features or functions added previously are noted - by version - throughout the documentation.

Transaction Journal

View & Search

  • The /TransactionJournal endpoint enables you to obtain all available T-Log details and reporting data - via a GET method - for a range of transaction upload times. This transaction data can be for all customers or specific customers.
  • When a startTime and/or endTime are entered in the request parameters, the endpoint's query uses the timestamp from the TRN_uploadTime field to determine if a transaction should be included in the response.
  • The TRN_uploadTime defines if - and when - a transaction record is inserted in the Headquarters T-Log. As such, transactions with a TRN_uploadTime timestamp after the startTime, and/or before the endTime, will be returned.
  • Responses are provided in XML format by default. Content of the response body is modeled after the v_TJTrans (T-Log view) structure.
query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

startTime
required
string <date-time>
Example: startTime=2015-03-25T12:00:00

This parameter contains the start time. Only transactions which were inserted into the HQ T-Log database after this will be included in the output. This time should be in the following format: 2015-03-25T12:00:00 (ISO 8601).

endTime
required
string <date-time>
Example: endTime=2015-03-25T16:00:00

This parameter contains the end time. Only transactions which were inserted into the HQ T-Log database before this will be included in the output. This time should be in the following format: 2015-03-25T12:00:00 (ISO 8601).

CustomerID
string <= 16 characters
Example: CustomerID=4000000123456789

This parameter - available with CATAPULT 5.7.133 and newer - allows you to specify a Customer ID that you want to filter associated Transaction Journal information for.

  • If the entered Customer ID parameter does not exactly match a corresponding record in the CATAPULT database, no results will be returned.
  • If the Customer ID parameter is not sent in the query, all transactions within the specified date range will be returned.
  • If the Customer ID parameter is empty (i.e., null), all transactions within the specified date range that do not have a customer associated to them will be returned.
TransactionStatus
integer
Example: TransactionStatus=10

Introduction

  • This parameter - available with CATAPULT 5.7.149 and newer - allows you to specify a desired Transaction Status to filter the transactions returned from the transactionJournal endpoint.
  • If this query parameter is used but no Transaction Status code is specified, 0 will be used by default, which means only "Finalized Transactions" will be included in the response.
  • TIP: This parameter can be used in conjunction with the CustomerID parameter to further filter the transactions returned with this endpoint.

Available Transaction Statuses

Completed Transactions

TransactionStatus Description Details
0 Normal Sales Transaction A sale that was completed at a Transaction Server terminal by accepting payment, or by performing an All Void or No Sale.
1 Training Mode Transaction A sale that was completed at a Transaction Server terminal while in Training Mode.
15 Merged Transaction A transaction that was originally started on a different Transaction Server terminal (e.g., Made-To-Order Kiosk), but was suspended and merged into another transaction for payment and completion.

Pending Transactions

TransactionStatus Description Details
2 Checkpoint During a transaction, Transaction Server creates snapshots of the transaction as a whole after each action (e.g., item scan, etc.). Doing so provides recent recovery points, should they be needed. Each of these transaction snapshots is assigned a "Checkpoint" status.
3 Suspended Transaction A transaction that was manually or programmatically suspended to be resumed and completed later.
4 Parked In Self-Service environments at the end of the transaction, if a customer is selecting to add value to their charge account, Transaction Server will assign a "Parked" status to the transaction until the customer completes their action.
5 Resumed A transaction that was previously suspended but was resumed for modification or completion. When resumed transactions are completed, they will receive a 0 status.
6 Web Order: Paid A transaction that was started and paid for online in CATAPULT WebCart™ or the merchant's eCommerce platform, but still must be finalized and completed in Transaction Server.
7 Web Order A transaction that was started online in CATAPULT WebCart or the merchant's eCommerce platform that must be finalized and completed in Transaction Server.
8 Recalled A transaction that was previously completed, but was recalled/reopened to perform a return or other action.
9 Delete A transaction that has been marked for deletion by Transaction Server.
10 Order Pick Picking A transaction that contains items which are being picked/processed via PickAssist™, but the order picker suspended the transaction before picking was completed.
11 Order Pick Ready A transaction that contains items which are being picked/processed via PickAssist, and the status of the order is "Ready for Customer".
12 Picking in Progress A transaction that contains items which are actively being picked/processed via PickAssist.
13 Fuel: Pay Inside A fuel transaction that was initiated at a fuel pump (by the shopper) with the intention of being completed in-store at a Transaction Server terminal.
14 Web Order: Editing A transaction that was started and submitted online, but is actively being edited by the shopper.

Note that some of the Pending Transactions listed above may not be applicable as a query parameter, as they may not return any associated data.

AllVoid
boolean
Example: AllVoid=1

This parameter - available with CATAPULT 5.7.149 and newer - allows you to filter for "All Void" transactions using the following options:

  • 0 = This option will exclude All Void transactions from the response.
  • 1 = This option will cause All Void transactions to be the only ones included in the response.

If this query parameter is used but neither option is specified, 0 will be used by default, which means "All Void" transactions will be excluded from the response.

TIP: This parameter can be used in conjunction with the CustomerID parameter to further filter the transactions returned with this endpoint.

Responses

Response Schema:
object
object (transactionjournal)
TRN_PK
integer

The unique identifier for a transaction.

TRN_CPK
integer

The creator identifier for a transaction.

TRN_STO_FK
integer

The unique identifier for the store where the transaction was completed.

TRN_STO_CFK
integer

The unique creator identifier for the store where the transaction was completed.

TRN_StartTime
string/([0-9]{4})-(?:[0-9]{2})-([0-9]{2}) ([0-9]{2}...

The data and time a transaction was started.

Note: For accuracy, use TRN_EndTime if the specific transaction time is needed.

TRN_EndTime
string/([0-9]{4})-(?:[0-9]{2})-([0-9]{2}) ([0-9]{2}...

The date and time a transaction was finalized. This is used as the transaction time in all reporting processes.

TRN_ReceiptNumber
integer

The numeric Receipt Number value generated by the terminal that processed the transction. This number is unique only to that specific terminal. Receipt Numbers will over to 1 after reaching 999,999.

TRN_Type
integer

The terminal type where the associated transaction was started.

  • 0 = Point of Sale Terminal
  • 1 = Vending Kiosk
  • 2 = Self-Checkout Kiosk
  • 3 = Customer Boarding Station
  • 4 = WebCart
  • 5 = Attended AutoScale
  • 6 = Self-Service AutoScale
  • 7 = Made-To-Order Kiosk
  • 8 = Price Checker Station
  • 9 = eCommerce Site
  • 10 = Fuel: Pay at Pump
TRN_EMP_FK
integer

The unique identifier for the Employee who finalized the transaction.

TRN_EMP_CFK
integer

The unique creator identifier for the Employee who finalized the transaction.

TRN_SequenceNumber
integer

The numeric value of the transaction Sequence Number, per the terminal where it was processed.

TRN_TCF_FK
integer

The unique identifier for the terminal record of the completed transaction.

TRN_TCF_CFK
integer

The unique creator identifier for the terminal record of the completed transaction.

TRN_CUS_FK
integer

The unique identifier for the customer associated with this transaction. Only valid if a customer record was actually associated with the transaction.

TRN_CUS_CFK
integer

The unique creator identifier for the customer associated with this transaction. Only valid if a customer record was actually associated with the transaction.

TRN_AllVoid
boolean

Whether or not the transaction has been voided by an All Void action.

  • 0 = Normal Transaction
  • 1 = Voided Transaction
TRN_UploadTime
string/([0-9]{4})-(?:[0-9]{2})-([0-9]{2}) ([0-9]{2}...

The date and time this transaction record is sent from the POS Terminal where it was processed and uploaded into the store database. Based on time received by database server.

TRN_Status
integer

Returns the transaction status/state.

Completed Transactions:

  • 0 = Normal Sales Transaction
  • 1 = Training Mode Transaction
  • 15 = Merged Transaction

Pending Transactions:

  • 2 = Checkpoint
  • 3 = Suspended Sale
  • 4 = Parked
  • 5 = Resumed
  • 6 = Web Order: Paid
  • 7 = Web Order
  • 8 = Recalled
  • 9 = Delete
  • 10 = Order Pick Picking
  • 11 = Order Pick Ready
  • 12 = Picking in Progress
  • 13 = Fuel: Pay Inside
  • 14 = Web Order: Editing

Note that some of the Pending Transactions listed above may never be included in a response (e.g., "Parked"), as they are not valid statues for transactions recorded to the database.

TCF_Description
string <= 30 characters

Name of the terminal that completed the transaction.

TCF_Number
integer

Number of the terminal that completed the transaction.

TCF_TerminalId
string <= 8 characters

The unique identifier of terminal where the transaction was completed.

EMP_Number
integer

The Employee ID for the user (i.e. cashier) logged in to the terminal when the transaction was completed.

EMP_FirstName
string <= 30 characters

The First Name of the user (i.e. cashier) logged in to the terminal when the transaction was completed.

EMP_LastName
string <= 30 characters

The Last Name of the user (i.e. cashier) logged in to the terminal when the transaction was completed.

CUS_AccountNumber
string <= 16 characters

The Customer ID of the customer record associated with the transaction. Only valid if a customer record was actually associated with the transaction.

CUS_FirstName
string <= 25 characters

The First Name of the customer record associated with the transaction. Only valid if a customer record was actually associated with the transaction.

CUS_LastName
string <= 25 characters

The Last Name of the customer record associated with the transaction. Only valid if a customer record was actually associated with the transaction.

CUS_Company
string <= 50 characters

The Company from the customer record associated with the transaction. Only valid if a customer record was actually associated with the transaction.

TLI_PK
integer

The itemized, sequenced identifier of an item on a transaction.

TLI_LIT_FK
integer

Defines the type of item referenced in a transaction line.

TLI Type definitions:

  • 1 - Inventory Item (Normal Sale of any Inventory Item )
  • 2 - Tender (Tender associated with a Transaction)
  • 3 - Tax
  • 4 - Discount
  • 5 - Item Correct (Item removed from sale)
  • 6 - No Sale
  • 7 - All Void
  • 8 - No Tax
  • 9 - Tax Mod Total
  • 10 - Suspend
  • 11 - Resume
  • 12 - Tax Mod Indicator
  • 13 - Recovered Transaction
  • 14 - Totals Entry
  • 15 - Return Merchandise (Return Transaction, identical to type 1)
  • 16 - Customer Payment (Payment on House Charge Accounts)
  • 17 - Change Tender
  • 18 - Receipt Block
  • 19 - Tender Correct (Tender removed from transaction)
  • 20 - No Tax Total
  • 21 - Reconciliation Action
  • 22 - Tender Loan
  • 23 - Tender Safe Drop
  • 24 - Tender Mod Indicator
  • 25 - Discount Total
  • 26 - Discount Total Correct
  • 27 - Paid Out
  • 28 - Paid In
  • 29 - Paid Out Correct
  • 30 - Age Verification
  • 31 - Vendor Coupon
  • 32 - Credit Card Soft Check
  • 33 - POS Prompt
  • 34 - Salesperson (The Salesperson associated with a Transaction)
  • 35 - Combo Total
  • 36 - Combo Item
  • 37 - Combo Removed
  • 38 - WIC ID
  • 39 - WIC Voucher Number
  • 40 - WIC Voucher First Date
  • 41 - WIC Voucher Last Date
  • 42 - WIC Date Valid
  • 43 - WIC Voucher Amount
  • 44 - Prescription Info
  • 45 - Signature Capture
  • 46 - Electronic Gift Card
  • 47 - Electronic Gift Card Info
  • 48 - Buy Down Correct
  • 49 - Buy Down
  • 50 - Safe Drop Warning
  • 51 - Loyalty
  • 52 - Auto Transaction
  • 53 - Paid In Correct
  • 54 - Prepaid Cards
  • 55 - Receipt Plug-in
  • 56 - Cash Back
  • 57 - Fuel Info
  • 58 - Do Not Use / Type Not Used By Transaction Server
  • 59 - Rewards
  • 60 - Special Order
  • 61 - Transaction Merge
  • 62 - Return Limit Info
  • 63 - Discount Card
TLI_StartTime
string/([0-9]{4})-(?:[0-9]{2})-([0-9]{2}) ([0-9]{2}...

This field contains the line item start time.

Note: For accuracy, use TRN_EndTime as the indicator of a particular transaction time.

TLI_EndTime
string/([0-9]{4})-(?:[0-9]{2})-([0-9]{2}) ([0-9]{2}...

This field contains the line item end time.

Note: For accuracy, use TRN_EndTime as the indicator of a particular transaction time.

TLI_Amount
string <decimal> <= 16 characters

The dollar amount of the for a line item of the transaction.

TLI_ReceiptAlias
string <= 50 characters

The Receipt Alias for a line item of the transaction.

TLI_Quantity
string <decimal> <= 12 characters

The Quantity of a particular line item on the transaction.

TLI_ScanCode
string <= 50 characters

The scancode/UPC of a line item on the transaction. Only valid for line items defined as Inventory Items. Conditionally returns either a base Item ID or an Alternate ID.

TLI_TaxDifference
string <decimal> <= 16 characters

Not currently recommended as reliable source of data.

ExtendedPrice
string <decimal> <= 16 characters

The extended price for a particular base line item sold in the transaction.

Note: For accuracy, use ExtendedBasePrice instead.

ExtendedBasePrice
string <decimal> <= 16 characters

The extended base price of a particular base line item sold in the transaction.

Field Formula: Base Price × Alternate ID Item Count in Pkg × Unit Quantity Sold.

CTI_CMB_FK
integer
CTI_CMB_CFK
integer
CTI_DiscountAmount
numreric
CTI_SellingAmount
numeric
CTI_TLI_FK_Item
integer

The relational ink between a combo and line item, where applicable.

CMB_Name
string

The name of a combo associated with a line item on the transaction, where applicable.

CPT_Void
boolean

Whether or not the charge payment, if used in the transaction, was accepted or voided. Only valid when TLI_LIT_FK = 16 (Charge Payment).

  • 0 = Charge Payment is good.
  • 1 = Charge Payment is voided.
DLI_TypeDollar
boolean

Whether or not the line item discount, if applied in the transaction, was a dollar-based reduction. Only valid when TLI_LIT_FK = 4 (Discount Line Item).

  • 0 = Discount is not a dollar reduction.
  • 1 = Discount is a dollar reduction.
DLI_TypePercent
boolean

Whether or not the line item discount was a percentage-based reduction. Only valid when TLI_LIT_FK = 4 (Discount Line Item).

  • 0 = Discount is not a percent reduction.
  • 1 = Discount is a percent reduction.
DLI_LineItem
string
DLI_DIS_FK
integer

The unique identifier for the discount line item applied in the transaction, where applicable.

DLI_Void
boolean

Whether or not the particular discount line item was completed or voided. Only valid when TLI_LIT_FK = 4 (Discount Line Item).

  • 0 = Discount Line Item is completed.
  • 1 = Discount Line Item is voided.
DLI_DIS_CFK
integer

The unique creator identifier for the discount line item applied in the transaction, where applicable.

DLI_ApplyBeforeTax
boolean

Whether or not the discount is calculated before or after tax(es). Only valid when TLI_LIT_FK = 4 (Discount Line Item).

  • 0 = Discount is applied before tax.
  • 1 = Discount is applied after tax.

See also: Discount Generator (Applying Taxes).

DLI_Return
boolean

Whether or not the discount is a return. Only valid when TLI_LIT_FK = 4 (Discount Line Item).

  • 0 = Discount is applied in a normal sale.
  • 1 = Discount is applied in a return.
DLI_INV_FK
integer

The unqiue identifer for the particular base item on which the discount was applied. Only valid when TLI_LIT_FK = 4 (Discount Line Item).

DLI_INV_CFK
integer

The unqiue creator dentifer for the particular base item on which the discount was applied. Only valid when TLI_LIT_FK = 4 (Discount Line Item).

DLI_Automatic
boolean

Whether the discount is Manual or Automatic. Only valid when TLI_LIT_FK = 4 (Discount Line Item).

  • 0 = Manual Discount
  • 1 = Automatic Discount
DLI_ASC_FK
integer

The unique identifer of the Alternate ID item on which the discount was applied. Only valid when TLI_LIT_FK = 4 (Discount Line Item).

  • If applied to an Alternate ID line item, this returns the respective AdditionalScanCodes identifier particular to that Alternate ID item.
  • If applied to a Base ID line item, this returns a null value.
DLI_ASC_CFK
integer

The unique creator identifer of the Alternate ID item on which the discount was applied. Only valid when TLI_LIT_FK = 4 (Discount Line Item).

  • If applied to an Alternate ID line item, this returns the respective AdditionalScanCodes creator identifier particular to that Alternate ID item.
  • If applied to a Base ID line item, this returns a null value.
DLI_InventoryLineItem
integer

The transaction item record which the discount applies to. Only valid when TLI_LIT_FK = 4 (Discount Line Item).

DLI_ReportConsolidated
boolean

Whether or not the discount is to be consolidated in reports. Only valid when TLI_LIT_FK = 4 (Discount Line Item).

  • 0 = Discount is not consolidated.
  • 1 = Discount is consolidated.
ITI_AverageCost
string <decimal> <= 16 characters

The average cost of the base item at the time of the transaction. Only valid when TLI_LIT_FK = 1 or TLI_LIT_FK = 15 (Inventory Item).

ITI_EntryMethod
integer

The method by which the line item was entered onto the transaction. Only valid when TLI_LIT_FK = 1 or TLI_LIT_FK = 15 (Inventory Item).

  • 1 = Item was manually entered.
  • 2 = Item was scanned.
ITI_Return
boolean

Whether or not the line item is a return. Only valid when TLI_LIT_FK = 1 or TLI_LIT_FK = 15 (Inventory Item).

  • 0 = Line item was not a return (normal sale).
  • 1 = Line item was a return.
ITI_INV_FK
integer

The unique identifier of the base item that was sold/returned in the transaction. Only valid when TLI_LIT_FK = 1 or TLI_LIT_FK = 15 (Inventory Item).

ITI_Void
boolean

Whether or not the sale of a particular base item was completed or voided. Only valid when TLI_LIT_FK = 1 or TLI_LIT_FK = 15 (Inventory Item).

  • 0 = Sale of base item is completed.
  • 1 = Sale of base item is voided.
ITI_INV_CFK
integer

The unique creator identifier of the base item that was sold/returned in the transaction. Only valid when TLI_LIT_FK = 1 or TLI_LIT_FK = 15 (Inventory Item).

ITI_SellingPrice
string <decimal> <= 16 characters

The actual selling price of the base item after automatic discounts are applied. Only valid when TLI_LIT_FK = 1 or TLI_LIT_FK = 15 (Inventory Item).

Note: Does not include manual discounts, combos, promotions, etc.

ITI_BasePrice
string <decimal>

The price of the base item before any automatic discounts or taxes are applied. Only valid when TLI_LIT_FK = 1 or TLI_LIT_FK = 15 (Inventory Item).

ITI_ASC_FK
integer

The unique identifer of the Alternate ID item that was sold/returned in the transaction. Only valid when TLI_LIT_FK = 1 or TLI_LIT_FK = 15 (Inventory Item).

  • For Alternate ID items, this returns the respective AdditionalScanCodes creator identifier particular to a Alternate ID line item.
  • For Base ID line item, this returns a null value.
ITI_ASC_CFK
integer

The unique creator identifer of the Alternate ID item that was sold/returned in the transaction. Only valid when TLI_LIT_FK = 1 or TLI_LIT_FK = 15 (Inventory Item).

  • For Alternate ID items, this returns the respective AdditionalScanCodes creator identifier particular to a Alternate ID line item.
  • For Base ID line item, this returns a null value.
ITI_ASCQuantity
string <decimal> <= 12 characters

The item count within the defined package for an Alternate ID line item in the transction, where applicable. Only valid when TLI_LIT_FK = 1 or TLI_LIT_FK = 15 (Inventory Item).

ITI_PriceLevel
integer

The Price Level of the item at the time of transaction sale. Only valid when TLI_LIT_FK = 1 or TLI_LIT_FK = 15 (Inventory Item).

ITI_DiscountPriceOverride
integer

Always returns 1.

DPT_Name
string <= 30 characters

The Department Name associated with the line item at the time of transaction sale. Only valid when TLI_LIT_FK = 1 or TLI_LIT_FK = 15 (Inventory Item).

DPT_Number
integer

The Department ID for the department associated with a line item at the time of transaction sale.

DPT_OmitFromSales
boolean
  • 0 = Sales Department.
  • 1 = Omit from Sales Department.
TTI_TAX_FK
integer

The unique identifier for the applied tax record. Only valid when TLI_LIT_FK = 3.

TTI_TAX_CFK
integer

The unique creator identifier for the applied tax record. Only valid when TLI_LIT_FK = 3.

TTI_ReturnTax
boolean

Whether the tax was applied in a normal sale or return. Only valid when TLI_LIT_FK = 3.

  • 0 = Tax applied to normal sale item.
  • 1 = Tax applied to a return item.
TTI_TaxableAmount
string <decimal> <= 16 characters

The taxable dollar amount of the transaction subtotal. Only valid when TLI_LIT_FK = 3.

NTI_TEN_FK
integer

The unique identifier for the tender used on the transaction. Only valid when TLI_LIT_FK = 2 (Tender Record).

NTI_TEN_CFK
integer

The unique creator identifier for the tender used on the transaction. Only valid when TLI_LIT_FK = 2 (Tender Record).

NTI_AuthorizationCode
string <= 20 characters

The authorization code for the tender used on the transaction, where applicable.

TRN_ETI_AccountName
string <= 40 characters

The cardholder name, where applicable.

TRN_ETI_AccountNumber
string <= 4 characters

The last 4 digits of the card number used on the transaction.

TRN_ETI_CardType
string <= 5 characters

The Card Type used on the transaction.

TRN_ETI_TenderAmount
string <decimal> <= 14 characters

The amount tendered to the card in the transaction.

NTI_TenderType
integer

Defines the type of tender received as payment in the transaction. Only valid when TLI_LIT_FK = 2 (Tender Record).

NTI_Amount
string <decimal> <= 16 characters

The amount tendered. Only valid when TLI_LIT_FK = 2 (Tender Record).

NTI_Void
boolean

Whether the tendered transaction was completed or voided. Only valid when TLI_LIT_FK = 2 (Tender Record).

  • 0 = Not voided.
  • 1 = Voided.
NTI_SafeDrop
boolean

Whether or not this line item is a safe drop. Only valid when TLI_LIT_FK = 23 (Safe Drop).

  • 0 = No.
  • 1 = Yes.

Note: This will always return 1 when the line item type is set to safe drop. All other line item types return either 0 or NULL.

NTI_Loan
integer

Whether or not this line item is a drawer loan. Only valid when TLI_LIT_FK = 22 (Drawer Loan).

  • 0 = No.
  • 1 = Yes.

Note: This will always return 1 when the line item type is set to drawer loan. All other line item types return either 0 or NULL.

NTI_FCExchangeRate
string <decimal> <= 14 characters

The Foreign Currency Exchange Rate at the time of sale.

NTI_FCTenderAmount
string <decimal> <= 16 characters

The Foreign Currency Amount tendered.

NTI_ForeignCurrency
integer

Whether or not the transaction was tendered with a foreign currency.

  • 0 = Not Foreign Currency.
  • 1 = Foreign Currency.
TEN_PK
integer

The unique identifier of the tender received for the transaction. References the Tenders table. Only valid when TLI_LIT_FK = 2.

TEN_CPK
integer

The unique creator identifier of the tender received for the transaction. References the Tenders table. Only valid when TLI_LIT_FK = 2.

TEN_Description
string <= 30 characters

The description of the tender received for the transaction. Only valid when TLI_LIT_FK = 2.

CTI_BonusAmount
string <decimal> <= 16 characters

The total amount deducted from a line item by a vendor coupon. Only valid when TLI_LIT_FK = 31 (Vendor Coupon).

CTI_EntryMethod
boolean

Whether the vendor coupon was keyed in as a POS function or scanned at the time of transaction. How Only valid when TLI_LIT_FK = 31 (Vendor Coupon).

  • 1 = Vendor Coupon POS Function.
  • 2 = Scan.
  • 3 = Coupon from a Third-Party provider, such as Inmar®.
CTI_Void
integer

Only valid when TLI_LIT_FK = 31 (Vendor Coupon).

  • 0 = Good record.
  • 01 = Voided record.
CTI_ManufacturerCode
string <= 8 characters

The Coupon Manufacturer Code. Only valid when TLI_LIT_FK = 31 (Vendor Coupon).

CTI_FamilyCode
string <= 8 characters

The Coupon Family Code. Only valid when TLI_LIT_FK = 31 (Vendor Coupon).

CTI_CouponCode
string <= 8 characters

The Coupon Code. Only valid when TLI_LIT_FK = 31 (Vendor Coupon).

SalespersonFK
integer

The unique identifer for the employee designated as the the salesperson associated with the sale or return of an item, where applicable. Applies to normal sales, a returns, and on associated discount lines items. Only valid when TLI_LIT_FK = 1, TLI_LIT_FK = 4, or TLI_LIT_FK = 15.

SalespersonCFK
integer

The unique creator identifer for the employee designated as the the salesperson associated with the sale or return of an item, where applicable. Applies to normal sales, a returns, and on associated discount lines items. Only valid when TLI_LIT_FK = 1, TLI_LIT_FK = 4, or TLI_LIT_FK = 15.

GCT_Void
boolean
  • 0 = Gift Card Line is good.
  • 1 = Gift Card Line is voided.
LTN_Start1
string <= 32 characters

This field contains the starting value for Lot Number range 1.

LTN_End1
string <= 32 characters

This field contains the ending value for Lot Number range 1.

LTN_Start2
string <= 32 characters

This field contains the starting value for Lot Number range 2.

LTN_End2
string <= 32 characters

This field contains the ending value for Lot Number range 2.

LTN_Start3
string <= 32 characters

This field contains the starting value for Lot Number range 3.

LTN_End3
string <= 32 characters

This field contains the ending value for Lot Number range 3.

LTN_Start4
string <= 32 characters

This field contains the starting value for Lot Number range 4.

LTN_End4
string <= 32 characters

This field contains the ending value for Lot Number range 4.

LTN_Start5
string <= 32 characters

This field contains the starting value for Lot Number range 5.

LTN_End5
string <= 32 characters

This field contains the ending value for Lot Number range 5.

LTN_Start6
string <= 32 characters

This field contains the starting value for Lot Number range 6.

LTN_End6
string <= 32 characters

This field contains the ending value for Lot Number range 6.

LTN_AddtlRanges
string

This field contains values for any additional Lot Number ranges.

TRN_Total
string <decimal> <= 16 characters

The transaction total.

TRN_NetSales
string <decimal> <= 16 characters

The transaction sales amount after any modifiers.

TRN_ItemQuantity
string <= 12 characters
TRN_ItemCorrects
string
TRN_Negatives
string
StoreNumber
string <= 10 characters

The store number where the transaction was completed.

TRN_ETI_Approval
string <= 20 characters
TRN_ETI_Reference
string <= 20 characters
TRN_ETI_RemainingBalance
string <decimal> <= 16 characters
TRN_ETI_CvvResult
string <= 1 characters
TRN_ETI_AvsResult
string <= 1 characters
TRN_ETI_Bin
string <= 6 characters
TRN_ETI_AuthorizationDate
string <= 8 characters
TRN_ETI_AuthorizationTime
string <= 8 characters
TRN_ETI_AuthorizationType
string <= 20 characters
TRN_ETI_AuthorizationStan
string <= 6 characters
CTI_ApplyToFoodstamps
boolean
CTI_ApplyToFSA
boolean
CTI_CouponBarcode
string <= 100 characters
CTI_ProviderId
string <= 32 characters
CTI_FaceValue
string <decimal>
NTI_CHG_FK
integer
NTI_CHG_CFK
integer
NTI_TLI_CashBack
integer
TLI_Divider
integer
ITI_BasePriceDivider
integer
ITI_PL1BasePriceDivider
integer
ITI_WeightEntryMethod
integer
ITI_TareEntryMethod
integer
ITI_Pl1BasePrice
string <decimal> <= 16 characters
ITI_Pl1PromptForPrice
boolean
ITI_TareWeight
string <decimal>
ITI_EmbeddedPrice
string <decimal> <= 16 characters
ITI_SpecialPricing
boolean
ITI_Variation
integer
ITI_LinkType
integer
ITI_ModQuantity
string <decimal> <= 12 characters
ITI_ModPrice
string <decimal> <= 16 characters
ITI_EmbeddedDiscount
string <decimal>
ITI_FSA
boolean
ITI_SNAP
boolean
ITI_WeightUnit
integer
PromptName
string <= 30 characters

The name of the cashier prompt activated in the transaction, where applicable.

PromptResponse
string <= 30 characters
PromptItem
integer
CTI_Expiration
string/([0-9]{4})-(?:[0-9]{2})-([0-9]{2}) ([0-9]{2}...
ITI_MarkdownBarCode
string <= 64 characters
ITI_TLI_LinkLineItem
integer
ComboTotalLoyaltyProgram
string <= 32 characters
ComboTotalStoreCouponName
string <= 30 characters
CTH_Voided
boolean
CTH_EarnedLoyalty
string <decimal>
LoyaltyTransactionLoyaltyProgram
string <= 32 characters
LoyaltyTransactionStoreCouponName
string <= 30 characters
LTI_Expiring
string <decimal>
LTI_ExpirationDate
string/([0-9]{4})-(?:[0-9]{2})-([0-9]{2}) ([0-9]{2}...
CTI_ComboTotalLineItem
integer
ComboOmitFromSales
boolean
CMB_ApplyAfterTaxes
boolean
STI_Status
integer
EMD_SequenceNumber
integer
EMD_TransactionSequenceNumber
integer
EMD_Time
string/([0-9]{4})-(?:[0-9]{2})-([0-9]{2}) ([0-9]{2}...
EMD_Tender
string <= 60 characters
EMD_TLI_FK
integer
EMD_5A
string <= 10 characters
EMD_82
string <= 4 characters
EMD_84
string <= 20 characters
EMD_9A
string <= 6 characters
EMD_9F21
string <= 6 characters
EMD_9C
string <= 2 characters
EMD_5F34
string <= 2 characters
EMD_5F2A
string <= 3 characters
EMD_9F02
string <= 12 characters
EMD_9F03
string <= 12 characters
EMD_9F08
string <= 4 characters
EMD_9F09
string <= 4 characters
EMD_9F1A
string <= 3 characters
EMD_9F33
string <= 32 characters
EMD_9F34
string <= 6 characters
EMD_9F35
string <= 2 characters
EMD_9F36
string <= 4 characters
EMD_9F37
string <= 10 characters
EMD_9F0D
string <= 10 characters
EMD_9F0E
string <= 10 characters
EMD_9F0F
string <= 10 characters
EMD_TACD
string <= 10 characters
EMD_TACO
string <= 10 characters
EMD_TACF
string <= 10 characters
EMD_95_1GEN
string <= 10 characters
EMD_9F10_1GEN
string <= 32 characters
EMD_9F26_1GEN
string <= 16 characters
EMD_9F27_1GEN
string <= 2 characters
EMD_91
string <= 20 characters
EMD_95_2GEN
string <= 10 characters
EMD_9F26_2GEN
string <= 16 characters
EMD_9F27_2GEN
string <= 2 characters
EMD_8A
string <= 4 characters
EMD_9B
string <= 4 characters
EMD_AppName
string <= 60 characters
EMD_CardEntryMethod
string <= 10 characters
EMD_CardVerMethod
string <= 10 characters
EMD_Mode
string <= 30 characters
EMD_9F06
string <= 32 characters
ITI_RetailAccountingPrice
string <decimal> <= 16 characters
ITI_RetailAccountingReportCode
string <= 30 characters
GCT_GCP_FK
integer
GCT_GCP_CFK
integer
GCT_Code
string <= 3 characters
GCT_Account
string <= 16 characters
GCT_SendDate
string/([0-9]{4})-(?:[0-9]{2})-([0-9]{2}) ([0-9]{2}...

Date the gift card is sent to the recipient.

GCT_Print
boolean
GCT_RecipientEmail
string <= 254 characters

The gift card recipient e-mail address.

GCT_RecipientPhoneNumber
string <= 14 characters

The gift card recipient phone number.

GCT_RecipientName
string <= 64 characters

The gift card recipient full name.

GCT_SenderName
string <= 64 characters

The gift card sender first name.

TRN_WTR_FK
integer
TRN_WTR_CFK
integer
TRN_ETI_ExpDate
string <= 5 characters
TRN_ETI_CardSwiped
boolean
TRN_ETI_Processor
string <= 20 characters
BaseItemID
string <= 14 characters

Available with CATAPULT 5.8.157 and Newer

  • Displays the Item ID of the base item, if an Alternate ID of the item was sold in the transaction.
  • If only the base item was sold in the transaction, the values in this field and TLI_Scancode will match.
PriceChangeWorksheetName
string <= 40 characters

Available with CATAPULT 5.8.157 and Newer

  • Displays the name of the temporary Price Change Worksheet or Price & Cost Change Worksheet that was used to adjust the pricing of the item at Transaction Server terminals.
  • This worksheet must be - or have been - active during the specified startTime and endTime query parameters of the endpoint.
  • If no temporary Price Change or Price & Cost Change worksheets were active during the specified startTime and endTime, this field, along with the PriceChangeWrksheetSavings and PriceChangeWrksheetLineSavings fields will be omitted from the response.
PriceChangeWrksheetSavings
number

Available with CATAPULT 5.8.157 and Newer

Displays the savings for an item, as determined by the associated Price Change or Price & Cost Change worksheet.

PriceChangeWrksheetLineSavings
number

Available with CATAPULT 5.8.157 and Newer

  • Displays the total savings for an item based on the quantity sold.
  • This value is calculated by multiplying the PriceChangeWrksheetSavings by the total quantity sold of the item in the transaction.

Request samples 

curl --request GET \
  --url 'https://accountid.catapultweboffice.com/api/TransactionJournal?apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0&startTime=2015-03-25T12%3A00%3A00&endTime=2015-03-25T16%3A00%3A00&CustomerID=4000000123456789&TransactionStatus=10&AllVoid=1'

Response samples

Content type
<?xml version="1.0" encoding="windows-1252" ?>
<root>
    <row TRN_PK="18048",
    TRN_CPK="1002",
    TRN_STO_FK="3",
    TRN_STO_CFK="1000",
    TRN_StartTime="2016-01-06 10:37:20.870",
    TRN_EndTime="2016-01-06 10:37:20.870",
    TRN_ReceiptNumber="16029",
    TRN_Type="0",
    TRN_EMP_FK="4",
    TRN_EMP_CFK="1000",
    TRN_SequenceNumber="16029",
    TRN_TCF_FK="2",
    TRN_TCF_CFK="1002",
    TRN_CUS_FK="2",
    TRN_CUS_CFK="1000",
    TRN_AllVoid="0",
    TRN_UploadTime="2016-01-06 10:37:20.870",
    TRN_Status="0",
    TCF_Description="Terminal 1",
    TCF_Number="1",
    TCF_TerminalId="07325795",
    EMP_Number="99",
    EMP_FirstName="Self",
    EMP_LastName="Checkout",
    CUS_AccountNumber="4012345678900",
    CUS_FirstName="John",
    CUS_LastName="Smith",
    CUS_Company="ECRS",
    TLI_PK="1",
    TLI_LIT_FK="1",
    TLI_StartTime="2016-01-06 10:37:20.870",
    TLI_EndTime="2016-01-06 10:37:20.870",
    TLI_Amount="1.29",
    TLI_ReceiptAlias="Widget",
    TLI_Quantity="1.000",
    TLI_ScanCode="212345678901",
    TLI_TaxDifference="1.29",
    ExtendedPrice="1.29",
    ExtendedBasePrice="1.29",
    CTI_CMB_FK=0,
    CTI_CMB_CFK=0,
    CTI_DiscountAmount=null,
    CTI_SellingAmount=null,
    CTI_TLI_FK_Item="1",
    CMB_Name="string",
    CPT_Void="0",
    DLI_TypeDollar=true,
    DLI_TypePercent=true,
    DLI_LineItem="string",
    DLI_DIS_FK=0,
    DLI_Void="0",
    DLI_DIS_CFK=0,
    DLI_ApplyBeforeTax="0",
    DLI_Return="0",
    DLI_INV_FK="1",
    DLI_INV_CFK="1000",
    DLI_Automatic="0",
    DLI_ASC_FK="1",
    DLI_ASC_CFK="1000",
    DLI_InventoryLineItem="3",
    DLI_ReportConsolidated="0",
    ITI_AverageCost="1.29",
    ITI_EntryMethod="1",
    ITI_Return="0",
    ITI_INV_FK="1",
    ITI_Void=true,
    ITI_INV_CFK="1000",
    ITI_SellingPrice="1.29",
    ITI_BasePrice="string",
    ITI_ASC_FK="1",
    ITI_ASC_CFK="1000",
    ITI_ASCQuantity="1.00",
    ITI_PriceLevel="1",
    ITI_DiscountPriceOverride="1",
    DPT_Name="Grocery",
    DPT_Number="99",
    DPT_OmitFromSales="0",
    TTI_TAX_FK="1000",
    TTI_TAX_CFK="1000",
    TTI_ReturnTax="0",
    TTI_TaxableAmount="1.29",
    NTI_TEN_FK="1",
    NTI_TEN_CFK="1000",
    NTI_AuthorizationCode="string",
    TRN_ETI_AccountName="string",
    TRN_ETI_AccountNumber="stri",
    TRN_ETI_CardType="strin",
    TRN_ETI_TenderAmount="1.29",
    NTI_TenderType="2",
    NTI_Amount="1.2900",
    NTI_Void="0",
    NTI_SafeDrop="1",
    NTI_Loan="1",
    NTI_FCExchangeRate="0.76",
    NTI_FCTenderAmount="1.29",
    NTI_ForeignCurrency="0",
    TEN_PK="1",
    TEN_CPK="1000",
    TEN_Description="Cash",
    CTI_BonusAmount="1.29",
    CTI_EntryMethod="1",
    CTI_Void="0",
    CTI_ManufacturerCode="string",
    CTI_FamilyCode="string",
    CTI_CouponCode="string",
    SalespersonFK="1",
    SalespersonCFK="1000",
    GCT_Void="0",
    LTN_Start1="string",
    LTN_End1="string",
    LTN_Start2="string",
    LTN_End2="string",
    LTN_Start3="string",
    LTN_End3="string",
    LTN_Start4="string",
    LTN_End4="string",
    LTN_Start5="string",
    LTN_End5="string",
    LTN_Start6="string",
    LTN_End6="string",
    LTN_AddtlRanges="string",
    TRN_Total="string",
    TRN_NetSales="string",
    TRN_ItemQuantity="string",
    TRN_ItemCorrects="string",
    TRN_Negatives="string",
    StoreNumber="string",
    TRN_ETI_Approval="string",
    TRN_ETI_Reference="string",
    TRN_ETI_RemainingBalance="string",
    TRN_ETI_CvvResult="s",
    TRN_ETI_AvsResult="s",
    TRN_ETI_Bin="string",
    TRN_ETI_AuthorizationDate="string",
    TRN_ETI_AuthorizationTime="string",
    TRN_ETI_AuthorizationType="string",
    TRN_ETI_AuthorizationStan="string",
    CTI_ApplyToFoodstamps=true,
    CTI_ApplyToFSA=true,
    CTI_CouponBarcode="string",
    CTI_ProviderId="string",
    CTI_FaceValue="string",
    NTI_CHG_FK=0,
    NTI_CHG_CFK=0,
    NTI_TLI_CashBack=0,
    TLI_Divider=0,
    ITI_BasePriceDivider=0,
    ITI_PL1BasePriceDivider=0,
    ITI_WeightEntryMethod=0,
    ITI_TareEntryMethod=0,
    ITI_Pl1BasePrice="string",
    ITI_Pl1PromptForPrice=true,
    ITI_TareWeight="string",
    ITI_EmbeddedPrice="string",
    ITI_SpecialPricing=true,
    ITI_Variation=0,
    ITI_LinkType=0,
    ITI_ModQuantity="string",
    ITI_ModPrice="string",
    ITI_EmbeddedDiscount="string",
    ITI_FSA=true,
    ITI_SNAP=true,
    ITI_WeightUnit=0,
    PromptName="string",
    PromptResponse="string",
    PromptItem=0,
    CTI_Expiration="string",
    ITI_MarkdownBarCode="string",
    ITI_TLI_LinkLineItem=0,
    ComboTotalLoyaltyProgram="string",
    ComboTotalStoreCouponName="string",
    CTH_Voided=true,
    CTH_EarnedLoyalty="string",
    LoyaltyTransactionLoyaltyProgram="string",
    LoyaltyTransactionStoreCouponName="string",
    LTI_Expiring="string",
    LTI_ExpirationDate="string",
    CTI_ComboTotalLineItem=0,
    ComboOmitFromSales=true,
    CMB_ApplyAfterTaxes=true,
    STI_Status=0,
    EMD_SequenceNumber=0,
    EMD_TransactionSequenceNumber=0,
    EMD_Time="string",
    EMD_Tender="string",
    EMD_TLI_FK=0,
    EMD_5A="string",
    EMD_82="string",
    EMD_84="string",
    EMD_9A="string",
    EMD_9F21="string",
    EMD_9C="string",
    EMD_5F34="string",
    EMD_5F2A="string",
    EMD_9F02="string",
    EMD_9F03="string",
    EMD_9F08="string",
    EMD_9F09="string",
    EMD_9F1A="string",
    EMD_9F33="string",
    EMD_9F34="string",
    EMD_9F35="string",
    EMD_9F36="string",
    EMD_9F37="string",
    EMD_9F0D="string",
    EMD_9F0E="string",
    EMD_9F0F="string",
    EMD_TACD="string",
    EMD_TACO="string",
    EMD_TACF="string",
    EMD_95_1GEN="string",
    EMD_9F10_1GEN="string",
    EMD_9F26_1GEN="string",
    EMD_9F27_1GEN="string",
    EMD_91="string",
    EMD_95_2GEN="string",
    EMD_9F26_2GEN="string",
    EMD_9F27_2GEN="string",
    EMD_8A="string",
    EMD_9B="string",
    EMD_AppName="string",
    EMD_CardEntryMethod="string",
    EMD_CardVerMethod="string",
    EMD_Mode="string",
    EMD_9F06="string",
    ITI_RetailAccountingPrice="string",
    ITI_RetailAccountingReportCode="string",
    GCT_GCP_FK=0,
    GCT_GCP_CFK=0,
    GCT_Code="string",
    GCT_Account="string",
    GCT_SendDate="string",
    GCT_Print=true,
    GCT_RecipientEmail="string",
    GCT_RecipientPhoneNumber="string",
    GCT_RecipientName="string",
    GCT_SenderName="string",
    TRN_WTR_FK=0,
    TRN_WTR_CFK=0,
    TRN_ETI_ExpDate="string",
    TRN_ETI_CardSwiped=true,
    TRN_ETI_Processor="string",
    BaseItemID="4011",
    PriceChangeWorksheetName="Weekly Sale",
    PriceChangeWrksheetSavings="1.9900",
    PriceChangeWrksheetLineSavings="3.9800"/>
</root>

Items

CATAPULT Passport API offers three endpoints that allow you to obtain data for inventory items. For each endpoint, the data is obtained via a GET request. The three "Items" endpoints are:

  • Detailed Search - This endpoint allows you to query and receive item data by Receipt Alias, Item ID, or Item Group. Viewing item data at specific stores is also possible with this endpoint.
  • View All - This endpoint allows you query and receive all items from all stores. Note that only a subset of the fields available on an inventory record will be included in the response with this endpoint.
  • Deli Item Data - This endpoint, which is only available with CATAPULT 5.7.141 and newer, allows you to obtain item data with associated deli information and attributes (e.g., nutrition facts).

See the Detailed Search, View All, and Deli Item Data sections below for more information on each endpoint.

Detailed Search

  • This endpoint allows you to search for and retrieve information about a particular item, including promotional data.
  • Promotional details for an inventory record are returnable only if a provided storeNumber is correctly associated with an applicable Zone profile.
  • This endpoint can be called from either the Headquarters or a Remote Store Web Office address.
    • Note API Keys do not replicate and must be re-created for an employee record in a target RS Web Office interface. This RS-specific API Key can then be passed in the request header for authentication to that particular store.
query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

itemSearch
string <= 32 characters
Example: itemSearch=401234567890
  • Accepts exact or begins with text matches for Receipt Alias.
  • Accepts exact matches for an Item ID.
  • This parameter should always be populated with either an Item ID or Receipt Alias value. This parameter should not be left empty, as doing so will return all items. If all items are needed, the "View All" - /allItems - endpoint should be used.
groupSearch
string <= 30 characters
Example: groupSearch=Bakery
  • Accepts exact or begins with text matches for the name of a Conventional Item Group.
  • Returns the item in itemSearch when both paramaters are provided.
storeNumber
required
string <= 10 characters
Example: storeNumber=123
  • Accepts a Store Number to filter response data. The Store Number could represent a Headquarters (HQ) or Remote Store (RS).
  • Stores must have a Zone profile associated to return promotional data.

Responses

Response Schema:
Array
itemId
string

Item Id / scan code

receiptAlias
string

Item receipt alias

itemName
string

Item name

department
string

Department the item is assigned to

subDepartment
string

SubDepartment the item is assigned to

category
string

Category the item is assigned to

subCategory
string

SubCategory the item is assigned to

variety
string

Variety the item is assigned to

size
string

Size of the item

brand
string

Brand of the item

loyaltyMultiplier
number <double>

The loyalty multiplier for the default loyalty program for this customer

shelfLocation
string

Shelf Location of the item

shelfSequence
string

Shelf Sequence of the item

pricePL1
number <double>

Base Price of the item at Price Level 1

priceDividerPL1
number <double>

Price Divider for Price Level 1

pricePL2
number <double>

Base Price of the item at Price Level 2

priceDividerPL2
number <double>

Price Divider for Price Level 2

pricePL3
number <double>

Base Price of the item at Price Level 3

priceDividerPL3
number <double>

Price Divider for Price Level 3

pricePL4
number <double>

Base Price of the item at Price Level 4

priceDividerPL4
number <double>

Price Divider for Price Level 4

promoPricePL1
number <double>

Promotional Price of the item at Price Level 1, only returned if item is listed in active promotion worksheet

promoPriceDividerPL1
number <double>

Promotional Price Divider for Price Level 1, only returned if item is listed in active promotion worksheet

promoPricePL2
number <double>

Promotional Price of the item at Price Level 2, only returned if item is listed in active promotion worksheet

promoPriceDividerPL2
number <double>

Promotional Price Divider for Price Level 2, only returned if item is listed in active promotion worksheet

promoPricePL3
number <double>

Promotional Price of the item at Price Level 3, only returned if item is listed in active promotion worksheet

promoPriceDividerPL3
number <double>

Promotional Price Divider for Price Level 3, only returned if item is listed in active promotion worksheet

promoPricePL4
number <double>

Promotional Price of the item at Price Level 4, only returned if item is listed in active promotion worksheet

promoPriceDividerPL4
number <double>

Promotional Price Divider for Price Level 4, only returned if item is listed in active promotion worksheet

lastCost
number <double>

Last Cost of the item

averageCost
number <double>

Average Cost of the item

onHand
number <double>

Item quantity on hand

onOrder
number <double>

Item quantity on order

defaultSupplier
string

Default Supplier for the item

defaultSupplierUnitId
string

Default Supplier Unit Id for the item

defaultSupplierUnitQty
number <double>

Quantity in order unit for default supplier

powerField1
string

Power Field 1 associated with the item

storePowerField1
string

Store Power Field 1 associated with the item

type
string

Available with CATAPULT version 5.7.123 and newer, this field displays the 'Type' of each item, as assigned on the item's inventory record in CATAPULT Web Office. An item's Type determines if it's treated as an item that you sell and order regularly, or if it's only used to assist in transaction-specific scenarios (and is not sold as a "regular" item). There are two item Types:

  • Stock Inventory - Stock Inventory items are tangible products that you sell in store or online. On-Hand quantities are tracked for Stock Inventory items.
  • Service - Service items are non-tangible products. On-Hand quantities are not tracked for Service items, and they cannot be received on worksheets, transferred to another store, or sold by weight.
discontinued
boolean

Available with CATAPULT version 5.7.126 and newer, this field displays the Discontinued status (Discontinued or Not Discontinued) of an item at the store where the API query is performed for this endpoint. One of two responses can be given for this field:

  • 0 - Signifies that the item in question is NOT set as Discontinued for the store.
  • 1 - Signifies that the item in question IS set as Discontinued for the store.

Request samples 

curl --request GET \
  --url 'https://accountid.catapultweboffice.com/api/itemDetail?apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0&itemSearch=401234567890&groupSearch=Bakery&storeNumber=123'

Response samples

Content type
[
  • {
    }
]

View All

  • This endpoint allows for the bulk retrieval of all inventory records from the Headquarters CATAPULT database.
  • Basic, identifying item data will be returned for each item (e.g., Item ID, Receipt Alias, etc.). Store specific data such as pricing, or otherwise, is not included with this endpoint.
  • If specific items from specific stores are needed, the "Detailed Search" - /itemDetail - endpoint should be used.
query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

Responses

Response Schema:
object
object (allItems)
itemId
string

The unique item identifier (scancode).

name
string

The item name.

receiptAlias
string

The item receipt alias.

unitOfMeasure
string

The size/unit descriptor, where applicable.

departmentNumber
string

The item department number, where applicable.

brand
string

The item brand.

powerField1
string

The PowerField 1 value on this item record (only returns global PowerField values).

subDepartmentNumber
string

The item hierarchy sub-department number, if any.

See also: Item Hierarchies.

categoryNumber
string

The item hierarchy category number, if any.

subCategoryNumber
string

The item hierarchy sub-category number, if any.

variety
string

The item hierarchy variety, if any.

familyLine
string

The item family line, if any.

Request samples 

curl --request GET \
  --url 'https://accountid.catapultweboffice.com/api/allItems?apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0'

Response samples

Content type
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <row itemId="999" 
  name="REAL MEDLEYS APPLE NUT HARVEST BAR"
  receiptAlias="APPLE NUT HRVST BAR"
  unitOfMeasure="12 ea"
  departmentNumber="5"
  brand="QUAKER"
  powerField1="Fruit Bar Collection"
  subCategoryNumber="15"
  categoryNumber="45"
  variety="Harvest Bar"
  familyLine="Breakfast Bar"/>
</root>

Deli Item Data

CATAPULT Version Requirements

  • This endpoint was added in CATAPULT 5.7.141, and is available in all subsequent versions.

Overview

  • Endpoint = /labelDataExport
  • Calling this endpoint performs a GET request to the CATAPULT Database to obtain the Deli Scale Attributes - and other related information - for inventory items at a specified store.
  • The intent of this endpoint is to allow you to take the obtained data and use it with a third-party label software, deli scale management software, or with Electronic Shelf Labels.

Snapshots

  • When a request to the labelDataExport endpoint is performed, a "snapshot" of data is created, and this snapshot will be for the all of the available - and specified - inventory data. This snapshot is created so that you can make as many requests as needed to get all of your (paged) data without the system having to obtain and build the data repeatedly.
  • Each snapshot is maintained over a 3-minute sliding expiration period. Meaning, it will only expire 2-3 minutes after the last request for the data takes place.
  • Each snapshot is maintained per API Key + Store + Value of since Parameter; any subsequent requests for a specific Key/Store/Since combination will pull from the snapshot that was created.

Requirements

In order to use the /labelDataExport endpoint, the requirements detailed below must be met:

1) Authentication

Any user who calls the /labelDataExport endpoint must meet the following authentication requirements:

  • Have a valid API Key (generated on a designated Employee Record in CATAPULT Web Office)
  • The designated Employee Record must be "Active" (i.e., the Inactive checkbox must not be selected on their Employee Record in CATAPULT Web Office)

Should the user calling the endpoint not meet any of the authentication requirements, a 403 "Error" response will be returned.

2) Application of Advanced Settings

Two Advanced Settings must be applied in CATAPULT Web Office to allow a user to call the /labelDataExport endpoint:

Advanced Setting #1

  • KEY
    • unified.label.enabled
  • VALUE
    • true
  • LEVEL
    • Store Level - Headquarters
  • REQUIRED
    • Yes

Advanced Setting #2

IMPORTANT - This Advanced Setting should ONLY be Applied with CATAPULT Versions 5.7.141 - 5.7.152. For users on CATAPULT 5.7.153+, see the Create & Assign Third Party Label Service to Desired "Deli Items" requirement below.

  • KEY
    • LabelDataExportFilterName
  • VALUE
    • Name of Global Inventory Filter
  • LEVEL
    • Store Level - Headquarters
  • REQUIRED
    • Yes
  • CONTEXT
    • By default, when the /labelDataExport request is performed, all items in the store's CATAPULT database will be returned. To limit the returned results to only applicable "deli items", a Global Inventory Filter must be created and saved.
    • The created Global Inventory Filter must contain criteria that will only allow the desired items to be returned in the result set. This filter criteria will vary depending on your item set, but examples might include items within a certain Department, items with a specific Nutrition Fact Label Format, or any eligible combination of the available Inventory Filter points.
    • The created Global Inventory Filter should contain filter criteria that will EXCLUDE items marked as "Discontinued" from the result set, as these items will be included by default.
    • Once created and saved, the entered Name of the Global Inventory Filter filter will be used as the VALUE of the Advanced Setting.
      • When a Global Inventory Filter is created and saved, CATAPULT Web Office appends "(Global)" to the end of the filter name to indicate to all users the scope of the filter. This appended text should NOT be included in the Advanced Setting VALUE.
      • EXAMPLE - If a Global Inventory Filter is created, saved, and named "Label Data Export Filter", it will appear as Label Data Export Filter (Global) in CATAPULT Web Office. With this, only the filter's name (e.g., "Label Data Export Filter") would be entered as the Advanced Setting's VALUE.

For more information on applying Advanced Settings in CATAPULT Web Office, click here to view the HOW TO: Add, Edit, and Delete an Advanced Setting article in the ECRS Online Manual.

3) Create & Assign Third Party Label Service to Desired "Deli Items"

CONTEXT

  • Third Party Service Profile is Required
    • Beginning with CATAPULT 5.7.153, any users of the /labelDataExport endpoint must create and assign a "Label" Third Party Service Profile to the desired "deli items" in CATAPULT Web Office. "Deli items" are those that are returned from the Global Inventory Filter created in Requirement #2 above.
    • The Third Party Service profile must be a "Label" type; other types are not applicable. In addition, the profile should not have any Third Party Service Keys (i.e., it should only have a Name and a Type).
    • Applying the Third Party Service profile to the deli items provides CATAPULT with a more efficient and reliable identification point to ensure those items - and their associated data - are provided to the third party service expecting them.
    • Third Party Service profiles are created in CATAPULT Web Office. To create a "Label" Third Party Service profile, all associated requirements (i.e., licensing, Authorization Security requirements, etc.) must be met. See this article in the ECRS Online Manual for more information and instruction on Third Party Service profiles.
  • Use Inventory Multi-Edit to Assign Third Party Service Profile
    • Because multiple inventory items in CATAPULT will have a Third Party Service profile assigned to them, it is recommended to use Inventory Multi-Edit in CATAPULT Web Office for assignment. See this article in the ECRS Online Manual for more information and instruction on Inventory Multi-Edit.
  • Conditional: Remove "LabelDataExportFilterName" Advanced Setting
    • If you previously used the /labelDataExport endpoint before CATAPULT 5.7.153+, then the "LabelDataExportFilterName" will still be in your system. This Advanced Setting is no longer required to send deli item data to third party services.
    • To prevent unnecessary Advanced Settings being present in your system, the "LabelDataExportFilterName" Advanced Setting should be removed. See this article in the ECRS Online Manual for instrucitons on removing an Advanced Setting.

INSTRUCTIONS

  1. Create "Label" Third Party Service profile in CATAPULT Web Office. The profile should have a clearly identifiable Name (e.g., Passport Deli Item Data) and have a Type of Label.
    • See this article in the ECRS Online Manual for more information on Third Party Service profiles.
  2. Still in CATAPULT Web Office, filter for the "deli items" within Inventory using one of the two methods listed below:
    • Apply the previously created "deli items" Global Inventory Filter. If needed, reference the VALUE of the "LabelDataExportFilterName" Advanced Setting to verify the name of the Global Inventory Filter used.
    • Create and apply a new Inventory Filter that will return the desired "deli items".
  3. Once the items have been filtered for, select all of them from the grid.
  4. Use Inventory Multi-Edit to assign the created "Label" Third Party Service to the filtered/selected items.
    1. In Inventory Multi-Edit, select the Options category, then select the Label field.
    2. Select the Store(s) where the change should be applied to the items.
    3. Select the created "Label" Third Party Service profile, then select Add.
    4. When prompted, confirm that you want to make changes to the selected Inventory records by selecting Yes.
  5. Conditional: Remove the "LabelDataExportFilterName" Advanced Setting
    • If the "LabelDataExportFilterName" Advanced Setting was previously applied, it should be removed. See this article in the ECRS Online Manual for instrucitons on removing an Advanced Setting

4) API Endpoint Call Must Use Headquarters Web Office URL

  • When the /labelDataExport endpoint is called a URL will be used. This URL must use the Account ID of the Headquarters store in the enterprise.
  • Even though the Headquarters Web Office URL must be used, data for a specific store in the enterprise can be returned by using the storeNumber query parameter.
query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

page
required
integer non-empty
Example: page=1
  • When the /labelDataExport request is performed, the results will be all of the inventory data - that meet the filter criteria - for the store that is specified with the storeNumber parameter; this will be a large set of data.
  • To avoid extended wait times to process the returned results, the returned data must be viewed in "pages", and this parameter requires that you specify the page number of the result set that is returned.
  • To view the result set in its entirety, increment/increase this parameter by one and perform the /labelDataExport request until no results are returned (i.e., no further pages).
storeNumber
required
string <= 4 characters
Example: storeNumber=RS26

This parameter requires that you specify the Store ID - as entered on the Store Record in CATAPULT Web Office - of the store that you want to view results for. When a Store ID is specified, all of the applicable inventory data will be exported from the CATAPULT database at a chosen store.

since
string <date-time>
Example: since=2024-05-31T12:00:00

This parameter allows you to specify a date and time, and the returned results will be items modified since the specified date and time.

  • When Performing the Request for the First Time: To ensure that all applicable results are returned, it is recommended NOT to enter a date and time for the since parameter when performing the /labelDataExport request for the first time, as the default date and time of 01-01-1970T12:00:00 will be used. This date and time is far enough in the past to guarantee that all applicable results will be returned with the first request.

  • When Performing the Request Subsequent Times: Once the /labelDataExport request is performed intially, the date and time of the last request should be entered with this parameter. If no date and time are entered, 01-01-1970T12:00:00 will be used by default, which will return all applicable data.

    • EXAMPLE: If the initial /labelDataExport request was performed on 05-31-2024 at 11:00:00 A.M., the second time the request is performed, that would be the date and time that would be entered for this parameter.
pageSize
integer [ 1 .. 25000 ] characters
Example: pageSize=750

This parameter allows you to optionally set the number of returned items per page of results. If this parameter is not specificed, 500 items will be returned on a single result set page by default. Note that higher pageSize values (e.g., 15000) will result in extended response times. In some cases, if there is too much data, and the specified pageSize is too large, then the request might time out and not complete.

Responses

Response Schema:
object
object (labelDataExport)
Dept
integer [ 1 .. 8 ] characters

This field represents the ID of the item's assigned Department.

PLU
string [ 1 .. 14 ] characters

This field represents the Item ID of the item.

Price
number <= 10000000000000000 characters

This field represents price of the item for Price Level 1.

PromoPrice
number <= 10000000000000000 characters
  • Available with CATAPULT 5.7.153 and newer.
  • This field represents the Price Level 1 "promotional price" for an item.
  • The promotional price for the item will be determined by a committed - and active - temporary Price Change or Price & Cost Change worksheet that the item is on.
  • This field does not include an item's promotional pricing for any other Price Level.
  • If an item is not on any active + temporary Price Change or Price & Cost Change worksheet at the time of the request, this field will not be included in the response.
NetWt
string <= 20 characters

This field represents the item's "Size", as entered in CATAPULT Web Office.

ShelfLife
integer <= 999 characters

This field represents the entered Shelf Life of the item.

Ingredients
string

This field represents the entered Ingredients for the item.

Description1
string <= 64 characters

This field represents the Deli Attribute Description Line 1 of the item, as entered on the item's Inventory Record in CATAPULT Web Office. 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).

Description2
string <= 64 characters

This field represents the Deli Attribute Description Line 2 of the item, as entered on the item's Inventory Record in CATAPULT Web Office. 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).

Description3
string <= 64 characters

This field represents the Deli Attribute Description Line 3 of the item, as entered on the item's Inventory Record in CATAPULT Web Office. 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).

Description4
string <= 64 characters

This field represents the Deli Attribute Description Line 4 of the item, as entered on the item's Inventory Record in CATAPULT Web Office. 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).

UserAssigned1
string <= 30 characters

This field represents the Deli Attribute User Assigned 1 field of the item, as entered on the item's Inventory Record in CATAPULT Web Office.

UserAssigned2
string <= 30 characters

This field represents the Deli Attribute User Assigned 2 field of the item, as entered on the item's Inventory Record in CATAPULT Web Office.

UserAssigned3
string <= 30 characters

This field represents the Deli Attribute User Assigned 3 field of the item, as entered on the item's Inventory Record in CATAPULT Web Office.

UserAssigned4
string <= 30 characters

This field represents the Deli Attribute User Assigned 4 field of the item, as entered on the item's Inventory Record in CATAPULT Web Office.

UserAssigned5
integer <= 30 characters

This field represents the Deli Attribute User Assigned 5 field of the item, as entered on the item's Inventory Record in CATAPULT Web Office.

UserAssigned6
integer <= 30 characters

This field represents the Deli Attribute User Assigned 6 field of the item, as entered on the item's Inventory Record in CATAPULT Web Office.

UserAssigned7
integer <= 30 characters

This field represents the Deli Attribute User Assigned 7 field of the item, as entered on the item's Inventory Record in CATAPULT Web Office.

ItemFixedWeight
integer <= 9999 characters

Available with CATAPULT 5.7.152 and newer, this field represents the integer entered for the Fixed weight amount Deli Scale Attribute, as entered on the item's Inventory Record in CATAPULT Web Office.

Scaleable
bit

This field represents if the item has an assigned Weight Profile.

  • yes = The item has an assigned Weight Profile
  • no = The item does NOT have an assigned Weight Profile.
Tare
number <= 999999999999.999 characters

This field represents the "Fixed" tare weight, which is established on the item's Weight Profile in CATAPULT Web Office.

CategoryNum
integer

This field represents ID of the item's assigned Category.

Logo1
integer

This field represents the Image 1 field for the "Logo numbers" Deli Attribute of the item, as entered on the item's Inventory Record in CATAPULT Web Office.

Logo2
integer

This field represents the Image 2 field for the "Logo numbers" Deli Attribute of the item, as entered on the item's Inventory Record in CATAPULT Web Office.

Logo3
integer

This field represents the Image 3 field for the "Logo numbers" Deli Attribute of the item, as entered on the item's Inventory Record in CATAPULT Web Office.

Logo4
integer

This field represents the Image 4 field for the "Logo numbers" Deli Attribute of the item, as entered on the item's Inventory Record in CATAPULT Web Office.

Logo5
integer

This field represents the Image 5 field for the "Logo numbers" Deli Attribute of the item, as entered on the item's Inventory Record in CATAPULT Web Office.

CountryOfOrigin
string <= 100 characters

This field represents the entered Country of Origin for the item.

Brand
string <= 30 characters

This field represents the name of the item's assigned Brand.

SubDepartment
string <= 30 characters

This field represents the name of the item's assigned Sub-Department.

Category
string <= 30 characters

This field represents the name of the item's assigned Category.

SubCategory
string <= 30 characters

This field represents the name of the item's assigned Sub-Category.

Variety
string <= 30 characters

This field represents the name of the item's assigned Variety.

Request samples 

curl --request GET \
  --url 'https://accountid.catapultweboffice.com/api/labelDataExport?apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0&page=1&storeNumber=RS26&since=2024-05-31T12%3A00%3A00&pageSize=750'

Response samples

Content type
<?xml version='1.1' encoding='UTF-8'?>
<root>
    <row Dept="23" PLU="99515" Price="2.9900" PromoPrice="1.9900" NetWt="16 OZ" ShelfLife="5" Ingredients="Red Potatoes, Dill, Sour Cream, Mayonnaise, Salt, Pepper, Sugar" Description1="string" Description2="string" Description3="string" Description4="string" UserAssigned1="string" UserAssigned2="string" UserAssigned3="string" UserAssigned4="string" UserAssigned5="5" UserAssigned6="6" UserAssigned7="7" ItemFixedWeight="3" Scaleable="yes" Tare="0.250" CategoryNum="12" Logo1="1" Logo2="2" Logo3="3" Logo4="4" Logo5="5" CountryOfOrigin="USA" Brand="Urban Market Deli" SubDepartment="Prepared Foods" Category="Cold Items" SubCategory="Weighted Cold Items" Variety="House-Made"/>
</root>

Customers

The Customer endpoint provides a means to quickly view, create or update customer records outside your Web Office interface.

Use GET to obtain customer information that already exists in your database. You can provide a particular customerId to check individual records or, by leaving the customerId parameter blank, check all available records. Use PUT to create new customer records or update existing ones. Be sure the Web Office login associated with the apikey in the PUT request has the necessary Add Customer, Edit Customer Authorization Security checkpoints enabled. That security access will be inherited by the request.

View & Search

  • This endpoint allows you retrieve data from customer records.
  • Results can be limited by customerId and/or modifiedSince, or exclude optional parameters to return all available data.
query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

customerId
string <= 16 characters
Example: customerId=401234567890

The unique ID of a customer record. To request data for all customer records, do not send this parameter.

See also: Customer ID.

modifiedSince
datetime

Last modified date. Filters response data by cus_timestamp. Accepts date-only YYYY-MM-DD or full datetime YYYY-MM-DD hh:mm:ss. To request data for all customer records, do not send this parameter.

Note: Use datetime format to further refine search results from a date-only request.''

Responses

Response Schema:
object
object (customers)
lastName
string

Customer last name.

firstName
string

Customer first name.

middleName
string

Customer middle name, if availabe.

nickName
string

Customer nick-name, if availabe.

memo
string

The memo recorded for the customer record.

powerField1
string

The value of PowerField 1 for the customer.

powerField2
string

The value of PowerField 2 for the customer.

powerField3
string

The value of PowerField 3 for the customer.

powerField4
string

The value of PowerField 4 for the customer.

powerField5
string

The value of PowerField 5 for the customer.

powerField6
string

The value of PowerField 6 for the customer.

powerField7
string

The value of PowerField 7 for the customer.

powerField8
string

The value of PowerField 8 for the customer.

birthDate
string <date>

The customer birthdate in YYYY-MM-DD format.

lastModified
string <date>

The last modified date of the customer record, in YYYY-MM-DD HH:MM:SS.sss format.

membershipAccount
string

The Account Name of the customer's membership, if the customer is a part of membership at the store. By default, the Account Name will be comprised of the customer's Last Name and their Customer ID (e.g., Smith40100637000029).

checkAcceptanceProfile
string

The name of the Check Status profile assigned to this customer.

priceLevel
string

The name of any custom price level assigned to this customer.

automaticDiscount
string

The name of the automatic discount assigned to this customer.

suppressReceipt
boolean

If true then receipts are not automatically printed.

loyaltyEnabled
boolean

If true then the default loyalty program is enabled for this customer.

loyaltyAccrualMultiplier
number <double>

The loyalty multiplier for customer's default loyalty program, if set.

suffix
string

The suffix for this customer.

prefix
string

The prefix for this customer.

title
string

The title of this customer.

company
string

The company for this customer.

checkFileMemo
string

The text entered for the Check File Memo field for the associated customer.

billToPhoneNumber
string

The bill-to phone number for this customer.

billToPhoneDescription
string

The description for the bill-to phone number for this customer.

billToEmailAddress
string

The bill-to email address for this customer.

billToEmailDescription
string

The description of the bill-to email address for this customer.

billToEmailMarketing
boolean

If true then the bill-to email address is allowed to receive marketing materials.

billToEmailReceipt
boolean

If true then the bill-to email address is set to receive eReceipts for this customers purchases.

billToAddressLine1
string

The first line of the bill-to address for this customer.

billToAddressLine2
string

The second line of the bill-to address for this customer.

billToAddressCity
string

The city of this customer's bill-to address.

billToAddressStateProv
string

The state or province of this customer's bill-to address.

billToAddressPostalCode
string

The postal code of this customer's bill-to address.

billToAddressDescription
string

The description of this customer's bill-to address.

membershipAccountJoined
string
  • The date and time that the customer obtained membership in the store.
  • The "joined" date and time will be automatically determined by CATAPULT when a Membership Profile is assigned to the customer's record; it cannot be specified.
  • The "joined" date and time will be in the following format: YYYY-MM-DD HH:MM:SS.sss
hideInLookup
boolean

If true then this customer will not show up in lookup dialogs.

customerInactive
boolean

If true then this customer is marked as inactive.

loyaltyBalances
string

The dollar value of this customer's current loyalty points balance. If the customer is a member of a Household, this will be the combined sum of all associated household members' loyalty balances, regardless of the customer's "Redeem Household Loyalty" eligiblity setting. Multiple loyalty program balances will be separated with the pipe | character.

HeadOfHousehold
string

The ID of this customer's head of household, if it is a member of another household.

HouseholdAccounts
string

If this customer is the head of household for multiple accounts, then this field contains a group-seperated hex 0x1D delimited list of all the household member accounts.

Dependents
string

If this customer has any dependents, then this field contains a group-seperated hex 0x1D, delimited list of all dependents.

Each dependent record is made of three fields partitioned by a Record Seperator 0x1E:

  • Relation
  • Name
  • Date in YYYY-MM-DD format

Repeat the three-field pattern as-needed to include multiple dependents for the customer.

lastPurchaseStore
string

The name of the last store from which this customer made a purchase. Read-only.

lastPurchaseDate
string

The name of the last date at which this customer made a purchase. Read-only.

membershipProfileName
string

The name of this customer's assigned Membership Profile. Read-only.

taxExemption
string

The name of the Tax that the customer is exempt from. The records for each Tax are managed in CATAPULT Web Office.

DateCreated
string

Available with CATAPULT 5.6.101 or newer, displays the date and time - in YYY-MM-DD 00:00:00.000 format - at which the customer record was created. Note that this creation could occur from CATAPULT Web Office or through API action, and any customer record added before this column was added to the CATAPULT database will return a DateCreated value of 1900-01-01.

HomeStore
string

The Home Store currently associated with this Customer.

Request samples 

curl --request GET \
  --url 'https://accountid.catapultweboffice.com/api/Customer?apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0&customerId=401234567890&modifiedSince=SOME_DATETIME_VALUE'

Response samples

Content type
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <row customerId="40100637000029"
  lastName="Smith"
  firstName="John"
  middleName="Doe"
  nickName="Johnny"
  memo="Memo Text for this Customer"
  powerField1="string"
  powerField2="string"
  powerField3="string"
  powerField4="string"
  powerField5="string"
  powerField6="string"
  powerField7="string"
  powerField8="string"
  birthDate="1970-01-01"
  lastModified="2019-12-19 14:43:55.041"
  membershipAccount="Smith40100637000029"
  checkAcceptanceProfile="Approve"
  priceLevel="3 Senior"
  automaticDiscount="Senior 10% Discount"
  suppressReceipt="false"
  loyaltyEnabled="true"
  loyaltyAccrualMultiplier="1.000"
  suffix="Jr."
  prefix="Mr."
  title="string"
  company="ECRS"
  checkFileMemo="Check File Memo Text for this Customer"
  billToPhoneNumber="8281112222"
  billToPhoneDescription="Business"
  billToEmailAddress="string"
  billToEmailDescription="Business"
  billToEmailMarketing="false"
  billToEmailReceipt="false"
  billToAddressLine1="string"
  billToAddressLine2="string"
  billToAddressCity="string"
  billToAddressStateProv="string"
  billToAddressPostalCode="string"
  billToAddressDescription="Business"
  membershipAccountJoined="2023-09-12 03:30:25.213"
  hideInLookup="false"
  customerInactive="false"
  loyaltyBalances="Default Program=.0200|Program A=0.0000|Program B=0.0000"
  HeadOfHousehold="string"
  HouseholdAccounts="string"
  Dependents="Pet&#x1e;Fido&#x1e;2017-12-18"
  lastPurchaseStore="123"
  lastPurchaseDate="2014-08-17"
  membershipProfileName="Ownership"
  taxExemption="State Tax"
  DateCreated="2022-02-04 11:30:00.000"
  HomeStore="Spring Valley Store"/>
</root>

Edit & Update

Purpose

Use this endpoint to insert new - or update existing - customer records in your CATAPULT database.

Notes & Considerations

  • The lastName parameter is only required for new customer records. This operation is limited to the creation and modification of customer maintenance records.

  • This endpoint does not create Discounts, Price Levels, Check Profiles, or Membership Profiles. These must be created separately, either in WebOffice or by a supported API endpoint, before being used in a query parameter with this endpoint.

  • With CATAPULT 5.8.160 and newer, the following billToAddress fields can be cleared/emptied from an existing customer record if NONE is entered as the query parameter value:

    • Address Line 1
    • Address Line 2
    • City
    • State / Province
    • Postal (ZIP) Code
    • Email Address
    • Phone Number

    If an entire address needs to be removed from a customer's record, the /batch/addresses endpoint should be used. See the Batch Addresses section below for more information.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

customerId
string <= 16 characters
  • If this field’s value is not specified, then a new Customer will be created, with a Customer ID determined automatically.
  • Generated Customer ID's will be 12-digit integers, starting with a 4, and ending with a GS1 UPC/EAN-compliant check digit.
  • If this field’s value is specified, a new Customer will be created (or updated if already existing) having the specified Customer ID.
firstName
string <= 25 characters

This field contains the Customer’s First Name.

lastName
string <= 25 characters

This field contains the Customer’s Last Name.

Required for new records.

middleName
string <= 25 characters

This field contains the Customer’s Middle Name.

nickName
string <= 25 characters

This field contains the Customer’s Alias.

prefix
string <= 30 characters

This field contains the Customer’s Prefix (Rev., Mrs., Mr., etc.).

suffix
string <= 30 characters

This field contains the Customer’s Suffix (Jr.,Sr.,MD., etc.).

title
string <= 25 characters

This field contains the Customer’s Title.

company
string <= 50 characters

This field contains the Company associated with the Customer.

memo
string <= 254 characters

This field contains a string for entering notes about the Customer to save to the record.

automaticDiscount
string <= 30 characters

Enter name of the Automatic Discount to apply on a Customer's record. Send empty string to remove an Automatic Discount from existing customer record.

WARNING: If the specified Discount does not exist, an error will be returned and the record will not be created or updated.

If an Automatic Discount is specified, it will take priority over Automatic Discount Groups entered in the same query and remove those that already exist on the customer record. Records cannot have both an Automatic Discount and an Automatic Discount Group.

automaticDiscountGroup
string

This field contains the name of the Automatic Discount Group to apply to a Customer. Send empty string to remove an Automatic Discount Group from the customer record.

WARNING: If the specified Discount Group does not exist, an error will be returned and the record will not be created or updated.

If an Automatic Discount is specified in the same query, then any entered Automatic Discount Group will be blocked/dropped. Records cannot have both an Automatic Discount and an Automatic Discount Group.

priceLevel
tinyint

This field contains the Price Level assigned to the Customer. You may specify the name of the Price Level or the number (1, 2, 3, or 4).

WARNING: If the specified Price Level does not exist, an error will be returned and the record will not be created or updated.

powerField1
string <= 30 characters

This field contains the value of Power Field 1.

powerField2
string

This field contains the value of Power Field 2.

powerField3
string <= 30 characters

This field contains the value of Power Field 3.

powerField4
string <= 30 characters

This field contains the value of Power Field 4.

powerField5
string <= 30 characters

This field contains the value of Power Field 5.

powerField6
string <= 30 characters

This field contains the value of Power Field 6.

powerField7
string <= 30 characters

This field contains the value of Power Field 7.

powerField8
string <= 30 characters

This field contains the value of Power Field 8.

birthDate
date

This field contains the Customer’s Birth Date (YYYY-MM-DD).

loyaltyEnabled
boolean

This field is set to True if the Customer is to accrue Loyalty Points, False otherwise. For new Customers, true is assumed if the default accrual rate for new Customers is set in headquarters' Transaction Security Profile.

loyaltyAccrualMultiplier
number <double>

This field contains the Accrual Rate Multiplier of the new Customer (must be between 0 and 10 inclusive).

suppressReceipt
boolean

This field is set to true to opt the Customer out of paper receipts, false otherwise.

checkFileMemo
string <= 254 characters

This field contains a string for entering notes related to the Customer’s Check File.

membershipAccount
string <= 30 characters

This field contains the Customer’s Membership Account ID.

WARNING: If the specified Membership Profile does not exist, an error will be returned and the record will not be created or updated.

billToAddressLine1
string <= 50 characters
  • This parameter allows you to update or populate the first line of the customer’s street address (i.e., "Street 1").
  • With CATAPULT 5.8.160 and newer, NONE can be entered for this parameter to clear/empty the field on existing customer records.

WARNING: If this parameter is not specified in the request, the remaining billToAddress parameters will be ignored.

billToAddressLine2
string <= 50 characters
  • This parameter allows you to update or populate the second line of the customer’s street address (i.e., "Street 2").
  • With CATAPULT 5.8.160 and newer, NONE can be entered for this parameter to clear/empty the field on existing customer records.
billToAddressCity
string <= 20 characters
  • This parameter allows you to update or populate the "City" of the customer’s street address.
  • With CATAPULT 5.8.160 and newer, NONE can be entered for this parameter to clear/empty the field on existing customer records.
billToAddressStateProv
string <= 2 characters
  • This parameter allows you to update or populate the state or province of the customer’s street address (i.e., "State/Prov.").
  • With CATAPULT 5.8.160 and newer, NONE can be entered for this parameter to clear/empty the field on existing customer records.
billToAddressPostalCode
string <= 15 characters
  • This parameter allows you to update or populate the "Postal Code" of the customer’s street address.
  • With CATAPULT 5.8.160 and newer, NONE can be entered for this parameter to clear/empty the field on existing customer records.
billToAddressDescription
string <= 30 characters

This parameter allows you to specify the Address Description for the "Bill To" address that needs to be updated or created. Note the following about this parameter:

  • Any description entered with this parameter must exactly match an existing Address Description in the CATAPULT database.
  • If the entered description does not match an existing Address Description, a new Address Description will be created. It's a best practice to ensure the Address Description entered matches an existing record to avoid the creation of duplicate/similar descriptions.
  • If no Address Description is specified with this parameter, the "Home" Address Description will be used by default.
billToEmailAddress
string <= 254 characters
  • This parameter allows you to update or populate the customer's "Bill To" Email Address.
  • With CATAPULT 5.8.160 and newer, NONE can be entered for this parameter to clear/empty the field on existing customer records.
billToEmailDescription
string <= 30 characters

This parameter allows you to specify the Email Description for the "Bill To" email address that needs to be updated or created. Note the following about this parameter:

  • Any description entered with this parameter must exactly match an existing Email Description in the CATAPULT database.
  • If the entered description does not match an existing Email Description, a new Email Description will be created. It's a best practice to ensure the Email Description entered matches an existing record to avoid the creation of duplicate/similar descriptions.
  • If no Email Description is specified with this parameter, the "Home" Email Description will be used by default.
billToEmailMarketing
boolean

If this field is set to true, the specified e-mail address will be opted in for LoyaltyBot. If this field is set to false, the specified email address will be opted out for LoyaltyBot.

billToEmailReceipt
boolean

If this field is set to true, the specified e-mail address is opted in for eReceipt.; If this field is set to false, the specified e-mail address is opted out for eReceipt.

billToPhoneNumber
string <= 14 characters
  • This parameter allows you to update or populate the customer's "Bill To" Phone Number.
  • With CATAPULT 5.8.160 and newer, NONE can be entered for this parameter to clear/empty the field on existing customer records.
billToPhoneDescription
string <= 30 characters

This parameter allows you to specify the Phone Description for the "Bill To" phone number that needs to be updated or created. Note the following about this parameter:

  • Any description entered with this parameter must exactly match an existing Phone Description in the CATAPULT database.
  • If the entered description does not match an existing Phone Description, a new Phone Description will be created. It's a best practice to ensure the Phone Description entered matches an existing record to avoid the creation of duplicate/similar descriptions.
  • If no Phone Description is specified with this parameter, the "Home" Phone Description will be used by default.
hideInLookup
boolean

If this field is set to true, the specified customer will be hidden from POS lookup screens.

membershipInactive
boolean
  • Updates the Membership Inactive checkbox status for the associated customer.
  • This field accepts the following values:
    • true: The Membership Inactive checkbox will be checked/selected for the associated customer.
    • false: The Membership Inactive checkbox will be unchecked/unselected for the associated customer.
  • This field should only be used when the status of the Membership Inactive checkbox needs to be updated for the customer. It should not be used when creating a new customer record/account (i.e., setting the field to false), as doing so will void the account creation process.
customerInactive
boolean

Accepts true or false. Updates the customer inactive option.

Available in versions 5.5.4.142 and greater.

loyaltyProgram
string <= 30 characters

Selects a loyalty program to import Loyalty Points into. When omitted or not valid, the default loyalty program is selected

loyaltyPoints
integer
Example: loyaltyPoints=1

Imports a positive or negative loyalty point value. Value is points where 1 = 1.00 or 100 points. .01 = 0.01 or 1 single point

householdMainCustomerId
string <= 16 characters

This customer account ID that is desired to be the Parent. None of the household details are considered without this field. This replaces whatever is currently on the customer record. Pass none for this parameter value to remove all household data for the customer record.

householdRelation
string <= 30 characters

Text describing the relationship to the head of household, optional.

Available in versions 5.5.4.210 and greater.

householdCanRedeem
boolean

Defaults to true if not sent. Enables the household member to use the head of household loyalty points.

Available in versions 5.5.4.210 and greater.

householdCanCharge
boolean

Defaults to false if not sent. Enables the household member to use the head of household charge account.

Available in versions 5.5.4.210 and greater.

dependentsList
string <= 254 characters
Enum: "type%1dname%1dbirthdate" "none"
Example: dependentsList=dependentsList=Friend\John\2022-01-05\Pet\William\

List of dependents and their attributes (type, name, birthdate; birthDate is optional). The records in this list are delimited by ascii code RS (30 or hex 1e). The fields in the record are delimited by ascii code GS(29 or hex 1d). Added in 5.5.4.216 or better. Supply dependent attributes type, name, and birthDate (birthDate is optional) to add dependent(s) on a customer record.1 Pass keyword none as a request value for this parameter to remove all dependents from a customer record.2

  • Listed dependent records are delimited by ascii code RS30 or hex %1e.
  • Dependent attributes are delimited by ascii code GS29 or hex %1d. example: "Friend%1dJohn%1d1980-01-05%1ePet%1dFido%1d"
taxExemption
string
Example: taxExemption=GA_Gizmonic%1dVA_Deep13

Pass the name(s) of a tax to update customer record. Use group separator %1d to pass multiple tax exemptions onto a record. Use keyword none to remove all tax exemptions from a record. For example:

taxExemptionType
string
Value: "PF"
Example: taxExemptionType=PF&taxExemption=VA

Use this parameter coupled with the one above to affect bulk tax exemptions onto a customer record where the selected taxes each have the same Tax PowerField value as supplied in the request. For example:

  • ...?customerID=724&taxExemptionType=PF&taxExemption=GA will add all taxes with a PowerField value of GA as exemptions on customer record 724.
  • WARNING: Disabled by default. Enable parameter by Global Advanced Setting in HQ Web Office:
    • KEY: enableTaxPowerfield
    • VALUE: true

See also: Navigating & Understanding the Tax Generator (Tax PowerField), Advanced Settings.

Responses

Response Schema:
object
object (customers)
lastName
string

Customer last name.

firstName
string

Customer first name.

middleName
string

Customer middle name, if availabe.

nickName
string

Customer nick-name, if availabe.

memo
string

The memo recorded for the customer record.

powerField1
string

The value of PowerField 1 for the customer.

powerField2
string

The value of PowerField 2 for the customer.

powerField3
string

The value of PowerField 3 for the customer.

powerField4
string

The value of PowerField 4 for the customer.

powerField5
string

The value of PowerField 5 for the customer.

powerField6
string

The value of PowerField 6 for the customer.

powerField7
string

The value of PowerField 7 for the customer.

powerField8
string

The value of PowerField 8 for the customer.

birthDate
string <date>

The customer birthdate in YYYY-MM-DD format.

lastModified
string <date>

The last modified date of the customer record, in YYYY-MM-DD HH:MM:SS.sss format.

membershipAccount
string

The Account Name of the customer's membership, if the customer is a part of membership at the store. By default, the Account Name will be comprised of the customer's Last Name and their Customer ID (e.g., Smith40100637000029).

checkAcceptanceProfile
string

The name of the Check Status profile assigned to this customer.

priceLevel
string

The name of any custom price level assigned to this customer.

automaticDiscount
string

The name of the automatic discount assigned to this customer.

suppressReceipt
boolean

If true then receipts are not automatically printed.

loyaltyEnabled
boolean

If true then the default loyalty program is enabled for this customer.

loyaltyAccrualMultiplier
number <double>

The loyalty multiplier for customer's default loyalty program, if set.

suffix
string

The suffix for this customer.

prefix
string

The prefix for this customer.

title
string

The title of this customer.

company
string

The company for this customer.

checkFileMemo
string

The text entered for the Check File Memo field for the associated customer.

billToPhoneNumber
string

The bill-to phone number for this customer.

billToPhoneDescription
string

The description for the bill-to phone number for this customer.

billToEmailAddress
string

The bill-to email address for this customer.

billToEmailDescription
string

The description of the bill-to email address for this customer.

billToEmailMarketing
boolean

If true then the bill-to email address is allowed to receive marketing materials.

billToEmailReceipt
boolean

If true then the bill-to email address is set to receive eReceipts for this customers purchases.

billToAddressLine1
string

The first line of the bill-to address for this customer.

billToAddressLine2
string

The second line of the bill-to address for this customer.

billToAddressCity
string

The city of this customer's bill-to address.

billToAddressStateProv
string

The state or province of this customer's bill-to address.

billToAddressPostalCode
string

The postal code of this customer's bill-to address.

billToAddressDescription
string

The description of this customer's bill-to address.

membershipAccountJoined
string
  • The date and time that the customer obtained membership in the store.
  • The "joined" date and time will be automatically determined by CATAPULT when a Membership Profile is assigned to the customer's record; it cannot be specified.
  • The "joined" date and time will be in the following format: YYYY-MM-DD HH:MM:SS.sss
hideInLookup
boolean

If true then this customer will not show up in lookup dialogs.

customerInactive
boolean

If true then this customer is marked as inactive.

loyaltyBalances
string

The dollar value of this customer's current loyalty points balance. If the customer is a member of a Household, this will be the combined sum of all associated household members' loyalty balances, regardless of the customer's "Redeem Household Loyalty" eligiblity setting. Multiple loyalty program balances will be separated with the pipe | character.

HeadOfHousehold
string

The ID of this customer's head of household, if it is a member of another household.

HouseholdAccounts
string

If this customer is the head of household for multiple accounts, then this field contains a group-seperated hex 0x1D delimited list of all the household member accounts.

Dependents
string

If this customer has any dependents, then this field contains a group-seperated hex 0x1D, delimited list of all dependents.

Each dependent record is made of three fields partitioned by a Record Seperator 0x1E:

  • Relation
  • Name
  • Date in YYYY-MM-DD format

Repeat the three-field pattern as-needed to include multiple dependents for the customer.

lastPurchaseStore
string

The name of the last store from which this customer made a purchase. Read-only.

lastPurchaseDate
string

The name of the last date at which this customer made a purchase. Read-only.

membershipProfileName
string

The name of this customer's assigned Membership Profile. Read-only.

taxExemption
string

The name of the Tax that the customer is exempt from. The records for each Tax are managed in CATAPULT Web Office.

DateCreated
string

Available with CATAPULT 5.6.101 or newer, displays the date and time - in YYY-MM-DD 00:00:00.000 format - at which the customer record was created. Note that this creation could occur from CATAPULT Web Office or through API action, and any customer record added before this column was added to the CATAPULT database will return a DateCreated value of 1900-01-01.

HomeStore
string

The Home Store currently associated with this Customer.

Request samples 

curl --request PUT \
  --url 'https://accountid.catapultweboffice.com/api/Customer?apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0&customerId=SOME_STRING_VALUE&firstName=SOME_STRING_VALUE&lastName=SOME_STRING_VALUE&middleName=SOME_STRING_VALUE&nickName=SOME_STRING_VALUE&prefix=SOME_STRING_VALUE&suffix=SOME_STRING_VALUE&title=SOME_STRING_VALUE&company=SOME_STRING_VALUE&memo=SOME_STRING_VALUE&automaticDiscount=SOME_STRING_VALUE&automaticDiscountGroup=SOME_STRING_VALUE&priceLevel=SOME_TINYINT_VALUE&powerField1=SOME_STRING_VALUE&powerField2=SOME_STRING_VALUE&powerField3=SOME_STRING_VALUE&powerField4=SOME_STRING_VALUE&powerField5=SOME_STRING_VALUE&powerField6=SOME_STRING_VALUE&powerField7=SOME_STRING_VALUE&powerField8=SOME_STRING_VALUE&birthDate=SOME_DATE_VALUE&loyaltyEnabled=SOME_BOOLEAN_VALUE&loyaltyAccrualMultiplier=SOME_NUMBER_VALUE&suppressReceipt=SOME_BOOLEAN_VALUE&checkFileMemo=SOME_STRING_VALUE&membershipAccount=SOME_STRING_VALUE&billToAddressLine1=SOME_STRING_VALUE&billToAddressLine2=SOME_STRING_VALUE&billToAddressCity=SOME_STRING_VALUE&billToAddressStateProv=SOME_STRING_VALUE&billToAddressPostalCode=SOME_STRING_VALUE&billToAddressDescription=SOME_STRING_VALUE&billToEmailAddress=SOME_STRING_VALUE&billToEmailDescription=SOME_STRING_VALUE&billToEmailMarketing=SOME_BOOLEAN_VALUE&billToEmailReceipt=SOME_BOOLEAN_VALUE&billToPhoneNumber=SOME_STRING_VALUE&billToPhoneDescription=SOME_STRING_VALUE&hideInLookup=false&membershipInactive=false&customerInactive=false&loyaltyProgram=&loyaltyPoints=1&householdMainCustomerId=&householdRelation=&householdCanRedeem=false&householdCanCharge=false&dependentsList=dependentsList%3DFriend%5CJohn%5C2022-01-05%5CPet%5CWilliam%5C&taxExemption=GA_Gizmonic%251dVA_Deep13&taxExemptionType=PF%26taxExemption%3DVA'

Response samples

Content type
<?xml version='1.1' encoding='UTF-8'?>
  <root>
    <row customerId="123456789000"
    lastName="Smith" 
    firstName="Jane" 
    middleName="Doe" 
    nickName="Janie" 
    memo="Memo Text for this Customer" 
    powerField1="string" 
    powerField2="string" 
    powerField3="string" 
    powerField4="string" 
    powerField5="string" 
    powerField6="string" 
    powerField7="string" 
    powerField8="string" 
    birthDate="1990-01-01" 
    lastModified="2019-12-19 14:43:55.041" 
    membershipAccount="Smith123456789000" 
    checkAcceptanceProfile="Good" 
    priceLevel="2 VIP" 
    automaticDiscount="20% OFF" 
    suppressReceipt="false" 
    loyaltyEnabled="true" 
    loyaltyAccrualMultiplier="1.000" 
    suffix="III" 
    prefix="Ms." 
    title="string" 
    company="reciProfity" 
    checkFileMemo="Check File Memo Text for this Customer" 
    billToPhoneNumber="8281112222" 
    billToPhoneDescription="Personal" 
    billToEmailAddress="string" 
    billToEmailDescription="Personal" 
    billToEmailMarketing="false" 
    billToEmailReceipt="false" 
    billToAddressLine1="string" 
    billToAddressLine2="string" 
    billToAddressCity="string" 
    billToAddressStateProv="string" 
    billToAddressPostalCode="string" 
    billToAddressDescription="Home" 
    membershipAccountJoined="2022-10-12 03:30:25.213" 
    hideInLookup="false" 
    customerInactive="false" 
    loyaltyBalances="Default Program=.0200|Program A=0.0000|Program B=0.0000" 
    HeadOfHousehold="string" 
    HouseholdAccounts="string" 
    Dependents="Pet&#x1e;Fido&#x1e;2017-12-18" 
    lastPurchaseStore="123" 
    lastPurchaseDate="2014-08-17" 
    membershipProfileName="Ownership"
    taxExemption="State Tax"/>
  </root>

Dynamic Promotions

Available with CATAPULT 5.6.116+.

The Dynamic Promotion Details endpoint allows you to query and GET details about active Dynamic Promotions within a specified date range. These details include the Dynamic Promotion Name, Schedules, the Store Coupon required to fire the Dynamic Promotion, and more. See the Responses in the Get Dynamic Promotion Details section below for a complete list of the details you can GET about a Dynamic Promotion with this endpoint.

Notes

  • Details about Dynamic Promotions outside of the specified date range will not be returned.
  • When performing this query, Item Groups and individual items are returned in the Responses. If you have constructed Item Groups with a large number of items (e.g., 100,000 or more), and attached those Item Groups to the Dynamic Promotions returned within the query parameters, the performance of this endpoint may be impacted. Specifically, it may take an extended period of time for the responses to be returned.
  • Due to the data being separated by ASCII control characters GS (Group Separator) and RS (Record Separator), the CSV response for this endpoint becomes less useful, as most text editors fail to render those characters. Instead, the recommendation is to use either the JSON or XML response output for this endpoint.

Get Dynamic Promotion Details

This endpoint allows you to GET all details about active Dynamic Promotions within a specified date range.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

startDate
string <date>
Example: startDate=2023-01-01

The first day to return promotions for. If no startDate is specified in the query, it will default to 1 week in the past from the query date.

endDate
string <date>
Example: endDate=2023-07-01

The last day to return promotions for. If no endDate is specified in the query, it will default to the current date.

Responses

Response Schema:
Array
id
string

The unique identifier of the dynamic promotions

name
string

Name of the dynamic promotion.

alias
string

Receipt alias of the dynamic promotion.

storeCoupon
string

The store coupon required for the dynamic promotion, if present.

storeFilterType
string

The type of filter used to determine which stores this promo applies to. Either Zone, Store Groups, or Unknown.

zone
string

The zone to which this dynamic promotion is limited or All if no zone limit is applied.

storeGroup
string

The store group to which this dynamic promotion applied or All if no store group is applied.

powerField1
string

The value of PowerField 1 for the dynamic promotion.

powerField2
string

The value of PowerField 2 for the dynamic promotion.

powerField3
string

The value of PowerField 3 for the dynamic promotion.

powerField4
string

The value of PowerField 4 for the dynamic promotion.

powerField5
string

The value of PowerField 5 for the dynamic promotion.

powerField6
string

The value of PowerField 6 for the dynamic promotion.

powerField7
string

The value of PowerField 7 for the dynamic promotion.

powerField8
string

The value of PowerField 8 for the dynamic promotion.

terminalGroup
string

The terminal group to which this dynamic promotion is limited, if any.

BOGOflag
number

Indicator that this promotion is a BOGO

BOGOlesserValue
number

If this promotion is a bogo then this is the number of equal or lesser value items that the discount is applied to.

BOGOgreaterValue
number

If this promotion is a bogo then this is the number of equal or greater values items that the discount is applied to.

Array of objects

The item groups which are required for the promotion to fire. Note that Item Groups with a large number of items (e.g., 100,000 or more) may impact the performance of the endpoint. Specifically, it may take an extended period of time for the responses to be returned.

Array
itemGroupName
string

The name of the Item Group, as entered in CATAPULT Web Office. Note that this object is only returned within the itemGroups array with CATAPULT 5.7.130 and newer.

itemGroupID
string

The Primary Key (PK) and Composite Primary Key (CPK) of the Item Group, as found in the merchant's CATAPULT database for the store where the requst is being made. Both the PK and CPK values are concatenated - with the PK displaying first - and separated by a pipe (e.g., 5|1003). Note that this object is only returned within the itemGroups array with CATAPULT 5.7.130 and newer.

requiredQuantity
numeric

The number of items required for this item group to be satisified.

requiredAmount
numeric

The required total amount for this item group to be satisified.

distribution
numeric

The percent of the discount this item might receive.

receivesDiscount
numeric

1 if this item group can potentially receive the discount

itemCount
numeric

The number of items in this item group

items
Array of strings

The item id's belonging to this item group

Array of objects

The schedules on which the dynamic promotion will fire.

Array
startDate
string <date>

The date on which this schedule starts being valid

endDate
string <date>

The date after which this promotion is no longer valid

startTime
string <time>

The time on each day within the schedule that the promo starts being valid

endTime
string <time>

The time on each day after which the promo is no longer valid.

amount
numeric <decimal>

For amount based discounts this is the amount of the discount or override.

percent
percent <decimal>

For percent based discounts this is the amount of the discount.

overridePriceSequence
string

For override price sequence based discounts this is the divider/total of the pricing. Example - 5 / $10.0000

rounding
string

How the amount of the discount is rounded. One of 'Round Up', 'When half or more', 'Never', or 'Unknown'.

discountType
string

The type of discount which this promotion applies. Can be one of 'Override Price', 'Dollar Amount', 'Percent Amount', 'Override Price Sequence', or 'Unknown'.

maximumAllowedPerTransaction
number

The maximum number of times this promo can fire in a single transaction

maximumPurchaseAmount
number

The maximum amount of a transaction on which this promotion is allowed to fire.

stackLevel
string

The stack level on which the promotion fires.

includeItemGroup
string

An item group to include in the calculation of the total limits for this promotion

excludeItemGroup
string

An item group to exclude from the calculation of the total limits for this promotion

generalLedgerAccount
string

The name of the general ledger account to which this promotion contributes

storeCoupontriggers
string

The type of store coupon trigger which applies to this promotion. One of '', 'Require Scan or Attachment', 'Require Scan and Attachment', 'Require Scan', 'Require Attachment', 'Require Scan or Customer Association', or 'Unknown'

disabled
numeric

1 if the promotion is disabled.

applyToBasePrice
numeric

1 if the promotion applies to the base price.

DisableUseLimits
numeric

1 if use limits are disabled for this promotion.

deferrable
numeric

1 if use limits apply to this promotion and it is deferrable.

usesPerPeriod
numeric

If use limits are enabled, then this indicates how many times a promotion can be used in each period.

maxSavingsPerPeriod
numeric

If use limits are enabled, then this indicates the max savings amount allowed in each period.

limitAppliesTo
string

Indicates to what a uses limit applies. One of 'Transaction' or 'Total Promotions'.

enforceUseLimits
string

Indicates the scope at which use limits are tracked. One of 'Coupon Type', 'Customer', or 'Household'.

resetUsages
string

Describes the period of a use limit and when the tracked uses are reset.

rewardedLoyaltyOption
string

Described how loyalty points are awarded by the promotion. One of 'None', 'Apply multiplier to item groups only', 'Apply multiplier to entire transaction', 'Reward points to transaction', and 'Unknown'.

rewardedLoyaltyProgram
string

The name of the program to which any points are awarded.

rewardedLoyaltyPoints
numeric

The number of points awarded to the loyalty program.

rewardedLoyaltyMultiplier
numeric

The multiplier awarded to the loyalty program.

rewardCoupon
string

The name of a coupon awarded by the redemption of this promotion

rewardedReceiptPromoSection
string

The name of a receipt section awarded by this promotion.

maxDiscountPerPromo
numeric

1 if the maximum transaction discount amount is per instance of the promotion, else discount amount is per transaction.

maximumTransactionDiscount
string

The maximum amount of the discount allowed by this promotion. 0 is unlimited.

minimumPurchaseAmount
numeric

the minimum purchase amount before this promotion is allowed to fire.

weightedItemOptions
string

How weighted items are treated by this promotion. One of 'Discount by calculated unit quantity', 'Discount by line item', 'Discount by line item per each unit of weight', or 'Unknown'.

Request samples 

curl --request GET \
  --url 'https://accountid.catapultweboffice.com/api/dynamicPromotionsDetail?apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0&startDate=2023-01-01&endDate=2023-07-01'

Response samples

Content type
[
  • {
    }
]

Maintenance Profiles

Maintenance Profiles include endpoints that enable you to obtain or modify information on the more nuanced elements of your CATAPULT data, such as customer/store coupons and departments. Additional profile endpoints are in development and will be released with supporting information as they become available.

The Customer Store Coupon Management endpoint enables you to obtain a list of, attach new, and remove existing Customer Store Coupons associated to a customer. Also use it change existing Store Coupon expiration dates. GET will let you view existing Customer Store Coupons; PUT will allow you to attach and change the expiration dates; DELETE will remove the coupon from a specified record.

The Department Detail endpoint enables read-only information requests on your item hierarchy departments. GET will let you view details for all departments or, if specified in the request, a certain one.

The Membership Profile endpoint allows you to query, create, or update membership profiles.
GET lets you find information about existing Membership Profiles, while PUT will have you create new and update existing records.

The Supplier Detail endpoint enables read-only information requests on supplier (vendor) records in your database.
Use GET to view details for all available suppliers. Requests can be filtered using optional parameters.

Customer Store Coupon

Use GET to obtain a list of Store Coupons attached to a customer maintenance record.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

customerId
string <= 16 characters

See also: Customer ID.

Responses

Response Schema:
object
object
customerId
string

The unique ID for the customer in the associated row.

couponCode
string

The code used by the coupon in the associated row.

couponReceiptAlias
string

The receipt alias used by the coupon in the associated row.

couponName
string

The coupon name.

couponExpires
date

The coupon expiration date, if set.

Request samples 

curl --request GET \
  --url 'https://accountid.catapultweboffice.com/api/CustomerStoreCoupon?apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0&customerId=SOME_STRING_VALUE'

Response samples

Content type
<?xml version='1.1' encoding='UTF-8'?>
<root>
    <row customerId="1234567" 
      couponCode="V8>OS1" 
      couponReceiptAlias="" 
      couponName="Household Coupon" 
      couponExpires=""/>
    <row customerId="1234567" 
      couponCode="V8>ORS" 
      couponReceiptAlias="" 
      couponName="Household Coupon Category" 
      couponExpires=""/>
    <row customerId="1234567" 
      couponCode="V8>OSC" 
      couponReceiptAlias="" 
      couponName="Household Special" 
      couponExpires=""/>
</root>

Customer Store Coupon

Use PUT to attach new Store Coupons on a customer record or change the expiry date on existing ones. Responses are sorted to display the most recent coupon attachments at the top.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

customerId
required
string <= 16 characters

See also: Customer ID.

couponCode
required
string

The couponCode or couponReceiptAlias to attach on the specified customer record. See also: Store Coupons/Customer Groups.

couponExpires
required
date

Expiration date for the Store Coupon attached on the specified customer record. Accepts YYYY-MM-DD format.

Responses

Response Schema:
object
object
customerId
string

The unique ID for the customer in the associated row.

couponCode
string

The code used by the coupon in the associated row.

couponReceiptAlias
string

The receipt alias used by the coupon in the associated row.

couponName
string

The coupon name.

couponExpires
date

The coupon expiration date, if set.

Request samples 

curl --request PUT \
  --url 'https://accountid.catapultweboffice.com/api/CustomerStoreCoupon?apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0&customerId=SOME_STRING_VALUE&couponCode=SOME_STRING_VALUE&couponExpires=SOME_DATE_VALUE'

Response samples

Content type
<?xml version='1.1' encoding='UTF-8'?>
<root>
    <row customerId="1234567" 
      couponCode="V8>OSC" 
      couponReceiptAlias="" 
      couponName="Household Special" 
      couponExpires=""/>
    <row customerId="1234567" 
      couponCode="V8>OS1" 
      couponReceiptAlias="" 
      couponName="Household Coupon" 
      couponExpires=""/>
    <row customerId="1234567" 
      couponCode="V8>ORS" 
      couponReceiptAlias="" 
      couponName="Household Coupon Category" 
      couponExpires=""/>
</root>

Customer Store Coupon

Use DELETE to remove a particular Store Coupon from a customer record. Responses will return the list of coupons, if any, that remain on the customer record.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

customerId
required
string <= 16 characters

See also: Customer ID.

couponCode
required
string

The couponCode or couponReceiptAlias of the coupon association targeted for removal. See also: Store Coupons/Customer Groups.

Responses

Response Schema:
object
object
customerId
string

The unique ID for the customer in the associated row.

couponCode
string

The code used by the coupon in the associated row.

couponReceiptAlias
string

The receipt alias used by the coupon in the associated row.

couponName
string

The coupon name.

couponExpires
date

The coupon expiration date, if set.

Request samples 

curl --request DELETE \
  --url 'https://accountid.catapultweboffice.com/api/CustomerStoreCoupon?apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0&customerId=SOME_STRING_VALUE&couponCode=SOME_STRING_VALUE'

Response samples

Content type
<?xml version='1.1' encoding='UTF-8'?>
<root>
    <row customerId="1234567" 
      couponCode="V8>OS1" 
      couponReceiptAlias="" 
      couponName="Household Coupon" 
      couponExpires=""/>
    <row customerId="1234567" 
      couponCode="V8>ORS" 
      couponReceiptAlias="" 
      couponName="Household Coupon Category" 
      couponExpires=""/>
</root>

Department Detail

The Department Detail endpoint allows you to retrieve data for your global department(s). You may optionally pass a specific department number in the call operation to limit the server response to information for that particular object. Information for all available, global departments are returned if a unique department number is not specified.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

deptNumber
string <= 254 characters
Example: deptNumber=42

Unique identifier for a global department. Use this parameter to limit response data for that particular department. Store-specific departments are not included. Inalvid, non-global, or unrecognized department numbers will result in an error.

Responses

Response Schema:
Array
departmentNumber
string <= 8 characters

The unique department identifier.

See also: Department ID.

departmentName
string <= 30 characters

The department name.

See also: Department Name.

departmentBuyer
string <= 25 characters

Name of employee associated with department purchases.

See also: Department Buyer.

departmentOpenSaleLowAmt
number <double> <= 12 characters

Department Prompt for Price minimum.

See also: Department Limits.

departmentOpenSaleHighAmt
number <double> <= 12 characters

Department Prompt for Price maximum.

departmentHighQtyMultiplier
number <double> <= 12 characters

Maximum value allowed for quantity or weight adjustment multiplier.

See also: Department Adjustment Multiplier (High).

departmentLowQtyMultiplier
number <double> <= 12 characters

Minimum value allowed for quantity or weight adjustment multiplier.

See also: Department Adjustment Multiplier (Low).

departmentOmitFromSales
boolean

Defines if the department is reported separately from general sales: returns 0 if disabled/false and 1 if enabled/true.

See also: Department Omit from Sales.

departmentTransLimit
number <double> <= 12 characters

Department purchase limit.

See also: Department Purchase Limit.

departmentAdjustWarning
number <double> <= 12 characters

Maximum value (positive or negative) for a quantity adjustment that can be made to an on-hand item before a warning is prompted.

See also: Department Quantity Adjustments.

departmentMemo
string <= 254 characters

The department memo.

Request samples 

curl --request GET \
  --url 'https://accountid.catapultweboffice.com/api/departmentDetail?apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0&deptNumber=42'

Response samples

Content type
[
  • {
    }
]

Membership Profile

Use with GET to retreive a list of all membership profiles in your database.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

membershipProfile
string

Provide the name of a particular membership profile to query, otherwise leave this parameter blank to return all applicable profiles.

Responses

Response Schema:
object
object
membershipProfile
string

Name of a particular membership profile.

isPrivate
boolean

Declares if the membership profile is private or open.

isDefault
boolean

If the given profile has been flagged to automatically apply, by default, on new customers.

automaticDiscount
string

Name of the Automatic Discount applied to the membership profile. Returns an empty string if none exist.

priceLevel
string

The Price Level applied to the given membership profile.

equityEnabled
boolean

Declares whether or not equity payments are enabled on the membership profile.

maxEquity
currency

Maximum level of equity set for customers associated with the membership profile.

equityMode
string

Method of equity payment collection for the membership profile.

equityPaymentAmount
currency

Dollar amount of incremental equity payments when equityMode is set to standard.

equityPaymentInterval
string

Interval of recurring equity payments when equityMode is set to standard.

surchargePercent
percent

Percentage of a transaction total to be charged towards customer accounts that have not yet paid-in-full. Requires equityMode set to surcharge.

membershipFeeEnabled
boolean

Declares whether or not a recurring, non-equity membership fee is enabled on the membership profile.

membershipFeeAmount
currency

Dollar amount of membership fee payments when membershipFeeEnabled is set to true.

membershipFeeInterval
string

Interval of recurring membership fee payments when membershipFeeEnabled is set to true.

joinFeeEnabled
boolean

Declares whether or not a one-time join fee is enabled on the membership profile.

joinFeeAmount
currency

Dollar amount of one-time join fee when joinFeeEnabled is set to true.

Request samples 

curl --request GET \
  --url 'https://accountid.catapultweboffice.com/api/MembershipProfile?apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0&membershipProfile=SOME_STRING_VALUE'

Response samples

Content type
<?xml version='1.1' encoding='UTF-8'?>
<root>
    <row membershipProfile="Equity Member"
    isPrivate="false"
    isDefault="false"
    automaticDiscount="VIP 5% off"
    priceLevel="1 Price Level"
    equityEnabled="true"
    maxEquity="100.0000"
    equityMode="standard"
    equityPaymentAmount="5.0000"
    equityPaymentInterval="monthly"
    surchargePercent="0"
    membershipFeeEnabled="true"
    membershipFeeAmount="1.0000"
    membershipFeeInterval="monthly"
    joinFeeEnabled="true"
    joinFeeAmount="5.0000"/>
</root>

Membership Profile

Use PUT to create new membership profiles and to update existing ones.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

membershipProfile
required
string

Name of a particular membership profile to create or update.

newName
string

New name for a membership profile, if renaming an existing one.

isPrivate
boolean

Defaults to false when not specified. Set to true to mark the profile as private.

isDefault
boolean

Defaults to false when not specified. Set to true to mark the profile as default for new accounts.

autoDiscount
string

Name of the Automatic Discount associated with the selected profile. Exclude this parameter from the request to leave it unchanged. Send a blank or empty string with the parameter to unset (remove) the association.

priceLevel
string

Set Price Level for the selected profile. Accepted values include the Price Level name or number (1, 2, 3, 4). Send a blank or empty string with the parameter to unset (remove) the association.

equityEnabled
boolean

Set to true if equity payments are enabled on the selected profile. Set to false if not.

equityMode
string

Set to standard for flat equity payments, or to surcharge to charge a percentage of transaction totals.

Required if equityEnabled = true

equityPaymentAmount
unsigned double

The dollar amount for standard-mode equity payments associated with the selected profile.

Required if equityMode = standard

equityPaymentInterval
string

Interval of recurring payments. Accepted values include monthly, quarterly, semianually, and annually.

Required if equityMode = standard

preservePaidInFull
boolean

Set to false to mark accounts that have paid less than their total equity amount as not paid-in-full.

Required when you raise a membership profile equityAmount and at least one customer record associated with that selected profile was already marked paid-in-full

surchargePercentage
unsigned double

The percentage of a transaction total, to be charged on customer accounts not paid-in-full with each transaction, until all associated membership profile equity is paid.

Required if equityMode = surcharge

joinFeeEnabled
boolean

Set to true if membership joining fees are enabled on the selected profile. Set to false if not.

joinFeeAmount
unsigned double

The amount of the joining fee for a selected membership profile.

Required if joinFeeEnabled = true

membershipFeeEnabled
boolean

Set to true if a recurring, non-equity membership fee is enabled on the selected profile. Set to false if not.

membershipFeeAmount
unsigned double

The amount of the recurring membership fee for a selected profile.

Required if membershipFeeEnabled = true

membershipFeeInterval
string

Interval for a recurring membership fee. Accepted values include monthly, quarterly, semianually, and annually.

Required if membershipFeeEnabled = true

Responses

Response Schema:
object
object
membershipProfile
string

Name of a particular membership profile.

isPrivate
boolean

Declares if the membership profile is private or open.

isDefault
boolean

If the given profile has been flagged to automatically apply, by default, on new customers.

automaticDiscount
string

Name of the Automatic Discount applied to the membership profile. Returns an empty string if none exist.

priceLevel
string

The Price Level applied to the given membership profile.

equityEnabled
boolean

Declares whether or not equity payments are enabled on the membership profile.

maxEquity
currency

Maximum level of equity set for customers associated with the membership profile.

equityMode
string

Method of equity payment collection for the membership profile.

equityPaymentAmount
currency

Dollar amount of incremental equity payments when equityMode is set to standard.

equityPaymentInterval
string

Interval of recurring equity payments when equityMode is set to standard.

surchargePercent
percent

Percentage of a transaction total to be charged towards customer accounts that have not yet paid-in-full. Requires equityMode set to surcharge.

membershipFeeEnabled
boolean

Declares whether or not a recurring, non-equity membership fee is enabled on the membership profile.

membershipFeeAmount
currency

Dollar amount of membership fee payments when membershipFeeEnabled is set to true.

membershipFeeInterval
string

Interval of recurring membership fee payments when membershipFeeEnabled is set to true.

joinFeeEnabled
boolean

Declares whether or not a one-time join fee is enabled on the membership profile.

joinFeeAmount
currency

Dollar amount of one-time join fee when joinFeeEnabled is set to true.

Request samples 

curl --request PUT \
  --url 'https://accountid.catapultweboffice.com/api/MembershipProfile?apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0&membershipProfile=SOME_STRING_VALUE&newName=SOME_STRING_VALUE&isPrivate=SOME_BOOLEAN_VALUE&isDefault=SOME_BOOLEAN_VALUE&autoDiscount=SOME_STRING_VALUE&priceLevel=SOME_STRING_VALUE&equityEnabled=SOME_BOOLEAN_VALUE&equityMode=SOME_STRING_VALUE&equityPaymentAmount=SOME_UNSIGNED%20DOUBLE_VALUE&equityPaymentInterval=SOME_STRING_VALUE&preservePaidInFull=SOME_BOOLEAN_VALUE&surchargePercentage=SOME_UNSIGNED%20DOUBLE_VALUE&joinFeeEnabled=SOME_BOOLEAN_VALUE&joinFeeAmount=SOME_UNSIGNED%20DOUBLE_VALUE&membershipFeeEnabled=SOME_BOOLEAN_VALUE&membershipFeeAmount=SOME_UNSIGNED%20DOUBLE_VALUE&membershipFeeInterval=SOME_STRING_VALUE'

Response samples

Content type
<?xml version='1.1' encoding='UTF-8'?>
  <root>
      <row membershipProfile="Homegroup Membership" 
        isPrivate="false" 
        isDefault="true" 
        automaticDiscount="% Discount" 
        priceLevel="1 Price Level" 
        equityEnabled="true" 
        maxEquity="0.0000" 
        equityMode="standard" 
        equityPaymentAmount="1.0000" 
        equityPaymentInterval="monthly" 
        surchargePercent="0" 
        membershipFeeEnabled="false" 
        membershipFeeAmount="0.0000" 
        membershipFeeInterval="monthly" 
        joinFeeEnabled="true" 
        joinFeeAmount="5.0000"/>
  </root>

Supplier Detail

The Get Supplier Detail endpoint allows you to retrieve information associated with the suppliers/vendors stored in your database. You may optionally pass a specific supplier code in the request operation to limit the server response to information on a single record Information for all available supplier records are returned if a unique supplier number is not specified.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

venCode
string <= 254 characters
Example: venCode=42

Optionally provide a unique supplier code to return information specific to that record. Inalvid or unrecognized supplier codes will result in an error.

Responses

Response Schema:
Array
supplierCode
string <= 10 characters

The unique supplier identifier. See also: Supplier ID.

supplierName
string <= 25 characters

The supplier name. See also: Supplier Name.

supplierContact
string <= 25 characters

Name of Contact #1 for the supplier. See also: Supplier Contacts.

supplierMemo
string <= 254 characters

Memo field for the supplier record.

supplierTerms
string <= 12 characters

Returns the Terms Profile associated with the supplier record, where applicable. See also: Supplier Terms.

supplierOrdersAddressLine1
string

First line of the street address used for supplier orders. See also: Supplier Addresses.

supplierOrdersAddressLine2
string

Second line of the street address used for supplier orders.

supplierOrdersAddressCity
string <= 20 characters

Name of the city associated with the supplier order address.

supplierOrdersAddressState
string <= 2 characters

State or province associated with the supplier order address.

supplierOrdersAddressZip
string <= 15 characters

Postal code of the street address used for supplier orders.

supplierOrdersAddressCountry
string <= 2 characters

Country associated with the supplier order address. The Country will be returned as a two-character abbreviation, and will only be retuned with CATAPULT versions 5.6.119 and newer.

supplierReturnsAddressLine1
string

First line of the street address used for supplier returns.

supplierReturnsAddressLine2
string

Second line of the street address used for supplier returns.

supplierReturnsAddressCity
string <= 20 characters

Name of the city associated with the supplier return address.

supplierReturnsAddressState
string <= 2 characters

State or province associated with the supplier return address.

supplierReturnsAddressZip
string <= 15 characters

Postal code of the street address used for supplier returns.

supplierReturnsAddressCountry
string <= 2 characters

Country associated with the supplier return address. The Country will be returned as a two-character abbreviation, and will only be retuned with CATAPULT versions 5.6.119 and newer.

supplierOrdersPhoneNumber
string <= 14 characters

Phone number used for supplier orders. See also: Supplier Phone Numbers.

supplierReturnsPhoneNumber
string <= 14 characters

Phone number used for supplier returns.

supplierOrdersEmailAddress
string <= 254 characters

E-mail address used for supplier orders. See also: Supplier E-mail Addresses.

supplierReturnsEmailAddress
string <= 254 characters

E-mail address used for supplier returns.

Request samples 

curl --request GET \
  --url 'https://accountid.catapultweboffice.com/api/supplierDetail?apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0&venCode=42'

Response samples

Content type
[
  • {
    }
]

Purchase Orders

Available in CATAPULT version 5.6.97 and greater, all PUT Purchase Order endpoints provide a means to query, create, or update non-committed purchase order worksheets. Likewise, available with CATAPULT version 5.6.117 and greater, the GET endpoint provides a means to obtain order details about committed and non-committed worksheets. Operations will respond with a simple confirmation on success or provide details on the cause and related item(s) on failure. You may optionally use the endpoints to submit a new worksheet, modify the inventory records and details associated with that worksheet, and finally commit the worksheet all outside of Web Office. Endpoints conditionally support both Conventional and ReceiveOnly purchase orders; see parameters for specifics.

Purchase Order Header enables you to update the status of a purchase order worksheet. Use PUT to pass worksheet parameters to the server. Use the CREATE action(s) to start a new order, the EDIT action to modify an order, the SUBMIT action to process the worksheet into to the Ordered state, and COMMIT action to finalize the worksheet and close the order. Worksheets must have an invoiceNumber to allow commits. In CATAPULT version 5.6.117 and newer, the purchaseOrderId is returned upon a successful call to this endpoint.

Purchase Order Items enables you to modify specific rows and item associations on a particular worksheet. Use PUT to add/update/remove worksheet items.

Create New

Purpose of Endpoint

This endpoint is used to create new Conventional or Receive-Only Purchase Orders in Web Office.

Using the Endpoint

  • Use Action=N to create a new conventional worksheet.
  • Use Action=R to create a new receive-only worksheet.
  • Additional optional parameters for use with the create actions can be found in the Edit & Update endpoint below.

Success Response

A purchaseOrderId is returned when this endpoint is used successfully.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

Action
required
string <= 1 characters
Example: Action=N

Type of Action to be Performed:

  • N - CREATE Conventional purchase order worksheet.
  • R - CREATE Receive-Only purchase order worksheet.
supplier
string <= 10 characters
  • Supplier ID associated with the Purchase Order.
  • This parameter can not be edited once set.
receivingStore
required
string <= 4 characters
  • Conventional purchase orders only.
  • Store ID to receive the Purchase Order when worksheet is created at HQ.
  • The Receiving Store can not be specified when a Purchase Order is created at a RS.
  • This parameter can not be edited once set.
receivingStoreHq
boolean
Example: receivingStoreHq=0
  • Conventional purchase orders only.
  • Defines if the order can be edited at the HQ once submitted.
  • This parameter cannot be specified when a Purchase Order is created and/or edited for HQ.
  • 0 - Worksheet can only be edited from the receivingStore.
    • Defaults to 0 when the PO is created at HQ and submitted for another RS location.
  • 1 - Worksheet can be edited from the HQ.
    • Defaults to 1 when the PO is created and submitted for HQ.

Responses

Request samples 

curl --request PUT \
  --url 'https://accountid.catapultweboffice.com/api/purchaseOrderHeader?apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0&Action=N&supplier=SOME_STRING_VALUE&receivingStore=SOME_STRING_VALUE&receivingStoreHq=0'

Response samples

Content type
Example
"{\n \"code\": 4,\n \"message\":\"RAISERROR executed: User not authorized to submit Purchase Orders\\n\"\n}"

Edit & Update

Purpose of Endpoint

  • This endpoint is used to edit existing or update the status of an active, non-committed Purchase Order worksheets in Web Office.
  • This endpoint can be used to conditionally modify both Conventional and Receive-Only purchase orders.

Using the Endpoint

  • Edits CANNOT be made to worksheets have been received or are already committed.
  • Optional editable parameters listed here may also be passed in new worksheets, see the Create New endpoint above.

Success Response

A purchaseOrderId is returned when this endpoint is used successfully.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

purchaseOrderId
required
string <= 32 characters
Example: purchaseOrderId=31428-5083
  • This required parameter is the output of a call to purchaseOrderHeader.
  • It is a unique identifier for the Purchase Order; a dash-separated worksheet PurchaseOrderID and store CreatorID, formatted in the query as: WRK_PK-WRK_CPK.
  • If the output of a call to purchaseOrderHeader is not available, another way to determine this parameter is to examine the URL when a Purchase Order worksheet is opened in Web Office. Here, the worksheet's purchaseOrderId value can be extracted from the final bits of the web address, where the WRK_PK will be a string of digits before %257C, and the WRK_CPK will be the string of digits afterward.

EXAMPLE

https://162fi.catapultweboffice.com/weboffice/#purchaseOrder:pk=31428%257C5083

This Purchase Order has a WRK_PK-WRK_CPK value of 31428-5083, as seen by the string at the end of the web address.

Action
required
string <= 1 characters
Example: Action=E

Type of Action to be Performed:

  • E - EDIT the purchase order worksheet.
invoiceNumber
required
string <= 30 characters
  • The vendor invoice number for a received/completed purchase order.
  • Applies to conventional and receive-only orders.
  • This parameter is required to finalize and ultimately commit an order.
alias
string <= 40 characters

The worksheet alias.

DoNotSubmitViaGateway
boolean
  • Conventional purchase orders only.
  • Confirms if the purchase order will or won't be submitted through Gateway:
    • 0 - PO is submitted via Gateway.
    • 1 - PO is NOT submitted via Gateway.
  • Defaults to: 0
orderingEmployee
string <= 9 characters
  • Conventional purchase orders only.
  • Employee ID of account creating the purchase order.
  • Pass value NONE to clear parameter.
receivingEmployee
string <= 9 characters
  • Employee ID of account receiving the purchase order.
  • Pass value NONE to clear parameter.
receivingStoreHq
boolean
  • Conventional purchase orders only.
  • Defines if the order can be edited at the HQ once submitted.
  • 0 - Worksheet can only be edited from the receivingStore.
    • Defaults to 0 when the PO is created at HQ and submitted for another RS location.
  • 1 - Worksheet can be edited from the HQ.
    • Defaults to unchangeable 1 when the PO is created and submitted for HQ.
receiveDate
date
  • Receive date of purchase order in YYYY-MM-DD format.
  • Conventional purchase orders must be in SUBMITTED state to set this parameter.
  • No special restrictions for edits to this parameter on Receive-Only purchase orders.
invoiceDate
date
  • Invoice date of purchase order in YYYY-MM-DD format.
  • Conventional purchase orders must be in SUBMITTED state to set this parameter.
  • No special restrictions for edits to this parameter on Receive-Only purchase orders.
terms
string <= 30 characters
  • Name of terms profile to associate with purchase order.
  • Pass value NONE to clear parameter.
  • Defaults to term associated with supplier, if available.
neededByDate
date
  • Conventional purchase orders only.
  • Anticipated need-by date of purchase order in YYYY-MM-DD format.
cancelByDate
date
  • Conventional purchase orders only.
  • Available cancellation date of purchase order in YYYY-MM-DD format.
shipAfterDate
date
  • Conventional purchase orders only.
  • Anticipated ship-after date of purchase order in YYYY-MM-DD format.
shipVia
string <= 30 characters

Conventional purchase orders only.

referenceNumber
string <= 30 characters
trackingNumber
string <= 50 characters
freightOnBoard
string <= 20 characters
Example: freightOnBoard=FOB Townsville, NY

Location at which ordered freight changes hands over from the supplier to the purchaser.

freightCharges
double
Example: freightCharges=52.99

Freight/shipping amount associated with delivery of purchase order.

miscellaneousCharges
double

Any additional charge amount associated with purchase order.

discountAmount
double

Total discounted amount associated with purchase order. Only accepts negative values.

tax
double

Total amount of tax for items on purchase order.

exciseTax
double

Total excise tax amount applied on purchase order for margin accuracy, where applicable.

exciseSupplier
string <= 10 characters
  • Supplier authority associated with excise tax amount.
  • Requires a non-zero exciseTax value included in the query or already present on the worksheet.
  • Supplier profile must also have a GL Account set in CATAPULT.
  • Pass value NONE to clear both this parameter and exciseTax parameter.
expectedPurchaseTotal
double

Anticipated total amount for purchase order prior shipping and receiving.

exchangeRate
decimal
Example: exchangeRate=.90

Currency exchange rate for purchase orders received from foreign supplier.

remarks
string <= 254 characters

Remarks/memo field for purchase order.

printRemarksOnPo
boolean
  • Conventional purchase orders only.
  • Applies to remarks in Purchase Order Information tab.
  • 0 - Remarks NOT printed on PO.
  • 1 - Remarks printed on PO.
  • Defaults to: 0
printRemarksReceive
boolean
  • Applies to remarks in Receiving Information tab.
  • 0 - Remarks NOT printed on received PO.
  • 1 - Remarks printed on received PO.
  • Defaults to: 0
distributeFreight
boolean
  • Determines if freight charges are to be distributed across cost of all received items via the following options:
    • 0 - NOT Distributed
    • 1 - Distributed
  • Requires a non-zero freightCharges value included in the query or already present on the worksheet.

Responses

Request samples 

curl --request PUT \
  --url 'https://accountid.catapultweboffice.com/api/purchaseOrderHeader?apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0&purchaseOrderId=31428-5083&Action=E&invoiceNumber=SOME_STRING_VALUE&alias=SOME_STRING_VALUE&DoNotSubmitViaGateway=SOME_BOOLEAN_VALUE&orderingEmployee=SOME_STRING_VALUE&receivingEmployee=SOME_STRING_VALUE&receivingStoreHq=SOME_BOOLEAN_VALUE&receiveDate=SOME_DATE_VALUE&invoiceDate=SOME_DATE_VALUE&terms=SOME_STRING_VALUE&neededByDate=SOME_DATE_VALUE&cancelByDate=SOME_DATE_VALUE&shipAfterDate=SOME_DATE_VALUE&shipVia=SOME_STRING_VALUE&referenceNumber=SOME_STRING_VALUE&trackingNumber=SOME_STRING_VALUE&freightOnBoard=FOB%20Townsville%2C%20NY&freightCharges=52.99&miscellaneousCharges=SOME_DOUBLE_VALUE&discountAmount=SOME_DOUBLE_VALUE&tax=SOME_DOUBLE_VALUE&exciseTax=SOME_DOUBLE_VALUE&exciseSupplier=SOME_STRING_VALUE&expectedPurchaseTotal=SOME_DOUBLE_VALUE&exchangeRate=.90&remarks=SOME_STRING_VALUE&printRemarksOnPo=SOME_BOOLEAN_VALUE&printRemarksReceive=SOME_BOOLEAN_VALUE&distributeFreight=SOME_BOOLEAN_VALUE'

Response samples

Content type
Example
"{\n \"code\": 4,\n \"message\":\"RAISERROR executed: User not authorized to submit Purchase Orders\\n\"\n}"

Submit & Commit

Purpose of Endpoint

This endpoint is used submit or commit Conventional or Receive-Only Purchase Orders in Web Office.

Using the Endpoint

  • Use Action=S to submit
  • Use Action=C to commit.

Success Response

A purchaseOrderId is returned when this endpoint is used successfully.

Notes

  • Worksheet must already have an invoiceNumber before it can be committed.

  • With CATAPULT 5.8.157 and newer, this endpoint allows for worksheets to be committed that contain items with a positive, zero, or negative Receive Quantity.

    • In CATAPULT versions prior to 5.8.157, this endpoint only allowed for zero or positive Receive Quantity values on worksheet items. If a negative Receive Quantity was present for one or more worksheet items, the following error would be returned when the worksheet was committed via this endpoint:
     {
    "code":4,
    "message": "RAISERROR executed: worksheet 3678-1000 has no items received.\n"
 }
query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

purchaseOrderId
required
string <= 32 characters
Example: purchaseOrderId=31428-5083
  • This required parameter is the output of a call to purchaseOrderHeader.
  • It is a unique identifier for the Purchase Order; a dash-separated worksheet PurchaseOrderID and store CreatorID, formatted in the query as: WRK_PK-WRK_CPK.
  • If the output of a call to purchaseOrderHeader is not available, another way to determine this parameter is to examine the URL when a Purchase Order worksheet is opened in Web Office. Here, the worksheet's purchaseOrderId value can be extracted from the final bits of the web address, where the WRK_PK will be a string of digits before %257C, and the WRK_CPK will be the string of digits afterward.

EXAMPLE

https://162fi.catapultweboffice.com/weboffice/#purchaseOrder:pk=31428%257C5083

This Purchase Order has a WRK_PK-WRK_CPK value of 31428-5083, as seen by the string at the end of the web address.

Action
required
string <= 2 characters
Example: Action=S

Type of Action to be Performed:

  • S - This action will SUBMIT the Purchase Order worksheet.
  • C - This action will COMMIT the Purchase Order worksheet.
  • CC - Available with CATAPULT 5.7.150 and newer, this action will COMMIT the COST of the Purchase Order worksheet.
    • The CC action is only available in a "split commit" scenario, where someone at a remote store first commits the item quantity on the worksheet.
    • The CC action should be performed last in the "split-commit" process.
    • If the CC action is performed, CATAPULT will use and insert the cost of each item as entered on the worksheet (at the remote store); item cost cannot be updated when using this action.
DoNotSubmitViaGateway
boolean
  • Conventional purchase orders only.
  • Confirms if the purchase order will or won't be submitted through Gateway:
    • 0 - PO is submitted via Gateway.
    • 1 - PO is NOT submitted via Gateway.
  • Defaults to: 0
AllowCommitWithNoReceivedItems
boolean

Confirms if purchase orders with a receivedQuantity=0 can or can't be committed:

  • 0 - PO will NOT allow commits without a positive receive quantity.
  • 1 - PO will allow commits without a positive receive quantity. Defaults to: 0

Responses

Request samples 

curl --request PUT \
  --url 'https://accountid.catapultweboffice.com/api/purchaseOrderHeader?apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0&purchaseOrderId=31428-5083&Action=S&DoNotSubmitViaGateway=SOME_BOOLEAN_VALUE&AllowCommitWithNoReceivedItems=SOME_BOOLEAN_VALUE'

Response samples

Content type
Example
"{\n \"code\": 4,\n \"message\":\"RAISERROR executed: User not authorized to submit Purchase Orders\\n\"\n}"

Purchase Order Items

Purpose of Endpoint

  • Adds, Updates, or Removes Items from a Purchase Order Worksheet.
  • Fields available for modification are conditional on the worksheet type (conventional or receive-only) and status. See the REQUEST BODY SCHEMA for details.

Notes

  • When this endpoint is used, the associated data is temporarily stored in a table within the CATAPULT database at the store (where the endpoint was used). After the data is processed for this endpoint, the table will be automatically cleared/purged to prevent bloat. This self-cleaning behavior cannot be changed or modified, and no action is required for it to occur.
query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

purchaseOrderId
required
string <= 32 characters
Example: purchaseOrderId=31428-5083
  • This required parameter is the output of a call to purchaseOrderHeader.
  • It is a unique identifier for the Purchase Order; a dash-separated worksheet PurchaseOrderID and store CreatorID, formatted in the query as: WRK_PK-WRK_CPK.
  • If the output of a call to purchaseOrderHeader is not available, another way to determine this parameter is to examine the URL when a Purchase Order worksheet is opened in Web Office. Here, the worksheet's purchaseOrderId value can be extracted from the final bits of the web address, where the WRK_PK will be a string of digits before %257C, and the WRK_CPK will be the string of digits afterward.

EXAMPLE

https://162fi.catapultweboffice.com/weboffice/#purchaseOrder:pk=31428%257C5083

This Purchase Order has a WRK_PK-WRK_CPK value of 31428-5083, as seen by the string at the end of the web address.

Request Body schema: application/json

List of purchase order line items to modify.

Array
action
required
string <= 1 characters
Enum: "A" "D"

Type of Action to be Performed:

  • A - Insert or Update provided items on the purchase order worksheet.
  • D - Remove or Delete items from the purchase order worksheet.
supplierUnitId
string <= 15 characters
  • Represents the item's Supplier Unit ID (SUID) for the associated Supplier, which in turn determines the line item to add/update/delete.
  • The Supplier Unit ID takes precedence over itemId when both are provided.
  • In CATAPULT versions 5.7.153 and earlier, if an item had an SUID that matched any other SUID in the system - regardless of item or supplier - when that item was included in the request it would fail with a message of:

    Supplier does not match that of the worksheet: SUID: XXXXX

    In CATAPULT 5.7.155+, however, that limitation has been corrected; items with the same SUID can be processed in the request without failure.

itemId
string <= 14 characters

Determines the line item to add/update/delete. When an itemId is provided without a specific supplierUnitId, the latter is determined based on the supplier defaults for that item.

orderQuantity
number <double>
  • The number of supplier units to be ordered, for a given line item, on this worksheet.
  • If a quantity is already defined for a supplierUnitId line item on the worksheet, it will be replaced by the value provided in the request body.
  • Valid for either purchase order worksheet type with PENDING status.
shippedQuantity
number <double>
  • The number of supplier units shipped by the supplier.
  • Replaces any pre-existing value for the matching supplierUnitId.
  • Valid for conventional purchase order worksheets with ORDERED status.
  • Valid for receive-only purchase order worksheets with PENDING or ORDERED status.
receivedQuantity
number <double>
  • The number of supplier units received from the supplier.
  • This value can be positive, negative, or zero.
  • Replaces any pre-existing value for the matching supplierUnitId.
  • Valid for conventional purchase order worksheets with ORDERED status.
  • Valid for receive-only purchase order worksheets with PENDING or ORDERED status.
distributeDiscountsFlag
boolean
Enum: 0 1

Defaults to 1 for newly added worksheet items.

verifiedFlag
boolean
Enum: 0 1

Defaults to 1 for newly added worksheet items.

receivedFlag
boolean
Enum: 0 1

Defaults to 0 for newly added worksheet items.

Only valid for conventional purchase order worksheets with ORDERED status.
Valid for receive-only purchase order worksheets with PENDING or ORDERED status.

applyExiseTaxFlag
boolean
Enum: 0 1

Defaults to 0 for newly added worksheet items.
Operation will only accept 1 if the worksheet has a non-zero Excise Tax amount.

backOrderedFlag
boolean
Enum: 0 1

Defaults to 0 for newly added worksheet items.

Only valid for conventional purchase order worksheets with ORDERED status.
Not valid for receive-only worksheets.

totalAllowances
number <double>

Calculates the package and unit values for allowances.

Valid for either purchase order worksheet type with PENDING or ORDERED status.

totalCharges
number <double>

Calculates the package and unit values for charges.

Valid for either purchase order worksheet type with PENDING or ORDERED status.

totalCost
number <double>

Total cost of a worksheet item, which is comprised of the total ordered quantity of the item on the Purchase Order and the calculated cost of the item. When the totalCost field is omitted or null, an item's total cost is calculated using catalog costs, cost change worksheets, and last cost.

Updates the Ordered Total Cost value for purchase order worksheets with a PENDING status.
Updates the Invoiced Total Cost value for purchase order worksheets with a ORDERED status.

itemTagQuantity
string <= 3 characters

Number of Item Tags to print.

signQuantity
string <= 1 characters

Number of Signs to print.

shelfTagQuantity
string <= 1 characters

Number of Shelf Labels to print.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/xml
Example
{"code":2,"message":"Invalid API Key."}

View & Search

Purpose of Endpoint

Use the purchaseOrderDetail endpoint with GET requests to retrieve information on committed or non-committed Purchase Order worksheets, either in bulk or filtered for a particular date range.

Filtering Results

Limit results by committed startdate and/or enddate if requesting committed (type = 0), or by order date if requesting submitted (type = 1). If no type is specified, it will default to 0 (i.e., committed).

Notes

  • Note that Receive Only Purchase Order Worksheets will be returned after they have been committed.
  • Server responses are provided in XML format by default.
query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

startdate
required
string <date-time>
Example: startdate=2015-03-25T12:00:00

This field contains the start date. Only worksheets which were committed or submitted (depending on the value passed to type) after this date/time will be included in the output. This parameter should be in the following format: 2015-03-25T12:00:00 (ISO 8601).

enddate
string <date-time>
Example: enddate=2015-03-25T12:00:00

This field contains the end date. Only worksheets which were committed or submitted (depending on the value passed to type) before this date/time will be included in the output. This parameter should be in the following format: 2015-03-25T12:00:00 (ISO 8601). If not provided, the value will default to current date/time.

Type
string
Example: Type=1

This parameter allows you to specify what status of Purchase Order worksheets are returned with the query. There are three status Type parameters available:

  • 0 - Returns Committed Purchase Order worksheets.
  • 1 - Returns Ordered Purchase Order worksheets.
  • 2 - Returns Pending Purchase Order worksheets. Note that this parameter is only available with CATAPULT version 5.7.123 and newer, and that it will only return Pending worksheets that have one or more items on them. Pending Purchase Order worksheets with no items will not be returned with this query parameter.

Responses

Response Schema:
object
object (purchaseOrderDetail)
worksheetName
string <= 40 characters

Name given to worksheet.

worksheetAlias
string <= 40 characters

Optional alias that may have been given to the worksheet.

worksheetVendorCompany
string <= 25 characters

Vendor / supplier name.

worksheetVendorCode
string <= 10 characters

Vendor / supplier code.

worksheetSubmittedDate
string <datetime>

Date the worksheet was submitted.

worksheetPurchaseEmpFirstName
string <= 30 characters

First name of employee who created the worksheet.

worksheetPurchaseEmpLastName
string <= 30 characters

Last name of employee who created the worksheet.

worksheetPurchaseEmpNumber
integer

Employee number of employee who created the worksheet.

worksheetOrderNumber
integer <= 20 characters

Order number for the worksheet.

worksheetTerms
string <= 30 characters

Supplier terms.

worksheetReceivingStoreName
string <= 60 characters

Name of the store receiving the order.

worksheetReceivingStoreNumber
string <= 10 characters

Store number of the store receiving the order.

worksheetSubmitViaGateway
boolean

0: Order was eligible to be processed by Gateway 1: Order was not eligible to be processed by Gateway

worksheetReceivingEmpFirstName
string <= 30 characters

First name of employee who received the order.

worksheetReceivingEmpLastName
string <= 30 characters

Last name of employee who received the order.

worksheetReceivingEmpNumber
integer

Employee number of employee who received the order.

worksheetReferenceNumber
string <= 30 characters

Invoice reference number associated with the order.

worksheetTrackingNumber
string <= 50 characters

Tracking number associated with the order.

worksheetInvoiceNumber
string <= 30 characters

Invoice number associated with the order.

worksheetInvoiceDate
string <datetime> <= 20 characters

Date order was invoiced.

worksheetFreightOnBoard
string <= 20 characters

Comment related to point at which freight changes hands from supplier to buyer.

worksheetExciseTax
number <decimal>

Excise tax related to the order.

worksheetExciseTaxAuthority
string <= 25 characters

Excise tax authority related to the order.

worksheetPurchaseTotal
number <decimal>

Cost of the order.

worksheetFreightCharges
number <decimal>

Freight charges related to the order.

worksheetDistributeFreight
boolean

1 if distribute freight option was checked, else 0.

worksheetMiscCharges
number <decimal>

Miscellaneous charges related to the order.

worksheetDiscount
number <decimal>

Discount related to the order.

worksheetTax
number <decimal>

Tax related to the order.

worksheetExpectedPurchaseTotal
number <decimal>

Expected total cost of the order.

worksheetInvoiceTotal
number <decimal>

Actual total cost of the order.

worksheetExchangeRate
number <decimal>

Exchange rate of the order.

worksheetSupplierUnitID
string <= 15 characters

Supplier stock number / unit ID for the item.

worksheetSupplierUnitDescription
string <= 30 characters

Supplier unit description for the item.

worksheetQtyInOrderUnit
number <decimal>

Supplier unit quantity for the supplier unit.

worksheetItemID
string <= 14 characters

The Item ID / Scan code of the item.

worksheetItemName
string <= 254 characters

The name of the item.

worksheetItemReceiptAlias
string <= 32 characters

The receipt alias of the item.

worksheetItemSize
string <= 20 characters

The size of the item.

worksheetItemBrandName
string <= 30 characters

The brand name of the item.

worksheetItemPricingDivider
integer

Pricing divider of the item.

worksheetItemBasePrice
number <decimal>

Base price of the item.

worksheetItemDepartmentName
string <= 30 characters

The department name of the item.

worksheetItemShelfLocation
string <= 30 characters

The shelf location of the item.

worksheetItemSuggestedRetail
number <decimal>

Suggested retail price of the item.

worksheetItemGlobalPF1
string <= 30 characters

Power field 1 of the item.

worksheetItemGlobalPF2
string <= 30 characters

Power field 1 of the item.

worksheetItemGlobalPF3
string <= 30 characters

Power field 3 of the item.

worksheetItemGlobalPF4
string <= 30 characters

Power field 4 of the item.

worksheetItemGlobalPF5
string <= 30 characters

Power field 5 of the item.

worksheetItemGlobalPF6
string <= 30 characters

Power field 6 of the item.

worksheetItemGlobalPF7
string <= 30 characters

Power field 7 of the item.

worksheetItemGlobalPF8
string <= 30 characters

Power field 8 of the item.

worksheetOrderedQuantity
number <decimal>

Quantity of the item that was ordered.

worksheetShippedQuantity
number <decimal>

Quantity of the item that was shipped.

worksheetReceivedQuantity
number <decimal>

Quantity of the item that was received.

worksheetItemVerified
boolean

1 if the item has been verified, else 0.

worksheetItemOrderCost
number <decimal>

Total cost of the item, accounting for quantity.

worksheetItemInvoiceCost
number <decimal>

Total cost of the item as invoiced, accounting for allowances, etc.

worksheetItemPkgTempDiscount
number <decimal>

Temporary discount of the item.

worksheetItemPkgAllowance
number <decimal>

Total allowance for the item as calculated after commit (if type parameter is 0), else at submission.

worksheetItemPkgCharges
number <decimal>

Total charges for the item.

worksheetItemUnitTempDiscount
number <decimal>

Unit allowance for the item.

worksheetItemUnitAllowance
number <decimal>

Additional unit allowance for the item.

worksheetItemUnitCharges
number <decimal>

Unit charges for the item.

worksheetItemTotalTempDiscount
number <decimal>

Base allowance for the item.

worksheetItemTotalAllowance
number <decimal>

Allowance for the item, accounting for allowances, etc.

worksheetItemTotalCharges
number <decimal>

Total charges for the item, accounting for quantity.

worksheetItemBackordered
boolean

1: Item was back ordered 0: Item was not back ordered

worksheetItemReceived
boolean

1: Item was received 0: Item was not received

worksheetItemExciseApplied
boolean

1: Item has had excise tax applied 0: Item has not had excise tax applied

worksheetItemDiscountApplied
boolean

1: Item has "distribute discounts" checked 0: Item does not have "distribute discounts" checked

existingWorksheetId
string

The PK-CPK of the Purchase Order worksheet, as referenced and obtained from the CATAPULT database.

Request samples 

curl --request GET \
  --url 'https://accountid.catapultweboffice.com/api/purchaseOrderDetail?apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0&startdate=2015-03-25T12%3A00%3A00&enddate=2015-03-25T12%3A00%3A00&Type=1'

Response samples

Content type
<?xml version="1.1" encoding='UTF-8'?>
<root>
    <row worksheetName="EXAMPLE-008813-HQ-HQ",
    worksheetAlias="EXAMPLE",
    worksheetVendorCompany="EXAMPLE VENDOR",
    worksheetVendorCode="EVC",
    worksheetSubmittedDate="2019-01-10 08:45:08.961834",
    worksheetPurchaseEmpFirstName="Bob",
    worksheetPurchaseEmpLastName="Smith",
    worksheetPurchaseEmpNumber="123",
    worksheetOrderNumber="8813",
    worksheetTerms="Net 30",
    worksheetReceivingStoreName="Main Store 123",
    worksheetReceivingStoreNumber="7504",
    worksheetSubmitViaGateway="0",
    worksheetReceivingEmpFirstName="Sam",
    worksheetReceivingEmpLastName="Smith",
    worksheetReceivingEmpNumber="456",
    worksheetReferenceNumber="7714",
    worksheetTrackingNumber="1234",
    worksheetInvoiceNumber="4567",
    worksheetInvoiceDate="2019-01-10 08:45:08.961834",
    worksheetFreightOnBoard="FOB - Boone NC",
    worksheetExciseTax="0.0000",
    worksheetExciseTaxAuthority="EXAMPLE",
    worksheetPurchaseTotal="0.0000",
    worksheetFreightCharges="0.0000",
    worksheetDistributeFreight="0",
    worksheetMiscCharges="0.0000",
    worksheetDiscount="-2.0000",
    worksheetTax="0.0000",
    worksheetExpectedPurchaseTotal="0.0000",
    worksheetInvoiceTotal="-2.000000",
    worksheetExchangeRate="0.000"
    worksheetSupplierUnitID="2",
    worksheetSupplierUnitDescription="BALE-3",
    worksheetQtyInOrderUnit="1.000",
    worksheetItemID="4011",
    worksheetItemName="Yellow Bananas",
    worksheetItemReceiptAlias="BANANAS",
    worksheetItemSize="8 OZ"
    worksheetItemBrandName="USDA PRODUCE",
    worksheetItemPricingDivider="1",
    worksheetItemBasePrice="0.0000",
    worksheetItemDepartmentName="Produce",
    worksheetItemShelfLocation="Produce Display",
    worksheetItemSuggestedRetail="0.0000",
    worksheetItemGlobalPF1="EXAMPLE",
    worksheetItemGlobalPF2="EXAMPLE",
    worksheetItemGlobalPF3="EXAMPLE",
    worksheetItemGlobalPF4="EXAMPLE",
    worksheetItemGlobalPF5="EXAMPLE",
    worksheetItemGlobalPF6="EXAMPLE",
    worksheetItemGlobalPF7="EXAMPLE",
    worksheetItemGlobalPF8="EXAMPLE",
    worksheetOrderedQuantity="1.000",
    worksheetShippedQuantity="1.000000",
    worksheetReceivedQuantity="1.000",
    worksheetItemVerified="0",
    worksheetItemOrderCost="0.0000",
    worksheetItemInvoiceCost="0.000000",
    worksheetItemPkgTempDiscount="0.0000",
    worksheetItemPkgAllowance="0.0000",
    worksheetItemPkgCharges="0.0000",
    worksheetItemUnitTempDiscount="0.0000",
    worksheetItemUnitAllowance="0.0000",
    worksheetItemUnitCharges="0.0000",
    worksheetItemTotalTempDiscount="0.0000",
    worksheetItemTotalAllowance="0.0000",
    worksheetItemTotalCharges="0.0000",
    worksheetItemBackordered="0",
    worksheetItemReceived="0",
    worksheetItemExciseApplied="0",
    worksheetItemDiscountApplied="0"
    existingWorksheetId="113416-1000"/>
</root>

Price Changes

The Price Change Detail endpoint provides a means to query price change worksheets. GET will let you retrieve worksheet data from within a defined date range.

Get Price Change Worksheet Details

Get data from all Price Change Worksheets in the specified date range. The request must be for a temporary price change worksheet in the committed state. Permanent price changes and/or non-committed worksheets are not included in the responses.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

startDate
required
string <date>
Example: startDate=2022-01-31

The start of the date range to query for Price Change worksheets.

endDate
string <date>
Example: endDate=2022-10-31

The end of the date range to query for Price Change worksheets. If endDate not supplied then all data after startDate is returned.

Responses

Response Schema:
object
object (priceChangeDetail)
worksheetCreated
datetime

Creation date WRK_CreateDate for the returned worksheet.

worksheetPriority
integer
Enum: "1" "2" "3"

Defines priority level PSW_PriorityLevel of the returned worksheet:

  • 1 - High
  • 2 - Medium
  • 3 - Low \

See also: Worksheet Priority.

worksheetMemo
string <= 254 characters

Enter the supplier name into the worksheet memo field PSW_Memo when the Price Change Worksheet is created in Web Office. This supplier name will then display in the worksheetMemo response parameter.

See also: Worksheet Memo.

itemID
string <= 14 characters

The UPC INV_scanCode associated with an inventory record on the worksheet.

worksheetStartDate
datetime

The start date PSW_startTime for the temporary price change on the returned worksheet.

See also: Price Change Start.

worksheetEndDate
datetime

The end date PSW_endTime for the temporary price change on the returned worksheet.

See also: Price Change End.

worksheetIdentifier
string

The unique identifier WRK_CPK + WRK_PK for the returned worksheet.

worksheetSalePrice
string <decimal(16,4)>

The temporary non-retail price PSD_promotionalPrice_pl1 of an inventory record from the returned worksheet.

worksheetSaleDiscount
string <= 30 characters

The discount name DIS_Description associated with an inventory record from the returned worksheet.

See also: Price Change Auto Discount.

worksheetItemDescription
string

Description of the inventory record as entered on the returned worksheet. If this field is not directly available, the operation will return either the INV_Name or INV_ReceiptAlias instead.

See also: Receipt Alias (Price Change).

worksheetName
string <= 40 characters

Returns the name of the committed worksheet WRK_Name with an active temporary price change between the requested start and end dates.

See also: Name (Price Change).

worksheetItemSize
string

Total size/amount of the inventory record INV_Size as entered on the returned worksheet.

See also: Size (Inventory Maintenance).

worksheetCreateEmpFirstName
string

Available with CATAPULT 5.6.104+

Displays the First Name of the store employee who created the Price and Cost Change worksheet. This name is managed on each employee's record in CATAPULT Web Office.

worksheetCreateEmpLastName
string

Available with CATAPULT 5.6.104+

Displays the Last Name of the store employee who created the Price and Cost Change worksheet. This name is managed on each employee's record in CATAPULT Web Office.

worksheetCreateEmpNumber
string

Available with CATAPULT 5.6.104+

Displays the Employee ID of the store employee who created the Price and Cost Change worksheet. This ID is managed on each employee's record in CATAPULT Web Office.

worksheetCommitEmpFirstName
string

Available with CATAPULT 5.6.104+

Displays the First Name of the authorized employee who committed the Price and Cost Change worksheet from CATAPULT Web Office. This name is managed on the employee's record in CATAPULT Web Office.

worksheetCommitEmpLastName
string

Available with CATAPULT 5.6.104+

Displays the Last Name of the authorized employee who committed the Price and Cost Change worksheet from CATAPULT Web Office. This name is managed on the employee's record in CATAPULT Web Office.

worksheetCommitEmpNumber
string

Available with CATAPULT 5.6.104+

Displays the Employee ID of the authorized employee who committed the Price and Cost Change worksheet from CATAPULT Web Office. This ID is managed on the employee's record in CATAPULT Web Office.

worksheetItemCost
string <decimal(16,4)>

Available with CATAPULT 5.6.117+

The new cost entered on the worksheet.

Request samples 

curl --request GET \
  --url 'https://accountid.catapultweboffice.com/api/priceChangeDetail?apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0&startDate=2022-01-31&endDate=2022-10-31'

Response samples

Content type
<?xml version='1.1' encoding='UTF-8'?>
<root>
    <row worksheetCreated="2022-02-03 12:00:00.000"
    worksheetPriority="1"
    worksheetMemo="Ven Dor's A-Z Supplies"
    itemId="3145236"
    worksheetStartDate="2022-03-14 06:00:00.000"
    worksheetEndDate="2022-03-18 23:59:59.000"
    worksheetIdentifier="100021"
    worksheetSalePrice="100.99"
    worksheetSaleDiscount="Mid-March Discount"
    worksheetItemDescription="Gala Apples"
    worksheetName="Seasonal Price Change"
    worksheetItemSize="12"
    worksheetCreateEmpFirstName="Bob"
    worksheetCreateEmpLastName="Smith"
    worksheetCreateEmpNumber="7"
    worksheetCommitEmpFirstName="Terry"
    worksheetCommitEmpLastName="Smith"
    worksheetCommitEmpNumber="8"
    worksheetItemCost="10.99"/>
</root>

Inventory Adjustments

There are three endpoints available for Inventory Adjustment worksheets in CATAPULT Web Office. Specifically:

  1. Inventory Adjustment Details
  2. Inventory Adjustment Header (create/edit/commit)
  3. Inventory Adjustment Items (add)

Available with CATAPULT 5.6.98+, the Inventory Adjustment Details endpoint allows you to query and GET data about committed Inventory Adjustment worksheets. This worksheet data includes:

  • Worksheet Name
  • Timestamp Committed
  • Item ID
  • Item Description (Receipt Alias)
  • Adjustment Quantity (positive or negative)
  • Base Item Adjustment Quantity
  • Adjustment Reason
  • Adjustment Memo

Available with CATAPULT 5.6.117+, the inventoryAdjustmentHeader endpoint allows you to create new Inventory Adjustment worksheets, make edits to the Memo or Worksheet Name fields, or even commit the worksheet. These actions are done through PUT commands.

Available with CATAPULT 5.6.118+, the inventoryAdjustmentItems endpoint allows you to add items to Inventory Adjustment worksheets. These actions are done through PUT commands.

Inventory Adjustments

Get Inventory Adjustment Worksheet Details. Through a query, this endpoint allows you to Get data from all committed Inventory Adjustment worksheets in a specified date range; non-committed worksheets are not included in the responses. The query is comprised of three parameters:

  1. Apikey
  2. StartDate
  3. EndDate
query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

startDate
required
string <date>
Example: startDate=2022-01-31 12:30:00:00

The start of the date range to query for Inventory Adjustment worksheets

endDate
string <date>
Example: endDate=2022-01-31 12:30:00:00

The end of the date range to query for Inventory Adjustment worksheets. If endDate is not supplied then all data after startDate is returned up to the current date/time of the query.

Responses

Response Schema:
Array
object (inventoryAdjustments_get)
worksheetName
string <= 40 characters

Returns the name of the committed Inventory Adjustment worksheet WRK_Name between the requested start and end dates.

existingWorksheetId
string

The unique ID of the Inventory Adjustment worksheet, as automatically assigned by CATAPULT when the worksheet is created.

storeName
string <= 60 characters

The store's Name, as entered on the associated Store Record in CATAPULT Web Office.

storeNumber
string <= 4 characters

The store's Number, as entered on the associated Store Record in CATAPULT Web Office.

storeId
string

The unique ID of the store where the Inventory Adjustment worksheet was created and committed. This ID is automatically assigned by CATAPULT when the associated store record is created.

worksheetTimestampCommitted
string <date>
  • Returns the date and time that the Inventory Adjustment worksheet was committed [WRK_TimestampCommitted]
  • Only those worksheets with a worksheetTimestampCommitted date within the startDate and endDate will be returned.
worksheetItemID
string <= 14 characters
  • The UPC [INV_scanCode] associated with an item that was on the committed Inventory Adjustment worksheet.
  • Note that if an item was an Alternate ID of the base item, then alternate ID [ASC_Scancode] is used.
worksheetItemDescription
string <= 32 characters
  • Description of the inventory record as entered on the Inventory Adjustment worksheet.
  • If this field is not directly available, the operation will return either the INV_Name or INV_ReceiptAlias instead.
worksheetItemAdjustment
string
  • The value entered as a quantity adjustment for the item. This value can be positive or negative.
  • If an item is a Base Item, this field will display the same quantity as the worksheetBaseItemAdjustment field.
  • If an item is an Alternate ID of the Base Item, this field will display the adjustment quantity of the Alternate ID.
worksheetBaseItemAdjustment
string
  • Displays the value entered as a quantity adjustment for the item. This value can be positive or negative.
  • If an item is a Base Item, this field will display the same quantity as the worksheetItemAdjustment field.
  • If an item is an Alternate ID of the Base Item, this field will display the Adjustment Quantity x Alternate ID Quantity.
worksheetItemAdjustmentReason
string <= 32 characters

Reason applied for the inventory adjustment.

worksheetItemAdjustmentMemo
string <= 254 characters

Any data from the worksheet memo.

Request samples 

curl --request GET \
  --url 'https://accountid.catapultweboffice.com/api/inventoryAdjustmentDetail?apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0&startDate=2022-01-31%2012%3A30%3A00%3A00&endDate=2022-01-31%2012%3A30%3A00%3A00'

Response samples

Content type
<?xml version='1.1' encoding='UTF-8'?>
<root>
  <row worksheetName="Produce Item Adjustments"
  existingWorksheetId = "101722-1000"
  storeName = "Urban Market HQ"
  storeNumber = "277"
  storeId = "1-1000"
  worksheetTimestampCommitted = "2022-02-03 12:00:00.000"
  worksheetItemID = "4011"
  worksheetItemDescription = "Banana"
  worksheetItemAdjustment = "-2"
  worksheetBaseItemAdjustment = "-4"
  worksheetItemAdjustmentReason = "Spoiled - Too Ripe" 
  worksheetItemAdjustmentMemo = "Disposed of Correctly"
  />
</root>

Create / Edit / Commit

Used to create, edit, and commit Inventory Adjustment worksheets in CATAPULT Web Office. This action fills the "header" portion of the worksheet, that is, the portion of the worksheet except for the actual items. It does not allow for adding items to the worksheet. Note that an Inventory Adjustment worksheet must be created at the store where the adjustment needs to be made. Thus, calls to the API must be submitted to the store where the Inventory Adjustment needs to take place. The worksheetName is required for new worksheets. Upon success, you will be provided with an existingWorksheetId

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

Action
required
string
Example: Action=N

Type of Action to be Performed:

  • N - CREATE a NEW Inventory Adjustment worksheet.
  • E - EDIT an Inventory Adjustment worksheet.
  • C - COMMIT an Inventory Adjustment worksheet.
worksheetName
string <= 40 characters
Example: worksheetName=Misplaced Items

Required when Action is N; optional when Action is E. The name that identifies the Inventory Adjustment worksheet (e.g., Misplaced Items). The name can be adjusted once the worksheet has been created. It cannot be adjusted after the worksheet has been committed.

existingWorksheetId
string <= 40 characters
Example: existingWorksheetId=3302-1000

Required when Action is E or C. This is the unique ID for the worksheet. This ID is provided upon successful creation of an Inventory Adjustment worksheet when calling this endpoint for the first time (passing N for Action).

memo
string <= 254 characters

Text field that allows you to enter any notes or memos about the worksheet as a whole.

Responses

Request samples 

curl --request PUT \
  --url 'https://accountid.catapultweboffice.com/api/inventoryAdjustmentHeader?apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0&Action=N&worksheetName=Misplaced%20Items&existingWorksheetId=3302-1000&memo=SOME_STRING_VALUE'

Response samples

Content type
application/xml
<?xml version="1.1" encoding="UTF-8"?><root><row existingWorksheetId="1234-1000"/></root>

Add Item Records

Available in CATAPULT 5.6.118+, the Add Item Records action adds item records to an existing Inventory Adjustment worksheet in CATAPULT Web Office. This action allows you to **PUT** data to the Inventory Adjustment Details endpoint. The item data includes:
  • Adjustment reasons
  • Adjustment value (positive or negative)
  • Memo / Comment
Note that when this endpoint is used, the associated data is temporarily stored in a table within the CATAPULT database at the store (where the endpoint was used). After the data is processed for this endpoint, the table will be automatically cleared/purged to prevent bloat. This self-cleaning behavior cannot be changed or modified, and no action is required for it to occur.
query Parameters
existingWorksheetId
required
string
Example: existingWorksheetId=31428-5083

This required parameter is the output of a call to . It consists of the key identifying the worksheet. Another way to determine this parameter, if required, would be to examine the URL when an Inventory Adjustment worksheet is opened in Web Office.. Here the worksheet's existingWorksheetId value can be extracted from the final bits of the web address, where the first number will be a string of digits before %257C, and the second number will be the string of digits afterward. For example:

https://162FI.catapultweboffice.com/weboffice/#invAdjustment:pk=31428%257C5083

This Inventory Adjustment has an existingWorksheetId value of 31428-5083, as seen by the string at the end of the web address.

apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

Request Body schema:

List of Adjustments

Array
ItemID
required
string

The Item ID or Alternate ID of the item.

Adjustment
required
string <decimal(16,4)>

Amount to adjust the item by (positive or negative).

Reason
string

The Reason for the adjustment.

Comments
string

Comment related to the adjustment.

Responses

Request samples

Content type
[
  • {
    }
]

Response samples

Content type
"{\n \"code\": 4,\n \"message\":\"RAISERROR executed: Reasons provided must match existing values from a reason profile. Invalid reasons: Dmaged,Loost\"\n}"

Physical Inventory

Available with CATAPULT 5.6.98+. The Physical Inventory Details endpoint allows you to perform an HTTP GET query and obtain data from committed Physical Inventory worksheets. This worksheet data includes:

  • Worksheet Name
  • Timestamp Committed
  • Item ID
  • Item Description
  • Prior On Hand Count
  • New On Hand Count

Get Physical Inventory Details

Through a query, this endpoint allows you to Get data from all committed Physical Inventory worksheets in a specified date range; non-committed worksheets are not included in the responses. The query is comprised of three parameters:

  1. apikey
  2. startDate
  3. endDate
query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

startDate
required
string <date>
Example: startDate=2022-01-31 11:58:18.541085

The start of the date range to query for Physical Inventory worksheets.

endDate
string <date>
Example: endDate=2022-10-31 11:58:18.541085

The end of the date range to query for Physical Inventory worksheets. If endDate not supplied then all data after startDate is returned.

Responses

Response Schema:
object
object (physicalInventoryDetails)
worksheetName
string

Returns the name of the Physical Inventory worksheet WRK_Name with a commit date within startDate and endDate.

worksheetTimestampCommitted
datetime

The date and time that the Physical Inventory worksheet as committed WRK_TimestampCommitted . Only those worksheets with a worksheetTimestampCommitted date within the startDate and endDate will be returned.

worksheetItemID
string <= 14 characters

The UPC INV_scanCode associated with an inventory record on the worksheet.

worksheetItemDescription
string

Description of the inventory record as entered on the returned worksheet. If this field is not directly available, the operation will return either the INV_Name or INV_ReceiptAlias instead.

worksheetPriorOnHand
string <= 7 characters

Displays the On Hand quantity associated with an item on the worksheet. This quantity will be the count that is currently present on the item - for the store - in CATAPULT. This is essentially how many the system thinks that it has available for the item in-store. EXAMPLE with Base Item + Alternate IDs:

  • 3 items on a Physical Inventory worksheet
  • 1 Base Item with an On Hand count of '2'
  • 1 Alternate ID that represents a 4-pack of the Base Item with an On Hand Count of 5 (5 x 4 = 20 Base Items)
  • 1 Alternate ID that represents a 6-pack of the Base Item with an On Hand Count of 6 (6 x 6 = 36 Base Items)
  • The end result would be one returned item (the Base Item) with a worksheetPriorOnHand of 58.
worksheetCountedOnHand
string <= 7 characters

Returns the entered/counted On Hand quantity associated with an item on the worksheet. This quantity will be the count manually entered by a store employee as the Physical Inventory is performed. For example, if a Physical Inventory worksheet was started, and the worksheetPriorOnHand was '15' for crackers, the store employee would enter '14' as the worksheetCountedOnHand at the end of the Physical Inventory (counting the items in store).

Request samples 

curl --request GET \
  --url 'https://accountid.catapultweboffice.com/api/physicalInventoryDetail?apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0&startDate=2022-01-31%2011%3A58%3A18.541085&endDate=2022-10-31%2011%3A58%3A18.541085'

Response samples

Content type
<?xml version='1.1' encoding='UTF-8'?>
<root>
    <row worksheetName="End of Year Physical Inventory"
    worksheetTimestampCommitted="2022-12-31 12:00:00.000"
    itemId="4011"
    worksheetItemDescription="Bananas"
    worksheetPriorOnHand="76"
    worksheetCountedOnHand="75"
</root>

Summary Item Data

Available with CATAPULT 5.6.99+. The Summary Item Data endpoint allows you to perform a GET query to obtain summarized transaction data for Items OR Departments over a date range for a specific store.

The summarized Department data includes:

  • Department Number
  • Department Name
  • (Net) quantity sold within the Department over the specified period
  • Extended cost of the items sold within the Department over the specified period
  • (Net) sales of the Department over the specified period
  • Store Number
  • Store Name
  • Omitted from Sales or Not (CATAPULT 5.8.164+)

The summarized Item data includes:

  • Item ID
  • Item Description (Receipt Alias)
  • (Net) quantity sold of the item over the specified period
  • Extended cost of the item sold over the specified period
  • (Net) sales of the item over the specified period
  • Store Number
  • Store Name
  • Omitted from Sales or Not (CATAPULT 5.8.164+)

Get Summary Item Data

Through a query, this endpoint allows you to GET summarized transaction data from Departments OR Items in a specified date range. The query is comprised of five parameters:

  1. apikey
  2. startDate
  3. endDate
  4. stores
  5. type
query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

startDate
required
string <date>
Example: startDate=2022-01-31 11:58:18.541085

The start of the date range to query for summary item data.

endDate
string <date>
Example: endDate=2022-10-31 11:58:18.541085

The end of the date range to query for summary item data. If endDate not supplied then all data after startDate is returned.

stores
string
Example: stores=682 (Single Store ID) OR 682:683:684 (Multiple Store IDs)

The Store ID of the store where the desired summary item data is located. This parameter can be a single Store ID or multiple Store IDs separated by a colon. If no Store ID is established as the parameter, the ID of the store where the API is being executed will be used.

Type
string
Example: Type=0 or 1

This parameter - which is 0 or 1 - allows you to specify what type of summarized item data is returned. Entering a parameter of 0 will return summarized Department sales data. Entering a parameter of 1 will return summarized Item net sales data.

Responses

Response Schema:
object
object (summaryItemData)
summaryDepartmentNumber
string

Returns the value entered into the "Department ID" field in CATAPULT Web Office for the returned Department. This field will only be returned when the Type parameter is set to 0 (for Department formatted data).

summaryDepartmentName
string

Returns the text entered into the "Department Name" field in CATAPULT Web Office for the returned Department. This field will only be returned when the Type parameter is set to 0 (for Department formatted data).

summaryItemID
string <= 14 characters

The UPC INV_scanCode associated with an inventory record in the summarized transaction data. This field will only be returned when the Type parameter is set to 1 (for Item formatted data).

summaryItemDescription
string

"Receipt Alias" associated with an inventory record in the summarized transaction data. This field will only be returned when the Type parameter is set to 1 (for Item formatted data).

summaryQtySold
string

Returns the total net quantity sold of a Department (if Type parameter = 0) OR the total net quantity sold of an item (if Type parameter = 1) within the specified period.

summaryExtCost
string

Returns the total cost of the goods sold for a Department (if Type parameter = 0) OR the total cost of an item (if Type parameter = 1) within the specified period.

summaryNetSales
string

Returns the total dollars sold for a Department (if Type parameter = 0) OR the total dollars sold for an item (if Type parameter = 1) within the specified period.

summaryStoreNumber
string

Returns the value entered into the "Store ID" field in CATAPULT Web Office for the specified store(s), or for the store where the API is being executed (if no store was specified).

summaryStoreName
string

Returns the value entered into the "Store Name" field in CATAPULT Web Office for the specified store(s), or for the store where the API is being executed (if no store was specified).

omitFromSales
boolean

Available with CATAPULT 5.8.164+

Indicates whether or not the associated Department or Item is omitted from the summarized sales data. This field returns 0 or 1.

  • 0: The record is NOT omitted from sales.
  • 1: The record is omitted from sales.

Request samples 

curl --request GET \
  --url 'https://accountid.catapultweboffice.com/api/summaryItemData?apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0&startDate=2022-01-31%2011%3A58%3A18.541085&endDate=2022-10-31%2011%3A58%3A18.541085&stores=682%20(Single%20Store%20ID)%20OR%20682%3A683%3A684%20(Multiple%20Store%20IDs)&Type=0%20or%201'

Response samples

Content type
<?xml version='1.1' encoding='UTF-8'?>
<root>
    summaryDepartmentNumber="140"
    summaryDepartmentName="ALCOHOL"
    summaryQtySold="13.000000"
    summaryExtCost="76.509900"
    summaryNetSales="105.290000"
    summaryStoreNumber="CA"
    summaryStoreName="California Ave Store"
    omitFromSales="0"
</root>

OR

<root>
    summaryItemID="000000000000"
    summaryItemDescription="STAN BREAD COUNTRY WHITE 28oz"
    summaryQtySold="6.000000"
    summaryExtCost="21.900000"
    summaryNetSales="31.080000"
    summaryStoreNumber="CA"
    summaryStoreName="California Ave Store"
    omitFromSales="1"
</root>

Summary Financials

Available with CATAPULT 5.6.117+ The Summary Financials endpoint allows you to perform a HTTP GET query to obtain summarized financial data over a date range for a specific store or list of stores. The data returned will be all data collected and summarized for a 24-hour period for the specified store(s).

The summarized data includes:

  • Date
  • Store ID
  • Store Name
  • Type of Financial Data - Buydowns - Discounts - Line Item - Discounts - Subtotal - Discounts - Excluded - Drawer Loans - Dynamic Promotions - Dynamic Promotions - Excluded - Negatives (i.e., All Voids, Item Corrects, Returns, No Sale) - Paid Ins / Paid Outs - Safe Drops - Taxes - Taxes - Exempt - Tenders - Totals (i.e., Gross Sales, Gross Sales - Training Mode) - Vendor Coupons
  • Name or Description of the Financial Data Type (e.g., "Cash")
  • Amount of the Financial Data (e.g., total amount of the "Cash" Tender collected)
  • Count of the Financial Data (e.g., how many Tenders were collected)
  • Omit from Sales Indicator
  • Foreign Currency Exchange Rate
  • Foreign Currency Amount

Get Summary Financial Data

Through a query, this endpoint allows you to Get summarized financial data for a store - or list of stores - in a specified date range. The query is comprised of three parameters:

  1. startDate
  2. endDate
  3. stores
query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

startDate
string <date>
Example: startDate=2022-01-31 11:58:18.541085

The start of the date range to query for Summary Financial Data. If no startDate is specified, default will return data for yesterday and display 24 hour's worth of data. Note that if a startDate is specified, an endDate must also be specified.

endDate
string <date>
Example: endDate=2022-10-31 11:58:18.541085

The end of the date range to query for Summary Financial Data. If no endDate is specified, default will return data for yesterday and display 24 hour's worth of data. Note that if an endDate is specified, a startDate must also be specified.

stores
string
Example: stores=HQ:RS1:RS2

The Store ID to query for Summary Financial Data. The Store ID as it is entered in CATAPULT Web Office must be used. If no stores are specified, then all data for all stores - within the specified reporting range - will be returned. If multiple stores, must be specified, they must be separated with a colon ( : ).

Responses

Response Schema:
object
object (summaryFinancialDataDetails)
groupDate
date

Returns the date in YYYY-MM-DD format that the associated response data is applicable for.

storeID
string

The Store ID, as entered in CATAPULT Web Office, that the associated response data is tied to.

storeName
string

The Store Name, as entered in CATAPULT Web Office, that the associated response data is tied to.

dataType
string

The type of financial data. This could be any one of the following types:

  • Buydowns
  • Discounts - Line Item
  • Discounts - Subtotal
  • Discounts - Excluded
  • Drops
  • Dynamic Promotions
  • Dynamic Promotions - Excluded
  • Loans
  • Negatives
  • Paid In
  • Paid Out
  • Taxes
  • Taxes - Exempt
  • Tenders
  • Totals (Gross Sales or Gross Sales - Training Mode)
  • Vendor Coupons
description
string

Returns the name or description of the dataType, as entered in CATAPULT Web Office.

amount
number <decimal>

Returns the total dollar amount of the financial data collected for the reporting range.

quantity
number <decimal>

Returns the total number of dataType records for the reporting range; note that "Taxes" and "Taxes - Exempt" are excluded from this count.

omitFromSales
boolean

Returns if an individual dataType was set to be omitted from sales or not.

  • 1 = dataType is omitted from sales
  • 0 = dataType is NOT omitted from sales
foreignCurrencyExchangeRate
number <decimal>

ONLY applies to dataType = Tenders Returns the Currency Exchange Rate for a Foreign Tender, as entered in CATAPULT Web Office.

foreignCurrencyAmount
number <decimal>

ONLY applies to the dataType = Tenders Returns the Currency Amount for a Foreign Tender.

Request samples 

curl --request GET \
  --url 'https://accountid.catapultweboffice.com/api/summaryFinancialData?apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0&startDate=2022-01-31%2011%3A58%3A18.541085&endDate=2022-10-31%2011%3A58%3A18.541085&stores=HQ%3ARS1%3ARS2'

Response samples

Content type
<?xml version='1.1' encoding='UTF-8'?>
<root>
    <row groupDate="2023-09-05"
    storeID="RS1"
    storeName="Main Store 123"
    dataType="Totals"
    description="Gross Sales"
    amount="746.4700"
    quantity="9.0000"
    omitFromSales="0"
    foreignCurrencyExchangeRate="0.000"
    foreignCurrencyAmount="0.0000"
</root>

File Cache

Available with CATAPULT 5.6.120+ The filecache endpoint allows you to perform a POST request to the CATAPULT Database to place a text file into the File Cache table. When a text file is placed in the database through this endpoint, other ECRS applications - such as Gateway - can reference and use the files as needed (e.g., pick the file up and move it to a specific destination). The specific CATAPULT Database where the file will be placed will be determined by the location where this endpoint is used. For example, if the POST request is made from the Headquarters location, the file will be placed in the Headquarters CATAPULT Database.

File Cache

Available with CATAPULT 5.6.120+ Use this endpoint to POST a text file into the File Cache table within the CATAPULT database. The request body for this endpoint will contain the contents of the text file, and it must not contain any type of formatting (JSON, XML, etc.). The request will be sent as plain text. The specific CATAPULT Database where the file will be placed will be determined by the location where this endpoint is used. For example, if the POST request is made from the Headquarters location, the file will be present in the Headquarters CATAPULT Database.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

FileName
required
string <= No Limit characters
Example: FileName=Example Text File Name

This parameter allows you to specify the name of the text file that you are inserting into the File Cache table of the CATAPULT Database.

Responses

Request samples 

curl --request POST \
  --url 'https://accountid.catapultweboffice.com/api/filecache?apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0&FileName=Example%20Text%20File%20Name'

Response samples

Content type
{
  "code": 4,
  "message": "File not provided"
}

Gift Cards

This collection of endpoints allows for the management of CATAPULT gift cards (i.e., "self-hosted" gift cards). These endpoints are in no way associated with - or have any affect on - gift card services or providers used/hosted outside of CATAPULT.

The following gift card endpoints are available:

  • /giftCardBulk - Available with CATAPULT 5.7.135+, this endpoint allows for the bulk creation of CATAPULT gift cards within your store's CATAPULT database.

  • /giftCardUpdate - Available with CATAPULT 5.8.164+, this endpoint allows for the balance of previously-created CATAPULT gift cards to be updated in bulk via a positive or negative adjustment or by setting the balance to a specified amount.

Create Gift Cards in Bulk

CATAPULT Version Requirements

  • A merchant must be running CATAPULT 5.7.135 or newer at their store location(s) for this endpoint to create gift cards.

Overview

  • Endpoint = /giftCardBulk

  • This endpoint allows for you to perform a POST request to the CATAPULT Database to create and automatically activate a bulk set of CATAPULT Self-Hosted Gift Cards. This endpoint is useful if your business needs to fulfill a large order of gift cards for a customer (e.g., corporate Christmas gifts).

  • When using this endpoint to generate the Gift Cards, you must specify the quantity of the Gift Cards that need to be generated, in addition to the pre-loaded dollar amount that needs to be on each Gift Card.

  • You can optionally choose the numerical prefix of the Gift Card's code, while the option to choose if the Gift Cards require a Personal Identification Number (PIN) to complete payment is also available.

Using the Created Gift Cards

  • When /giftCardBulk endpoint is used and the Gift Cards are successfully created, the response will contain the following information about each Gift Card:

    • Gift Card Number
    • Beginning Balance (i.e., the pre-loaded amount)
    • Gift Card PIN (if present)
    • The Employee ID, First Name, and Last Name of the employee who performed the request to generate the Gift Cards (as entered on their Employee Record in CATAPULT Web Office)
    • The date and time at which the Gift Card was generated

  • All information about each Gift Card will be stored in your CATAPULT database, which will in turn allow recipients of those Gift Cards to use their card at any store location in the enterprise. In addition, because each Gift Card is activated upon creation, the Gift Card recipients can immediately use their card as a purchasing tender.

  • Once the Gift Cards have been created, you can use this information and distribute the Gift Cards as desired. Examples include:

    • Sending the Gift Cards electronically (e.g., email) to the desired recipients.
    • Printing the Gift Card details on a physical card using a desired service.
    • Ordering Gift Cards from ECRS and using the endpoint to create the range of Gift Cards instead of the tools within CATAPULT Web Office. Note that if the /giftCardBulk endpoint is used to order Gift Cards from ECRS, the minimum order quantity of 500 still applies.

Authentication Requirements

  • A store employee with an Employee Record in CATAPULT Web Office must perform the giftCardBulk request and must properly authenticate to do so. Specifically, this employee must meet the following authentication requirements:

    • Have a valid API Key (generated on the Employee Record in CATAPULT Web Office)
    • Must be "Active" (i.e., the Inactive checkbox must not be selected on their Employee Record in CATAPULT Web Office)

  • Should the employee performing the request not meet any of the authentication requirements, a 403 "Error" response will be returned.

Authorization Requirements

  • A store employee with an Employee Record in CATAPULT Web Office must perform the giftCardBulk request and must have the Gift Card Bulk Load checkpoint enabled in their assigned Authorization Security profile.

  • Should the employee performing the request not meet this authorization requirement, a 403 "Error" response will be returned.

    • In these scenarios, if the unauthorized employee has the Gift Card Bulk Load checkpoint enabled at a later time, note that it may take up to five (5) minutes from the time the checkpoint is enabled for the employee for the changes to take effect.
      • EXAMPLE: If the Gift Card Bulk Load checkpoint is enabled for an employee at 1:30 P.M., they will not be able to perform the giftCardBulk request until 1:35 P.M.

Reporting

  • When a store employee (with an Employee Record in CATAPULT Web Office) performs the giftCardBulk request, and Gift Cards are successfully generated, the Employee ID, First Name, and Last Name of the employee - as entered on their Employee Record - will be permanently associated with that Gift Card creation record in the CATAPULT database.

  • You can report on and verify the "creating employee" information in CATAPULT Web Office 5.7.136+ using the Gift Card Balances report. This report allows you to view the "creating employee" information for each Gift Card, in addition to viewing the current balance of each card.

Limitations

  • The giftCardBulk method can only be used to create CATAPULT (i.e., "self hosted") Gift Cards. It cannot be used to update anything about pre-existing CATAPULT Gift Cards. Likewise, it cannot be used to create or update any Third-Party Gift Cards.

  • General Ledger (GL) Accounts

    • If your business uses the General Ledger (GL) Accounts module with CATAPULT, you can opt to select a GL Profile as the "Gift Card Liability Account" for Gift Cards. This is done on the Gift Card plugin of the Transaction Security profile.

    • IMPORTANT: If a GL profile is chosen for the Gift Card Liability Account, using the giftCardBulk method does NOT Debit or Credit the account. Instead, the General Ledger entries must be imported into CATAPULT from the third party accounting system in these scenarios.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

amount
required
currency [ 0.01 .. 999.99 ] characters
Example: amount=50

This parameter requires that you to specify the dollar amount that will be pre-loaded onto each Gift Card created. In a 200 "Success" response, each Gift Card's amount can be verified and viewed in the BeginningBalance field.

count
required
integer [ 1 .. 99999 ] characters
Example: count=300

This parameter requires that you specify the quantity/number of Gift Cards that should be created - and pre-loaded with the specificed amount - with each request.

prefix
integer = 3 characters
Example: prefix=780

This optional parameter allows you to establish the first three numeric characters of each Gift Card's code created with the request.

  • If a prefix is established, you can verify it was applied by viewing the GiftCardNumber for each Gift Card in the response.

  • If no prefix is established, a default prefix of 780 will be used.

  • If more than three numeric characters are submitted with this parameter, only the first three characters will be accepted; the remaining characters will be removed.

  • If less than three numeric characters are submitted with this parameter, or alphanumeric characters are used, then the request will fail and return a 422 "Error" response code (i.e., "Invalid Range").

pin_required
BIT
Example: pin_required=1

This optional parameter allows you to choose if each generated Gift Card has an associated Personal Identification Number (PIN) that must be entered when the card is used for payment. The following options can be submitted with this parameter:

  • 0 - Passing 0 for this parameter - or not including the pin_required parameter in the request at all - will cause all generated Gift Cards to NOT have an associated PIN. Meaning, when these cards are used at the Point of Sale for payment, your customers will not be required to enter a PIN to complete payment.

  • 1 - Passing 1 for this parameter will cause all generated Gift Cards to have an associated PIN. As such, shoppers who use the Gift Cards must enter this PIN at Point of Sale to complete payment.

    • For security, each Gift Card's PIN will be a randomly generated four-digit numeric code, and this randomization will occur for each Gift Card generated.
    • Each Gift Card's PIN will only be visible in the SecurityCode field within the response. Otherwise, it will be securely hashed and stored in your CATAPULT database (i.e., it will not be visible/accessible).

Responses

Response Schema:
object
object (giftCardBulk)
GiftCardNumber
string = 19 characters

This field represents the automatically generated code/number of each Gift Card. This code will always be 19 alphanumeric digits. If a prefix is established as a query parameter, the entered prefix - if valid - will be included in this field.

BeginningBalance
number

This field represents the pre-loaded amount on the Gift Card, which is established with the amount query parameter.

SecurityCode
integer <= 3 characters

This field represents the Personal Identificatiion Number (PIN) of the Gift Card. This field will only be present if the pin_required query parameter is set to 1.

IssuingEmployeeID
integer <= 9 characters

This field represents the Employee ID of the store employee that initiated the request to create/generate the Gift Cards. This ID is established on the corresponding Employee Record in CATAPULT Web Office.

IssuingEmployeeFirst
string <= 30 characters

This field represents the First Name of the store employee that initiated the request to create/generate the Gift Cards. This name is established on the corresponding Employee Record in CATAPULT Web Office.

IssuingEmployeeLast
string <= 30 characters

This field represents the Last Name of the store employee that initiated the request to create/generate the Gift Cards. This name is established on the corresponding Employee Record in CATAPULT Web Office.

IssueDate
string <date-time>

This field represents the date and time on which the Gift Cards were successfully generated.

Request samples 

curl --request POST \
  --url 'https://accountid.catapultweboffice.com/api/giftCardBulk?apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0&amount=50&count=300&prefix=780&pin_required=1'

Response samples

Content type
<?xml version='1.1' encoding='UTF-8'?>
<root>
    <row GiftCardNumber="999X4KE25KU9MPGJ3E5" BeginningBalance="25.000" SecurityCode="547" IssuingEmployeeID="789" IssuingEmployeeFirst="Sally" IssuingEmployeeLast="Jones" IssueDate="2024-05-31 09:20.57.731"/>
    <row GiftCardNumber="999D9JH6LA89ABCJ5KF" BeginningBalance="25.000" SecurityCode="928" IssuingEmployeeID="789" IssuingEmployeeFirst="Sally" IssuingEmployeeLast="Jones" IssueDate="2024-05-31 09:20.57.731"/>
</root>

Update Gift Cards in Bulk

CATAPULT Version Requirements

  • A merchant must be running CATAPULT 5.8.164 or newer at their store location(s) for this endpoint to make changes to their gift cards.

Overview

  • Endpoint = /giftCardUpdate

  • This endpoint allows you to perform PUT requests to the CATAPULT database to update the balance of previously created and activated CATAPULT gift cards (i.e., "self-hosted" gift cards). Both electronic and physical CATAPULT gift cards can be updated with this endpoint.

  • Both the prefix and number of each gift card must be specified when using this endpoint. For each gift card, the balance can be adjusted positively or negatively (by a set amount) OR be changed to a specific dollar amount.

  • This endpoint allows you to update the balances of any desired quantity of gift cards. While there is technically no limit to the quantity of gift cards that can be updated per request, it's a best practice not to include a large quantity of gift cards in each request to a) maintain system performance, and b) avoid having a data set that is too large to troubleshoot, should issues arise.

Example Use Cases

  • Decreasing the balance of multiple gift cards to $0.00 to comply with state and/or federal dormancy regulations.

  • Increasing the balance on gift cards to correct a mistake when the cards were originally created.

DISCLAIMER

ECRS is not responsible for the validation and/or tracking of state or federal law governing gift card value adjustments, dormancy fees, and/or cancellation requirements.

Limitations

  • This endpoint only updates the balance of physical or electronic CATAPULT gift cards. It does not facilitate updating the balance of gift cards hosted by a third party.

  • A gift card's prefix, number, and PIN (personal identification number) cannot be updated using this endpoint.

  • General Ledger (GL) Accounts

    • If your business uses the General Ledger (GL) Accounts module with CATAPULT, you can opt to select a GL Profile as the "Gift Card Liability Account" for gift cards. This is done on the Gift Card plugin of the Transaction Security profile.

    • IMPORTANT: If a GL profile is chosen for the Gift Card Liability Account, using the giftCardUpdate endpoint does NOT Debit or Credit the account. Instead, the General Ledger entries must be imported into CATAPULT from the third party accounting system in these scenarios.

Authentication Requirements

  • Only a store employee with an Employee Record in CATAPULT Web Office can use the giftCardUpdate endpoint and must properly authenticate with the API to do so. Specifically, this employee must meet the following authentication requirements:

    • Have a valid API Key (generated on the Employee Record in CATAPULT Web Office)
    • Must be "Active" (i.e., the Inactive checkbox must not be selected on their Employee Record in CATAPULT Web Office)

  • Should the employee performing the request not meet any of the authentication requirements, a 403 "Error" response will be returned.

Authorization Requirements

  • Store employees using the giftCardUpdate endpoint must have the Gift Card Bulk Adjustment checkpoint enabled in their assigned Authorization Security profile.

  • Should the employee performing the request not meet this authorization requirement, a 403 "Error" response will be returned.

    • In these scenarios, if the unauthorized employee has the Gift Card Bulk Adjustment checkpoint enabled at a later time, note that it may take up to five (5) minutes from the time the checkpoint is enabled for the employee for the changes to take effect.
      • EXAMPLE: If the Gift Card Bulk Adjustment checkpoint is enabled for an employee at 1:30 P.M., they will not be able to perform the giftCardBulk request until 1:35 P.M.

Reporting

  • The updated balances of gift cards will display in the Gift Card Account Balances report in the "Current Bal." column.

  • Any gift cards that have an updated balance will be organized into their own section in the Gift Card Account Activity report. This report displays all relevant information about the gift card adjustment, including:

    • The prefix, number, and PIN of the gift cards.
    • The date and time the gift cards were updated.
    • The employee who performed the update to the gift cards.
query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

Request Body schema:
CardNumber
required
string = 16 characters

  • The unique card number of the gift card (i.e., the last 16 digits of the gift card's number).

  • This number, along with the Prefix of the gift card, will determine the card that is to receive an updated balance.

  • The card numbers of existing gift cards can be obtained from the following locations:

    • The responses from the giftCardBulk endpoint, if that endpoint was initially called to create gift cards.
    • The Gift Card Account Activity or Gift Card Account Balances report, which are generated in CATAPULT Web Office.
    • The printed card number on physical gift cards (i.e., the last 16 digits).
Prefix
required
integer = 3 characters

  • The prefix of the gift card (i.e., the first 3 digits of the gift card's number).

  • This number, along with the Card Number of the gift card, will determine the card that is to receive an updated balance.

  • The prefixes of existing gift cards can be obtained from the following locations:

    • The responses from the giftCardBulk endpoint, if that endpoint was initially called to create gift cards.
    • The Gift Card Account Activity or Gift Card Account Balances report, which are generated in CATAPULT Web Office.
    • The printed card number on physical gift cards (i.e., the first 3 digits).
AdjustBy
required
bit

  • This update option allows for the gift card's balance to be adjusted by a specific amount.

  • The desired AdjustBy dollar amount is specified in the Value parameter for this endpoint. The specified Value can be a positive or negative amount. Should a negative value be specified, the endpoint will prohibit a gift card from having a negative balance (i.e., the lowest a gift card's balance could possibly be is $0.00).

  • When using the giftCardUpdate endpoint, this parameter must be set to either of the following:

    • 0: The AdjustBy update option will NOT be used to update the gift card's balance; rather, the SetTo update option must be used.
    • 1: The AdjustBy option will be used to update the gift card's balance.

  • If both the AdjustBy and SetTo fields have a value of 1 for updating a gift card's balance, the endpoint call will fail as only one update method can be used.

SetTo
required
bit

  • This update option allows for the gift card's balance to be set to a desired amount. This option should be used if gift cards need to be "cancelled" (i.e., have their balance set to $0.00).

  • The desired SetTo dollar amount is specified in the Value parameter for this endpoint. The specified Value can be 0.00 or a positive amount; it cannot be negative.

  • When using the giftCardUpdate endpoint, this parameter must be set to either of the following:

    • 0: The SetTo option will NOT be used to update gift card's balance; rather, the AdjustBy update option must be used.
    • 1: The SetTo option will be used to update the gift card's balance.

  • If both the SetTo and AdjustBy fields have a value of 1 for updating a gift card's balance, the endpoint call will fail as only one update method can be used.

Value
required
number

  • The dollar amount that the gift card needs to be adjusted by or set to, depending on the update option used (i.e., AdjustBy or SetTo).

  • If using the AdjustBy update option, this field can be positive (e.g., 5.0000) or negative (e.g., -5.0000). Should a negative value be specified, the endpoint will prohibit a gift card from having a negative balance (i.e., the lowest a gift card's balance could possibly be is $0.00).

  • If using the SetTo update option, this field can only be zero (e.g., 0.0000) or positive (e.g., 25.0000). It cannot be negative.

  • If no Value is specified, the call to this endpoint will fail and a 500 "Error" response will be returned.

Responses

Response Schema:
object
object (giftCardUpdate_response)
CardNumber
string = 16 characters
  • The number of the gift card, which serves as a primary method of identification for the gift card with an updated dollar amount.
  • This number will exclude the gift card's associated prefix number at the beginning of the card number.
Prefix
integer = 3 characters
  • The prefix number of the gift card, which serves as a secondary method of identification for the gift card with an updated dollar amount.
Balance
number
  • The updated balance - in U.S. dollars - on the associated Gift Card after the giftCardUpdate endpoint has been called.

Request samples

Content type
[
  • {
    }
]

Response samples

Content type
<?xml version='1.1' encoding='UTF-8'?>
<root>
    <row CardNumber="X4KE25KU9MPGJ3E5" Prefix="780" Balance="25.0000"/>
    <row CardNumber="D9JH6LA89ABCJ5KF" Prefix="780" Balance="25.0000"/>
</root>

Batch Updates

Overview

  • The Batch Update endpoints are the recommended method for secure manipulation of data outside of the Web Office interface. Each Batch Update endpoint is used for bulk additions and modifications to a specific dataset or task, such as inventory and suppliers or worksheet processing and promotion configuration.

  • The Batch Update endpoints are commonly used for synchronizing data from Legacy systems during migration or the automation of certain tasks. Each endpoint is limited to POST requests unless where noted otherwise in the operation description.

  • The Batch Update endpoints are extensions of the Staging Tables procedures, and as such are only used when the Staging Tables module is present on a database.

  • When using any of the Batch Update endpoints, the order of the data records included in each request does not determine the order in which the API will process the data and make the corresponding updates.

Best Practices

  • Perform all batch updates (i.e., use of the endpoints) be made at the Headquarters location. Doing so will leverage CATAPULT's data synchronization model and correctly update corresponding data records at applicable remote stores.

  • Avoid sending multiple rows in a single batch referencing the same item, as this can cause slow performance in batch processing.

Using Batch Update Endpoints

  • When any of the Batch Update endpoints are used, only fields with updated values should be included in the request. If fields need to be preserved/unchanged, then those fields should NOT be included in the request. If a field is included in the request with an empty value, the API will use that empty value and create a corresponding empty record.

  • When any of the Batch Update endpoints are used, the associated data is temporarily stored in a table within the CATAPULT database at the store (where the endpoint was used). After the data is processed for any of the endpoints, the table will be automatically cleared/purged to prevent bloat. This self-cleaning behavior cannot be changed or modified, and no action is required for it to occur.

  • With CATAPULT 5.7.142 and newer, if the Staging Tables are used outside of the Batch Update endpoints, please note that the database tables associated with each endpoint - except for batch_ImportMessages - will be cleared upon database restart.

Batch Item Maintenance

Overview

  • The /batch/itemMaintenance endpoint is used to post bulk, multi-store additions or changes to your inventory records.

  • This endpoint can create Departments (when a Department Number does not exist and a Department Name is entered), Brands, and Power Fields. New entries are added to their respective tables when not found in the database.

  • This endpoint can only be used when performing batch updates to the Headquarters CATAPULT database; meaning, the fully-qualified domain name of the Headquarters location must be used in the URL/call of the endpoint. Using the endpoint for Remote Stores will result in an error.

New Item Behavior

  • New items created by this batch process will inherit all applicable department default values associated with the Department Number entered in the batch record. Additional item hierarchy defaults are pulled from the Sub-Department Number, Category Number, Sub-Category Number, and Variety Number field values, if subsequently entered in the batch record. The full item hierarchy (numbers) must be included to update or insert item records.

  • New items will have pricing records created for all zones. Specifically, the item's promptForPrice setting will be set to enabled (i.e., 1) on Price Level 1 and disabled (i.e., 0) with a dollar value of $0.00 on Price Levels 2-4.

    • To override this default behavior and have new items be added with promptForPrice disabled and a $0.00 Base Price on Price Level 1, apply the following (global) Advanced Setting:

      KEY = stagingTables.NewItemsAddWithZeroPrice

      VALUE = true

Batch Process Updates and Message Log

  • Batch processing status and log can be viewed by calling the /batch/importMessages endpoint.

  • Beginning with CATAPULT 5.7.143 and newer, if one or more items within a batch fails or encounters an error, the items that failed - and why - will be included in the detail line of the importMessages response.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

batch
required
integer
Example: batch=123

A unique identifier used to define related objects in a batch operation.

Request Body schema:

List of Items To Be Updated

Array
action
required
string
Enum: "U" "R"

Type of Action to be Performed:

  • 'U' - Insert or Update
  • 'R' - Remove
itemId
required
string <= 14 characters

The Item ID of the item being added or edited.

replaceItemID
string <= 14 characters

Supported CATAPULT Version

  • Available with CATAPULT 5.8.163 and newer.

IMPORTANT

Field Purpose

  • This field allows you to replace the existing Item ID of an item with another ID.

Potential Use Cases of Field

  • Replacing non-standard PLUs on produce items to standard PLUs.
  • Replacing the Item IDs of non-barcoded items (e.g., homemade baked goods) to a new standard set by the merchant or otherwise.
  • Replacing Item IDs without check digits to Item IDs with check digits.

Field Behavior

  • The entered replaceItemID value will not create an Alternate ID for the item; it will truly replace the existing Item ID.
  • The entered replaceItemID value must not match any existing Item ID or Alternate ID in the CATAPULT database. Item records with replaceItemID values that match an existing ID will be rejected during batch processing, with error details available in the /batch/importMessages endpoint.
  • Any replaceItemID values with leading spaces will be automatically adjusted to remove those spaces.
  • Any replaceItemID values with one or more spaces in the middle of the value will be preserved (i.e., the spaces won't be removed).
  • If a replaceItemID value has one or more spaces at the end of the value, those spaces will be ignored and not processed.
  • Any replaceItemID values longer than 14 characters will be automatically truncated during batch processing (e.g., A value of 73852073966492000 would be truncated to 73852073966492).

Best Practices

  • In addition to the guidelines and best practices outlined in this article, a best practice when using this field is to ensure that only one record of an Item ID is being replaced in each request. If multiple records with the same Item ID are being replaced in the same request, the endpoint may or may not apply the desired replacement ID due to how all batch endpoints process data (i.e., the order of the data within the request is not honored).
deptNo
integer
  • The Department Number of the new or existing item.
  • This value is required for new items.
deptName
string <= 30 characters
  • The Department Name of the new or existing item.
  • This value is required for new items.
name
string <= 254 characters

The descriptive name of the item.

receiptAlias
string <= 32 characters
  • The descriptive text of the item that will appear on receipts.
  • This value is required for new items.
brand
string <= 30 characters
  • The Brand of the item.
  • Use 'NONE' to set to null/no choice.
size
string <= 20 characters

The package size of the item (e.g., 16 OZ).

promptList
string <= 30 characters
  • List of prompts names separated by colon(:). Note that the entered list will replace any currently listed prompts.
  • Enter 'NONE' to remove all.
discountList
string <= 30 characters
  • List of discount names separated by colon(:). Note that the entered list will replace any currently listed discounts.
  • Enter 'NONE' to remove all; 'DEFAULT' to use department default.
suggestedRetail
string <decimal(16,4)>

The suggested retail price (SRP) of the item.

pf1
string <= 30 characters
  • The item's Power Field 1 assignment.
  • Enter 'NONE' to set to null/no choice.
pf2
string <= 30 characters
  • The item's Power Field 2 assignment.
  • Enter 'NONE' to set to null/no choice.
pf3
string <= 30 characters
  • The item's Power Field 3 assignment.
  • Enter 'NONE' to set to null/no choice.
pf4
string <= 30 characters
  • The item's Power Field 4 assignment.
  • Enter 'NONE' to set to null/no choice.
pf5
string <= 30 characters

The item's Power Field 5 assignment.

pf6
string <= 30 characters

The item's Power Field 6 assignment.

pf7
string <= 30 characters

The item's Power Field 7 assignment.

pf8
string <= 30 characters

The item's Power Field 8 assignment.

memo
string <= 254 characters

Any text that should be entered into the Memo field on the item's inventory record.

linkGroup
string
  • This parameter allows you to specify a Linked Item Group for the item. Note that if a Linked Item Group is specified, it will be appllied to ALL stores for that item. Enter 'NONE' to set to null/no choice.
  • NOTE: If you want to choose an item's Linked Item Group for a specific store, use the Batch Item Store Data endpoint.
nonReturnable
boolean

Determines if the item is returnable or not.

  • true: The item cannot be returned, and the corresponding "Item cannot be returned" checkbox on the item's inventory record in Web Office will be checked.
  • false: The item can be returned, and the corresponding "Item cannot be returned" checkbox on the item's inventory record in Web Office will NOT be checked.
embeddedPriceAsUnit
boolean

Determines if the sale of the embedded price package for the item will be treated as a single unit.

  • true: The "Treat the sale of embedded price package as a single unit" checkbox on the item's inventory record in Web Office will be checked.
  • false: The "Treat the sale of embedded price package as a single unit" checkbox on the item's inventory record in Web Office will NOT be checked.
countryOfOrigin
string <= 28 characters

The item's "Country of Origin Label" text that can be used for identification and marketing purposes.

subDeptNumber
integer
  • The number of the Sub-Department Item Hierarchy level that the item should be added or moved into.
  • You must also specify a deptNo if using this field.
categoryNumber
integer
  • The number of the Category Item Hierarchy level that the item should be added or moved into.
  • You must also specify a deptNo and subDeptNumber if using this field.
subCategoryNumber
integer
  • The number of the Sub-Category Item Hierarchy level that the item should be added or moved into.
  • You must also specify a deptNo, subDeptNumber, and categoryNumber if using this field.
varietyNumber
integer
  • The number of the Variety Item Hierarchy level that the item should be added or moved into.
  • You must also specify a deptNo, subDeptNumber, categoryNumber, and subCategoryNumber if using this field.

Request samples

Content type
[
  • {
    }
]

Batch Item Pricing

The Item Pricing endpoint is used to post bulk, multi-store additions or changes to the Price Levels on your inventory maintenance records. Discounts are not created by this operation and must be created separately in WebOffice before being used in the request parameters. The operation will, however, create new Family Lines if one is entered in the parameters and does not already exist.

Note promptForPrice defaults to disabled 0 when not specified in the request. To adjust this behaviour and have promptForPrice default to enabled 1 when A) not defined in the request and B) the price of the respective inventory item is $0.00, add the following Global-level Advanced Setting in WebOffice:

KEY = stagingTables.automaticPromptForPrice
VALUE = true

If the inventory price is any other dollar amount then it will default to disabled.

See also: Inventory Pricing & Costs.

Batch processing status and log can be viewed by calling the /batch/importMessages endpoint.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

batch
required
integer
Example: batch=123

A unique identifier used to define related objects in a batch operation.

Request Body schema:

List of Item Prices to be updated

Array
itemId
required
string <= 14 characters

See also: Item ID.

zoneId
required
string <= 30 characters

See also: Zones.

retail1
string <decimal(16,4)>

See also: Price Levels.

promptForPrice1
boolean

See also: Prompt for Price.

discount1
string <= 30 characters

See also: Auto Discount.

quantityOnly1
boolean
idealMargin1
string <decimal(16,4)>

See also: Ideal Margin.

divider1
integer [ 1 .. 99 ]

See also: Pricing Divider.

retail2
string <decimal(16,4)>
promptForPrice2
boolean
discount2
string <= 30 characters
quantityOnly2
boolean
idealMargin2
string <decimal(16,4)>
divider2
integer [ 1 .. 99 ]
retail3
string <decimal(16,4)>
promptForPrice3
boolean
discount3
string <= 30 characters
quantityOnly3
boolean
idealMargin3
string <decimal(16,4)>
divider3
integer [ 1 .. 99 ]
retail4
string <decimal(16,4)>
promptForPrice4
boolean
discount4
string <= 30 characters
quantityOnly4
boolean
idealMargin4
string <decimal(16,4)>
divider4
integer [ 1 .. 99 ]
familyLine
string <= 30 characters

Family Line name. Enter 'NONE' to set to null/no choice. See also: Family Lines.

retailAccountingPrice
string <decimal(16,4)>

Applies to all stores in the Zone specified. Use 'Batch Item Store Data' for updates to a single store. This value will be recorded with transactions. See also: Retail Value.

retailAccountingReportCode
string <= 30 characters

Applies to all stores in the Zone specified. Use 'Batch Item Store Data' for updates to a single store. This value will be recorded with transactions. See also: Report Code.

Request samples

Content type
[
  • {
    }
]

Batch Item Store Data

The Item Store Data endpoint is used to post per-store bulk updates to your inventory Pricing & Costs and related fields. It allows a more nuanced, targeted alternative when the larger scope of its sister function, Batch Item Pricing, isn't necessary.

See also: Inventory Pricing & Costs, Inventory Options.

Batch processing status and log can be viewed by calling the /batch/importMessages endpoint.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

batch
required
integer
Example: batch=123

A unique identifier used to define related objects in a batch operation.

Request Body schema:

List of Item Store Data to be Updated

Array
itemId
required
string <= 14 characters

See also: Item ID.

storeId
required
string <= 10 characters

See also: Store ID.

taxList
string <= 30 characters

List of tax names separated by colon(:). Enter 'NONE' to remove all; 'DEFAULT' to use department default.
Entered list will replace any currently listed taxes. See also: Taxes.

specialTendersList
string <= 30 characters

List of tender names separated by colon(:). Enter 'NONE' to remove all; 'DEFAULT' to use department default.
Entered list will replace any currently listed special tenders. See also: Special Tenders Allowed.

itemRestriction
string <= 30 characters

Enter 'NONE' to set to null/no choice; 'DEFAULT' to use department default.
See also: Item Restrictions.

lastCost
string <decimal(16,4)>

See also: Last Cost.

defaultSupplierId
string <= 10 characters

Enter 'NONE' to set to null/no choice.
Item must have an ordering item ID for selected supplier. See also: Suppliers Section.

loyaltyMultiplier
string <decimal(4,3)>

Negative number will use department default. See also: Loyalty Accrual Multiplier.

weightProfile
string <= 30 characters

Enter 'NONE' to set to null/no choice; 'DEFAULT' to use department default.
See also: Weight Profiles.

qtyEntry
boolean
discontinued
boolean
promptForPriceMin
string <decimal(16,4)>
promptForPriceMax
string <decimal(16,4)>
retailAccountingPrice
string <decimal(16,4)>

See also: Retail Value.

retailAccountingReportCode
string <= 30 characters

See also: Report Code.

linkGroup
string <= 30 characters
pf1
string <= 30 characters

See also: PowerFields.

pf2
string <= 30 characters
pf3
string <= 30 characters
pf4
string <= 30 characters
pf5
string <= 30 characters
pf6
string <= 30 characters
pf7
string <= 30 characters
pf8
string <= 30 characters
location
string <= 30 characters

See also: Location.

shelfSequence
integer

See also: Shelf Information Tab. Note that this field can support a maximum value of 999999999.

Request samples

Content type
[
  • {
    }
]

Batch Item Alternate Ids

The Item Alternate ID endpoint provides you with a means to post bulk updates for managing the Alternate IDs associated with targeted inventory records. As a single inventory record can have multiple Alternate IDs, the base Item ID is required for each line item of the request body (one line item, or row, for each Alternate ID). The same base Item ID can be used as many times as needed to affect all necessary Alternate IDs on its respective maintenance record.

See also: Inventory Alternate IDs.

Batch processing status and log can be viewed by calling the /batch/importMessages endpoint.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

batch
required
integer
Example: batch=123

A unique identifier used to define related objects in a batch operation.

Request Body schema:

List of Item Alternate Ids

Array
action
required
string
Enum: "U" "R"

Type of Action to be Performed:

  • 'U' - Insert or Update
  • 'R' - Remove
itemId
required
string <= 14 characters

See also: Item ID.

alternateId
required
string <= 14 characters
alternateIdReceiptAlias
string <= 32 characters
alternateIdQty
required
string <decimal(12,3)>

Request samples

Content type
[
  • {
    }
]

Batch Item Ordering Information

Overview

  • This endpoint allows you to post bulk updates to manage the Suppliers (and related ordering information) associated with specific inventory records.

Notes

  • Because a single inventory record can have multiple suppliers, the base Item ID is required for each line item of the request body.
  • The same base Item ID can be used as many times as needed to affect all necessary supplier-related ordering information on its respective maintenance record.
  • If this endpoint is used to add supplier ordering information to an item that previously did not have any such information, the Batch Item Store Data endpoint (/batch/itemStoreData) must also be used to specify the item's Default Supplier. If the item's Default Supplier is not set, when the item is edited in CATAPULT Web Office, it will require that a Default Supplier be specified before any other changes can be saved.

Batch Process Updates and Message Log

  • Batch processing status and log can be viewed by calling the /batch/importMessages endpoint.
query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

batch
required
integer
Example: batch=123

A unique identifier used to define related objects in a batch operation.

Request Body schema:

List of Item Ordering Information

Array
action
required
string
Enum: "U" "R" "D"

Type of Action to be Performed:

  • 'U' - Insert or Update
  • 'R' - Remove
  • 'D' - Discontinue
itemId
required
string <= 14 characters

The Item ID of the item - as entered in CATAPULT Web Office on the Inventory Record - that is to have ordering information updated.

supplierId
required
string <= 10 characters

The ID Number of the item's Supplier, as entered in CATAPULT Web Office on the Supplier Record. This ID should match the Supplier for the item where ordering information needs to be updated.

orderId
required
string <= 15 characters

The Supplier Unit ID (SUID) of the item - as entered in CATAPULT Web Office on the Inventory Record - that is to have ordering information updated.

orderQty
string <decimal(12,3)> [ 1 .. 999999999999 ] characters
  • The quantity of packages/items included in one order unit.
  • IMPORTANT: This field is required if the U action is performed.
orderUnitName
string <= 30 characters

A descriptive name for the unit that the order item comes as (e.g., CS or EA).

Adding/Inserting New Supplier Unit ID Records

  • IMPORTANT: The orderUnitName field is required if new Supplier Unit ID records are being added to inventory records via the U action. If no name is specified, the Supplier Unit ID record will not be added and an error will be recorded in the /batch/importMessages endpoint for the corresponding batch.
  • With CATAPULT 5.8.161 and newer, new Order Units will be created if the name specified in the request does not match an existing entry in the CATAPULT database. If new Order Units are created, they will have a default orderQty of 0. In previous CATAPULT versions, passing an orderUnitName that did not match an existing Order Unit would result in an error.

Updating Existing Supplier Unit ID Records

  • The orderUnitName field is NOT required if updates to existing Supplier Unit ID records are being made (via the U action).
  • If existing Supplier Unit ID records are being updated, and an orderUnitName is included in the request, the specified name must exactly match an existing Order Unit Name in the CATAPULT database. If the specified Order Unit Name does not match an existing record, then either a new Order Unit will be created (with CATAPULT 5.8.161 and newer), or an error will be recorded in the /batch/importMessages endpoint for the corresponding batch (with CATAPULT 5.8.160 or older).
orderPrimary
boolean

Determines whether or not the SUID is the Default ordering preference for the item for the specified Supplier.

  • true = The SUID is the Default selection.
  • false = The SUID is not the Default selection.
vendorDistributionCenterID
string <= 32 characters

Available with CATAPULT 5.6.101 and newer

  • This field allows you to look up or create a Supplier Distribution Center record's "ID" field.
  • Each inventory item's orderId (a.k.a Supplier Unit ID) will be used to identify the correct Supplier where the Distribution Center needs to be looked up or added.
  • If this field is populated, along with the vendorDistributionCenterName, new Distribution Center records will be added for the supplier if they are not originally found.
  • If this field is populated with NONE, then the Distribution Center will be removed/unassociated from the item's orderId.
vendorDistributionCenterName
string <= 32 characters

Available with CATAPULT 5.6.101 and newer

  • This field allows you to enter the name of a new Distribution Center being added for a supplier.
  • Each inventory item's orderId (a.k.a Supplier Unit ID) will be used to identify the correct Supplier where the Distribution Center needs to be added.
  • This field is only required when adding a new Distribution Center for a Supplier.
  • If this field is not populated, and a new Distribution Center is being added, the vendorDistributionCenterID value will be copied and used as the "Name" for the new Distribution Center.
minimumOrder
number <= 999999999999.999 characters

This field allows you to specify the Supplier Unit ID's minimum order quantity (i.e., the quantity of the Supplier Unit ID (SUID) that must be ordered from the supplier at any given time).

Note the following:

  • The Minimum Order Quantity entered must be a positive number. If negative, the request will fail.
  • The Minimum Order Quantity entered must not be longer than the maximum length of 999999999999.999. If longer, then the request will fail.
  • This field is not required, but if no Minimum Order Quantity is specified, and default value of 0.000 will be used.
  • Only if minimumOrder is included in the request will the corresponding field be updated for the inventory item. Meaning, other aspects about the item's Supplier Unit ID can be updated or specified and the minimumOrder can remain unchanged, if desired.
suggestedMultiple
integer <= 999999999 characters

This field allows you to specify the Supplier Unit ID's Case Pack Multiple, which is the multiple that the SUID must be ordered by. For example, if an item's suggestedMultiple is set to '2', and it was recommended to order 7.25 of the SUID, then '8' would be ordered for the SUID, as 8 is a multiple of 2.

Note the following:

  • The Case Pack Multiple entered must be a positive integer. If negative, the request will fail.
  • The Case Pack Multiple entered must not be longer than the maximum length of 999999999. If longer, then the request will fail.
  • This field is not required, but if no Case Pack Multiple is specified, and default value of 0 will be used.
  • Only if suggestedMultiple is included in the request will the corresponding field be updated for the inventory item. Meaning, other aspects about the item's Supplier Unit ID can be updated or specified and the suggestedMultiple can remain unchanged, if desired.

Request samples

Content type
[
  • {
    }
]

Batch Permanent Price and Cost

Overview

  • The /batch/PermanentPriceCost endpoint allows you to create and commit permanent Price & Cost Change Worksheets.

  • Worksheets created with this endpoint do not include an end date (thus the "permanent" context), but changes can be overridden by future worksheets.

  • These worksheet are applied at the Zone level, so committed price changes will be reflected in every store included in the selected pricing zone.

Endpoint + Worksheet Behavior

  • When using the /batch/PermanentPriceCost endpoint, each row in the batch represents an item and includes fields that determine which worksheet the item should be placed on. If any of the fields listed below differ between rows, separate worksheets will be created. If you want to ensure all rows (i.e., items) are placed into the same worksheet, make sure these fields match across all rows:

    • name

    • zoneName

    • startDate

    • commitAtStore

    • worksheetTypeProfileName (available with CATAPULT 5.6.121 and newer)

  • Beginning with CATAPULT 5.6.107, should the /batch/PermanentPriceCost endpoint initially fail to commit a worksheet, it will reattempt the commit until successful (up to 10 times). After 10 failed attempts, the entry for the failed worksheet/batch will display an 'E' (for error) in /batch/importMessages/, at which point you will need to commit the worksheet through CATAPULT Web Office.

Batch Process Updates and Message Log

  • Batch processing status and log can be viewed by calling the /batch/importMessages endpoint.
query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

batch
required
integer
Example: batch=123

A unique identifier used to define related objects in a batch operation.

appendExistingWorksheets
boolean
Example: appendExistingWorksheets=0

Available with CATAPULT 5.8.165+, this query parameter supports values of 0 and 1.

  • 0: Causes Passport API to create a new permanent Price & Cost Change worksheet using the data included in the request. Note that this may result in duplicate worksheets if the Worksheet Name, Zone, Priority and Start Date are the same as an existing worksheet with a Pending status.
  • 1: Causes Passport API to add the data included in request to any existing permanent Price & Cost Change worksheet that exactly matches the specified Worksheet Name, Zone, Priority, and Start Date. This behavior is true regardless of where the worksheet was created. If no existing worksheet is found, Passport API will create a new worksheet with the dataset.
  • This parameter is not required. If no value is specified, Passport API will default to using 1 (i.e., Passport API will attempt to add data to an existing worksheet).

IMPORTANT

  • Any value other than 0 or 1 for this parameter (e.g., 2) will result in Passport API using 0 for this parameter (i.e., a new permanent Price & Cost Change worksheet will be created). The default value of 1 will NOT be used in these scenarios.
  • If this parameter is set to 1, should two or more worksheets have the exact same details (i.e., Worksheet Name, Zone, Priority, Start Date), Passport API will update the most recently created worksheet; all matching worksheets will not be updated.
autoCommit
boolean
Example: autoCommit=1

Available with CATAPULT 5.8.165+, this query parameter supports values of 0 and 1.

  • 0: Prevents Passport API from committing any pre-existing Pending worksheets (that were updated as a result of the /batch/PermanentPriceCost endpoint) or any newly created worksheets.
  • 1: Causes Passport API to automatically commit any permanent Price & Cost Change worksheet created within the batch.
    • Setting this parameter to 1 will cause Passport API to only commit worksheets created within the associated batch. Any existing permanent Price & Cost change worksheets with a Pending status and matching details (i.e., Worksheet Name, Zone, Priority, Start Date) will NOT be committed.
  • This parameter is not required. If no value is specified, Passport API will default to using 1 (i.e., Passport API will automatically commit any worksheet created within the batch).

IMPORTANT

  • If worksheets are NOT committed by Passport API, the worksheets must be committed within CATAPULT Web Office for the associated permanent price and cost changes to take effect.
  • Any value other than 0 or 1 for this parameter (e.g., 2) will result in Passport API using 0 for this parameter (i.e., a new Price & Cost Change worksheet will be created). The default value of 1 will NOT be used in these scenarios.
Request Body schema:

List of Permanent Prices and Costs to update

Array
name
string <= 40 characters

See also: Name (P&CC).

zoneName
required
string <= 30 characters

See also: Zones (P&CC).

startDate
required
string <date-time>

The date and time on which the price and/or cost changes for the items on the permanent Price & Cost Change worksheet take effect. The format of this field is: yyyy-mm-dd hh:mm:ss

memo
string <= 254 characters

The optional memo text entered for the permanent Price & Cost Change worksheet.

commitAtStore
boolean

List of store numbers separated by colon(:). If not supplied then it will default to all stores in the Pricing Zone.
See also: Commit at Store (P&CC).

itemType
string
Enum: "I" "F" "G"

I - Item (Default)
F - Family Line
G - Item Group

itemId
required
string <= 30 characters

Identifier for itemType parameter: Use itemId for Items and specify the name for Family Lines and Item Groups. maxLength for Family Line names is 254, for Item IDs and Item Group names the maxLength is 30.
See also: Item ID, Family Lines, Item Groups.

cost
string <decimal(16,4)>

See also: New Cost.

price1
string <decimal(16,4)>

See also: Adjust Price.

promptForPrice1
boolean
discount1
string <= 30 characters

Define the PL1 auto discount to use.
Use default to instruct the worksheet to use any auto discount presently attached on the inventory record.
Specify the name of an auto discount to include it on worksheet for this line item.
Omit this parameter to exclude PL1 auto discounts for this line item.
See also: Auto Discount (P&CC).

qtyOnly1
boolean
idealMargin1
string <decimal(16,4)>
noManualDiscount1
boolean
divider1
integer [ 1 .. 99 ]
priceLabel1
string <= 30 characters

Available with CATAPULT 5.7.144 and Newer

  • Allows you to specify the desired Price Label Type that should be assigned to an item on the permanent Price & Cost Change worksheet for Price Level 1. This specification is done by entering the name of the Price Label Type, exactly as it appears in CATAPULT Web Office.
  • If the entered name of a Price Label Type doesn't match a record in CATAPULT Web Office, or the Price Label Type does not exist yet, only the associated item(s) - not the entire batch - will fail to update/insert into the permanent Price & Cost Change worksheet. In addition, the message "RAISERROR executed: Price Label 1 not found" will display for the item in batch/importMessages.
  • The specified Price Label Type can only be permanet; i.e., the Permanent box must be checked in CATAPULT Web Office for that Price Label Type. If a temporary Price Label Type is specified for an item, that item will fail to update/insert into the permanent Price & Cost Change worksheet. In addition, the message "RAISERROR executed: One or more PriceLabels are temporary when permanent price labels are required" will display in batch/importMessages.
price2
string <decimal(16,4)>
promptForPrice2
boolean
discount2
string <= 30 characters

Define the PL2 auto discount to use.
Use default to instruct the worksheet to use any auto discount presently attached on the inventory record.
Specify the name of an auto discount to include it on worksheet for this line item.
Omit this parameter to exclude PL2 auto discounts for this line item.

qtyOnly2
boolean
idealMargin2
string <decimal(16,4)>
noManualDiscount2
boolean
divider2
integer [ 1 .. 99 ]
priceLabel2
string <= 30 characters

Available with CATAPULT 5.7.144 and Newer

  • Allows you to specify the desired Price Label Type that should be assigned to an item on the permanent Price & Cost Change worksheet for Price Level 2. This specification is done by entering the name of the Price Label Type, exactly as it appears in CATAPULT Web Office.
  • If the entered name of a Price Label Type doesn't match a record in CATAPULT Web Office, or the Price Label Type does not exist yet, only the associated item(s) - not the entire batch - will fail to update/insert into the permanent Price & Cost Change worksheet. In addition, the message "RAISERROR executed: Price Label 2 not found" will display for the item in batch/importMessages.
  • The specified Price Label Type can only be permanent; i.e., the Permanent box must be checked in CATAPULT Web Office for that Price Label Type. If a temporary Price Label Type is specified for an item, that item will fail to update/insert into the permanent Price & Cost Change worksheet. In addition, the message "RAISERROR executed: One or more PriceLabels are temporary when permanent price labels are required" will display in batch/importMessages.
price3
string <decimal(16,4)>
promptForPrice3
boolean
discount3
string <= 30 characters

Define the PL3 auto discount to use.
Use default to instruct the worksheet to use any auto discount presently attached on the inventory record.
Specify the name of an auto discount to include it on worksheet for this line item.
Omit this parameter to exclude PL3 auto discounts for this line item.

qtyOnly3
boolean
idealMargin3
string <decimal(16,4)>
noManualDiscount3
boolean
divider3
integer [ 1 .. 99 ]
priceLabel3
string <= 30 characters

Available with CATAPULT 5.7.144 and Newer

  • Allows you to specify the desired Price Label Type that should be assigned to an item on the permanent Price & Cost Change worksheet for Price Level 3. This specification is done by entering the name of the Price Label Type, exactly as it appears in CATAPULT Web Office.
  • If the entered name of a Price Label Type doesn't match a record in CATAPULT Web Office, or the Price Label Type does not exist yet, only the associated item(s) - not the entire batch - will fail to update/insert into the permanent Price & Cost Change worksheet. In addition, the message "RAISERROR executed: Price Label 3 not found" will display for the item in batch/importMessages.
  • The specified Price Label Type can only be permanent; i.e., the Permanent box must be checked in CATAPULT Web Office for that Price Label Type. If a temporary Price Label Type is specified for an item, that item will fail to update/insert into the permanent Price & Cost Change worksheet. In addition, the message "RAISERROR executed: One or more PriceLabels are temporary when permanent price labels are required" will display in batch/importMessages.
price4
string <decimal(16,4)>
promptForPrice4
boolean
discount4
string <= 30 characters

Define the PL4 auto discount to use.
Use default to instruct the worksheet to use any auto discount presently attached on the inventory record.
Specify the name of an auto discount to include it on worksheet for this line item.
Omit this parameter to exclude PL4 auto discounts for this line item.

qtyOnly4
boolean
idealMargin4
string <decimal(16,4)>
noManualDiscount4
boolean
divider4
integer [ 1 .. 99 ]
priceLabel4
string <= 30 characters

Available with CATAPULT 5.7.144 and Newer

  • Allows you to specify the desired Price Label Type that should be assigned to an item on the permanent Price & Cost Change worksheet for Price Level 4. This specification is done by entering the name of the Price Label Type, exactly as it appears in CATAPULT Web Office.
  • If the entered name of a Price Label Type doesn't match a record in CATAPULT Web Office, or the Price Label Type does not exist yet, only the associated item(s) - not the entire batch - will fail to update/insert into the permanent Price & Cost Change worksheet. In addition, the message "RAISERROR executed: Price Label 4 not found" will display for the item in batch/importMessages.
  • The specified Price Label Type can only be permanent; i.e., the Permanent box must be checked in CATAPULT Web Office for that Price Label Type. If a temporary Price Label Type is specified for an item, that item will fail to update/insert into the permanent Price & Cost Change worksheet. In addition, the message "RAISERROR executed: One or more PriceLabels are temporary when permanent price labels are required" will display in batch/importMessages.
worksheetTypeProfileName
string <= 30 characters

Available with CATAPULT 5.6.121 and newer.
Allows you to define what Worksheet Type Profile is assigned to the permanent Price & Cost Change worksheet. This assignment relies on the name that you enter for the Worksheet Type Profile in the request row. With this in mind, there are three scenarios possible when assigning a Worksheet Type Profile:

  1. No Worksheet Type Profile Name is Specified - If no Worksheet Type Profile is specified, the Default Worksheet Type Profile will be assigned to the worksheet. This essentially specifies that the worksheet is not assigned a type.
  2. Worksheet Type Profile Name is Specified, but Name Doesn't Match - If a Worksheet Type Profile is specified, but the entered name of the profile doesn't match any prexisting profile, CATAPULT will create a new Worksheet Type Profile - with the entered Name - and assign it to the worksheet. Please note, this new profile will have the 'Prevent ordering during active worksheet period' setting disabled, and will not have any store-specific settings in place.
  3. Worksheet Type Profile Name is Specified, and Name Matches - If a Worksheet Type Profile is specified, and the entered name of the profile matches an existing profile, the existing/specified Worksheet Type Profile will be assigned to the worksheet. Any and all settings associated with the Worksheet Type Profile will also be assigned and apply to the worksheet.

Request samples

Content type
[
  • {
    }
]

Batch Price and Cost

Overview

  • The /batch/PriceCost endpoint allows you to create and commit Price & Cost Change Worksheets.

  • These worksheets are applied at the Zone level through the required zoneName parameter, but particular stores within a zone can be specified to narrow the recipients of committed changes.

  • Both the startDate and endDate parameters are required to specify when the changes made by the worksheet will take effect and end.

Endpoint + Worksheet Behavior

  • When using the /batch/PriceCost endpoint, each row in the batch represents an item and includes fields that determine which worksheet the item should be placed on. If any of the fields listed below differ between rows, separate worksheets will be created. If you want to ensure all rows (i.e., items) are placed into the same worksheet, make sure these fields match across all rows:

    • name

    • zoneName

    • startDate

    • endDate

    • commitAtStore

    • worksheetTypeProfileName (available with CATAPULT 5.6.121 and newer)

  • Beginning with CATAPULT 5.6.107, should the /batch/PriceCost endpoint initially fail to commit a worksheet, it will reattempt the commit until successful (up to 10 times). After 10 failed attempts, the entry for the failed batch/worksheet will display an 'E' (for error) in /batch/importMessages, at which point you will need to commit the worksheet through CATAPULT Web Office.

Batch Process Updates and Message Log

  • Batch processing status and log can be viewed by calling the /batch/importMessages endpoint.
query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

batch
required
integer
Example: batch=123

A unique identifier used to define related objects in a batch operation.

appendExistingWorksheets
boolean
Example: appendExistingWorksheets=0

Available with CATAPULT 5.8.165+, this query parameter supports values of 0 and 1.

  • 0: Causes Passport API to create a new Price & Cost Change worksheet using the data included in the request. Note that this may result in duplicate worksheets if the Worksheet Name, Zone, Priority and Start/End Dates are the same as an existing worksheet with a Pending status.
  • 1: Causes Passport API to add the data included in request to any existing Price & Cost Change worksheet that exactly matches the specified Worksheet Name, Zone, Priority, and Start/End Dates. This behavior is true regardless of where the worksheet was created. If no existing worksheet is found, Passport API will create a new worksheet with the dataset.
  • This parameter is not required. If no value is specified, Passport API will default to using 1 (i.e., Passport API will attempt to add data to an existing worksheet).

IMPORTANT

  • Any value other than 0 or 1 for this parameter (e.g., 2) will result in Passport API using 0 for this parameter (i.e., a new Price & Cost Change worksheet will be created). The default value of 1 will NOT be used in these scenarios.
  • If this parameter is set to 1, should two or more worksheets have the exact same details (i.e., Worksheet Name, Zone, Priority, Start/End Dates), Passport API will update the most recently created worksheet; all matching worksheets will not be updated.
autoCommit
boolean
Example: autoCommit=1

Available with CATAPULT 5.8.165+, this query parameter supports values of 0 and 1.

  • 0: Prevents Passport API from committing any pre-existing Pending worksheets (that were updated as a result of the /batch/PriceCost endpoint) or any newly created worksheets.
  • 1: Causes Passport API to automatically commit any Price & Cost Change worksheet created within the batch.
    • Setting this parameter to 1 will cause Passport API to only commit worksheets created within the associated batch. Any existing Price & Cost change worksheets with a Pending status and matching details (i.e., Worksheet Name, Zone, Priority, Start/End Dates) will NOT be committed.
  • This parameter is not required. If no value is specified, Passport API will default to using 1 (i.e., Passport API will automatically commit any worksheet created within the batch).

IMPORTANT

  • If worksheets are NOT committed by Passport API, the worksheets must be committed within CATAPULT Web Office for the associated price and cost changes to take effect.
  • Any value other than 0 or 1 for this parameter (e.g., 2) will result in Passport API using 0 for this parameter (i.e., a new Price & Cost Change worksheet will be created). The default value of 1 will NOT be used in these scenarios.
Request Body schema:

List of Prices and Costs to update

Array
name
string <= 40 characters

See also: Name (P&CC).

zoneName
required
string <= 30 characters

See also: Zones (P&CC).

stores
string <= 10 characters

List of store numbers separated by colon(:).
If not supplied then it will default to all stores in the Pricing Zone. See also: Store ID.

startDate
required
string <date-time>

Allows you to specify the date and time that the temporary changes included on the Price and Cost Change worksheet are to take effect. The format of this field is: yyyy-mm-dd hh:mm:ss

endDate
required
string <date-time>

Allows you to specify the date and time that the temporary changes included on the Price and Cost Change worksheet are to end. Omitting this field will not result in a permanent Price & Cost Change worksheet; this field must be populated to determine when the worksheet's changes will end. The format of this field is: yyyy-mm-dd hh:mm:ss

priority
integer

Worksheet priority if multiple start at the same time.
1 - High
2 - Medium
3 - Low
Default is 3. See also: Priority (P&CC).

commitAtStore
boolean

Defaults to 0 when not specified. Enter 1 and the worksheet will be created at the applicable stores but require manual input to activate and commit. See also: Commit at Store (P&CC).

itemType
string
Enum: "I" "F" "G"

I - Item (Default)
F - Family Line
G - Item Group

itemId
required
string <= 30 characters

Identifier for itemType parameter: Use itemId for Items and specify the name for Family Lines and Item Groups. maxLength for Family Line names is 254, for Item IDs and Item Group names the maxLength is 30.
See also: Item ID, Family Lines, Item Groups.

cost
string <decimal(16,4)>

See also: New Cost.

price1
string <decimal(16,4)>

See also: Adjust Price.

promptForPrice1
boolean
discount1
string <= 30 characters

Define the PL1 auto discount to use.
Use default to instruct the worksheet to use any auto discount presently attached on the inventory record.
Specify the name of an auto discount to include it on worksheet for this line item.
Omit this parameter to exclude PL1 auto discounts for this line item.
See also: Auto Discount (P&CC).

qtyOnly1
boolean
idealMargin1
string <decimal(16,4)>
noManualDiscount1
boolean
divider1
integer [ 1 .. 99 ]
priceLabel1
string <= 30 characters

Available with CATAPULT 5.7.144 and Newer

  • Allows you to specify the desired Price Label Type that should be assigned to an item on the temporary Price & Cost Change worksheet for Price Level 1. This specification is done by entering the name of the Price Label Type, exactly as it appears in CATAPULT Web Office.
  • If the entered name of a Price Label Type doesn't match a record in CATAPULT Web Office, or the Price Label Type does not exist yet, only the associated item(s) - not the entire batch - will fail to update/insert into the temporary Price & Cost Change worksheet. In addition, the message "RAISERROR executed: Price Label 1 not found" will display for the item in batch/importMessages.
  • The specified Price Label Type can only be temporary; i.e., the Permanent box must not be checked in CATAPULT Web Office for that Price Label Type. If a "Permanent" Price Label Type is specified for an item, that item will fail to update/insert into the temporary Price & Cost Change worksheet. In addition, the message "RAISERROR executed: One or more PriceLabels are permanent when temporary price labels are required" will display in batch/importMessages.
price2
string <decimal(16,4)>
promptForPrice2
boolean
discount2
string <= 30 characters

Define the PL2 auto discount to use.
Use default to instruct the worksheet to use any auto discount presently attached on the inventory record.
Specify the name of an auto discount to include it on worksheet for this line item.
Omit this parameter to exclude PL2 auto discounts for this line item.

qtyOnly2
boolean
idealMargin2
string <decimal(16,4)>
noManualDiscount2
boolean
divider2
integer [ 1 .. 99 ]
priceLabel2
string <= 30 characters

Available with CATAPULT 5.7.144 and Newer

  • Allows you to specify the desired Price Label Type that should be assigned to an item on the temporary Price & Cost Change worksheet for Price Level 2. This specification is done by entering the name of the Price Label Type, exactly as it appears in CATAPULT Web Office.
  • If the entered name of a Price Label Type doesn't match a record in CATAPULT Web Office, or the Price Label Type does not exist yet, only the associated item(s) - not the entire batch - will fail to update/insert into the temporary Price & Cost Change worksheet. In addition, the message "RAISERROR executed: Price Label 2 not found" will display for the item in batch/importMessages.
  • The specified Price Label Type can only be temporary; i.e., the Permanent box must not be checked in CATAPULT Web Office for that Price Label Type. If a "Permanent" Price Label Type is specified for an item, that item will fail to update/insert into the temporary Price & Cost Change worksheet. In addition, the message "RAISERROR executed: One or more PriceLabels are permanent when temporary price labels are required" will display in batch/importMessages.
price3
string <decimal(16,4)>
promptForPrice3
boolean
discount3
string <= 30 characters

Define the PL3 auto discount to use.
Use default to instruct the worksheet to use any auto discount presently attached on the inventory record.
Specify the name of an auto discount to include it on worksheet for this line item.
Omit this parameter to exclude PL3 auto discounts for this line item.

qtyOnly3
boolean
idealMargin3
string <decimal(16,4)>
noManualDiscount3
boolean
divider3
integer [ 1 .. 99 ]
priceLabel3
string <= 30 characters

Available with CATAPULT 5.7.144 and Newer

  • Allows you to specify the desired Price Label Type that should be assigned to an item on the temporary Price & Cost Change worksheet for Price Level 3. This specification is done by entering the name of the Price Label Type, exactly as it appears in CATAPULT Web Office.
  • If the entered name of a Price Label Type doesn't match a record in CATAPULT Web Office, or the Price Label Type does not exist yet, only the associated item(s) - not the entire batch - will fail to update/insert into the temporary Price & Cost Change worksheet. In addition, the message "RAISERROR executed: Price Label 3 not found" will display for the item in batch/importMessages.
  • The specified Price Label Type can only be temporary; i.e., the Permanent box must not be checked in CATAPULT Web Office for that Price Label Type. If a "Permanent" Price Label Type is specified for an item, that item will fail to update/insert into the temporary Price & Cost Change worksheet. In addition, the message "RAISERROR executed: One or more PriceLabels are permanent when temporary price labels are required" will display in batch/importMessages.
price4
string <decimal(16,4)>
promptForPrice4
boolean
discount4
string <= 30 characters

Define the PL4 auto discount to use.
Use default to instruct the worksheet to use any auto discount presently attached on the inventory record.
Specify the name of an auto discount to include it on worksheet for this line item.
Omit this parameter to exclude PL4 auto discounts for this line item.

qtyOnly4
boolean
idealMargin4
string <decimal(16,4)>
noManualDiscount4
boolean
divider4
integer [ 1 .. 99 ]
priceLabel4
string <= 30 characters

Available with CATAPULT 5.7.144 and Newer

  • Allows you to specify the desired Price Label Type that should be assigned to an item on the temporary Price & Cost Change worksheet for Price Level 4. This specification is done by entering the name of the Price Label Type, exactly as it appears in CATAPULT Web Office.
  • If the entered name of a Price Label Type doesn't match a record in CATAPULT Web Office, or the Price Label Type does not exist yet, only the associated item(s) - not the entire batch - will fail to update/insert into the temporary Price & Cost Change worksheet. In addition, the message "RAISERROR executed: Price Label 4 not found" will display for the item in batch/importMessages.
  • The specified Price Label Type can only be temporary; i.e., the Permanent box must not be checked in CATAPULT Web Office for that Price Label Type. If a "Permanent" Price Label Type is specified for an item, that item will fail to update/insert into the temporary Price & Cost Change worksheet. In addition, the message "RAISERROR executed: One or more PriceLabels are permanent when temporary price labels are required" will display in batch/importMessages.
worksheetTypeProfileName
string <= 30 characters

Available with CATAPULT 5.6.121 and newer. Allows you to define what Worksheet Type Profile is assigned to the temporary Price & Cost Change worksheet. This assignment relies on the name that you enter for the Worksheet Type Profile in the request row. With this in mind, there are three scenarios possible when assigning a Worksheet Type Profile:

  1. No Worksheet Type Profile Name is Specified - If no Worksheet Type Profile is specified, the Default Worksheet Type Profile will be assigned to the worksheet. This essentially specifies that the worksheet is not assigned a type.
  2. Worksheet Type Profile Name is Specified, but Name Doesn't Match - If a Worksheet Type Profile is specified, but the entered name of the profile doesn't match any prexisting profile, CATAPULT will create a new Worksheet Type Profile - with the entered Name - and assign it to the worksheet. Please note, this new profile will have the 'Prevent ordering during active worksheet period' setting disabled, and will not have any store-specific settings in place.
  3. Worksheet Type Profile Name is Specified, and Name Matches - If a Worksheet Type Profile is specified, and the entered name of the profile matches an existing profile, the existing/specified Worksheet Type Profile will be assigned to the worksheet. Any and all settings associated with the Worksheet Type Profile will also be assigned and apply to the worksheet.

Request samples

Content type
[
  • {
    }
]

Batch Inventory Labels

  • The inventoryLabel endpoint allows for the creation and posting of Inventory Label Worksheets.
  • Inventory Label worksheets can be used to trigger the bulk output of label types associated with the provided Item IDs: particularly Shelf Tabs, Labels, and/or Signs.
  • Labels can be printed from both uncommitted and committed worksheets.

See also: Inventory Label (IL) Worksheet, Label Catalog.

Batch processing status and log can be viewed by calling the /batch/importMessages endpoint.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

batch
required
integer
Example: batch=123

A unique identifier used to define related objects in a batch operation.

Request Body schema:

List of Inventory Labels to Update

Array
name
required
string <= 40 characters
storeNumber
required
string <= 10 characters

See also: Store ID.

itemId
required
string <= 14 characters

See also: Add Items (IL).

itemTagQuantity
string <= 3 characters

See also: Type (IL).

shelfLabelQuantity
string <= 1 characters

See also: Type (IL).

signsQuantity
string <= 1 characters

See also: Type (IL).

Request samples

Content type
[
  • {
    }
]

Batch Store Promotions

Overview

  • This endpoint allows you to create new Dynamic Store Promotions.
  • This endpoint cannot be used to update existing Dynamic Store Promotions, due to the logic and requirements surrounding updates. Therefore, if the "Update" (U) action is used with this endpoint, it will only be to insert new records.
  • If desired, use the "Batch Item Promotions" (/batch/itemPromotions) endpoint to create new Dynamic Item Promotions.

Notes

  • This endpoint can only be used for the Headquarters store (i.e., the Account ID of the Headquarters store must be used). If it is used for a Remote Store, a RAISERROR 50001 will return.
  • Store Coupons, Exclude Groups, and Customers are not created by this endpoint and therefore must be created in CATAPULT Web Office before they can be used in the request parameters.
  • Use the DISCONTINUE action rather than the REMOVE action whenever possible.

Batch Process Updates and Message Log

  • Batch processing status and log can be viewed by calling the /batch/importMessages endpoint.
query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

batch
required
integer
Example: batch=123

A unique identifier used to define related objects in a batch operation.

Request Body schema:

List of Store Promotions to Update

Array
action
required
string
Enum: "U" "R" "D"

Type of Action to be Performed:

  • 'U' - Insert or Update
  • 'R' - Remove
  • 'D' - Discontinue
name
string <= 128 characters

See also: Name.

zoneName
string <= 30 characters

See also: Pricing Zone.

storeGroupName
string <= 30 characters

See also: Store Groups.

receiptAlias
required
string <= 32 characters

See also: Receipt Alias.

minPurchase
string <decimal(16,4)>
requireMin
boolean
maxPerTrans
integer
maxTransactionDiscount
string <decimal(16,4)>
maxDiscountPerPromo
boolean
scheduleName
string <= 30 characters

Must provide name of an existing schedule in Web Office. Providing a Schedule Name means StartDate and EndDate will not be used. See also: Promotion Schedule.

startDate
string <date>

Format yyyy-mm-dd. See also: Promotion Start Day.

endDate
string <date>

Format yyyy-mm-dd. See also: Promotion End Day.

startTime
string <time>

Start Time for each day of schedule. 24-hour format (hh:mm:ss) required, defaults to 00:00:00. See also: Promotion Start Time.

endTime
string <time>

End Time for each day of schedule. 24-hour format (hh:mm:ss) required, defaults to 00:00:00. See also: Promotion End Time.

type
required
integer

2 - Amount
3 - Percent
See also: Promotion Type.

value
required
string <decimal(16,4)>

Meaning of this value depends on type of promotion selected.

excludeGroup
string <= 30 characters
storeCoupon
string <= 30 characters

See also: Store Coupon.

customers
string <long varchar>
  • List of customer numbers separated by colon (:).
  • This field is only used if named Store Coupon is supplied.
  • Format and maxLength of individual CUS_AccountNum is char(16).

See also: Customer Groups.

deferrable
boolean

See also: Deferrable Usages.

usesPerPeriod
integer

See also: Uses per Period.

resetPeriod
integer

1 - Never
2 - Every X days
3 - Weekly
4 - Monthly
Defaults to 'Never'. See also: Reset Usages.

periodDow
integer

Required when resetPeriod = 3 (Weekly). Accepted values:
1 = Sunday
2 = Monday
3 = Tuesday
4 = Wednesday
5 = Thursday
6 = Friday
7 = Saturday \

periodDays
integer

Required when resetPeriod = 2 (Every X Days).

applyToPl1
boolean
applyToPl2
boolean
applyToPl3
boolean
applyToPl4
boolean

Request samples

Content type
[
  • {
    }
]

Batch Item Promotions

Overview

  • This endpoint allows you to create new Dynamic Item Promotions.
  • This endpoint cannot be used to update existing Dynamic Item Promotions, due to the logic and requirements surrounding updates. Therefore, if the "Update" (U) action is used with this endpoint, it will only be to insert new records.
  • If desired, use the "Batch Store Promotions" (/batch/storePromotions) endpoint to create new Dynamic Store Promotions.

Notes

  • This endpoint can only be used for the Headquarters store (i.e., the Account ID of the Headquarters store must be used). If it is used for a Remote Store, a RAISERROR 50001 will return.
  • Store Coupons, Exclude Groups, and Customers are not created by this endpoint and therefore must be created in CATAPULT Web Office before they can be used in the request parameters.
  • The Distribution Percentage (%) - if supplied - must calculate to a sum total of 100% or the process will fail.
  • Use the DISCONTINUE action rather than the REMOVE action whenever possible.

Batch Process Updates and Message Log

  • Batch processing status and log can be viewed by calling the /batch/importMessages endpoint.
query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

batch
required
integer
Example: batch=123

A unique identifier used to define related objects in a batch operation.

Request Body schema:

List of Item Promotions to Update

Array
action
required
string
Enum: "U" "R" "D"

Type of Action to be Performed:

  • 'U' - Insert or Update
  • 'R' - Remove
  • 'D' - Discontinue
name
string <= 128 characters

See also: Name).

zoneName
string <= 30 characters

See also: Pricing Zone.

storeGroupName
string <= null characters

See also: Store Groups.

receiptAlias
required
string <= 32 characters

See also: Receipt Alias.

minPurchase
string <decimal(16,4)>
requireMin
boolean
maxPerTrans
integer
maxTransactionDiscount
string <decimal(16,4)>
maxDiscountPerPromo
boolean
itemGroups
string <= 30 characters
  • List of Item Group names, their Distribution Percentage (%), and their Required Quantity are separated by a colon(:).
  • Distinct Item Groups (and their associated values) are separated by a pipe (|).
  • This field is required when request Action = U

See also: Item Groups.

scheduleName
string <= 30 characters

Must provide name of an existing schedule in WebOffice. Providing a Schedule Name means StartDate and EndDate will not be used. See also: Promotion Schedule.

startDate
required
string <date>

Format yyyy-mm-dd. See also: Promotion Start Day.

endDate
required
string <date>

Format yyyy-mm-dd. See also: Promotion End Day.

startTime
string <time>

Start Time for each day of schedule. 24-hour format (hh:mm:ss) required, defaults to 00:00:00. See also: Promotion Start Time.

endTime
string <time>

End Time for each day of schedule. 24-hour format (hh:mm:ss) required, defaults to 00:00:00. See also: Promotion End Time.

type
integer

1 - Price
2 - Amount
3 - Percent
See also: Promotion Type.

value
string <decimal(16,4)>

Meaning of this value depends on type of promotion selected.

excludeGroup
string <= 30 characters
storeCoupon
string <= 30 characters
customers
string <long varchar>

List of customer numbers separated by colon (:). This field is only used if named Store Coupon is supplied. See also: Customer Groups (Promo).

oneTimeUse
boolean
couponEntryType
integer
stackLevel
integer
applyToPl1
boolean
applyToPl2
boolean
applyToPl3
boolean
applyToPl4
boolean

Request samples

Content type
[
  • {
    }
]

Batch Conventional Item Groups

The Conventional Item Groups endpoint enables you to post changes to existing Item Groups and/or to create new ones. An Item Group includes all inventory records that contain the same itemGroupName. Note this process will replace rather than update, so if an existing itemGroupName is presently defined in the database it, along with any itemIds which are listed in that group, will be replaced by the value(s) supplied in the request.

See also: Item Group Profiles.

Batch processing status and log can be viewed by calling the /batch/importMessages endpoint.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

batch
required
integer
Example: batch=123

A unique identifier used to define related objects in a batch operation.

Request Body schema:

List of Conventional Item Groups to Update

Array
itemGroupName
required
string <= 30 characters
itemId
required
string <= 14 characters

See also: Item ID.

Request samples

Content type
[
  • {
    }
]

Batch Item Groups Store Level

The Item Groups Store Level endpoint functions similarly to the Conventional Item Group endpoint, but with the added Store Group filter. This allows you to post more refined changes to Item Groups so as to include or exclude certain stores. Note while it can create new Item Groups, it does not create new Store Groups: requests must therefore reference Store Groups that already exist in your database. Additionally, it will replace rather than update existing records, so if an itemGroupName is already defined in the database it will be replaced by the value(s) supplied in the request.

See also: Store Group Profiles.

Batch processing status and log can be viewed by calling the /batch/importMessages endpoint.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

batch
required
integer
Example: batch=123

A unique identifier used to define related objects in a batch operation.

Request Body schema:

List of Store Level Item Groups to Update

Array
itemGroupName
required
string <= 30 characters
itemId
required
string <= 14 characters

See also: Item ID.

storeGroupName
string <= 30 characters

If no Store Group is defined then the function defaults to all stores. See also: Name (Store Group).

Request samples

Content type
[
  • {
    }
]

Batch Customer Maintenance

The Customer Maintenance endpoint enables you to create and post changes to the customer records in your database. In general, this endpoint avails itself for updates related to general, demographic fields of a customer maintenance record. More precise updates, which are associated with individual sections of the customer maintenance record, can be found in the batch_addresses, batch_emailAddress, batch_phoneNumbers, and (to a lesser degree) batch_itemPromotions endpoints. Note that any Store Coupons included in the request must already exist in the database, as this procedure will not create new ones. It will, however, create/insert newly defined Prefixes and PowerField values into their respective tables, where present in the request.

See also: Customer Maintenance.

Batch processing status and log can be viewed by calling the /batch/importMessages endpoint.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

batch
required
integer
Example: batch=123

A unique identifier used to define related objects in a batch operation.

Request Body schema:

List of Customers to Update

Array
action
required
string
Enum: "U" "R"

Type of Action to be Performed:

  • 'U' - Insert or Update
  • 'R' - Remove
customerId
required
string <= 16 characters

See also: Customer ID.

prefix
string <= 30 characters

See also: Customer Prefix.

firstName
string <= 25 characters
middleName
string <= 25 characters
lastName
string <= 25 characters
suffix
string <= 30 characters

See also: Customer Suffix.

alias
string <= 25 characters

See also: Customer Alias.

pf1
string <= 30 characters
pf2
string <= 30 characters
pf3
string <= 30 characters
pf4
string <= 30 characters
pf5
string <= 30 characters
pf6
string <= 30 characters
pf7
string <= 30 characters
pf8
string <= 30 characters
title
string <= 25 characters

See also: Customer Title.

company
string <= 50 characters

See also: Customer Company.

memo
string <= 254 characters

See also: Memo (Customer).

birthDate
string <date> <= 30 characters
priceLevel
string
Enum: 1 2 3 4
optOutReceipt
boolean

See also: Receipt Opt-Out.

blockSuspendedSales
boolean
hideInLookup
boolean

See also: Hide in Lookup.

inactive
boolean
loyalty
boolean

See also: Loyalty (Customer).

loyaltyAccrualMultiplier
number <numeric(4,3)>

The loyalty multiplier for the default loyalty program for this customer

taxExempt
boolean

Defaults to 0. Set as 1 to mark this customer exempt from all taxes. See also: Tax Exempt.

storeCouponList
string <long varchar>

List of Store Coupon names separated by colon (:). Entered values will replace any current values listed on customer record.
Enter 'NONE' to remove all without replacement. Format and maxLength of individual storeCoupon names is char(30).
See also: Store Coupons / Customer Groups.

householdMainCustomerId
string <= 16 characters

Customer ID for the customer's Head of Household. See also: Head of Household.

householdRelation
string <= 30 characters

Requires householdMainCustomerId be set. Enter text describing relationship to household. See also: Household Relationship.

householdCanRedeem
boolean

Requires householdMainCustomerId be set. Set to 1 to allow customer to redeem loyalty points from household. See also: Redeem Household Loyalty.

dependentList
string <long varchar>

List of customer dependents. Component field parameters of each individual dependent record are: type, name, birthdate (birthDate is optional). Distinct dependent records in the list are delimited by ascii code RS (30 or hex 1d). The component fields in each dependent record are delimited by ascii code GS (29 or hex 1e). Dependent types that do not exist in your database are created by the batch process.
Birth Date format: YYYY-MM-DD
Example: Spouse\x1eCameron\x1e1991-06-10\x1dPet\x1eFido\x1e2015-10-14
See also: Household Dependents.

Request samples

Content type
[
  • {
    }
]

Batch Addresses

Overview of the Batch Addresses Endpoint

  • This endpoint allows you to post mailing addresses updates for select records in the CATAPULT system. Specifically:

    • Customers
    • Employees
    • Stores
    • Suppliers

  • This endpoint can create new Address Descriptions on a supported record and will create new Address Descriptions ('labels', i.e. Business, Home, Warehouse, etc.) where they do not already exist. When entered in a row of the request body,the category corresponds to the type of maintenance record ultimately called by the entityId in the same row.

Example

  • A request is posted to update entityId '40000001234' in Category 'C' with a new email. This instructs the Address procedure that a Customer record (i.e., Category 'C') where customerId = entityId is to receive the new Address Description.

Notes

  • Beginning with CATAPULT 5.6.112+, this endpoint will only update addresses for records where the system detects there is a change (or a new address is being added). This prevents records from being unnecessarily updated with the same data each time the endpoint is used.

Batch Process Updates and Message Log

  • Batch processing status and log can be viewed by calling the /batch/importMessages endpoint.
query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

batch
required
integer
Example: batch=123

A unique identifier used to define related objects in a batch operation.

Request Body schema:

List of Addresses to be updated.

Array
action
required
string
Enum: "U" "R"

Type of Action to be Performed:

  • 'U' - Insert or Update
  • 'R' - Remove
category
required
string
Enum: "C" "E" "S" "V"

Category of the address:

  • 'C' - Customer Address
  • 'E' - Employee Address
  • 'S' - Store Address
  • 'V' - Vendor / Supplier Address
    See also: Address Profiles.
entityId
required
string <= 30 characters

Exact value of the entityId depends entirely on, and must correspond to, the selected category: it can conditionally be the customerId, employeeId, storeId, or supplierId.

description
required
string <= 30 characters

Name of the address description to use. See also: Address Description.

streetaddressline1
string <= 50 characters

See also: Address Line 01

streetaddressline2
string <= 50 characters

See also: Address Line 02.

city
string <= 20 characters

See also: City.

stateProvince
string <= 2 characters

Uses standard two-character postal abbreviations. See also: State/Province, USPS State Abbreviations.

country
string <= 2 characters

See also: Country. Country entries of more than 2 characters on an imported record will prevent that record from updating.

postalCode
string <= 15 characters

See also: Postal Code.

Request samples

Content type
[
  • {
    }
]

Batch Phone Numbers

The Phone Numbers endpoint allows you to manage the phone numbers associated with select records in the CATAPULT system. Specifically:

  • Customers
  • Employees
  • Suppliers
  • Stores

When entered in a row of the request body,the category corresponds to the type of maintenance record ultimately called by the entityId in the same row.

EXAMPLE: - A value of '1234567' is in the respective ID field for two unrelated customer and employee records in CATAPULT. We only want to post a new phone number on the customer record, so in the request body we would enter 'C' and '1234567' for the Category and entityId parameters, respectively. This directs the procedure to identify and update the customer (Category 'C') maintenance record whose customerId matches the provided entityId ('1234567').

Beginning with CATAPULT 5.6.111+, this endpoint will only update phone numbers for records where the system detects there is a change (or a new phone number is being added). This prevents records from being unnecessarily updated with the same data each time the endpoint is used.

See also: Phone Descriptions (Profiles).

Batch processing status and log can be viewed by calling the /batch/importMessages endpoint.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

batch
required
integer
Example: batch=123

A unique identifier used to define related objects in a batch operation.

Request Body schema:

List of Phone Numbers to Update

Array
action
required
string
Enum: "U" "R"

Type of Action to be Performed:

  • 'U' - Insert or Update
  • 'R' - Remove
category
required
string
Enum: "C" "E" "S" "V"

Category of the address:

  • 'C' - Customer Address
  • 'E' - Employee Address
  • 'S' - Store Address
  • 'V' - Vendor / Supplier Address
    See also: Phone Profiles.
entityId
required
string <= 30 characters

Exact value of the entityId depends entirely on, and must correspond to, the selected category: it can conditionally be the customerId, employeeId, storeId, or supplierId.

description
required
string <= 30 characters

Name of the Phone Number description to use. See also: Phone Description.

phoneNumber
required
string <= 14 characters

See also: Phone Number.

Request samples

Content type
[
  • {
    }
]

Batch Email Addresses

The Email Addresses endpoint allows you to manage the email addresses associated with select records in the CATAPULT system. Specifically:

  • Customers
  • Employees
  • Stores
  • Suppliers

This endpoint creates new email addresses on a supported record and will create new Email Descriptions ('labels', i.e. Home Email, Work Email, Vendor Support Email, etc.) where they do not already exist. When entered in a row of the request body,the category corresponds to the type of maintenance record ultimately called by the entityId in the same row.

EXAMPLE - A request is posted to update entityId '7101' in Category 'S' with a new email. This instructs the Email Address procedure that a Store record (i.e., Category 'S') where storeId = entityId is to receive the new email.

Beginning with CATAPULT 5.6.112+, this endpoint will only update email addresses for records where the system detects there is a change (or a new email address is being added). This prevents records from being unnecessarily updated with the same data each time the endpoint is used.

See also: Email Descriptions (Profiles).

Batch processing status and log can be viewed by calling the /batch/importMessages endpoint.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

batch
required
integer
Example: batch=123

A unique identifier used to define related objects in a batch operation.

Request Body schema:

List of Phone Numbers to Update

Array
action
required
string
Enum: "U" "R"

Type of Action to be Performed:

  • 'U' - Insert or Update
  • 'R' - Remove
category
required
string
Enum: "C" "E" "S" "V"

Category of the address:

  • 'C' - Customer Address
  • 'E' - Employee Address
  • 'S' - Store Address
  • 'V' - Vendor / Supplier Address
    See also: E-mail Profiles.
entityId
required
string <= 30 characters

Exact value of the entityId depends entirely on, and must correspond to, the selected category: it can conditionally be the customerId, employeeId, storeId, or supplierId.

description
required
string <= 30 characters

Enter the name of the Email Description to use. See also: E-mail Description.

address
required
string <= 254 characters

See also: E-mail Address.

marketingOptIn
boolean

Declares if this e-mail address, and subject of the associated maintenance record by extension, has agreed to receive marketing messages. Defaults to 0 (disabled) if left empty or not otherwise specified. See also: Marketing Opt-In.

Request samples

Content type
[
  • {
    }
]

Batch BIN Lookup Overrides

The BIN Lookup Overrides endpoint is one of two endpoints built to assist with offline transactions, in this case offline transactions tendered by card (credit or debit). BIN records are imported via request content then distributed to applicable POS terminals to enable automatic acceptance/rejection of tendered cards if transaction server (TS) goes offline and the the tendered card is referenced in the BIN Lookup. The process is enabled at the terminal-level and above by Advanced Setting in WebOffice:

KEY = com.ecrsoft.tserver.control.useImportedBinOverride
VALUE = true

This has been effectively replaced by the Secure Store & Forward (SaF) process, however the endpoint is still maintained as a secure and viable option. Note the BIN Lookup table is rebuilt in the database with every post of the endpoint procedure (data submitted in a request will overwrite/replace any existing list of BIN Lookup records), so individual entries can't be inserted or sequentally added to an existing list.

See also: Secure Store & Forward.

Batch processing status and log can be viewed by calling the /batch/importMessages endpoint.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

batch
required
integer
Example: batch=123

A unique identifier used to define related objects in a batch operation.

Request Body schema:

List of BIN Lookup Overrides to update.

Array
min
required
string <= 20 characters

Minimum BIN for range. Note any records within the min and max range are subject to normal type restrictions.

max
string <= 20 characters

Maximum BIN for range. Defaults to MIN value if not set.

type
integer
Enum: 0 1 2

0 - Not Allowed in SaF processing.
1 - Allowed in SaF Processing.
2 - Not allowed for online processing.
Anything else will be interpreted as 0

Request samples

Content type
[
  • {
    }
]

Batch Check File

The Check File endpoint is the second of two endpoints provided to assist with offline transactions, in this case transactions tendered by check. Check information is imported, encrypted, then distributed to applicable POS terminals to enable automatic acceptance/rejection of tendered checks if the terminal goes offline and the tendered check information is listed in the Check File table. The process is enabled at the terminal-level and above by Advanced Setting in WebOffice (the same Advanced Setting as BIN Lookup Override):

KEY = com.ecrsoft.tserver.control.useImportedBinOverride
VALUE = true

This has been effectively replaced by the Secure Store & Forward (SaF) process, however the endpoint is still maintained as a secure and viable option. Note the Check File table is rebuilt in the database with every post of the endpoint procedure (data submitted in a request will overwrite/replace any existing list of Check File records), so individual entries can't be inserted or sequentally added to an existing list.

See also: Secure Store & Forward.

Batch processing status and log can be viewed by calling the /batch/importMessages endpoint.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

batch
required
integer
Example: batch=123

A unique identifier used to define related objects in a batch operation.

Request Body schema:

List of Check File records to update.

Array
routingNumber
string

Routing number for checking account

accountNumber
required
string

Account number for checking account

Request samples

Content type
[
  • {
    }
]

Batch Remove Temporary Price Change

The Remove Temporary Price Change endpoint allows you to delete any non-permanent Price & Cost Change Worksheets, including those temporary worksheets created by the Batch Item Price Cost endpoint. Only entering the name will remove all applicable temporary worksheets with a matching name, regardless of dates. Specify the startDate and endDate parameters as needed to narrow the scope of the removal.

See also: Price & Cost Change (P&CC) Worksheets.

Batch processing status and log can be viewed by calling the /batch/importMessages endpoint.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

batch
required
integer
Example: batch=123

A unique identifier used to define related objects in a batch operation.

Request Body schema:

List of Temporary Price Changes to Remove

Array
name
required
string <= 40 characters

See also: Name (P&CC).

startDate
string <date-time>

The start date and time for the temporary Price & Cost Change worksheet that is to be deleted. The format of this field is: yyyy-mm-dd hh:mm:ss

endDate
string <date-time>

The end date and time for the temporary Price & Cost Change worksheet that is to be deleted. The format of this field is: yyyy-mm-dd hh:mm:ss

Request samples

Content type
[
  • {
    }
]

Batch Item Catalog Cost (Item)

The Catalog Cost (Item) endpoint is used to post supplier catalog cost updates to your inventory. It is one of two endpoints available for this task: here the Item ID (UPC scancode) is used to refine the operational scope and direct which inventory maintenance records receive the cost modifications. Each row in this batch operation represents one such inventory record to update.

It's recommended to use a unique batch number for each store and/or supplier: in this way you more easily reference importMessages for those store- or supplier-specific changes using the unique batch number.

See also: Importing Supplier Catalogs, View & Modify Catalog Cost.

Batch processing status and log can be viewed by calling the /batch/importMessages endpoint.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

batch
required
integer
Example: batch=123

A unique identifier used to define related objects in a batch operation.

Request Body schema:

List of item catalog costs to be updated.

Array
itemId
required
string <= 14 characters

The Item ID (UPC scancode) of the recipient inventory record. See also: Item ID.

storeId
required
string <= 10 characters

Store Number where the item is located and where the cost will update. See also: Store ID.

supplierId
required
string

The unique supplier identification code to verify recipient catalog. See also: Supplier ID.

catalogCost
required
string <decimal(16,4)>

See also: Catalog Cost.

Request samples

Content type
[
  • {
    }
]

Batch Item Catalog Cost (SUID)

The Catalog Cost (SUID) endpoint is used to post supplier catalog cost updates to your inventory. It is one of two endpoints available for this task: here the Supplier Unit ID (SUID) is used to refine the operational scope and direct which inventory maintenance records receive the cost modifications. Each row in this batch operation represents one such inventory record to update.

It's recommended to use a unique batch number for each store and/or supplier: in this way you can more easily reference importMessages for those store- or supplier-specific changes with the unique batch number.

See also: Importing Supplier Catalogs, View & Modify Catalog Cost.

Batch processing status and log can be viewed by calling the /batch/importMessages endpoint.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

batch
required
integer
Example: batch=123

A unique identifier used to define related objects in a batch operation.

Request Body schema:

List of item catalog costs to be updated.

Array
importType
required
string <= 1 characters
Enum: "P" "T"

P - Permanent
T - Temporary
Defines the type of cost change. See also: Supplier Import Formats.

storeId
required
string <= 10 characters

Specify the store where the catalog cost change will take effect. See also: Store ID.

supplierId
required
string

The unique supplier identification code to verify recipient SUID and catalog. See also: Supplier ID.

supplierUnitId
required
string

Supplier-specific item code to verify which inventory record receives the cost change. See also: Supplier Unit ID.

catalogCost
string <decimal(16,4)>

See also: Catalog Cost.

allowance
string <decimal(16,4)>
stacked
string <= 1 characters
Enum: "A" "R"

A - Additive
R - Replacement
Required when importType = T. See also: Stacked.

startDate
string <date>

Format yyyy-mm-dd.
Required when importType = T.
See also: Start Date (Supplier).

endDate
string <date>

Format yyyy-mm-dd.
Required when importType = T.
See also: End Date (Supplier).

Request samples

Content type
[
  • {
    }
]

Batch Item Shelf Information

Overview

  • This endpoint is used to post store-specific updates to the Shelf Information field on inventory records.
  • An item's Shelf Information is comprised of up to nine (9) digits and is in the format of XXX-XXX-XXX. Typically, the Shelf Information represents the item's Aisle-Shelf-Sequence position within a store.
  • An Item's Shelf Information is established over three (3) sequence parts, which are defined in the request body. With this, leading zeroes will be automatically included (where necessary) to ensure each item's Shelf Information is nine (9) digits.

EXAMPLE

A complete Shelf Information value of 001-002-003 would be entered in the request body using the three sequence parts as:

  • sequencePart1 = 001
  • sequencePart2 = 002
  • sequencePart3 = 003
  • Each row in this batch defines the Shelf Information for one inventory record. It's recommended to use a unique batch number for each store, as this allows you to easily adjust multiple inventory records for a single store location.

CAUTION!

  • The /batch/shelfInformation endpoint was designed to delete the Shelf Information value from inventory records not specified in a batch.
  • Performing an update to a individual or set of items at a specific store is not possible without deleting all previously specified Shelf Information values from other inventory records.

Batch Process Updates and Message Log

Batch processing status and log can be viewed by calling the /batch/importMessages endpoint.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

batch
required
integer
Example: batch=123

A unique identifier used to define related objects in a batch operation.

Request Body schema:
Array
storeId
required
string <= 10 characters

This field accepts the Store Number where the item - whose Shelf Information will be updated - is located.

itemId
required
string <= 14 characters

This field accepts a the Item ID (UPC scancode) of the inventory record which will be updated.

sequencePart1
required
string
  • The first three digits of the item's Shelf Information.
  • Integers only.
sequencePart2
required
string
  • The second three digits of the item's Shelf Information.
  • Integers only.
sequencePart3
required
string
  • The final three digits of the item's Shelf Information.
  • Integers only.

Request samples

Content type
[
  • {
    }
]

Batch Import Messages

The Import Messages endpoint is provided to for logging purposes. Every individual action taken by a batch loading operation, down to the particular line item event, is recorded here (one action/event per row). Use it to retrieve the message log for any previously executed 'batch' operation. Response metrics include, but are not limited to, the date (message_time), type (information or error), and message content (message_text). Batch number (batchId) is required for the request parameters.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active Employee in CATAPULT Web Office. Required unless using the X-ECRS-APIKEY header.

batch
required
integer
Example: batch=123

A unique identifier used to define related objects in a batch operation.

Responses

Response Schema:
Array
messageTime
string <datetime>

The time at which the message was generated.

batchType
string

The type of batch for which this message was generated.

messageType
string
Enum: "I" "E" "W"

The type of message

  • I - Informational Message: These messages are used to indicate that a "success" or "processed" event occurred.
  • E - Error Message: These messages are used to indicate that a record failed to process. In these events, why the error occurred can be viewed in the detail line of the response.
  • W - Warning Message: These messages are used to indicate a part of the record is failing, but there is enough data to proceed with adding or updating the record.
messageText
string

The textual message associated with the import batch.

detail
string

Available with CATAPULT 5.7.143 and newer, if a failure condition is encountered, this field provides details on why the record(s) failed.

Request samples 

curl --request GET \
  --url 'https://accountid.catapultweboffice.com/api/batch/importMessages?apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0&batch=123'

Response samples

Content type
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]