Implementation Guide
Summary: Order Data API
You can use the Order API to fetch all of your order data, including personally identifiable information (PII) based on a range of dates in your query parameters. This is the most automated way to connect your order data with your CRM or third-party analytics and insight platforms.
Only orders that have reached their final state in the process will be returned, and represented by the following two (2) statuses, "completed" and "canceled". Returning only orders that have reached their final state offers the benefit of disregarding order status updates on your end and allows for fetching orders based on your last order's date as the start date in your date range query.
The Order Data API is available for all Enterprise level licenses. It is an add-on option for Growth Level licenses. If you do not have a license to it, please contact the Shoppable Sales team to sign up. salesteam@shoppable.com
Step 1: Authentication
All orders have Personal Identifiable Information (PII) data, due to the sensitivity of this data and due to our required compliance in accordance with our PCI certification, we can only share this information through server to server authentication. Prior to using the Order Range API you will need to get your access token, which is a tokenized value of a userID and password.
** If you haven't yet received your Order API credentials please reach out to your Customer Success Manager (CSM).
Auth Request
Order API Credentials (test):
userId: TEST
password: Test1234@!*&
API Endpoint:
POST: https://orders.shoppable.com:4433/auth
Request (all fields below are required)
{
"userId": "TEST",
"password": "Test1234@!*&"
}
Request parameters when generating your request along with some context:
| Name | Description |
| userId (string) | User id from the provided credentials |
| password (string) | Password from the provided credentials |
Response
[
{
"auth": Boolean,
"token": String,
"expire": Number
}
]
Response parameters when generating your request along with some context:
| Name | Description |
| auth (boolean) | Boolean for auth token token |
| token (string) | Token for Order API request access |
| expire (integer) | Timestamp for token's life |
Step 2: Orders
Now that you've received your authentication token from the authentication call in Step 1 you can use your token as an Authentication Bearer Token to fetch all of your orders within a given range of dates. In constructing your query you'll need to provide a startdate and an enddate.
**Please keep in mind that the dates need to be in ISO format.
API Endpoint:
REQUEST FORMAT: /orderData/{rows}/page/{page}/startdate/{startDate}/enddate/{endDate}
GET: https://orders.shoppable.com:4433/v4/orderData/100/page/0/startdate/2020-01-01T00:00:00.000Z/enddate/2021-02-10T00:00:00.000Z
***You can also add orders with the status "test" to the query by adding the url param of "test=true" to the endpoint.
GET: https://orders.shoppable.com:4433/v4/orderData/100/page/0/startdate/2020-01-01T00:00:00.000Z/enddate/2021-02-10T00:00:00.000Z?test=true
Request parameters when generating your request along with some context:
| Name | Description |
| x-access-token (header) | Token generated from Order API Auth Request |
| rows (path) (max 100) | Number of orders you want to be returned |
| page (path) | The page offset for the orders |
| startDate (path) | The starting date of the orders (use ISO Date Format) |
| endDate (path) | The ending date of the orders (use ISO Date Format) |
Response (if an item doesn't add to the cart it's due to the item being Out of Stock)
[
{
"order_number": String,
"order_date": String,
"campaign": String,
"update_date": String,
"order_status": String,
"partner_id": Number,
"total": String,
"shipping_total": String,
"id": Number,
"opt_in": Boolean,
"line_items": {
"item_total": String,
"merchants": [
{
"merchant": String,
"merchant_total": Number,
"commission_rate": Number,
"commission": String,
"products": [
{
"part_number": String,
"product_name": String,
"upc": String,
"brand": String,
"sku": String,
"title": String,
"quantity": Number,
"price": String,
"subtotal": Number,
"merchant": String,
"merchant_id": String,
"prevStatus": "String,
"lineitem_id": Number,
"lineitem_status": String,
}
]
}
]
},
"billing": {
"billing_first_name": String,
"billing_last_name": String,
"billing_postal_code": String,
"billing_state": String,
"billing_city": String,
"billing_street1": String,
"billing_street2": String,
"billing_company": String,
"billing_phone": String,
"billing_country": String,
"billing_email": String
},
"shipping": {
"shipping_first_name": String,
"shipping_country": String,
"shipping_last_name": String,
"shipping_postal_code": String,
"shipping_state": String,
"shipping_city": String,
"shipping_street1": String,
"shipping_street2": String,
"shipping_company": String,
"shipping_phone": String,
"shipping_email": String
}
}
]
Response parameters along with some context:
| order_number (string) | Order number for the entire order - includes all retailers and line items. |
| partner_id (integer) | minimum: 10000 maximum: 999999 Internal partner_id is related to staging/production token. |
| total (string) | Order Grand total for all line items. |
| shipping_total (string) | Shipping charges for this merchant’s line_items. |
| id (integer) | minimum: 10000 maximum: 999999 Order ID |
| billing_email (string) | The email on the billing address for the customer. |
| order_date (string) | Date order was placed. |
| order_status (string) |
|
| lineitem_status (string) |
|
| billing_first_name (string) | The first name on the billing address for the customer. |
| billing_last_name (string) | The last name on the billing address for the customer. |
| billing_postal_code (string) | Postal code for the billing address given by the customer during checkout. |
| billing_state (string) | State for the billing address given by the customer during checkout. |
| billing_city (string) | The city for the billing address given by the customer during checkout. |
| billing_street1 (string) | The street line 1 on the billing address given by the customer during checkout. |
| billing_street2 (string) | The street line 2 on the billing address given by the customer during checkout. |
| billing_company (string) | The company name on the billing address given by the customer during checkout. |
| billing_phone (string) | The phone number on the billing address given by the customer during checkout. |
| billing_country (string) | Country on the billing address given by the customer during checkout. |
| shipping_first_name (string) | The first name on the shipping address given by the customer during checkout. |
| shipping_country (string) | Country on the shipping address given by the customer during checkout. |
| shipping_last_name: | The last name on the shipping address given by the customer during checkout. |
| shipping_postal_code (string) | Postal code on the shipping address given by the customer during checkout. |
| shipping_state (string) | State on the shipping address given by the customer during checkout. |
| shipping_city (string) | City on the shipping address given by the customer during checkout. |
| shipping_street1 (string) | The street line 1 on the shipping address given by the customer during checkout. |
| shipping_street2 (string) | The street line 2 on the shipping address given by the customer during checkout. |
| shipping_company (string) | The company name on the shipping address given by the customer during checkout. |
| shipping_phone (string) | The phone number on the shipping address given by the customer during checkout. |
| shipping_email (string) | The email on the shipping address given by the customer during checkout |
| item_total (string) | The total amount for all line items in this order. This value is applied across retailers and will be the same value for all line items in a single order. |
| opt_in (string) | The boolean string that shows if the user subscribes to the email list. |
| part_number (string) | Shoppable's part number for the product. |
| merchant_order_id (string) | Order id provided by the merchant. |
| product_name (string) | Name of the item purchased. |
| upc (string) | UPC code for this specific product variation. |
| brand (string) | The brand name. |
| sku (string) | Shoppable's SKU for this line_item variation. |
| title (string) | Name of the item title. |
| quantity (string) | Merchant selling the product and the party handling shipping. |
| price (string) | Unit Price for this line_item. |
| subtotal (string) | Price*qty. |
| merchant (string) | Merchant selling the product and the party handling shipping. |
| merchant_id (string) |
Id of the merchant. |
| prevStatus (string) |
|
| lineitem_id (integer) | minimum: 10000 maximum: 999999 Shoppable's id for each line item. |
| lineitem_url (string) | Line item's product link. |
| lineitem_image_url (string) | Line item's product image link. |
| lineitem_color (string) | Line item's color variation. |
| lineitem_size (string) | Line item's size variation. |
| line_items (array) | Array of all Merchants included in the order |
| merchants (array) | Array of a Merchants items included in the order |
| commission_rate (integer) | minimum: 0 maximum: 100 Partner's commission rate. |
| commission (string) | Partner's commission. |
| merchant_total (string) | Total of the subtotal for each line item for this merchant. |
| tax (number) | Charged tax. |
| partner_name (string) | Partner name for the order. |
| partner_domain (string) | Partner domain that registered under the partner profile. |
Congrats! 🎉
You're now successfully fetching all of your order information. Please reach out to your assigned Customer Success Manager (CSM) if you have any questions or encounter any issues.