Order API

Intro

The Order API is intended to collect order/shipment data used to generate SMARTSlips® in line with their business processes.

The API is only made up of a single POST endpoint through which clients can submit their data programmatically.

Order API URLs

Production

https://orders.smartslip.io/

Beta

https://orders-beta.smartslip.io/

Authentication

Treat the API key and API password like you would any other password, since whoever has access to these credentials has full API access.

To interact with the Retain.me Order API, your application must provide the necessary authentication credentials on each HTTP request to the Retain.me Order API. The way to provide these credentials is more or less the same with which ever tech stack you choose to use.

Applications can interact with the Retain.me Order API via basic HTTP authentication over SSL. The required credentials must be generated/requested from the Retain.Me team and can be regenerated upon request.

Applications authenticate through basic HTTP authorization, where the API key of the application is the username, and the API Password is the password.

Some HTTP clients support basic authentication by prepending username:password to the hostname in the URL. For example:

POST 45634643FGDFGFDG:hfcdethuzzjhg54 @'https://orders-beta.smartslip.io/api/v2/orders'

If your HTTP client doesn't support basic authentication using this method, then you can provide the credentials in the Authorization header field instead:

Join the API key and API password with a single colon (:). Encode the resulting string in base64 representation. Prepend the base64-encoded string with Basic and a space:

Authorization: Basic NDQ3OGViN2FjMTM4YTEzNjg1MmJhYmQ4NjE5NTZ...=

API Requests

POST/api/v2/orders

Body

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

idstring

order_number*string

order_created_at*string

batch_idstring

total_pricenumber (double)

subtotal_pricenumber (double)

total_shipping_pricenumber (double)

total_taxnumber (double)

tax_ratenumber (double)

currencystring

total_discountsnumber (double)

total_products_pricenumber (double)

shipping_methods*array of ShippingMethod (object)

shipments*array of Shipment (object)

customer*all of

billing_addressall of

order_offersarray of OrderOffer (object)

products*array of Product (object)

recommendationsarray of Recommendation (object)

languagestring

reviewsarray of Review (object)

document_barcodestring

internal_document_idstring

wh_document_idstring

nearest_store_line_1string

nearest_store_line_2string

nearest_store_line_3string

nearest_store_line_4string

nearest_store_citystring

nearest_store_postal_codestring

nearest_store_country_codestring

nearest_store_phonestring

customer_service_emailstring

customer_service_phonestring

customer_service_twitterstring

customer_service_address_line_1string

customer_service_address_line_2string

customer_service_address_line_3string

customer_service_address_line_4string

customer_service_address_line_5string

customer_service_postal_codestring

returns_emailstring

returns_phonestring

returns_twitterstring

returns_address_line_1string

returns_address_line_2string

returns_address_line_3string

returns_address_line_4string

returns_address_line_5string

returns_postal_codestring

final_dispatchstring

review_percentstring

review_populationstring

review_urlstring

custom_1string

custom_2string

custom_3string

custom_4string

custom_5string

custom_6string

custom_7string

custom_8string

custom_9string

custom_10string

custom_11string

custom_12string

custom_13string

custom_14string

custom_15string

custom_16string

custom_17string

custom_18string

custom_19string

custom_20string

partner_idstring

returns_urlstring

tagsstring

sourcestring

giftall of

Response

200

Success

Request

JavaScriptCurlPython

const response = await fetch('/api/v2/orders', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json-patch+json"
    },
    body: JSON.stringify([
      {
        "customer": {
          "customer_id": "text"
        },
        "order_created_at": "text",
        "order_number": "text",
        "products": [
          {
            "product_id": "text",
            "shipment_id": "text"
          }
        ],
        "shipments": [
          {
            "shipment_id": "text",
            "shipping_method_id": "text"
          }
        ],
        "shipping_methods": [
          {
            "shipping_method_id": "text"
          }
        ]
      }
    ]),
});
const data = await response.json();

POST/api/v3/orders

Body

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

idstring

order_number*string

order_created_at*string

batch_idstring

total_pricenumber (double)

subtotal_pricenumber (double)

total_shipping_pricenumber (double)

total_taxnumber (double)

tax_ratenumber (double)

currencystring

total_discountsnumber (double)

total_products_pricenumber (double)

shipping_methods*array of ShippingMethod (object)

shipments*array of Shipment (object)

customer*all of

billing_addressall of

order_offersarray of OrderOffer (object)

products*array of Product (object)

recommendationsarray of Recommendation (object)

languagestring

reviewsarray of Review (object)

document_barcodestring

internal_document_idstring

wh_document_idstring

nearest_store_line_1string

nearest_store_line_2string

nearest_store_line_3string

nearest_store_line_4string

nearest_store_citystring

nearest_store_postal_codestring

nearest_store_country_codestring

nearest_store_phonestring

customer_service_emailstring

customer_service_phonestring

customer_service_twitterstring

customer_service_address_line_1string

customer_service_address_line_2string

customer_service_address_line_3string

customer_service_address_line_4string

customer_service_address_line_5string

customer_service_postal_codestring

returns_emailstring

returns_phonestring

returns_twitterstring

returns_address_line_1string

returns_address_line_2string

returns_address_line_3string

returns_address_line_4string

returns_address_line_5string

returns_postal_codestring

final_dispatchstring

review_percentstring

review_populationstring

review_urlstring

custom_1string

custom_2string

custom_3string

custom_4string

custom_5string

custom_6string

custom_7string

custom_8string

custom_9string

custom_10string

custom_11string

custom_12string

custom_13string

custom_14string

custom_15string

custom_16string

custom_17string

custom_18string

custom_19string

custom_20string

partner_idstring

returns_urlstring

tagsstring

sourcestring

giftall of

Response

200

Success

Request

JavaScriptCurlPython

const response = await fetch('/api/v3/orders', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json-patch+json"
    },
    body: JSON.stringify([
      {
        "customer": {
          "customer_id": "text"
        },
        "order_created_at": "text",
        "order_number": "text",
        "products": [
          {
            "product_id": "text",
            "shipment_id": "text"
          }
        ],
        "shipments": [
          {
            "shipment_id": "text",
            "shipping_method_id": "text"
          }
        ],
        "shipping_methods": [
          {
            "shipping_method_id": "text"
          }
        ]
      }
    ]),
});
const data = await response.json();

Helpful Information

Customer names should be split into shipment.first_name / shipment.last_name in the shipment object so the first name can be used in a welcome message on the SMARTSlip® to the person the goods are being shipped to.

Gift messaging will be shown on the SMARTSlip® if the data is passed through in the order data. is_gift should be set to True in the JSON and gift_message should contain the gift message, ## is used to denote a carriage return in the current data flow.

A Customer ID should be populated in customer.customer_id.

Language content versions are triggered based on the contents of the shipment.country_code using ISO 3166 2 Alpha-2 codes, if a client requires multiple languages.

Transaction panel data as below, the barcode will be the data in order.order_number, shipment.custom_1 and order.custom_3 can be your references for the order/pick:-

A Transaction panel may contain as much or as little information as required by your Operation.

Example Transaction table layout

A SMARTSlip® may have detachable integrated labels for an outbound carriage and return carriage. In the Primary Data call to the Order API, outbound and inbound carrier labels can also be sent in the order/shipment JSON as base64 data here https://orders.smartslip.io/v2/Shipment, if required. This is an advanced integration which eliminates the need for label printers and potential mismatch and saves considerable time in the DC Operation.