Order Data Schema Specifications

Use this specification to format your order information prior to submitting to Listrak. Submitting your data to Listrak in the right format is important for delivering successful campaigns and insights.

Please also use the following schema specifications for other data objects:

Click here for Order sample file

Attribute
(Column)
Format
Requirements and Suggestions
ATTRIBUTE (COLUMN)
ordernumber
FORMAT

Attribute Description
The orders unique identifier

Example
0531435151

Syntax
String
Max. 50 characters

Requirements and Suggestions
  • This attribute is required as a primary key and must be included for every order.
  • If you provide supplemental order data via REST API or data file feed, your ordernumber must match was is captured by the Listrak JavaScript on your brand's website.
  • When sending updates to an order, ensure your ordernumber does not change.
  • This attribute's value must match the ordernumber provided in your Order Items data feed.
ATTRIBUTE (COLUMN)
alternateordernumber
FORMAT

Attribute Description
The orders alternate order number

Example
065651

Syntax
String
Max. 50 characters

Requirements and Suggestions
  • Used as an alternate order number that may derive from an Order Management System that is separate from your ecommerce order data.
  • The alternateordernumber will be used as the ordernumber in the event an ordernumber is not provided in the data file.
ATTRIBUTE (COLUMN)
dateentered
FORMAT

Attribute Description
The order's datetime

Example
2018-08-23T17:23:48Z

Syntax
Datetime
ISO 8601

Requirements and Suggestions
  • Precise timestamps that include the minutes and seconds are recommended so that all unique events are accurately reported, such as multiple purchases made by the same person in one day.
ATTRIBUTE (COLUMN)
email
FORMAT

Attribute Description
The customer's email address

Example
jmiller@gmail.com

Syntax
String
Max. 100 characters

Requirements and Suggestions
  • Provide the customer's email address whenever possible. This ensures online and offline orders are appropriately attributed to the campaign from which they originated.
ATTRIBUTE (COLUMN)
customernumber
FORMAT

Attribute Description
The customer's unique identifier

Example
18941316

Syntax
String
Max. 20 characters

Requirements and Suggestions
  • If you provide order data from multiple sources (Listrak integrations, REST API, data file feed), the customernumber you supply should be consistent across all sources.
  • customernumber can be used as an alternative method of customer lookup in Listrak CRM.
ATTRIBUTE (COLUMN)
itemtotal
FORMAT

Attribute Description
The total of value of all order items

Example
50.00

Syntax
Decimal

Requirements and Suggestions
  • This attribute is the sum of all order line items' itemtotal.
  • If discounts are applied to merchandise at the order-level, those discounts should be defined using merchandisediscount instead of being subtracted from itemtotal.
  • For example, $10 off your entire order! is defined using merchandisediscount, and itemtotal will reflect the total order item value before the discount is applied.
  • Download an ordertotal calculation worksheet
ATTRIBUTE (COLUMN)
shippingtotal
FORMAT

Attribute Description
The order's total shipping value

Example
10.50

Syntax
Decimal

Requirements and Suggestions
  • This attribute's value is before any order-level discounts are applied via nonmerchandisediscount.
ATTRIBUTE (COLUMN)
handlingtotal
FORMAT

Attribute Description
The order's total handling value

Example
2.00

Syntax
Decimal

Requirements and Suggestions
  • This attribute's value is before any order-level discounts are applied via nonmerchandisediscount.
ATTRIBUTE (COLUMN)
taxtotal
FORMAT

Attribute Description
The order's total tax value

Example
3.00

Syntax
Decimal

Requirements and Suggestions
  • This attribute's value is before any order-level discounts are applied via nonmerchandisediscount.
ATTRIBUTE (COLUMN)
merchandisediscount
FORMAT

Attribute Description
The total discount applied to merchandise at the order-level

Example
10.00

Syntax
Decimal

Requirements and Suggestions
  • This attribute is currently only available to Listrak CRM users.
  • This attribute is used to indicate the total discount applied to merchandise at the order-level.
  • In the example above, $10 off your entire order! is applied using merchandisediscount.
  • To understand how this attribute is used when calculating ordertotal, see below.
  • Order-level discounts and promotions for shipping, handling, or tax is defined using nonmerchandisediscount.
ATTRIBUTE (COLUMN)
nonmerchandisediscount
FORMAT

Attribute Description
The total discount applied to the order, not attributed to merchandise

Example
8.50

Syntax
Decimal

Requirements and Suggestions
  • This attribute is currently only available to Listrak CRM users.
  • This attribute is used to define discounts and promotions for shipping, handling, or tax.
  • For example, Free Shipping! discount values would be defined using this attribute.
ATTRIBUTE (COLUMN)
ordertotal
FORMAT

Attribute Description
The order's total value

Example
47.00

Syntax
Decimal

Requirements and Suggestions
  • Use the following equation to calculate ordertotal:
  • ordertotal = (itemtotal + taxtotal + shippingtotal + handlingtotal) - (merchandisediscount + nonmerchandisediscount)
  • An accurate ordertotal is key to accurate reporting and attribution. Furthermore, Listrak CRM enables you to conduct a detailed analysis on the impact discounts have on your customers' purchasing behavior.
  • Download an ordertotal calculation worksheet
ATTRIBUTE (COLUMN)
merchandisediscounttype
FORMAT

Attribute Description
The type of the discount applied to the merchandise at the order-level

Example
QuantityDiscount

Syntax
String

Supported Values
null, PriceOverride, PriceRule, Promotion, SeniorCitizen, Markdown, Coupon, QuantityDiscount, Rebate, CashDiscount, TradeDiscount, TradeInKind, PromptPaymentDiscount, GeneralDiscount, GiftVoucher, FlexibleDiscount, RewardProgram, ManufacturerReward, CreditCardReward

Requirements and Suggestions
  • This attribute is currently only available to Listrak CRM users.
  • For discounts applied to merchandise at the order-level, supply one of the supported values that best describes the discount.
  • Listrak CRM enables you to conduct a detailed analysis on the impact discounts have on your customers' purchasing behavior.
ATTRIBUTE (COLUMN)
merchandisediscountdescription
FORMAT

Attribute Description
The description of the discount applied to the merchandise at the order-level

Example
BOGO Half Off through November 2018

Syntax
String
Max. 100 characters

Requirements and Suggestions
  • This attribute is currently only available to Listrak CRM users.
  • This attribute can be used with or without merchandisediscounttype.
  • Supply intuitive, easily searchable descriptions. For example, BOGO Half Off through November 2018 instead of BOGO.
ATTRIBUTE (COLUMN)
nonmerchandisediscounttype
FORMAT

Attribute Description
The type of the discount applied to the order not associated with merchandise

Example
Promotion

Syntax
String

Supported Values
null, PriceOverride, PriceRule, Promotion, SeniorCitizen, Markdown, Coupon, QuantityDiscount, Rebate, CashDiscount, TradeDiscount, TradeInKind, PromptPaymentDiscount, GeneralDiscount, GiftVoucher, FlexibleDiscount, RewardProgram, ManufacturerReward, CreditCardReward

Requirements and Suggestions
  • This attribute is currently only available to Listrak CRM users.
  • For discounts applied to shipping, handling, or taxes at the order-level, supply one of the supported values that best describes the discount.
ATTRIBUTE (COLUMN)
nonmerchandisediscountdescription
FORMAT

Attribute Description
The description of the discount applied to the order not associated with merchandise

Example
Free Shipping for New Customers 2018

Syntax
String
Max. 100 characters

Requirements and Suggestions
  • This attribute is currently only available to Listrak CRM users.
  • This attribute can be used with or without nonmerchandisediscounttype.
  • Supply intuitive, easily searchable descriptions. For example, Free Shipping for New Customers 2018 instead of Free Shipping.
ATTRIBUTE (COLUMN)
couponcode
FORMAT

Attribute Description
The coupon code used on the order

Example
FreeShip2019

Syntax
String
Max. 32 characters

Requirements and Suggestions
ATTRIBUTE (COLUMN)
status
FORMAT

Attribute Description
The current status of the order

Example
Completed

Syntax
String
Integer

Supported Values
0=NotSet, 1=Misc, 2=PreOrder, 3=BackOrder, 4=Pending, 5=Hold, 6=Processing, 7=Shipped, 8=Completed, 9=Returned, 10=Canceled, 11=Unknown

Requirements and Suggestions
  • You may supply either the integer or string associated with the order's status.
  • Use this attribute to update an order as the status changes.
  • Remember to update canceled and returned orders with the appropriate status to ensure accurate revenue reporting via Listrak CRM.
ATTRIBUTE (COLUMN)
source
FORMAT

Attribute Description
The source of the order

Example
Store

Syntax
String
Max. 25 characters

Requirements and Suggestions
  • Supply the source of each order (such as Store, Phone, or Online).
  • For the best possible reporting and analytics, ensure that values are supplied for all possible orders.
ATTRIBUTE (COLUMN)
storenumber
FORMAT

Attribute Description
The storenumber of the order

Example
897315

Syntax
String
Max. 100 characters

Requirements and Suggestions
  • For orders that occurred in a physical store location, supply the store's unique identifier using storenumber.
  • Do not supply a value, such as "N/A", for orders that did not occur at a store.
ATTRIBUTE (COLUMN)
associateid
FORMAT

Attribute Description
The sales associate's unique identifier

Example
SA55217

Syntax
String
Max. 20 characters

Requirements and Suggestions
ATTRIBUTE (COLUMN)
shipdate
FORMAT

Attribute Description
The order's shipping date

Example
2018-08-26T07:43:48Z

Syntax
Datetime
ISO 8601

Requirements and Suggestions
ATTRIBUTE (COLUMN)
shippingmethod
FORMAT

Attribute Description
The order's shipping method

Example
UPS

Syntax
String
Max. 32 characters

Requirements and Suggestions
ATTRIBUTE (COLUMN)
trackingnumber
FORMAT

Attribute Description
The order's tracking number

Example
1Z999AA10123456784

Syntax
String
Max. 32 characters

Requirements and Suggestions
ATTRIBUTE (COLUMN)
shippingfirstname
FORMAT

Attribute Description
The shipping contact's first name

Example
Jane

Syntax
String
Max. 50 characters

Requirements and Suggestions
ATTRIBUTE (COLUMN)
shippinglastname
FORMAT

Attribute Description
The shipping contact's last name

Example
Miller

Syntax
String
Max. 50 characters

Requirements and Suggestions
ATTRIBUTE (COLUMN)
shippingaddress1
FORMAT

Attribute Description
The first line of the shipping contact's address

Example
529 Maple Avenue

Syntax
String
Max. 255 characters

Requirements and Suggestions
ATTRIBUTE (COLUMN)
shippingaddress2
FORMAT

Attribute Description
The second line of the shipping contact's address

Example
Apartment 39

Syntax
String
Max. 255 characters

Requirements and Suggestions
ATTRIBUTE (COLUMN)
shippingaddress3
FORMAT

Attribute Description
The third line of the shipping contact's address

Syntax
String
Max. 255 characters

Requirements and Suggestions
ATTRIBUTE (COLUMN)
shippingcity
FORMAT

Attribute Description
The city of the shipping contact

Example
Philadelphia

Syntax
String
Max. 40 characters

Requirements and Suggestions
ATTRIBUTE (COLUMN)
shippingstate
FORMAT

Attribute Description
The abbreviated state of the shipping contact

Example
PA

Syntax
String
Max. 3 characters

Requirements and Suggestions
ATTRIBUTE (COLUMN)
shippingzipcode
FORMAT

Attribute Description
The shipping contact's zip code

Example
19103

Syntax
String
Max. 20 characters

Requirements and Suggestions
ATTRIBUTE (COLUMN)
shippingcountry
FORMAT

Attribute Description
The abbreviated country of the shipping contact

Example
US

Syntax
String
Max. 2 characters

Requirements and Suggestions
ATTRIBUTE (COLUMN)
shippingphone
FORMAT

Attribute Description
The shipping contact's phone number

Example
17175559636

Syntax
String
E.164 formatting

Requirements and Suggestions
ATTRIBUTE (COLUMN)
billingfirstname
FORMAT

Attribute Description
The billing contact's first name

Example
Jane

Syntax
String
Max. 50 characters

Requirements and Suggestions
ATTRIBUTE (COLUMN)
billinglastname
FORMAT

Attribute Description
The billing contact's last name

Example
Miller

Syntax
String
Max. 50 characters

Requirements and Suggestions
ATTRIBUTE (COLUMN)
billingaddress1
FORMAT

Attribute Description
The first line of the billing contact's address

Example
529 Maple Avenue

Syntax
String
Max. 255 characters

Requirements and Suggestions
ATTRIBUTE (COLUMN)
billingaddress2
FORMAT

Attribute Description
The second line of the billing contact's address

Example
Apartment 39

Syntax
String
Max. 255 characters

Requirements and Suggestions
ATTRIBUTE (COLUMN)
billingaddress3
FORMAT

Attribute Description
The third line of the billing contact's address

Syntax
String
Max. 255 characters

Requirements and Suggestions
ATTRIBUTE (COLUMN)
billingcity
FORMAT

Attribute Description
The city of the billing contact

Example
Philadelphia

Syntax
String
Max. 40 characters

Requirements and Suggestions
ATTRIBUTE (COLUMN)
billingstate
FORMAT

Attribute Description
The abbreviated state of the billing contact

Example
PA

Syntax
String
Max. 3 characters

Requirements and Suggestions
ATTRIBUTE (COLUMN)
billingzipcode
FORMAT

Attribute Description
The billing contact's zip code

Example
19103

Syntax
String
Max. 20 characters

Requirements and Suggestions
ATTRIBUTE (COLUMN)
billingcountry
FORMAT

Attribute Description
The country of the billing contact

Example
US

Syntax
String
Max. 2 characters

Requirements and Suggestions
ATTRIBUTE (COLUMN)
billingphone
FORMAT

Attribute Description
The phone number of the billing contact

Example
17175559636

Syntax
String
E.164 formatting

Requirements and Suggestions
ATTRIBUTE (COLUMN)
meta1
FORMAT

Attribute Description
Supplemental order information

Syntax
String
Max. 500 characters

Requirements and Suggestions
  • Supply a custom value describing the order that can be used for enhanced CRM reporting or solution functionality.
  • This field can also be a comma delimited list and has operations (such as equals, contains, is not blank, etc.) associated to it for additional operational level performance in Listrak and Listrak CRM.
  • Though you may add boolean values to this field, it is of string type and will not convert to provide operations such as is true or is false.
ATTRIBUTE (COLUMN)
meta2
FORMAT

Attribute Description
Supplemental order information

Syntax
String
Max. 500 characters

Requirements and Suggestions
ATTRIBUTE (COLUMN)
meta3
FORMAT

Attribute Description
Supplemental order information

Syntax
String
Max. 500 characters

Requirements and Suggestions
ATTRIBUTE (COLUMN)
meta4
FORMAT

Attribute Description
Supplemental order information

Syntax
String
Max. 500 characters

Requirements and Suggestions
ATTRIBUTE (COLUMN)
meta5
FORMAT

Attribute Description
Supplemental order information

Syntax
String
Max. 500 characters

Requirements and Suggestions