OMS DOCUMENTATIONRESOURCE CENTER

These guides provide examples for many tasks that a developer will need to be familiar with during implementation.

KIBO OMS DEVELOPMENT

Documentation

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.

Version2.0
Callhttps://integration.shopatron.com/api/v2/importOrder/
Supported FormatsJSON
HTTP MethodPOST
Schemahttps://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.

ParameterTypeDescription
externalOrderIDstringA client-generated unique identifier for the order sent to OMS. The minimum length is 1 and the maximum length is 100.
manufacturerIDintegerA unique identifier for the manufacturer. The minimum value is “1”.
catalogIDintegerThe catalog number for the manufacturer. The minimum value is “0”.
localestringAn Internet Engineering Task Force code identifier consisting of information about the manufacturer’s language or region. The default is “en-US”.
currencyenumA International Standards Organization code indicating the currency of the order.
customerobjectThe customer purchasing the order.
orderItemsarrayThe list of items included with the order.
shippingMethodobjectThe method by which to ship the order.
shippingAddressobjectThe address that the order will be shipped to.
orderPaymentsarrayThe payment method and data used to purchase the order.
customerIPstringThe 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.
sendEmailbooleanWhether email(s) should be sent to customer regarding order status. The default is “true”.
orderStatusenumThe 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.

ParameterTypeDescription
orderIDintegerA unique identifier for the order. The minimum value is “1”.
importedCreationDatestringThe original date-time that the order was created, will override the import date as the created date for the order.
cartIDstringThe cart identifier from which this order originated. The maximum length is 512.
currencyLocalestringAn Internet Engineering Task Force code identifier consisting of information about the manufacturer’s language or region. The default is “en-US”.
orderGiftobjectGift information for the order. See the schema for the list of parameters associated with this object.
shippingTaxnumberThe amount of shipping tax to be applied. The minimum value is “0”.
shippingTaxRatenumberThe shipping tax rate to be applied. The minimum value is “0”.
forceItemTaxOverridebooleanWhether to override the calculated item tax and force the orderItem -> itemSpecifics -> itemTaxOverride to be required.
orderCommentstringThe customer-entered order comments field. The maximum length is 1000.
optInRetailerbooleanWhether the retailer can use the customer’s email address for marketing purposes.
landingCodestringUsed to identify the site or source of the order. The minimum length is 10 and the maximum length is 200.
customOrderDataobjectA hash of custom data to be associated with order, used for many purposes.
fraudDataarrayFraud information about the order. See the schema for the options to build this array, or refer to the External Fraud guide.
allowSplitbooleanWhether the order is allowed to be split into multiple shipments. The default is “false”.
isTestOrderbooleanWhether the order is a test order or not. The default is “false”.
expectedDeliveryDatestringThe expected date of delivery of the items on the order. It should be in date-time format.
promotionsarrayAny promotions that are applied to the order. See the schema for details.
discountsarrayAny discounts that are applied to the order. See the schema for details.
channelstringCustom channel of order creation.
assignedLocationstringThe external_store_id of the location the order is assigned to.
useInventorybooleanMarks 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 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
}