How do I set up Shoppable® Order Data API v4?

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

IMG_0395-1

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)
  • Complete: Order has been completed by Shoppable and sent to the merchant.
  • Canceled: Shoppable has canceled the order.
lineitem_status (string)
  • Invalid cc: CC has been rejected by the retailer.
  • Out of stock: This item is no longer in stock.
  • Invalid billing: Shipment has no tracking information for 7 days since added, or has no further updates for 30 days since the last update.
  • Invalid shipping: New shipments added that are pending to track, or new shipments without tracking information available yet.
  • Invalid payment: Payment info is invalid.
  • Invalid coupon: The order contains an invalid coupon.
  • Retailer attention: The retailer needs more information before processing the order.
  • Retailer processing: The retailer is processing.
  • Fraud detected: Fraud was detected.
  • Test: This is a test line item.
  • Invalid product info: The product information provided was invalid.
  • Returned: The product was returned to the merchant.
  • Attention required: This order requires attention.
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)
  • Complete: Order has been completed by shoppable and sent to the merchant
  • Pending: Shoppable is processing the order with the merchant
  • Canceled: Shoppable has canceled the order
  • Invalid cc: CC has been rejected by the retailer.
  • Out of stock: This item is no longer in stock.
  • Invalid billing: Shipment has no tracking information for 7 days since added, or has no further updates for 30 days since the last update.
  • Invalid shipping: New shipments added that are pending to track, or new shipments without tracking information available yet.
  • Invalid payment: Payment info is invalid.
  • Invalid coupon: The order contains an invalid coupon.
  • Retailer attention: The retailer needs more information before processing the order.
  • Retailer processing: The retailer is processing.
  • Fraud detected: Fraud was detected.
  • Test: This is a test line item.
  • Invalid product info: The product information provided was invalid.
  • Returned: The product was returned to the merchant.
  • Attention required: This order requires attention.
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.