Listrak Data Import REST API
Import retail-specific data including customers, orders, products, and reviews as a programmatic alternative to FTP-based data ingestion.
OpenAPI Specification
openapi: 3.0.0
info:
version: v1
title: Listrak Data Import REST API
description: "# INTRODUCTION\r\nWelcome to the Listrak Data Import <a href='https://en.wikipedia.org/wiki/Representational_state_transfer'>REST\
\ API</a>!\n# Versioning\r\n\r\nThe API version is denoted in the URI. This API's\
\ base URI is:\r\n\r\n`https://api.listrak.com/data/v1`\r\n\r\n<br />\r\n\r\n\
The API version will be incremented if breaking changes are introduced. Breaking\
\ changes may include:\r\n\r\n- Addition of required headers, parameters, or model\
\ fields to a current route\r\n- Alterations that would result in currently valid\
\ requests failing, or performing unexpectedly\r\n\r\n<br />\r\n\r\nChanges that\
\ are not considered breaking may include:\r\n\r\n- Addition of new model fields\r\
\n- Addition of new routes\r\n- Addition of new response headers\r\n- Any alteration\
\ to a route that is marked as <span class=\"inDev\">In Development</span>\r\n\
# Usage\r\n\r\n## External Libraries\r\n\r\nThe C# code examples featured on this\
\ site require the following packages:\r\n\r\n- <a href=\"https://www.nuget.org/packages/Microsoft.AspNet.WebApi.Client/\"\
>Microsoft.AspNet.WebApi.Client</a>\r\n- <a href=\"https://www.nuget.org/packages/Newtonsoft.Json/\"\
>Newtonsoft.Json</a>\r\n\r\nThe Php code examples require the following package:\r\
\n- <a href=\"http://docs.guzzlephp.org/en/stable/#\">Guzzle 6</a>\n# Feedback\r\
\n\r\nWe are actively seeking feedback in the following areas:\r\n- Code samples\r\
\n- Response examples\r\n- Resource and field descriptions\r\n\r\n<br />\r\n\r\
\nPlease provide your feedback to us at [email protected].\n# INTEGRATION\
\ SETUP\r\nTo enable API access, **you must create an _Integration_** on the _Integrations_\
\ page. In the Listrak application left menu, go to: Integrations → Integration\
\ Management.\r\n\r\nPlease specify integration type `Data` for your integration.\r\
\n\r\nMake sure to securely store a copy of your _Client ID_ and _Client Secret_.\
\ These values will be needed to authenticate with the API. For your security,\
\ the _Client Secret_ cannot be retrieved if it is lost.\r\n\n# Status Codes\r\
\n\r\n| Status Code | Status | Description |\r\n|-|-|-|\r\n| 200 | OK | The request\
\ succeeded. |\r\n| 201 | Created | A new resource has been created. |\r\n| 400\
\ | Bad Request | Your request is malformed or invalid. |\r\n| 401 | Unauthorized\
\ | Authentication is required. |\r\n| 404 | Not Found | The resource does not\
\ exist. |\r\n| 405 | Method Not Allowed | The route does not support the requested\
\ method. |\r\n| 415 | Unsupported Media Type | Please use a `Content-Type` of\
\ `application/json`. |\r\n| 500 | Internal Server Error | An unexpected error\
\ occurred. Our development team has been notified. |\r\n\n# Parameters\r\n##\
\ Route Parameters\r\n\r\nResource identifiers are specified in the route. For\
\ example, in the route `/Resource/{resourceId}`, `resourceId` is a route parameter.\
\ In this example, if you wish to interact with Resource #123, its route would\
\ be `/Resource/123`.\r\n\r\n## Query Parameters\r\n\r\nSome routes support additional\
\ query parameters; for example, some resources support query parameters relating\
\ to paging. Supported query parameters are described in their respective documentation\
\ areas.\r\n\r\n## Request Body\r\n\r\nRequest bodies are required for most `POST`\
\ and `PUT` requests. Please use a `Content-Type` of `application/json` and provide\
\ a JSON object in your request body.\r\n\r\nThe maximum accepted request body\
\ size is 250 MB (262,144,000 bytes). Headers are not counted against this limit.\
\ Requests larger than this limit will result in a `404 Not Found` response.\r\
\n\n"
x-logo:
url: /Data/Documentation/Images/Logo.png
paths:
/v1/Customer:
post:
operationId: Customer_PostCustomerCollection
summary: Start a Customer Import
description: Starts a new import using the supplied customer collection.
tags:
- Customer
responses:
'400':
description: BadRequest
content:
application/json:
schema:
$ref: '#/definitions/Error'
'201':
description: Created
content:
application/json:
schema:
$ref: '#/definitions/ResourceCreated'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/definitions/Error'
security:
- OAuth 2:
- Customer
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
$ref: '#/definitions/Customer'
/v1/Order:
post:
operationId: Order_PostOrderCollection
summary: Start an Order Import
description: Starts a new import using the supplied order collection.
tags:
- Order
responses:
'400':
description: BadRequest
content:
application/json:
schema:
$ref: '#/definitions/Error'
'201':
description: Created
content:
application/json:
schema:
$ref: '#/definitions/ResourceCreated'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/definitions/Error'
security:
- OAuth 2:
- Order
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
$ref: '#/definitions/Order'
/v1/Product:
post:
operationId: Product_PostProductCollection
summary: Start a Product Import
description: Starts a new import using the supplied product collection.
tags:
- Product
responses:
'400':
description: BadRequest
content:
application/json:
schema:
$ref: '#/definitions/Error'
'201':
description: Created
content:
application/json:
schema:
$ref: '#/definitions/ResourceCreated'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/definitions/Error'
security:
- OAuth 2:
- Product
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
$ref: '#/definitions/Product'
/v1/RatingSummary:
post:
operationId: RatingSummary_PostRatingSummaryCollection
summary: Start a Rating Summary Import
description: Starts a new import using the supplied rating summary collection.
tags:
- RatingSummary
responses:
'400':
description: BadRequest
content:
application/json:
schema:
$ref: '#/definitions/Error'
'201':
description: Created
content:
application/json:
schema:
$ref: '#/definitions/ResourceCreated'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/definitions/Error'
security:
- OAuth 2:
- Review
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
$ref: '#/definitions/RatingSummary'
/v1/Review:
post:
operationId: Review_PostReviewCollection
summary: Start a Review Import
description: Starts a new import using the supplied review collection.
tags:
- Review
responses:
'400':
description: BadRequest
content:
application/json:
schema:
$ref: '#/definitions/Error'
'201':
description: Created
content:
application/json:
schema:
$ref: '#/definitions/ResourceCreated'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/definitions/Error'
security:
- OAuth 2:
- Review
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
$ref: '#/definitions/Review'
components:
schemas:
Customer:
description: Customer for the order - DEPRECATED - Please use the BillingAddress
and/or ShippingAddress fields instead.
type: object
properties:
address:
$ref: '#/definitions/Address'
description: Address of customer
birthday:
format: date-time
description: Customer birthdate
type: string
customerNumber:
description: Internal customer number
maxLength: 20
minLength: 0
type: string
email:
description: Email address of customer. This property is required for accounts
that are not CRM enabled.
maxLength: 100
minLength: 0
type: string
firstName:
description: First name
maxLength: 50
minLength: 0
type: string
gender:
description: Gender of customer (M/F, Male/Female)
maxLength: 50
minLength: 0
type: string
homePhone:
description: Landline phone number
maxLength: 50
minLength: 0
type: string
lastName:
description: Last name
maxLength: 50
minLength: 0
type: string
loyalty:
$ref: '#/definitions/Loyalty'
description: Loyalty data
meta1:
description: Additional meta information
maxLength: 250
minLength: 0
type: string
meta2:
description: Additional meta information
maxLength: 250
minLength: 0
type: string
meta3:
description: Additional meta information
maxLength: 250
minLength: 0
type: string
meta4:
description: Additional meta information
maxLength: 250
minLength: 0
type: string
meta5:
description: Additional meta information
maxLength: 250
minLength: 0
type: string
mobilePhone:
description: Mobile phone number
maxLength: 50
minLength: 0
type: string
preferredStoreNumber:
description: Preferred brick and mortar store location
maxLength: 100
minLength: 0
type: string
registered:
description: Indicates the customer registration state
type: boolean
social:
$ref: '#/definitions/Social'
description: Social data
workPhone:
description: Work phone number
maxLength: 50
minLength: 0
type: string
zipCode:
description: Customer ZIP Code
maxLength: 20
minLength: 0
type: string
Address:
description: Address of customer
type: object
properties:
address1:
description: Home address line 1
maxLength: 100
minLength: 0
type: string
address2:
description: Home address line 2
maxLength: 100
minLength: 0
type: string
address3:
description: Home address line 3
maxLength: 100
minLength: 0
type: string
city:
description: Home address city
maxLength: 100
minLength: 0
type: string
country:
description: Home address country
maxLength: 100
minLength: 0
type: string
state:
description: Home address state
maxLength: 100
minLength: 0
type: string
Loyalty:
description: Loyalty data for a Customer (This data will only be imported into
Listrak if there is an active loyalty integration setup for your account.)
type: object
properties:
activeLoyaltyMember:
description: Whether customer is an active loyalty member
type: boolean
availablePoints:
format: int32
description: Available points
type: integer
currentTierLevel:
description: Current tier level
maxLength: 100
minLength: 0
type: string
enrollDate:
format: date-time
description: Enrollment date/time
type: string
expiringPoints:
format: int32
description: Expiring points
type: integer
lastActivityDate:
format: date-time
description: Last activity date
type: string
lastPointEarnedDate:
format: date-time
description: Last date points were earned
type: string
lastPointRedemptionDate:
format: date-time
description: Last date points were redeemed
type: string
lifetimePoints:
format: int32
description: Lifetime points
type: integer
loyaltySignUpSource:
description: Sign-up source
maxLength: 100
minLength: 0
type: string
monthlyPoints:
format: int32
description: Monthly points
type: integer
nextTierLevel:
description: Next tier level
maxLength: 100
minLength: 0
type: string
numberOfReferrals:
format: int32
description: Number of referrals
type: integer
pendingPoints:
format: int32
description: Pending points
type: integer
personOfReferred:
description: Referrer of this customer
maxLength: 250
minLength: 0
type: string
pointExpirationDate:
format: date-time
description: Points expiration date
type: string
pointsToNext:
format: int32
description: Points to next milestone
type: integer
referralCode:
description: Referral code
maxLength: 100
minLength: 0
type: string
referralUrl:
description: Referral URL
maxLength: 250
minLength: 0
type: string
rewardsAvailable:
description: Rewards available
maxLength: 250
minLength: 0
type: string
rewardsClaimed:
description: Rewards claimed
maxLength: 250
minLength: 0
type: string
rewardsID:
description: Rewards ID
maxLength: 250
minLength: 0
type: string
spentPoints:
format: int32
description: Spent points
type: integer
tierID:
description: Tier ID
maxLength: 100
minLength: 0
type: string
weeklyPoints:
format: int32
description: Weekly points
type: integer
Social:
description: Social data for a Customer
type: object
properties:
facebookID:
description: Facebook ID
maxLength: 100
minLength: 0
type: string
facebookNumberOfFriends:
format: int32
description: Number of Facebook friends
type: integer
instagramID:
description: Instagram ID
maxLength: 100
minLength: 0
type: string
instagramNumberOfFollowers:
format: int32
description: Number of Instagram followers
type: integer
twitterID:
description: Twitter ID
maxLength: 100
minLength: 0
type: string
twitterNumberOfFollowers:
format: int32
description: Number of Twitter followers
type: integer
ResourceCreated:
type: object
properties:
status:
format: int32
description: HTTP status code.
type: integer
resourceId:
description: An identifier used to locate a resource.
type: string
Error:
type: object
properties:
status:
format: int32
description: HTTP status code.
type: integer
error:
description: Error code indicating what error has occured.
type: string
message:
description: Message describing the status and the error that occurred.
type: string
Order:
description: An order resource
required:
- orderNumber
type: object
properties:
associateID:
description: Associate ID of order
type: string
billingAddress:
$ref: '#/definitions/BillingAddress'
description: Billing address of order
couponCode:
description: Coupon code used with order
maxLength: 32
minLength: 0
type: string
customer:
$ref: '#/definitions/Customer'
description: Customer of order
customerNumber:
description: Internal customer number
maxLength: 20
minLength: 0
type: string
dateEntered:
format: date-time
description: Timestamp of order date (ET)
type: string
discountTotal:
format: double
description: DEPRECATED as of March 2022
type: number
email:
description: Email address of customer. This property is required for accounts
that are not CRM enabled.
maxLength: 100
minLength: 0
type: string
handlingTotal:
format: double
description: Total handling costs
type: number
items:
description: Order items
type: array
items:
$ref: '#/definitions/OrderItem'
itemTotal:
format: double
description: Total cost of items ordered (subtotal)
type: number
merchandiseDiscount:
format: double
description: Discount applied to the merchandise of the order
type: number
merchandiseDiscountDescription:
description: Description of the discount applied to the merchandise of the
order
type: string
merchandiseDiscountType:
description: Type of discount applied to the merchandise of the order
enum:
- NotSet
- PriceOverride
- PriceRule
- Promotion
- SeniorCitizen
- Markdown
- Coupon
- QuantityDiscount
- Rebate
- CashDiscount
- TradeDiscount
- TradeInKind
- PromptPaymentDiscount
- GeneralDiscount
- GiftVoucher
- FlexibleDiscount
- RewardProgram
- ManufacturerReward
- CreditCardReward
type: string
meta1:
description: Additional meta information
maxLength: 500
minLength: 0
type: string
meta2:
description: Additional meta information
maxLength: 500
minLength: 0
type: string
meta3:
description: Additional meta information
maxLength: 500
minLength: 0
type: string
meta4:
description: Additional meta information
maxLength: 500
minLength: 0
type: string
meta5:
description: Additional meta information
maxLength: 500
minLength: 0
type: string
nonMerchandiseDiscount:
format: double
description: Discounts applied to the order that is not related to the merchandise
type: number
nonMerchandiseDiscountDescription:
description: Description of the discount applied to the order not related
to the merchandise
type: string
nonMerchandiseDiscountType:
description: Type of discount applied to the order not related to the merchandise
enum:
- NotSet
- PriceOverride
- PriceRule
- Promotion
- SeniorCitizen
- Markdown
- Coupon
- QuantityDiscount
- Rebate
- CashDiscount
- TradeDiscount
- TradeInKind
- PromptPaymentDiscount
- GeneralDiscount
- GiftVoucher
- FlexibleDiscount
- RewardProgram
- ManufacturerReward
- CreditCardReward
type: string
orderNumber:
description: Unique order number
maxLength: 50
minLength: 0
type: string
orderTotal:
format: double
description: Total value of order
type: number
shipDate:
format: date-time
description: Timestamp when entire order shipped (ET)
type: string
shippingAddress:
$ref: '#/definitions/ShippingAddress'
description: Shipping address of order
shippingMethod:
description: Shipping method (e.g. UPS Ground)
maxLength: 32
minLength: 0
type: string
shippingTotal:
format: double
description: Total shipping costs
type: number
source:
description: Describes the source at which the order was placed (online,
POS, etc.)
maxLength: 25
minLength: 0
type: string
status:
description: Status indicator
enum:
- NotSet
- Misc
- PreOrder
- BackOrder
- Pending
- Hold
- Processing
- Shipped
- Completed
- Returned
- Canceled
- Unknown
- Closed
type: string
storeNumber:
description: Brick and mortar store location
maxLength: 100
minLength: 0
type: string
taxTotal:
format: double
description: Total sales tax charged
type: number
trackingNumber:
description: Shipment tracking number
maxLength: 32
minLength: 0
type: string
BillingAddress:
description: Billing address of order
type: object
properties:
firstName:
description: First name
type: string
lastName:
description: Last name
type: string
mobilePhone:
description: Mobile phone number
type: string
phone:
description: Phone number
type: string
zipCode:
description: Home address ZIP Code
type: string
address1:
description: Home address line 1
maxLength: 100
minLength: 0
type: string
address2:
description: Home address line 2
maxLength: 100
minLength: 0
type: string
address3:
description: Home address line 3
maxLength: 100
minLength: 0
type: string
city:
description: Home address city
maxLength: 100
minLength: 0
type: string
country:
description: Home address country
maxLength: 100
minLength: 0
type: string
state:
description: Home address state
maxLength: 100
minLength: 0
type: string
OrderItem:
description: An order resource
required:
- orderNumber
- sku
type: object
properties:
discountDescription:
description: Description of the discount for the line item
type: string
discountType:
description: Type of discount for the line item
enum:
- NotSet
- PriceOverride
- PriceRule
- Promotion
- SeniorCitizen
- Markdown
- Coupon
- QuantityDiscount
- Rebate
- CashDiscount
- TradeDiscount
- TradeInKind
- PromptPaymentDiscount
- GeneralDiscount
- GiftVoucher
- FlexibleDiscount
- RewardProgram
- ManufacturerReward
- CreditCardReward
type: string
discountedPrice:
format: double
description: Total discounted cost of product
type: number
itemTotal:
format: double
description: Total line item cost (quantity times price)
type: number
itemDiscountTotal:
format: double
description: Total amount of the discount for the line item
type: number
meta1:
description: Additional Optional Information
maxLength: 500
minLength: 0
type: string
meta2:
description: Additional Optional Information
maxLength: 500
minLength: 0
type: string
meta3:
description: Additional Optional Information
maxLength: 500
minLength: 0
type: string
meta4:
description: Additional Optional Information
maxLength: 500
minLength: 0
type: string
meta5:
description: Additional Optional Information
maxLength: 500
minLength: 0
type: string
orderNumber:
description: Order number
maxLength: 50
minLength: 0
type: string
price:
format: double
description: Price of one unit purchased
type: number
quantity:
format: int32
description: Total number of units purchased
type: integer
shipDate:
format: date-time
description: Timestamp when item shipped (ET)
type: string
shippingMethod:
description: Shipping method (e.g. UPS Ground)
maxLength: 32
minLength: 0
type: string
sku:
description: Unique stock number of product
maxLength: 100
minLength: 0
type: string
status:
description: Status indicator
enum:
- NotSet
- Misc
- PreOrder
- BackOrder
- Pending
- Hold
- Processing
- Shipped
- Completed
- Returned
- Canceled
- Unknown
- Closed
type: string
trackingNumber:
description: Shipment tracking number
maxLength: 32
minLength: 0
type: string
ShippingAddress:
description: Shipping address of order
type: object
properties:
firstName:
description: First name
maxLength: 50
minLength: 0
type: string
lastName:
description: Last name
maxLength: 50
minLength: 0
type: string
phone:
description: Phone number
type: string
zipCode:
description: Home address ZIP Code
type: string
address1:
description: Home address line 1
maxLength: 100
minLength: 0
type: string
address2:
description: Home address line 2
maxLength: 100
minLength: 0
type: string
address3:
description: Home address line 3
maxLength: 100
minLength: 0
type: string
city:
description: Home address city
maxLength: 100
minLength: 0
type: string
country:
description: Home address country
maxLength: 100
minLength: 0
type: string
state:
description: Home address state
maxLength: 100
minLength: 0
type: string
Product:
description: A product resource
required:
- sku
type: object
properties:
alternateImagesType1:
description: Alternate product images
type: array
items:
$ref: '#/definitions/AlternateImage'
alternateImagesType2:
description: Alternate product images
type: array
items:
$ref: '#/definitions/AlternateImage'
alternateImagesType3:
description: Alternate product images
type: array
items:
$ref: '#/definitions/AlternateImage'
brand:
description: Brand name of product
maxLength: 50
minLength: 0
type: string
category:
description: Category or department
maxLength: 50
minLength: 0
type: string
color:
description: Color of product (e.g. green, paisley, etc.)
maxLength: 100
minLength: 0
type: string
description:
description: Description of product
maxLength: 4000
minLength: 0
type: string
discontinued:
description: Explicit indicator that the item has been discontinued
type: boolean
gender:
description: Gender of product (if applicable)
maxLength: 50
minLength: 0
type: string
imageUrl:
description: URL for product image
maxLength: 500
minLength: 0
type: string
inStock:
description: Explicit indicator that the item is in stock
type: boolean
isClearance:
description: Explicit indicator that the item is a clearance item
type: boolean
isOutlet:
description: Explicit indicator that the item is an outlet item
type: boolean
isPurchasable:
description: Explicit indicator that the item can be included in recommendations
type: boolean
isViewable:
description: Flag used in some systems to determine if the item should be
included in recommendations
type: boolean
linkUrl:
description: URL for product webpage
maxLength: 500
minLength: 0
type: string
masterSku:
description: Unique stock number of the master product
maxLength: 100
minLength: 0
type: string
meta1:
description: Additional meta information
maxLength: 500
minLength: 0
type: string
meta2:
description: Additional meta information
maxLength: 500
minLength: 0
type: string
meta3:
description: Additional meta information
maxLength: 500
minLength: 0
type: string
meta4:
description: Additional meta information
maxLength: 500
minLength: 0
type: string
meta5:
description: Additional meta information
maxLength: 500
minLength: 0
type: string
msrp:
format: double
description: Retail price of the product
type: number
onSale:
description: Explicit indicator that the item is on sale
type: boolean
price:
format: double
description: List price of product
type: number
qoh:
format: int32
# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/listrak/refs/heads/main/openapi/listrak-data-openapi.yml