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
}