Historic Order Import
The Historic Order Import API enables manufacturers to import existing orders into OMS that have already been fulfilled or have begun the fulfillment process. Pre-existing cancelled orders and closed returns can also be loaded into OMS.
It is very similar in structure to the standard Create Order API call, but has a few different parameters and contexts as shown below.
| Version | 2.0 |
| Call | https://integration.shopatron.com/api/v2/importOrder/ |
| Supported Formats | JSON |
| HTTP Method | POST |
| Schema | https://integration.shopatron.com/api/v2/schema/importOrder.json |
The .json address above can be used to access the schema within Postman. An example use of the Historic Order Import API follows below, or view the schema or the sample Postman Collection.
Example
The example case creates an API call for a pre-existing order that has the following properties:
- Shipped non-inventory gift order
- Sent with standard shipping
- Paid for with a no-op payment type
- Accepted by the Kount fraud cartridge
- Currency – USD
- One order item
This guide will demonstrate how to put together each section of the request to build this order.
Required Parameters
These parameters are necessary for the Historic Order Import API to return a successful response. Note that the required parameter “orderStatus” is one of the elements that differs from the standard Create Order call. This value indicates whether the order being imported has been shipped, is in Ready state, or has been cancelled.
| Parameter | Type | Description |
| externalOrderID | string | A client-generated unique identifier for the order sent to OMS. The minimum length is 1 and the maximum length is 100. |
| manufacturerID | integer | A unique identifier for the manufacturer. The minimum value is “1”. |
| catalogID | integer | The catalog number for the manufacturer. The minimum value is “0”. |
| locale | string | An Internet Engineering Task Force code identifier consisting of information about the manufacturer’s language or region. The default is “en-US”. |
| currency | enum | A International Standards Organization code indicating the currency of the order. |
| customer | object | The customer purchasing the order. |
| orderItems | array | The list of items included with the order. |
| shippingMethod | object | The method by which to ship the order. |
| shippingAddress | object | The address that the order will be shipped to. |
| orderPayments | array | The payment method and data used to purchase the order. |
| customerIP | string | The unique external IP address (IPv4) of the customer purchasing the order. This should not be an internal IP address or the IP address of the web server. |
| sendEmail | boolean | Whether email(s) should be sent to customer regarding order status. The default is “true”. |
| orderStatus | enum | The status that the order is in at the time of import (SHIPPED, READY, or CANCELLED). |
Optional Parameters
Other possible parameters can be provided to specify other details about the order. Note that two more variables are unique to the Historic Order Import and do not appear in the standard Create Order call. The Assigned Location is used to indicate the location where an order that has already been assigned belongs, and Use Inventory marks the order as either inventory or non-inventory.
If the order is imported without a specified orderCreationDate, then the date will be automatically set as the time of import. If this parameter is provided, then it will override that automatic assignment and allow the original date of order creation to be set.
| Parameter | Type | Description |
| orderID | integer | A unique identifier for the order. The minimum value is “1”. |
| importedCreationDate | string | The original date-time that the order was created, will override the import date as the created date for the order. |
| cartID | string | The cart identifier from which this order originated. The maximum length is 512. |
| currencyLocale | string | An Internet Engineering Task Force code identifier consisting of information about the manufacturer’s language or region. The default is “en-US”. |
| orderGift | object | Gift information for the order. See the schema for the list of parameters associated with this object. |
| shippingTax | number | The amount of shipping tax to be applied. The minimum value is “0”. |
| shippingTaxRate | number | The shipping tax rate to be applied. The minimum value is “0”. |
| forceItemTaxOverride | boolean | Whether to override the calculated item tax and force the orderItem -> itemSpecifics -> itemTaxOverride to be required. |
| orderComment | string | The customer-entered order comments field. The maximum length is 1000. |
| optInRetailer | boolean | Whether the retailer can use the customer’s email address for marketing purposes. |
| landingCode | string | Used to identify the site or source of the order. The minimum length is 10 and the maximum length is 200. |
| customOrderData | object | A hash of custom data to be associated with order, used for many purposes. |
| fraudData | array | Fraud information about the order. See the schema for the options to build this array, or refer to the External Fraud guide. |
| allowSplit | boolean | Whether the order is allowed to be split into multiple shipments. The default is “false”. |
| isTestOrder | boolean | Whether the order is a test order or not. The default is “false”. |
| expectedDeliveryDate | string | The expected date of delivery of the items on the order. It should be in date-time format. |
| promotions | array | Any promotions that are applied to the order. See the schema for details. |
| discounts | array | Any discounts that are applied to the order. See the schema for details. |
| channel | string | Custom channel of order creation. |
| assignedLocation | string | The external_store_id of the location the order is assigned to. |
| useInventory | boolean | Marks the order as an inventory order or not an inventory order. |
Primary Elements
The required elements of Customer, Order Items, Shipping Method, and Order Payments have their own parameters. The examples below apply to this example of the Historic Order Import, so see the schema for a full list of available parameters and alternate options to build the objects.
Customer
Much like the standard Create Order, the Customer can be identified with both IP information (which is its own parameter) and a block of code building the Customer object. It is important to note that the Customer IP is the external address of the consumer purchasing the order, NOT the internal address of the web server or client. The Customer IP is required for bundled clients, and providing the incorrect address will hinder the fraud review process.
Parameters for the Customer object are defined in the API request as shown below:
"customer": {
"customerID": null,
"firstName": "Test",
"lastName": "Customer",
"email": "testcustomer@kibocommerce.com",
"password": null,
"phone1": "0001110000",
"phone2": "1110001111",
"accountCreated": null
},Order Items
The following snippet shows the JSON array attached to this example call. Although there are a number of properties, the crucial elements in this structure include:
- Part Number
- Price and Quantity
- Name
See the schema for the full list of other require and optional elements in Order Items.
"orderItems": [
{
"product": {
"partNumber": "0123456",
"productID": null,
"availability": "Y",
"name": "Part 1",
"retailPrice": 2.00,
"averageDealerMargin": 0.30,
"UPC": "8989898989",
"SKU": "9898989898"
},
"itemSpecifics": {
"externalItemID": null,
"actualPrice": 1.00,
"quantity": 1,
"shipping": null,
"shippingTax": null,
"itemTaxOverride": 0,
"customItemData": {
"image_url": "http:/picture.jpeg"
},
"options": {
"color": "blue"
},
"customData": null
}
}
],Shipping Method
The segment that defines the shipping instructions for the order has two parts:
- The general type and class of shipping
- The address where the order will be shipped
This example shows an order with the Standard shipping type being shipped to 123 Elm Lane, San Luis Obispo, CA 93405, US. See the schema for a full list of possible parameters and values.
"shippingMethod": {
"shippingType": "standard",
"shippingClass": "Standard"
},
"shippingAddress": {
"addressID": null,
"customerID": null,
"addressLine1": "55 Example St",
"addressLine2": null,
"addressLine3": null,
"phone": "000-111-0000",
"city": "Phoenix",
"postalCode": "00000",
"state": "CA",
"countryCode": "US",
"latitude": null,
"longitude": null,
"fraudLock": false,
"active": false
},Order Payments
The Order Payments structure contains information about the way the customer is paying for the order. This piece of the API call must contain a valid billing address (which supports up to 250 characters per addressLine1, addressLine2, and addressLine3) and payment method. Possible payment types vary depending on implementation and should be verified before placing the call.
Some examples of paymentType:
- CC, CS, LV : Credit Card
- PP, EB: PayPal
- PZ: PayEezy
- NO: No-Operation
This example lists a credit card as the method of payment. See the schema for a full list of possible parameters and values.
"orderPayments": [
{
"orderPaymentID": null,
"paymentMethod": {
"billingAddress": {
"addressID": null,
"customerID": null,
"addressLine1": "15 Example Blvd.",
"addressLine2": null,
"addressLine3": null,
"phone": "000-111-2222",
"city": "Phoenix",
"postalCode": "93420",
"state": "CA",
"countryCode": "US",
"latitude": null,
"longitude": null,
"fraudLock": false,
"active": true
},
"paymentType":"NO",
"noOperationType":"HI",
"cardNumber":"0000000000000123"
},
"paymentMethodID": null,
"maxAmount": -1,
"transactionID": "12123",
"authorizationID": "48484",
"paymentType": null,
"authAmount": 20
}
],The Full Request
This is the entire request that will import an order.
{
"externalOrderID":"0987654321",
"manufacturerID":01010,
"catalogID":0,
"orderStatus":"SHIPPED",
"assignedLocation":"00000055",
"useInventory":false,
"locale":"en-US",
"currency":"USD",
"sendEmail":true,
"customer":{
"customerID":null,
"firstName":"Test",
"lastName":"Customer",
"email":"testcustomer@kibocommerce.com",
"password":null,
"phone1":"0001110000",
"phone2":"1110001111",
"accountCreated":null
},
"orderItems":[
{
"product":{
"partNumber":"0123456",
"productID":null,
"availability":"Y",
"name":"Part 1",
"retailPrice":2.00,
"averageDealerMargin":0.30,
"UPC":"8989898989",
"SKU":"9898989898"
},
"itemSpecifics":{
"externalItemID":null,
"actualPrice":1.00,
"quantity":1,
"shipping":null,
"shippingTax":null,
"itemTaxOverride":0,
"customItemData":{
"image_url":"http:/picture.jpeg"
},
"options":{
"color":"blue"
},
"customData":null
}
}
],
"shippingMethod":{
"shippingType":"standard",
"shippingClass":"Standard"
},
"shippingAddress":{
"addressID":null,
"customerID":null,
"addressLine1":"55 Example St",
"addressLine2":null,
"addressLine3":null,
"phone":"000-111-0000",
"city":"Phoenix",
"postalCode":"00000",
"state":"CA",
"countryCode":"US",
"latitude":null,
"longitude":null,
"fraudLock":false,
"active":false
},
"orderPayments":[
{
"orderPaymentID":null,
"paymentMethod":{
"billingAddress":{
"addressID":null,
"customerID":null,
"addressLine1":"15 Example Blvd.",
"addressLine2":null,
"addressLine3":null,
"phone":"000-111-2222",
"city":"Phoenix",
"postalCode":"93420",
"state":"CA",
"countryCode":"US",
"latitude":null,
"longitude":null,
"fraudLock":false,
"active":true
},
"paymentType":"NO",
"noOperationType":"HI",
"cardNumber":"0000000000000123"
},
"paymentMethodID":null,
"maxAmount":-1,
"transactionID":"12123",
"authorizationID":"48484",
"paymentType":null,
"authAmount":20
}
],
"customerIP":"0.0.0.0",
"orderID":null,
"shippingTax":2,
"forceItemTaxOverride":true,
"optInRetailer":true,
"landingCode":"TestLandingCode",
"customOrderData":{
"Custom Data Key 1":"Custom Data Value 001",
"Custom Data Key 2":"Custom Data Value 002",
"Custom Data Key 3":"Custom Data Value 003"
},
"fraudData":[
{
"fraudType":"KOUNT",
"fraudScore":350,
"fraudTransactionID":"ASDF324234142",
"fraudState":"ACCEPTED"
}
],
"allowSplit":true,
"orderGift":{
"recipient":"Test Customer",
"message":"this is the gift message0001"
},
"orderComment":null
}