Skip to main content
API docs by Redocly

Order Injection API (0.1)

Download OpenAPI specification:Download

Represents a current order or a historical order placed using an external system, identified by its external_id in NewStore. An order contains a list of shipments and the products in each shipment.

Create order

Creates an order in NewStore by importing an order placed via an external system. This is also referred as injecting an order.

Each request creates a single order in NewStore.

The request payload depends on the order you are creating. For example:

This method is idempotent, with regards to the external_id property. You can use the method multiple times to create the same order in the platform. The order itself is created only once, with the same response payload returned every time.

There can be transient errors (500) when creating an order, such as a timeout when communicating with the shipping provider. To fix these errors, retry the method again with the same payload.

Important:

  • Ensure that the request payload is same when creating an order with several tries. A retry with the same external_id but a different payload will fail.
  • Ensure that there is a small delay between each retry.
  • Only the 200 response implies that the order has been created correctly. Therefore, ensure that your integration has a retry logic set up.

For more information, see the request examples and Importing orders.

Configuration There are two configuration settings that impact injection flow: big_sales_order and skip_soft_routing_on_injection. For more information, see the page with all order_injection configuration.

Notes:

  • Ensure that you specify the correct number of decimal places for monetary values of prices, according to the specified currency. For example, if the currency is specified as USD and the price has more than 2 decimal places, it is considered as invalid by the platform. For more information, see pricing dependencies on currency.
  • To send payment-related metadata with the order, use the Create financial instrument method in the Payment Provider webhooks.
  • The validity of a shipping offer token can vary based on the shipping provider and shipping offer. For in-store pickup orders, a shipping offer token does not expire.
  • If you set shipments[].shipment_option.routing_strategy as "external" and the routing failed to communicate with shipping provider, the order will be cancelled. Check shipping provider integration, if you have customer integration, otherwise contact team delivery for support.
  • If the customer's phone number does not have a country calling code, the platform will attempt to use the billing address country code to derive the calling code while formatting the phone number to the E.164 standard. If the phone number cannot be formatted, it will be placed in the extended attribute injected-invalid-phone-number on customer profile. It can be updated later, if needed.
Authorizations:
newStoreAccessToken
Request Body schema: application/json
external_id
required
string [ 1 .. 64 ] characters
shop
required
string [ 1 .. 128 ] characters

The shop containing the items of the order.

channel_type
required
string
Enum: "web" "mobile" "store"
channel_name
required
string [ 1 .. 64 ] characters

A string used to distinguish between various sources of orders.

store_id
string <= 256 characters

ID of the store where this order was placed.

associate_id
string <= 256 characters

ID of the store associate who processed this order.

customer_name
string [ 1 .. 128 ] characters
customer_email
string [ 1 .. 64 ] characters
shop_locale
required
string [ 1 .. 128 ] characters

The locale of the customer used for the shop, in RFC 5646.

customer_language
string <= 2 characters

Language code according to ISO 639-1 to be used in the communication with the consumer (e.g. 'de', 'en' or 'fr')

external_customer_id
string <= 64 characters
placed_at
string <date-time>

Date representation of when the order was placed, containing date, time and timezone as defined by https://tools.ietf.org/html/rfc3339 (ISO 8601).

string or string
object
required
Array of objects or objects [ 1 .. 5 ] items
Array of objects <= 100 items [ items <= 2 properties ]
object
Array of objects <= 40 items
price_method
string
Enum: "tax_included" "tax_excluded"

Specifies if all item and shipping prices include tax or not.

is_preconfirmed
boolean
Default: false

Set to true, if the customer was already notified about order being placed. This is always true for in-store orders.

is_fulfilled
boolean
Default: false

Set to true if the order was already fulfilled. It is either an in-store purchase, or the order was fulfilled by an external system.

is_offline
boolean
Default: false

Set to true if the order was handled offline. It is an in-store purchase with internet connection failure.

is_historical
boolean
Default: false

Set to true if the order is historical was created and fulfilled by an external system.

notification_blacklist
Array of strings

Excludes the specified notifications from being sent to the customer.

currency
required
string
Enum: "AED" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AUD" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BOV" "BRL" "BSD" "BTN" "BWP" "BYN" "BZD" "CAD" "CDF" "CHE" "CHF" "CHW" "CLF" "CLP" "CNY" "COP" "COU" "CRC" "CUC" "CUP" "CVE" "CZK" "DJF" "DKK" "DOP" "DZD" "EGP" "ERN" "ETB" "EUR" "FJD" "FKP" "GBP" "GEL" "GHS" "GIP" "GMD" "GNF" "GTQ" "GYD" "HKD" "HNL" "HRK" "HTG" "HUF" "IDR" "ILS" "INR" "IQD" "IRR" "ISK" "JMD" "JOD" "JPY" "KES" "KGS" "KHR" "KMF" "KPW" "KRW" "KWD" "KYD" "KZT" "LAK" "LBP" "LKR" "LRD" "LSL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MOP" "MRU" "MUR" "MVR" "MWK" "MXN" "MXV" "MYR" "MZN" "NAD" "NGN" "NIO" "NOK" "NPR" "NZD" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PLN" "PYG" "QAR" "RON" "RSD" "RUB" "RWF" "SAR" "SBD" "SCR" "SDG" "SEK" "SGD" "SHP" "SLL" "SOS" "SRD" "SSP" "STN" "SVC" "SYP" "SZL" "THB" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TWD" "TZS" "UAH" "UGX" "USD" "USN" "UYI" "UYU" "UYW" "UZS" "VES" "VND" "VUV" "WST" "XAF" "XAG" "XAU" "XBA" "XBB" "XBC" "XBD" "XCD" "XDR" "XOF" "XPD" "XPF" "XPT" "XSU" "XTS" "XUA" "XXX" "YER" "ZAR" "ZMW" "ZWL"

The currency for all the prices contained within this payload.

Responses

Request samples

Content type
application/json
Example

From a mobile customer app with notifications suppressed. To send payment-related metadata with the order, use the Create financial instrument method.

{
  • "external_id": "INJECTED_regular-123456",
  • "placed_at": "2018-10-08T07:06:08.067Z",
  • "shop": "storefront-catalog-en",
  • "store_id": "807b05a4-5554-5302-a67f-aa3293107e92",
  • "associate_id": "3045c2140d2e4a5ba0f2ddc0a27d8798",
  • "channel_type": "mobile",
  • "channel_name": "retailer android app",
  • "currency": "USD",
  • "customer_name": "Jay Doubleyou",
  • "customer_email": "jw@example.com",
  • "shop_locale": "en-US",
  • "customer_language": "EN",
  • "external_customer_id": "CON0962868711",
  • "notification_blacklist": [
    ],
  • "shipping_address": {
    },
  • "billing_address": {
    },
  • "shipments": [
    ],
  • "payments": [
    ],
  • "price_method": "tax_excluded"
}

Response samples

Content type
application/json
{
  • "schema": {
    }
}