logo
Documentation Powered by ReDoc

Catapult Passport API Suite

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.

Authentication

Employee API Key in Header

In order to utilize any passport API methods, an API Key needs to be assigned to an Employee through Web Office. API Keys provide access to CATAPULT API programs, and allow employees to move data in and out of CATAPULT. Select +Create New and Web Office will automatically create a new API Key for this Employee Record.

Warning: Because API Keys do not replicate between stores, additional API Keys must be manually added on Employee maintenance records at Remote Stores. Doing so is optional, but necessary if you wish to enable authentication for select endpoints to be called from the Remote Store Web Office URI.

Security Scheme Type API Key
Header parameter name: X-ECRS-APIKEY

Employee API Key in Query

For backwards compatibility many Passport API methods continue to allow the API key to be included within the query string as "?apiKey=ABCDE". However, using this method of providing the API key is discouraged. While query parameters are secured during transport, it is not uncommon for clients, servers, or some routers to log query parameters. This can result in unintentional disclosure of the API key.

As an alternative, include the API key in the X-ECRS-APIKEY request header whenever possible.

Security Scheme Type API Key
Query parameter name: apiKey

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 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.

CSV Format 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 neccessary formatting criteria:

  • The CSV file must always start with a header row that names each column.
  • Each column is delimited by a comma ,.
  • Each row is delimited by 1 or more carriage return and/or newline characters.
  • 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 single-quote character is encountered.
  • Single-quotes within an quoted column 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 acccept:

  • 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 decimial-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.

Transaction Journal

The Transaction Journal endpoint enables you to obtain all available T-Log details and reporting data for a range of transaction upload times. Use GET to retrieve.

When a startTime and/or endTime are entered in the request parameters, the TransactionJournal query uses the timestamp from the TRN_uploadTime field to determine if a transaction should be included in the response. This is an important distinction as the TRN_uploadTime defines if, and when, a transaction record is inserted in the HQ T-Log. As such, transactions with a TRN_uploadTime timestamp after the startTime, and/or before the endTime, will be returned.

View & Search

Use the transactionjournal endpoint with GET requests to retrieve information on available transaction records, either in bulk or filtered for a particular date range. Limit results by transaction startTime and/or endTime, or exclude optional parameters to return all available data. Server responses are provided in XML format by default and 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, non-terminated Employee in Web Office. Required unless using the X-ECRS-APIKEY header.

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

This field 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
string <date-time>
Example: endTime=2015-03-25T16:00:00

This field 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).

Responses

Response Schema:
application/xml
application/xml
application/json
text/csv
object

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'

Response samples

Content type
application/xml
application/xml
application/json
text/csv
<?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="stri",
    EMD_84="string",
    EMD_9A="string",
    EMD_9F21="string",
    EMD_9C="st",
    EMD_5F34="st",
    EMD_5F2A="str",
    EMD_9F02="string",
    EMD_9F03="string",
    EMD_9F08="stri",
    EMD_9F09="stri",
    EMD_9F1A="str",
    EMD_9F33="string",
    EMD_9F34="string",
    EMD_9F35="st",
    EMD_9F36="stri",
    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="st",
    EMD_91="string",
    EMD_95_2GEN="string",
    EMD_9F26_2GEN="string",
    EMD_9F27_2GEN="st",
    EMD_8A="stri",
    EMD_9B="stri",
    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="str",
    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="strin",
    TRN_ETI_CardSwiped=true,
    TRN_ETI_Processor="string"/>
</root>

Items

The Items endpoint allows you to quickly pull inventory-related details from records in your CATAPULT database. Use GET to retrieve and filter results by Receipt Alias or Item ID: Item Detail is for queries on inventory and stock/local inventory by Store, while All Items better suited for broader searches of all inventory across locations.

Additional item-centric endpoints are in active development and will be released as they become available.

Detailed Search

The Item Detail endpoint allows you to search for and retrieve information about a particular item, including promotional data. Provide the exact Item ID, the Receipt Alias, or a Conventional Item Group to perform a search. The itemSearch parameter accepts exact text matches for Item IDs and exact or begins with text matches for the Receipt Alias or Conventional Item Group. Exclude any search parameters to return all inventory records. Promotional details for an inventory record are returnable only if a provided storeNumber is correctly associated with an applicable Zone profile.

Responses can be called from either the HQ or a RS 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, non-terminated Employee in Web Office. Required unless using the X-ECRS-APIKEY header.

itemSearch
string <= 32 characters
Example: itemSearch=401234567890

Accepts a Receipt Alias, the starting characters of a Receipt Alias, or an Item ID. Item ID must be an exact match.

See also: General tab (Inventory Maintenance).

groupSearch
string <= 30 characters
Example: groupSearch=Bakery

Accepts a Conventional Item Group name or the starting characters of a Conventional Item Group name. Returns the item in itemSearch when both paramaters are provided.

See also: Item Groups (Conventional Item Groups).

storeNumber
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 association to return promotional data. If the storeNumber is not specified in the request query, then only data will be returned for the store where the query is being performed. For example, if you are running the API against the HQ CATAPULT location, and a storeNumber is not specified in the query, then only data from the HQ will be returned.

See also: Zones (Profiles).

Responses

Response Schema:
application/json
application/json
application/xml
text/csv
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
application/json
application/json
application/xml
text/csv
[
  • {
    }
]

View All

The All Items endpoint allows for the bulk retrieval of inventory records from your CATAPULT database. The Item Detail endpoint (see previous) could be used to further refine details gleaned from responses to this endpoint.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

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

Responses

Response Schema:
application/xml
application/xml
application/json
text/csv
object

Request samples 

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

Response samples

Content type
application/xml
application/xml
application/json
text/csv
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <row itemId="999" 
  name="REAL MEDLEYS APPLE NUT HRVST 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>

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

Use with a GET request to retrieve data from customer records. Limit results 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, non-terminated Employee in 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:
application/xml
application/xml
application/json
text/csv
object

Request samples 

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

Response samples

Content type
application/xml
application/xml
application/json
text/csv
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <row customerId="40100637000029"
  lastName="Doe"
  firstName="John"
  middleName=""
  nickName=""
  memo=""
  powerField1=""
  powerField2=""
  powerField3=""
  powerField4=""
  powerField5=""
  powerField6=""
  powerField7=""
  powerField8=""
  birthDate="1970-01-01"
  lastModified="2019-12-19 14:43:55.041"
  membershipAccount=""
  checkAcceptanceProfile=""
  priceLevel=""
  automaticDiscount=""
  suppressReceipt="false"
  loyaltyEnabled="true"
  loyaltyAccrualMultiplier="1.000"
  suffix=""
  prefix=""
  title=""
  company=""
  checkFileMemo=""
  billToPhoneNumber="8281112222"
  billToPhoneDescription="Home"
  billToEmailAddress=""
  billToEmailDescription=""
  billToEmailMarketing="false"
  billToEmailReceipt="false"
  billToAddressLine1=""
  billToAddressLine2=""
  billToAddressCity=""
  billToAddressStateProv=""
  billToAddressPostalCode=""
  billToAddressDescription=""
  membershipAccountJoined=""
  hideInLookup="false"
  customerInactive="false"
  loyaltyBalances="Default Program=.0200|Program A=0.0000|Program B=0.0000"
  HeadOfHousehold=""
  HouseholdAccounts=""
  Dependents=""
  lastPurchaseStore="123"
  lastPurchaseDate="2014-08-17"
  membershipProfileName=""
  taxExemption="State Tax"
  DateCreated="2022-02-04 11:30:00.000"
  HomeStore="Spring Valley Store"/>
</root>

Edit & Update

Use the customer endpoint with a PUT request to insert new, or update existing, customer records in your CATAPULT database. The lastName parameter is only required for new customer records. Note that this operation is limited to the creation and modification of customer maintenance records. It 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 request parameter with the customer endpoint.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active, non-terminated Employee in 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.

checkAcceptanceProfile
string <= 30 characters

This field contains the name of the Customer’s Check Profile.

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

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 field contains the first line of the Customer’s street address.

Warning: If not specified, the remaining billToAddress parameters will be ignored.

billToAddressLine2
string <= 50 characters

This field contains the second line of the Customer’s street address.

billToAddressCity
string <= 20 characters

This field contains the city of the Customer’s street address.

billToAddressStateProv
string <= 2 characters

This field contains the state or province of the Customer’s street address.

billToAddressPostalCode
string <= 15 characters

This field contains the postal code of the Customer’s street address.

billToAddressDescription
string <= 30 characters

This field contains a brief description of the Customer’s street address. If not specified, this field defaults to “Home”.

billToEmailAddress
string <= 254 characters

This field contains the Customer’s email address.

billToEmailDescription
string <= 30 characters

This field contains a brief description of the Customer’s email address. If not specified, this field defaults to “Home”.

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 field contains the Customer’s Phone Number.

billToPhoneDescription
string <= 30 characters

This field contains a brief description of the Customer’s Phone Number.

membershipAccountJoined
date
Example: membershipAccountJoined=2021-01-01

This field contains the date the Customer obtained Membership in the Store (YYYY-MM-DD HH:MM:SS.sss).

hideInLookup
boolean

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

membershipInactive
boolean

Accepts true or false. Updates the membership inactive option.

Available in versions 5.5.4.142 and greater.

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.
  • 1Available in versions 5.5.4.216 and greater.* \
  • 2Available in versions 5.6.94 and greater.*

Responses

Response Schema:
application/xml
application/xml
application/json
text/csv
object

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&checkAcceptanceProfile=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&membershipAccountJoined=2021-01-01&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
application/xml
application/xml
application/json
text/csv
<?xml version='1.1' encoding='UTF-8'?>
  <root>
    <row customerId="123456789000"
    lastName="Doe" 
    firstName="Jane" 
    middleName="" 
    nickName="" 
    memo="" 
    powerField1="" 
    powerField2="" 
    powerField3="" 
    powerField4="" 
    powerField5="" 
    powerField6="" 
    powerField7="" 
    powerField8="" 
    birthDate="1970-01-01" 
    lastModified="2019-12-19 14:43:55.041" 
    membershipAccount="" 
    checkAcceptanceProfile="" 
    priceLevel="" 
    automaticDiscount="" 
    suppressReceipt="false" 
    loyaltyEnabled="true" 
    loyaltyAccrualMultiplier="1.000" 
    suffix="" 
    prefix="" 
    title="" 
    company="" 
    checkFileMemo="" 
    billToPhoneNumber="8281112222" 
    billToPhoneDescription="Home" 
    billToEmailAddress="" 
    billToEmailDescription="" 
    billToEmailMarketing="false" 
    billToEmailReceipt="false" 
    billToAddressLine1="" 
    billToAddressLine2="" 
    billToAddressCity="" 
    billToAddressStateProv="" 
    billToAddressPostalCode="" 
    billToAddressDescription="" 
    membershipAccountJoined="" 
    hideInLookup="false" 
    customerInactive="false" 
    loyaltyBalances="" 
    HeadOfHousehold="" 
    HouseholdAccounts="" 
    Dependents="" 
    lastPurchaseStore="123" 
    lastPurchaseDate="2014-08-17" 
    membershipProfileName=""
    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, non-terminated Employee in 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:
application/json
application/json
application/xml
text/csv
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 of objects

The schedules on which the dynamic promotion will fire.

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
application/json
application/json
application/xml
text/csv
[
  • {
    }
]

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, non-terminated Employee in Web Office. Required unless using the X-ECRS-APIKEY header.

customerId
string <= 16 characters

See also: Customer ID.

Responses

Response Schema:
application/xml
application/xml
application/json
text/csv
object

Request samples 

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

Response samples

Content type
application/xml
application/xml
application/json
text/csv
<?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, non-terminated Employee in 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:
application/xml
application/xml
application/json
text/csv
object

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
application/xml
application/xml
application/json
text/csv
<?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, non-terminated Employee in 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:
application/xml
application/xml
application/json
text/csv
object

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
application/xml
application/xml
application/json
text/csv
<?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, non-terminated Employee in 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:
application/json
application/json
application/xml
text/csv
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
application/json
application/json
application/xml
text/csv
[
  • {
    }
]

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, non-terminated Employee in Web Office. Required unless using the X-ECRS-APIKEY header.

membershipProfile
string

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

Responses

Response Schema:
application/xml
application/xml
application/json
text/csv
object

Request samples 

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

Response samples

Content type
application/xml
application/xml
application/json
text/csv
<?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, non-terminated Employee in 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, quartly, 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, quartly, semianually, and annually.

Required if membershipFeeEnabled = true

Responses

Response Schema:
application/xml
application/xml
application/json
text/csv
object

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
application/xml
application/xml
application/json
text/csv
<?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, non-terminated Employee in 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:
application/json
application/json
application/xml
text/csv
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
application/json
application/json
application/xml
text/csv
[
  • {
    }
]

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 Receive-Only 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

Used to create new Conventional or Receive-Only Purchase Orders in Web Office. Use Action=N to create a new conventional worksheet, per the example, or replace with 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 section after this. Success: purchaseOrderId is returned.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active, non-terminated Employee in 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.

See also: Supplier Maintenance.

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.

See also: General tab (Store Maintenance).

receivingStoreHq
boolean

Conventional purchase orders only. Defines if the order can be edited at the HQ once submitted. This parameter can not be specified when a Purchase Order is created and/or edited for HQ.

  • 0 - Worksheet can only be edited from the receivingStore.
  • 1 - Worksheet can be edited from the HQ.

Defaults to 0 when PO created at HQ and submitted for another RS location. Defaults to 1 when PO 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=SOME_BOOLEAN_VALUE'

Response samples

Content type
application/json
application/json
application/xml
Example
Web Office User Permissions
Web Office User Permissions
Purchase Order ID not found
"{\n \"code\": 4,\n \"message\":\"RAISERROR executed: User not authorized to submit Purchase Orders\\n\"\n}"

Edit & Update

Used to edit existing or update the status of an active, non-committed Purchase Order in Web Office. Endpoint can be used to conditionally modify both Conventional and Receive-Only purchase orders. Edits can NOT be made to worksheets have been received or are already committed. Optional editable parameters listed here may also be passed in new worksheets, see Create New above. Success: purchaseOrderId is returned.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active, non-terminated Employee in 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, 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. For 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.

See also: Receiving Information (Purchase Orders).

alias
string <= 40 characters

The worksheet alias.

See also: General tab (Purchase Orders).

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.

See also: Purchase Order Information.

receivingEmployee
string <= 9 characters

Employee ID of account receiving the purchase order. Pass value NONE to clear parameter.

See also: Receiving Information (Purchase Orders).

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.
  • 1 - Worksheet can be edited from the HQ.

Defaults to 0 when PO created at HQ and submitted for another RS location. Defaults to unchangeable 1 when PO 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.

See also: Terms Profiles.

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.

See also: Excise Tax (Purchase Orders).

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

If freight charges are to be distrubuted across cost of all received items. Requires a non-zero freightCharges value included in the query or already present on the worksheet.

  • 0 - NOT distrubuted.
  • 1 - Distributed.

See also: Distrubute Freight (Purchase Orders).

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
application/json
application/json
application/xml
Example
Web Office User Permissions
Web Office User Permissions
Purchase Order ID not found
"{\n \"code\": 4,\n \"message\":\"RAISERROR executed: User not authorized to submit Purchase Orders\\n\"\n}"

Submit & Commit

Use to submit or commit Conventional or Receive-Only Purchase Orders in Web Office. Worksheet must already have an invoiceNumber before it can be committed. Use Action=S to submit, per the example, or replace with Action=C to commit. Success: purchaseOrderId is returned.

query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active, non-terminated Employee in 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, 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. For 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=S

Type of Action to be Performed:

  • S - SUBMIT the purchase order worksheet.
  • C - COMMIT the purchase order worksheet.
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 wthout 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
application/json
application/json
application/xml
Example
Web Office User Permissions
Web Office User Permissions
Purchase Order ID not found
"{\n \"code\": 4,\n \"message\":\"RAISERROR executed: User not authorized to submit Purchase Orders\\n\"\n}"

Purchase Order Items

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.

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
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active, non-terminated Employee in 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, 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. For 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

Determines the line item to add/update/delete. Takes precedences over itemId when both are provided.

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.

Only 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. Replaces any pre-existing value for the matching supplierUnitId.

Only 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
API Key Not Found
API Key Not Found
Purchase Order Not Found
No receivedQty or totalCost Specified
{"code":2,"message":"Invalid API Key."}

View & Search

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. 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). 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, non-terminated Employee in 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:
application/xml
application/xml
application/json
text/csv
object

Request samples 

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

Response samples

Content type
application/xml
application/xml
application/json
text/csv
<?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, non-terminated Employee in 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:
application/xml
application/xml
application/json
text/csv
object

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
application/xml
application/xml
application/json
text/csv
<?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, non-terminated Employee in 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:
application/xml
application/xml
application/json
text/csv
Array
object (inventoryAdjustments_get)

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
application/xml
application/xml
application/json
text/csv
<?xml version='1.1' encoding='UTF-8'?>
<root>
  <row worksheetName="Adjustment worksheet name"
  worksheetTimestampCommitted = "2022-02-03 12:00:00.000"
  itemID = "4011"
  worksheetItemDescription = "Banana"
  worksheetItemAdjustment = "4"
  worksheetBaseItemAdjustment = "4"
  worksheetItemAdjustmentReason = "Spoiled" 
  worksheetItemAdjustmentMemo = "Memo Data"
  />
</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, non-terminated Employee in 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, non-terminated Employee in Web Office. Required unless using the X-ECRS-APIKEY header.

Request Body schema:
application/json
application/json
application/xml
text/csv

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
application/json
application/json
application/xml
text/csv
[
  • {
    }
]

Response samples

Content type
application/json
application/json
application/xml
"{\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, non-terminated Employee in 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:
application/xml
application/xml
application/json
text/csv
object

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
application/xml
application/xml
application/json
text/csv
<?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 HTTP 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

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

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, non-terminated Employee in 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:
application/xml
application/xml
application/json
text/csv
object

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
application/xml
application/xml
application/json
text/csv
<?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"
</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"
</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, non-terminated Employee in 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:
application/xml
application/xml
application/json
text/csv
object

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
application/xml
application/xml
application/json
text/csv
<?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, non-terminated Employee in 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
application/xml
application/xml
application/json
{
  "code": 4,
  "message": "File not provided"
}

Batch Updates

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. 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 the recommended method for secure manipulation of data outside of the Web Office interface.

These are commonly used for synchronizing data from Legacy systems during migration or the automatition of certain tasks. Each endpoint is limited to POST requests unless where noted otherwise in the operation description.

Note that when any of these 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.

External links to the CATAPULT Online Manual (OLM) are included for additional clarification of terms, fields, parameters, and data points where applicable.

Batch Item Maintenance

The Item Maintenance endpoint is used to post bulk, multi-store additions or changes to your inventory records. The operation can create Departments (when a DeptNo does not exist and a DeptName is entered), Brands, and PowerFields. New entries are added to their respective tables when not found in the database. It does not create Weight Profiles or Prompts. These must be created in WebOffice for use in a request parameter.

Note that new items will have pricing records created for all zones: promptForPrice will be set to enabled 1 on Price Level 1 and disabled 0 with a dollar value of $0.00 on Price Levels 2-4. Use the following global Advanced Setting to override this behaviour:

KEY = stagingTables.NewItemsAddWithZeroPrice
VALUE = true

With this setting in place, new items are added with promptForPrice disabled and a $0.00 base Price Level 1.

New items created by this batch process will inherit all applicable department default values associated with the DeptNo entered in the batch record. Additional item hierarchy defaults are pulled from the SubDeptNumber, CategoryNumber, SubCategoryNumber, and VarietyNumber field values, if subsequently entered in the batch record. The full item hierarchy (numbers) must be included to update or insert item records.

See also: Inventory 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, non-terminated Employee in 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:
application/json
application/json
application/xml
text/csv

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

See also: Item ID.

deptNo
integer

Required for new items. See also: Department ID.

deptName
string <= 30 characters

Required for new departments. See also: Department Name.

name
string <= 254 characters
receiptAlias
string <= 32 characters

Required for new items. See also: Receipt Alias.

brand
string <= 30 characters

'NONE' to set to null/no choice. See also: Brand.

size
string <= 20 characters
promptList
string <= 30 characters

List of prompts names separated by colon(:). Enter 'NONE' to remove all.
Entered list will replace any currently listed prompts.

discountList
string <= 30 characters

List of discount names separated by colon(:). Enter 'NONE' to remove all; 'DEFAULT' to use department default.
Entered list will replace any currently listed discounts. See also: Discount.

suggestedRetail
string <decimal(16,4)>

See also: SRP.

pf1
string <= 30 characters

List Power Field 1. Enter 'NONE' to set to null/no choice. See also: Power Fields (Global).

pf2
string <= 30 characters

List Power Field 2. Enter 'NONE' to set to null/no choice.

pf3
string <= 30 characters

List Power Field 3. Enter 'NONE' to set to null/no choice.

pf4
string <= 30 characters

List Power Field 4. Enter 'NONE' to set to null/no choice.

pf5
string <= 30 characters
pf6
string <= 30 characters
pf7
string <= 30 characters
pf8
string <= 30 characters
memo
string <= 254 characters

See also: Memo.

linkGroup
string

Link Item Group. Updates all stores. Enter 'NONE' to set to null/no choice.

  • This field has been moved to Item Store Data. It remains here for backwards compatibility. See also: Item Groups, Linked Items
nonReturnable
boolean

See also: Returns.

embeddedPriceAsUnit
boolean
countryOfOrigin
string <= 28 characters
subDeptNumber
integer

Must also specify a deptNo. See also: Item Hierarchy.

categoryNumber
integer

Must also specify a deptNo and subDeptNumber. See also: Item Hierarchy.

subCategoryNumber
integer

Must also specify a deptNo, subDeptNumber, and categoryNumber. See also: Item Hierarchy.

varietyNumber
integer

Must also specify a deptNo, subDeptNumber, categoryNumber, and varietyNumber. See also: Item Hierarchy

Request samples

Content type
application/json
application/json
application/xml
text/csv
[
  • {
    }
]

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, non-terminated Employee in 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:
application/json
application/json
application/xml
text/csv

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
application/json
application/json
application/xml
text/csv
[
  • {
    }
]

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, non-terminated Employee in 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:
application/json
application/json
application/xml
text/csv

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
application/json
application/json
application/xml
text/csv
[
  • {
    }
]

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, non-terminated Employee in 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:
application/json
application/json
application/xml
text/csv

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
application/json
application/json
application/xml
text/csv
[
  • {
    }
]

Batch Item Ordering Information

The Item Item Ordering Information endpoint allows you to post bulk updates to manage the Suppliers (and related ordering information) associated with targeted inventory records. 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.

See also: Suppliers Section (Inventory), Supplier 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, non-terminated Employee in 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:
application/json
application/json
application/xml
text/csv

List of Item Ordering Information

Array
action
required
string
Enum: "U" "R" "D" "E"

Type of Action to be Performed:

  • 'U' - Insert or Update
  • 'R' - Remove
  • 'E' - Un-Discontinue
  • 'D' - Discontinue
itemId
required
string <= 14 characters

See also: Item ID.

supplierId
required
string <= 10 characters

See also: Supplier ID.

orderId
required
string <= 15 characters

See also: Supplier Unit ID.

orderQty
string <decimal(12,3)>

See also: Order Quantity.

orderUnitName
string <= 30 characters

See also: Supplier Unit Name.

orderPrimary
boolean

See also: Default Supplier.

vendorDistributionCenterID
string <= 32 characters

This field, which is available with CATAPULT 5.6.101 and newer, 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. Likewise, if this field is populated with NONE, then the Distribution Center will be removed/unassociated from the item's orderId.

vendorDistributionCenterName
string <= 32 characters

This field, which is available with CATAPULT 5.6.101 and newer, 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.

Request samples

Content type
application/json
application/json
application/xml
text/csv
[
  • {
    }
]

Batch Permanent Price and Cost

This endpoint allows you to create and commit permanent Price & Cost Change Worksheets. Worksheets created here 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.

See also: Price & Cost Change (P&CC) Worksheets.

Please note the following about the Batch Permanent Price and Cost endpoint:

  • Batch processing status and log can be viewed by calling the /batch/importMessages endpoint.
  • When the Batch Permanent Price and Cost endpoint is used, each batch is comprised of different rows of data, and each row represents one item on the worksheet. Each row contains specific fields of data that help CATAPULT identify what worksheet(s) to create and what items to place on those worksheets. With this in mind, if any of the following fields within a batch are different, an entirely new worksheet will be created for the row that is different. Therefore, if you want to ensure that all rows within a batch populate the same worksheet, it's important to ensure that the following fields in all rows match.
    • name
    • zoneName
    • startDate
    • commitAtStore
    • worksheetTypeProfileName (available with CATAPULT 5.6.121 and newer)
  • Beginning with CATAPULT version 5.6.107, should the Batch Permanent Price and Cost endpoint initially fail to commit a worksheet, it will reattempt the commit until successful (up to 10 times). After 10 failed attempts, the importMessages for that worksheet will display an 'E' (for error), at which point you will need to commit the worksheet through CATAPULT Web Office.
query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active, non-terminated Employee in 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:
application/json
application/json
application/xml
text/csv

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>

See also: Start Date (P&CC).

memo
string <= 254 characters

See also: Memo (P&CC).

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 ]
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 ]
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 ]
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 ]
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
application/json
application/json
application/xml
text/csv
[
  • {
    }
]

Batch Price and Cost

This 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. Note that the startDate and endDate parameters are required to specify when the changes made by the worksheet will take effect and end.

See also: Price & Cost Change (P&CC) Worksheets.

Please note the following about the Batch Price and Cost endpoint:

  • Batch processing status and log can be viewed by calling the /batch/importMessages endpoint.
  • When the Batch Price and Cost endpoint is used, each batch is comprised of different rows of data, and each row represents one item on the worksheet. Each row contains specific fields of data that help CATAPULT identify what worksheet(s) to create and what items to place on those worksheets. With this in mind, if any of the following fields within a batch are different, an entirely new worksheet will be created for the row that is different. Therefore, if you want to ensure that all rows within a batch populate the same worksheet, it's important to ensure that the following fields in all rows match.
    • name
    • zoneName
    • startDate
    • endDate
    • commitAtStore
    • worksheetTypeProfileName (available with CATAPULT 5.6.121 and newer)
  • Beginning with CATAPULT version 5.6.107, should the Batch Price and Cost endpoint initially fail to commit a worksheet, it will reattempt the commit until successful (up to 10 times). After 10 failed attempts, the importMessages for that worksheet will display an 'E' (for error), at which point you will need to commit the worksheet through CATAPULT Web Office.
query Parameters
apikey
string
Example: apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0

This field requires a valid API Key for an active, non-terminated Employee in 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:
application/json
application/json
application/xml
text/csv

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 mm/dd/yy hh:mm am/pm. See also: Start Date (P&CC).

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 mm/dd/yy hh:mm am/pm. See also: End Date.

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 ]
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 ]
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 ]
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 ]
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
application/json
application/json
application/xml
text/csv
[
  • {
    }
]

Batch Inventory Labels

The Inventory Labels endpoint allows for the creation and posting of Inventory Label Worksheets. 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. Note that labels can only be printed from un-committed worksheets, so only commit an Inventory Label Worksheet once you've confirmed it's no longer needed (really though it can always be rebuilt).

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, non-terminated Employee in 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:
application/json
application/json
application/xml
text/csv

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
application/json
application/json
application/xml
text/csv
[
  • {
    }
]

Batch Store Promotions

The Store Promotions endpoint allows you to post updates to existing, and create new, Dynamic Promotions. Specifically, in this case, Store Promotions (as opposed to Item Promotions). Note that Store Coupons, Exclude Groups, and Customers are not created by this function and therefore must already be present in your database before they can be successfully included as part of a request. Use the DISCONTINUE action rather than the REMOVE action whenever possible.

See also: Dynamic Promotion Sections, Creating a Store Promotion.

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, non-terminated Employee in 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:
application/json
application/json
application/xml
text/csv

List of Store Promotions to Update

Array
action
required
string
Enum: "U" "R" "D" "E"

Type of Action to be Performed:

  • 'U' - Insert or Update
  • 'R' - Remove
  • 'E' - Un-Discontinue
  • 'D' - Discontinue
name
string <= 128 characters

See also: Name (Promo).

zoneName
string <= 30 characters
receiptAlias
required
string <= 32 characters
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 (|). See also: Item Groups (Promo).

This field is required when request Action = 'U'

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
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

1 - Price
2 - Amount
3 - Percent
See also: Promotion Type.

value
required
string <decimal(16,4)>

Meaning of this value depends on type of promotion selected. See also: Promotion Type.

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
application/json
application/json
application/xml
text/csv
[
  • {
    }
]

Batch Item Promotions

The Item Promotions endpoint allows you to post updates to existing, and create new, Dynamic Promotions of the Item Promotion variety. Note that Store Coupons, Exclude Groups, and Customers are not created by this function and therefore must be created in WebOffice before they can be used in the request parameters. Likewise 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.

See also: Dynamic Promotion Sections, Creating an Item Promotion.

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, non-terminated Employee in 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:
application/json
application/json
application/xml
text/csv

List of Item Promotions to Update

Array
action
required
string
Enum: "U" "R" "D" "E"

Type of Action to be Performed:

  • 'U' - Insert or Update
  • 'R' - Remove
  • 'E' - Un-Discontinue
  • 'D' - Discontinue
name
string <= 128 characters

See also: Name (Promo).

zoneName
string <= 30 characters
receiptAlias
required
string <= 32 characters
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 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

2 - Amount
3 - Percent
See also: Promotion Type.

value
string <decimal(16,4)>

Meaning of this value depends on type of promotion selected. See also: Promotion Type.

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. Format and maxLength of individual CUS_AccountNum is char(16).
See also: Customer Groups (Promo).

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
See also: Reset Usages (Day of Week).

periodDays
integer

Required when resetPeriod = 2 (Every X Days). See also: Reset Usages (Every X Days).

applyToPl1
boolean
applyToPl2
boolean
applyToPl3
boolean
applyToPl4
boolean

Request samples

Content type
application/json
application/json
application/xml
text/csv
[
  • {
    }
]

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, non-terminated Employee in 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:
application/json
application/json
application/xml
text/csv

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
application/json
application/json
application/xml
text/csv
[
  • {
    }
]

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, non-terminated Employee in 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:
application/json
application/json
application/xml
text/csv

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
application/json
application/json
application/xml
text/csv
[
  • {
    }
]

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, non-terminated Employee in 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:
application/json
application/json
application/xml
text/csv

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
application/json
application/json
application/xml
text/csv
[
  • {
    }
]

Batch Addresses

The Addresses endpoint allows you to post mailing addresses updates for select records in the CATAPULT system. Specifically:

  • Customers
  • Employees
  • Stores
  • Suppliers

This endpoint creates 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.

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.

See also: Address 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, non-terminated Employee in 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:
application/json
application/json
application/xml
text/csv

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
application/json
application/json
application/xml
text/csv
[
  • {
    }
]

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, non-terminated Employee in 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:
application/json
application/json
application/xml
text/csv

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
application/json
application/json
application/xml
text/csv
[
  • {
    }
]

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, non-terminated Employee in 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:
application/json
application/json
application/xml
text/csv

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
application/json
application/json
application/xml
text/csv
[
  • {
    }
]

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, non-terminated Employee in 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:
application/json
application/json
application/xml
text/csv

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
application/json
application/json
application/xml
text/csv
[
  • {
    }
]

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, non-terminated Employee in 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:
application/json
application/json
application/xml
text/csv

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
application/json
application/json
application/xml
text/csv
[
  • {
    }
]

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, non-terminated Employee in 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:
application/json
application/json
application/xml
text/csv

List of Temporary Price Changes to Remove

Array
name
required
string <= 40 characters

See also: Name (P&CC).

startDate
string <date-time>

See also: Start Date (P&CC).

endDate
string <date-time>

See also: End Date.

Request samples

Content type
application/json
application/json
application/xml
text/csv
[
  • {
    }
]

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, non-terminated Employee in 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:
application/json
application/json
application/xml
text/csv

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
application/json
application/json
application/xml
text/csv
[
  • {
    }
]

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 reasily 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, non-terminated Employee in 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:
application/json
application/json
application/xml
text/csv

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
application/json
application/json
application/xml
text/csv
[
  • {
    }
]

Batch Item Shelf Information

The Item Shelf Information endpoint is used to post inventory-record-per-store updates to your inventory shelf information. Up to nine (9) digits, spread across three (3) parameters, can be used to define the exact shelf sequnce for a given record. Each row in this batch defines the sequence for one such record: it's recommended to use a unique batch number for each store. This way you can easily adjust multiple inventory records for a single store location, then call importMessages for those store-specific changes using the unique batch number. Note the full sequence number of an inventory record's shelf location sequence will be the combined three sequence parts from the query parameters: leading zeroes will be automatically included, where necessary, to ensure each sequence is nine (9) digits.

For example, a complete shelf sequence of 001002003 would be entered in the parameters as:
sequencePart1 = 001
sequencePart2 = 002
sequencePart3 = 003

See also: Inventory Maintenance Shelf Information, Item Shelf Sequence in HHT.

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, non-terminated Employee in 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:
application/json
application/json
application/xml
text/csv

List of item shelf information, sequence data to be updated.

Array
storeId
required
string <= 10 characters

This field accepts the Store Number where the item whose sequence will be updated is located. See also: Store ID.

itemId
required
string <= 14 characters

This field accepts a the Item ID (UPC scancode) of the item record which will be updated. See also: Item ID.

sequencePart1
required
string

First three digits of the shelf location sequence. Numbers only.

sequencePart2
required
string

Second three digits of the shelf location sequence. Numbers only.

sequencePart3
required
string

Final three digits of the shelf location sequence. Numbers only.

Request samples

Content type
application/json
application/json
application/xml
text/csv
[
  • {
    }
]

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, non-terminated Employee in 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:
application/json
application/json
application/xml
text/csv
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"

The type of message
I - Informational Message E - Error Message

messageText
string

The textual message associated with the import batch.

Request samples 

curl --request GET \
  --url 'https://accountid.catapultweboffice.com/api/batch/importMessages?apikey=BP82MIFJTSJ5EP4MQCBDW7WYYVV0RPQ0&batch=123'

Response samples

Content type
application/json
application/json
application/xml
text/csv
[
  • {
    },
  • {
    }
]