Historical order import API (v0)

Download OpenAPI specification:Download

Past orders which have already been fulfilled, outside or before implementation on NewStore are called Historical orders.

Following are the few APIs that can be used to import past orders while on-boarding tenants or setting up a new fulfillment location.

Import historical orders

Use this API to import complete historical orders into NewStore.

This API can only be called 500 times in a minute and each request can handle not more than 250 orders.

Notes:

The imported historical orders are placed in a queue that is shared between all NewStore tenants and processed based on the timestamp when they entered the queue. Depending on the number of historical orders imported it can take some time to process the queue. The imported historical orders are processed from the queue with a rate of upto 250 orders per minute.
The product_ids inside shipments -> items are currently not validated against the catalog and the historical order import will work even if the product does not exist in the catalog. Please make sure to have your products imported before starting the import.
When creating the customer profile, we will use the phone number that is stored inside the billing address. If this 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.
When creating a shipping or billing address for a customer profile, we will attempt to convert the provided phone number to E.164 format using the country code from the address. If the conversion fails, we will retain and use the original phone number as provided in the address. It can be updated later, if needed.
Any imported historical order is marked as Complete in NOM.

Authorizations:

newStoreAccessToken

Request Body schema: application/json

required

Array of objects <= 250 items

Array (<= 250 items)

external_id required	string [ 1 .. 64 ] characters
placed_at required	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).
store_id	string <= 256 characters ID of the store where this order was placed.
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.
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.
customer_email required	string <email> [ 1 .. 64 ] characters
shop_locale required	string [ 1 .. 128 ] characters The locale of the customer used for the shop, in RFC 5646.
shop required	string [ 1 .. 128 ] characters The shop containing the items of the order.
required	object
required	object The name and phone number provided in the billing address will be used to create a customer profile for this order.
required	Array of objects <= 40 items
price_method required	string Enum: "tax_included" "tax_excluded" Specifies if all items and shipping prices include tax or not.
required	Array of objects
	Array of objects <= 100 items [ items <= 2 properties ] Extra information about the order, which is propagated through NewStore applications.

Responses

Request samples

Payload

Content type

application/json

{"orders": [{"external_id": "HISTORIC_ORDER_123",
"placed_at": "2018-10-08T07:06:08.067Z",
"channel_type": "mobile",
"channel_name": "android app",
"currency": "USD",
"customer_email": "jw@example.com",
"shop_locale": "en-US",
"shop": "storefront-catalog-en",
"shipping_address": {"first_name": "Jay",
"last_name": "Doubleyou",
"country": "US",
"zip_code": "02111",
"city": "Boston",
"state": "Massachusetts",
"address_line_1": "601 South Street",
"address_line_2": "",
"phone": "202-555-0140"
},
"billing_address": {"first_name": "Jay",
"last_name": "Doubleyou",
"country": "US",
"zip_code": "02111",
"city": "Boston",
"state": "Massachusetts",
"address_line_1": "601 South Street",
"phone": "202-555-0140"
},
"payments": [{"instrument_id": "ch_1DIsE9GMCeo3G7b40EbEjfZX",
"amount": 68.66,
"method": "credit_card",
"wallet": "apple_pay",
"metadata": { },
"processed_at": "2018-10-08T07:06:08.067Z",
"adyen_merchant_account": "NewStorePOS",
"card_details": {"brand": "visa",
"last_four_digits": "1234"
}
},
{"instrument_id": "asdgretesg3tgdfAASdasd",
"amount": 126.11,
"method": "gift_card",
"processed_at": "2018-10-08T07:06:08.067Z"
}
],
"shipments": [{"items": [{"product_id": "1000011",
"product_name": "Short sleeve T-Shirt blue",
"status": "complete",
"external_item_id": "GD-10000001",
"price": {"item_price": 100.21,
"item_list_price": 100.21,
"item_tax_lines": [{"amount": 68.78,
"rate": 0.0758,
"name": "Custom Tax",
"country_code": "DE"
}
]
}
}
],
"shipping_option": {"service_level_identifier": "GROUND",
"shipping_type": "traditional_carrier",
"fulfillment_node_id": "DC01",
"shipping_carrier": "FedEx",
"display_name": "In store handover",
"price": 19,
"tax": 6.78,
"zip_code": "81379",
"country_code": "DE"
}
}
],
"price_method": "tax_excluded"
}
]
}

Response samples

200
400
405
415
500

Content type

application/json

Example

Historic order import successful.

{"status": "success"
}

Fetch historical order status

Use this API to fetch the status of an order that has been imported using the Import historical orders api.

Authorizations:

newStoreAccessToken

query Parameters

order_id

string

The external id of the imported order

Responses

Response samples

200
500

Content type

application/json

{"status": "pending"
}