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

Body

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

idstringOptional

order_numberstringRequired

order_created_atstringRequired

batch_idstringOptional

total_pricenumber · doubleOptional

subtotal_pricenumber · doubleOptional

total_shipping_pricenumber · doubleOptional

total_taxnumber · doubleOptional

tax_ratenumber · doubleOptional

currencystringOptional

total_discountsnumber · doubleOptional

total_products_pricenumber · doubleOptional

customerall ofRequired

billing_addressall ofOptional

languagestringOptional

document_barcodestringOptional

internal_document_idstringOptional

wh_document_idstringOptional

nearest_store_line_1stringOptional

nearest_store_line_2stringOptional

nearest_store_line_3stringOptional

nearest_store_line_4stringOptional

nearest_store_citystringOptional

nearest_store_postal_codestringOptional

nearest_store_country_codestringOptional

nearest_store_phonestringOptional

customer_service_emailstringOptional

customer_service_phonestringOptional

customer_service_twitterstringOptional

customer_service_address_line_1stringOptional

customer_service_address_line_2stringOptional

customer_service_address_line_3stringOptional

customer_service_address_line_4stringOptional

customer_service_address_line_5stringOptional

customer_service_postal_codestringOptional

returns_emailstringOptional

returns_phonestringOptional

returns_twitterstringOptional

returns_address_line_1stringOptional

returns_address_line_2stringOptional

returns_address_line_3stringOptional

returns_address_line_4stringOptional

returns_address_line_5stringOptional

returns_postal_codestringOptional

final_dispatchstringOptional

review_percentstringOptional

review_populationstringOptional

review_urlstringOptional

custom_1stringOptional

custom_2stringOptional

custom_3stringOptional

custom_4stringOptional

custom_5stringOptional

custom_6stringOptional

custom_7stringOptional

custom_8stringOptional

custom_9stringOptional

custom_10stringOptional

custom_11stringOptional

custom_12stringOptional

custom_13stringOptional

custom_14stringOptional

custom_15stringOptional

custom_16stringOptional

custom_17stringOptional

custom_18stringOptional

custom_19stringOptional

custom_20stringOptional

partner_idstringOptional

returns_urlstringOptional

tagsstringOptional

sourcestringOptional

giftall ofOptional

Responses

200

Success

post

HTTPcURLJavaScriptPython

POST /api/v2/orders HTTP/1.1
Host: 
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 7668

[
  {
    "id": "text",
    "order_number": "text",
    "order_created_at": "text",
    "batch_id": "text",
    "total_price": 1,
    "subtotal_price": 1,
    "total_shipping_price": 1,
    "total_tax": 1,
    "tax_rate": 1,
    "currency": "text",
    "total_discounts": 1,
    "total_products_price": 1,
    "shipping_methods": [
      {
        "shipping_method_id": "text",
        "name": "text"
      }
    ],
    "shipments": [
      {
        "shipment_id": "text",
        "shipping_method_id": "text",
        "title": "text",
        "first_name": "text",
        "last_name": "text",
        "is_gift": true,
        "gift_message": "text",
        "address1": "text",
        "address2": "text",
        "address3": "text",
        "address4": "text",
        "city": "text",
        "country": "text",
        "output_id": "text",
        "zip_postalcode": "text",
        "phone": "text",
        "latitude": "text",
        "longitude": "text",
        "country_code": "text",
        "note": "text",
        "document_type_id": "text",
        "shipment_required_date": "text",
        "shipment_date": "text",
        "carrier_label_base_64": "text",
        "return_carrier_label_base_64": "text",
        "carrier_label_url": "text",
        "invoice": {
          "invoice_template_id": 1,
          "invoice_number": "text",
          "currency": "text",
          "from": "text",
          "to": "text",
          "invoice_date": "2025-05-18T00:06:44.375Z",
          "billing_Date": "2025-05-18T00:06:44.375Z",
          "due_date": "2025-05-18T00:06:44.375Z",
          "lines": [
            {
              "unit_price": 1,
              "shipping_rate_type": 0,
              "shipping_rate": 1,
              "shipping_value": 1,
              "recycling_fee": 1,
              "gift_price": 1,
              "gift_tax_price": 1,
              "tax_type": 0,
              "tax_rate": 1,
              "tax_value": 1,
              "discount_type": 0,
              "discount_rate": 1,
              "discount_value": 1,
              "net_total_price": 1,
              "total_price": 1,
              "order_line_reference": "text"
            }
          ],
          "gift_options_tax_price": 1,
          "gift_options_price": 1,
          "insurance_price": 1,
          "notes": "text",
          "settlement_rate_type": 0,
          "settlement_rate": 1,
          "settlement_value": 1,
          "settlement_days": 1,
          "shipping_rate_type": 0,
          "shipping_rate": 1,
          "shipping_value": 1,
          "Discount_rate_type": 0,
          "Discount_rate": 1,
          "Discount_value": 1,
          "tax_rate_type": 0,
          "tax_rate": 1,
          "tax_value": 1,
          "net_total_price": 1,
          "total_price": 1
        },
        "custom_1": "text",
        "custom_2": "text",
        "custom_3": "text",
        "custom_4": "text",
        "custom_5": "text",
        "custom_6": "text",
        "custom_7": "text",
        "custom_8": "text",
        "custom_9": "text",
        "custom_10": "text",
        "custom_11": "text",
        "custom_12": "text",
        "custom_13": "text",
        "custom_14": "text",
        "custom_15": "text",
        "custom_16": "text",
        "custom_17": "text",
        "custom_18": "text",
        "custom_19": "text",
        "custom_20": "text"
      }
    ],
    "customer": {
      "customer_id": "text",
      "customer_status": "text",
      "email": "text",
      "first_name": "text",
      "last_name": "text",
      "phone": "text",
      "mobile": "text",
      "last_order_date": "text",
      "age": "text",
      "gender": "text",
      "average_order_value": 1,
      "loyalty_is_member": "text",
      "loyalty_member_id": "text",
      "loyalty_points": "text",
      "loyalty_offer_code": "text",
      "loyalty_offer_description": "text",
      "loyalty_url": "text",
      "is_new": "text",
      "opt_in": true,
      "custom_1": "text",
      "custom_2": "text",
      "custom_3": "text",
      "custom_4": "text",
      "custom_5": "text",
      "custom_6": "text",
      "custom_7": "text",
      "custom_8": "text",
      "custom_9": "text",
      "custom_10": "text",
      "custom_11": "text",
      "custom_12": "text",
      "custom_13": "text",
      "custom_14": "text",
      "custom_15": "text",
      "custom_16": "text",
      "custom_17": "text",
      "custom_18": "text",
      "custom_19": "text",
      "custom_20": "text",
      "tags": "text"
    },
    "billing_address": {
      "first_name": "text",
      "last_name": "text",
      "address1": "text",
      "address2": "text",
      "address3": "text",
      "address4": "text",
      "city": "text",
      "country": "text",
      "province": "text",
      "zip_postalcode": "text",
      "phone": "text",
      "latitude": "text",
      "longitude": "text",
      "country_code": "text",
      "province_code": "text"
    },
    "order_offers": [
      {
        "offer_type": "text",
        "offer_code": "text",
        "offer_message_1": "text",
        "offer_message_2": "text",
        "offer_message_3": "text",
        "offer_message_4": "text",
        "offer_message_5": "text",
        "offer_message_6": "text",
        "offer_message_7": "text",
        "offer_message_8": "text",
        "offer_message_9": "text",
        "offer_message_10": "text",
        "offer_url": "text",
        "offer_amt_or_pct": "text",
        "offer_discount": 1,
        "offer_min_spend": 1,
        "offer_start_date": "text",
        "offer_expiry_date": "text",
        "offer_name": "text",
        "offer_language": "text",
        "offer_currency": "text",
        "terms_url": "text",
        "share_url": "text",
        "share_control_url": "text",
        "external_offer_id": "text",
        "custom_field_1": "text",
        "custom_field_2": "text",
        "custom_field_3": "text",
        "custom_field_4": "text",
        "custom_field_5": "text",
        "custom_field_6": "text",
        "custom_field_7": "text",
        "custom_field_8": "text",
        "custom_field_9": "text",
        "custom_field_10": "text",
        "custom_field_11": "text",
        "custom_field_12": "text",
        "custom_field_13": "text",
        "custom_field_14": "text",
        "custom_field_15": "text",
        "custom_field_16": "text",
        "custom_field_17": "text",
        "custom_field_18": "text",
        "custom_field_19": "text",
        "custom_field_20": "text"
      }
    ],
    "products": [
      {
        "product_id": "text",
        "name": "text",
        "imageurl": "text",
        "quantity": 1,
        "price": 1,
        "tax": 1,
        "shipment_id": "text",
        "color": "text",
        "size": "text",
        "brand": "text",
        "category": "text",
        "status": "text",
        "custom_1": "text",
        "custom_2": "text",
        "custom_3": "text",
        "custom_4": "text",
        "custom_5": "text",
        "custom_6": "text",
        "custom_7": "text",
        "custom_8": "text",
        "custom_9": "text",
        "custom_10": "text",
        "custom_11": "text",
        "custom_12": "text",
        "custom_13": "text",
        "custom_14": "text",
        "custom_15": "text",
        "custom_16": "text",
        "custom_17": "text",
        "custom_18": "text",
        "custom_19": "text",
        "custom_20": "text",
        "order_line_reference": "text",
        "tags": "text"
      }
    ],
    "recommendations": [
      {
        "product_id": "text",
        "long_description": "text",
        "short_description": "text",
        "callout_message": "text",
        "product_name": "text",
        "product_description": "text",
        "product_image": "text",
        "retail_price": 1,
        "custom_1": "text",
        "custom_2": "text",
        "custom_3": "text",
        "custom_4": "text",
        "custom_5": "text",
        "custom_6": "text",
        "custom_7": "text",
        "custom_8": "text",
        "custom_9": "text",
        "custom_10": "text",
        "custom_11": "text",
        "custom_12": "text",
        "custom_13": "text",
        "custom_14": "text",
        "custom_15": "text",
        "custom_16": "text",
        "custom_17": "text",
        "custom_18": "text",
        "custom_19": "text",
        "custom_20": "text"
      }
    ],
    "language": "text",
    "reviews": [
      {
        "review_url": "text",
        "product_id": "text",
        "current_reviews": 1,
        "current_service_rating": "text",
        "custom_1": "text",
        "custom_2": "text",
        "custom_3": "text",
        "custom_4": "text",
        "custom_5": "text",
        "custom_6": "text",
        "custom_7": "text",
        "custom_8": "text",
        "custom_9": "text",
        "custom_10": "text",
        "custom_11": "text",
        "custom_12": "text",
        "custom_13": "text",
        "custom_14": "text",
        "custom_15": "text",
        "custom_16": "text",
        "custom_17": "text",
        "custom_18": "text",
        "custom_19": "text",
        "custom_20": "text"
      }
    ],
    "document_barcode": "text",
    "internal_document_id": "text",
    "wh_document_id": "text",
    "nearest_store_line_1": "text",
    "nearest_store_line_2": "text",
    "nearest_store_line_3": "text",
    "nearest_store_line_4": "text",
    "nearest_store_city": "text",
    "nearest_store_postal_code": "text",
    "nearest_store_country_code": "text",
    "nearest_store_phone": "text",
    "customer_service_email": "text",
    "customer_service_phone": "text",
    "customer_service_twitter": "text",
    "customer_service_address_line_1": "text",
    "customer_service_address_line_2": "text",
    "customer_service_address_line_3": "text",
    "customer_service_address_line_4": "text",
    "customer_service_address_line_5": "text",
    "customer_service_postal_code": "text",
    "returns_email": "text",
    "returns_phone": "text",
    "returns_twitter": "text",
    "returns_address_line_1": "text",
    "returns_address_line_2": "text",
    "returns_address_line_3": "text",
    "returns_address_line_4": "text",
    "returns_address_line_5": "text",
    "returns_postal_code": "text",
    "final_dispatch": "text",
    "review_percent": "text",
    "review_population": "text",
    "review_url": "text",
    "custom_1": "text",
    "custom_2": "text",
    "custom_3": "text",
    "custom_4": "text",
    "custom_5": "text",
    "custom_6": "text",
    "custom_7": "text",
    "custom_8": "text",
    "custom_9": "text",
    "custom_10": "text",
    "custom_11": "text",
    "custom_12": "text",
    "custom_13": "text",
    "custom_14": "text",
    "custom_15": "text",
    "custom_16": "text",
    "custom_17": "text",
    "custom_18": "text",
    "custom_19": "text",
    "custom_20": "text",
    "partner_id": "text",
    "returns_url": "text",
    "tags": "text",
    "source": "text",
    "gift": {
      "is_gift": true,
      "giftor": "text",
      "giftee": "text",
      "gift_note": "text",
      "occasion": "text",
      "custom_1": "text",
      "custom_2": "text",
      "custom_3": "text",
      "custom_4": "text",
      "custom_5": "text"
    }
  }
]

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

200

Success

No content

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.