SuperCat Solutions

JSON Data #

Our JSON order export uses the JavaScript Object Notation format, summarized here. There are a few important issues to note:

JSON uses floating point for all fractional values (e.g. 5.4). This may occasionally lead to odd values, e.g. "381.59999999999997" due to the fact that floating point numbers cannot represent all numbers. If the value is a price value, rounding it to the correct precision will yield the expected value.
JSON technically uses floating point for all numeric types (anything labeled "Number") below. We export integer values without the decimal place for consistency and readability, but we do recommend you use an existing JSON parsing library (such as DataContractJsonSerializer in .NET)

Orders exported in our standard JSON format will contain the following fields, not necessarily in this order.

Order Fields #

JSON field name	JSON type	Can be null	Comments
additional_fields	Dictionary/Object	No	(described below)
bill_to_city	String	Yes
bill_to_company_name	String	Yes
bill_to_country	String	Yes
bill_to_line1	String	Yes
bill_to_line2	String	Yes
bill_to_postal_code	String	Yes
bill_to_state	String	Yes
bill_to_address_changed	Boolean	Yes	Indicates whether the bill_to information has changed.
buyer_first_name	String	Yes
buyer_last_name	String	Yes
cancel_date	String, formatted YYYY-MM-DD	Yes
customer_email_address	String	Yes
customer_number	String	Yes	If local_customer_code is populated, this will contain the customer code entered by the rep in eCat. In this case, it may be blank. If local_customer_code is not populated, this value corresponds to the bill-to code provided in the customers.csv file.
customer_phone_number	String	Yes
customer_po_number	String	Yes
discount_amount_cents	Number	Yes
discount_percent	Number	Yes
ecat_version	String	Yes	The version of eCat that submitted this order.
id	Number	No	The internal identifier for this order.
is_exported	Boolean	Yes	Internal use only
is_submitted	Boolean	Yes	Internal use only
local_customer_code	String, UUID	Yes	If this is populated, it means the order was written for a customer that was created on the iPad. This is only available in the V2 format of our JSON order export. If it is populated, the "customer_number" field will contain the customer number entered in eCat by the rep.
notes	String	Yes	Order notes, as entered by the rep.
order_items	Array	No	(described below)
order_number	String	No	The official order number. This can change across resubmissions. If you need to track orders across resubmissions, see the uuid field below.
order_type	String	No	E.g. Confirmed, HFC, as specified by the rep, or the default value for eCat Online orders
organization_id	Number	Yes	The numeric identifier for your organization.
price_level	String	Yes	The price level code for this order.
rep_email	String	Yes
rep_first_name	String	Yes
rep_last_name	String	Yes
rep_number	String	Yes
rep_phone	String	Yes
ship_date	String (formatted YYYY-MM-DD)	Yes
ship_to_code	String	Yes
ship_to_city	String	Yes
ship_to_company_name	String	Yes
ship_to_country	String	Yes
ship_to_line1	String	Yes
ship_to_line2	String	Yes
ship_to_postal_code	String	Yes
ship_to_state	String	Yes
ship_to_address_changed	Boolean	Yes	Indicates whether ship_to information has changed.
submit_date	String (ISO 8601 timestamp, UTC time)	No	The timestamp that the order was submitted. Note that this maybe earlier than when the order showed up on the server. It records when the submit button was pressed.
surcharges	Array	Yes	(described below)
tag_for	String	Yes	The value of the "tag for" field, set by the rep
total_cents	Number	Yes	The total price of the order in cents. Why cents? This avoids floating point errors, because JSON does not have a decimal type, only a floating point type. You can divide by 100 to get the correct value.
total_product_volume	Number	Yes	The sum of extended_product_volume for all order items.
uuid	String (UUID)	No	A string globally unique to this order. This string will remain consistent between different resubmissions of the same order, so you can use it to track whether an order is a resubmission or not.

Additional Fields #

JSON Field Name	JSON Type
order_origin	String
shipment_preference	String
<order header custom 1 key>	String

Above, <order header custom 1 key> will be the key configured in your order header custom field. E.g. if the key you specified in your custom field configuration is "ship_via" then the additional_fields could look something like this:

{ "ship_via": "FedEx",
 "order_origin": "High Point Market",
 "shipment_preference": "HFC" }

Order Item Fields #

The order JSON object will contain an array called order_items. That array will contain the following values.

JSON field name	JSON type	Can be null	Comments
discount_notes	String	No	A convenience value containing notes about the discounts that were applied. This is intended for human consumption.
has_discount	Boolean	No	True if there is a discount or price override applied to this line item. This does not apply to contract prices.
option_notes	String	No	A convenience value containing notes about the options that were selected. This is for human consumption. See "option entry" below for the data intended for computer consumption.
line_notes	String	No	Notes entered by the rep for the line item.
extended_price	Number	Yes	A calculated value: final product unit price (after discount, override, option add-ons, etc) * quantity
extended_product_volume	Number	Yes	A calculated value: product volume * quantity
description	String	Yes	A description of the product at the time of ordering.
item_number	String	Yes	The base item code of the product for this line item.
matrix_option_item_code	String	Yes	Deprecated. Please use constructed_item_number instead.
constructed_item_number	String	Yes	The item number that was constructed based on various factors, such as option selection.
options	Array (described below)	Yes	The options that were selected for this line item.
quantity	Number	Yes	A number of items ordered.
units_per_carton	Number	Yes	A convenience value containing the pack quantity for this product at the time of ordering.

Options entry #

The options entry mentioned above, if present, will contain an array of JSON objects with the following fields:

JSON Field Name	JSON Type	Can be null	Comments
option_name	String	No	The name of the option that was selected.
option_code	String	No	The code of the option that was selected.
option_type_code	String	No	E.g. OptionSet1, from the product file.

Surcharges #

See Order Surcharges for an overview of order surcharges.

The surcharges entry mentioned above, if present, will contain an array of JSON objects with the following fields:

JSON Field Name	JSON Type	Can be null	Comments
label	String	No	A label describing the surcharge
amount	Number	Yes	For "amount" type surcharges, contains the amount of the surcharge, possibly overridden by the rep.
percent	Number	Yes	For percent type surcharges, contains the percentage to add onto the order as a surcharge

Above, if the surcharge is configured as a percentage, the percent of value will be populated. Otherwise, the amount value will be populated. The label field corresponds to the value specified when configuring the surcharge, as seen in the screenshot below.

Both amount and percent could be negative, in the case of using a surcharge as a discount of sorts.

Demo-Company-eCat-Tools-2016-02-25-15-51-11 — Configuring the label of a surcharge

Knowledgebase

JSON Order Fields

Table of Contents