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:

1. The general type and class of shipping
2. 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
}