KIBO OMS DOCUMENTATION

Create Order

After receiving authentication, the Create Order API is used to submit an order from a website into Kibo OMS. This call acts as the central API of the Customer Care Suite – all communication with Kibo OMS begins here. In order to query and manipulate orders, they must first be created. All APIs used to pull information about an order are used downstream from the Create Order API.

Version2.0
Callhttps://integration.shopatron.com/api/v2/createOrder/
Supported FormatsJSON
HTTP MethodPOST
Schemahttps://integration.shopatron.com/api/v2/schema/createOrder.json

The .json address above can be used to access the schema within Postman. An example use of the Create Order API follows below, or view the schema or the sample Postman Collection.

Example

The example case creates an API call for an order that has the following properties:

  • Currency – USD
  • Payment Type – Credit Card
  • Order Type – Gift
  • Two order items
  • Custom order and item data points

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 Create Order API to return a successful response:

ParameterTypeDescription
externalOrderIDstringA client-generated unique identifier for the order. The minimum length is 1 and the maximum length is 100.
manufacturerIDintegerA unique identifier for a manufacturer. The minimum value is "1".
catalogIDintegerThe catalog number for the manufacturer. The minimum value is "0".
localeenumAn Internet Engineering Task Force code indicating the location and language of the order. The default is "en-US".
currencyenumA International Standards Organization code indicating the currency of the order.
customerobjectThe customer purchasing the order.
orderItemsarrayThe items included in 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 IP address of the customer placing the order.
sendEmailbooleanWhether email(s) should be sent to customer regarding order status. The default is "true".

Optional Parameters

Other possible parameters can be provided to specify other details about the order. These variables are:

ParameterTypeDescription
cardIDstringThe 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.
carrierenumA specified carrier that will override the default for this order. The supported values are "FEDEX", "USPS", "UPS" and "FEDEX_CROSS_BORDER". Use with carrierType and serviceType.
carrierTypeenumA specified carrier type that will override the default for this order. The supported values are "US", "INTERNATIONAL", and "CANADA". Use with carrier and serviceType.
serviceTypeenumA specified service type that will override the default for this order. All available service types in OMS are supported (e.g. "UPS_NEXT_DAY_AIR", "FIRST_OVERNIGHT", and "INTERNATIONAL_ECONOMY") but they must be compatible with the associated carrier.
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.

Primary Elements

The required elements of Customer, Order Items, Shipping Method, and Order Payments have their own parameters. However, there are a few things to note in the initial block of Create Order data before delving deeper into those elements.

First, 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.

{
  "externalOrderID": "00000000-12345-54321",
  "manufacturerID": MFG_ID,
  "catalogID": CATALOG_ID,
  "locale": "en-US",
  "currency": "USD",
  "customerIP": "0.1.2.3."
}

Second, Kibo supports IETF codes to denote locales and languages for orders. These codes are listed below:

IETF CodeMeaningIETF CodeMeaningIETF CodeMeaning
en-USUS Englishde-DEGermannl-NLDutch
en-CACanadian Englishel-GRGreekno-NONorwegian
en-GBBritish Englishfr-CACanadian Frenchru-RURussian
en-HLHong Kong Englishfr-FRFrenchsv-SESwedish
en-INIndian Englishit-ITItalianzh-cmn-CNMandarin
es-ESSpanishja-JPJapanesezh-HANTTraditional Chinese
es-MXMexican Spanishko-KRKoreanzh-yue-CNCantonese

Likewise, ISO codes are used to refer to denote the currencies that orders are made in.

ISO CodeCurrencyISO CodeCurrencyISO CodeCurrency
USDUS DollarRUBRussian RubleUAHUkrainian Hryvnia
CADCanadian DollarMEXMexican PesoHUFHungarian Forint
GBPPound SterlingMXNMexican PesoIDRIndonesian Rupiah
CHFSwiss FrancEUREuroIRRIranian Rial
NOKNorwegian KroneDKKDanish KroneKWDKuwaiti Dinar
SEKSwedish KronaSGDSingapore DollarTWDNew Taiwan Dollar
HKDHong Kong DollarPLNPoland ZlotyQARQatari Rial
CNYYuan RenminbiRONRomanian LeuSARSaudi Riyal
JPYYenARSArgentine PesoTHBThai Baht
NZDNew Zealand DollarBRLBrazil RealAEDUAE Dirham
KRWSouth Korean WonHRKCroatian KunaAUDAustralian Dollar
INRIndian RupeeCZKCzech Koruna

Customer

The customer details can then be expanded upon with various properties from the Customer API. For this example, we use the following information:

"customer": {
  "customerID": null,
  "firstName": "Test",
  "lastName": "Customer",
  "email": "testemail@kibotest.com",
  "password": null,
  "phone1": "000-000-1111x000",
  "phone2": "0000000000",
  "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
  • Availability

In addition to these elements, custom data elements are used to send additional, non-structured data associated with the order items. Information such as serial numbers, warranty information, or any additional information in regards to the item can be included in the custom data part of the API call. See the schema for a full list of possible parameters and values.

The supported codes and definitions for the Availability parameter are listed below:

AvailabilityMeaningDescription
YYesProduct is in stock. This can proceed through the normal fulfillment process.
NNoProduct is not in stock but it may be in fulfiller inventory. The item can be backordered, and fulfillers can request the order if they have the item in stock.
LLimitedProduct is in stock but has limited availability. This will follow the normal fulfillment process.
MManufacturer Ship OnlyOrders with this product are always shipped by manufacturer. Stock is available, but the entire order is immediately assigned to a manufacturer or backup fulfiller instead of waiting to be requested.
JSplit to MerchantProduct is split from order and shipped by manufacturer. It is available, but order is immediately assigned to a manufacturer or backup fulfiller. If there are other products in the order, they are split into a separate order and behave according to their availability.
PPreorderProduct will be available soon. These orders appear to fulfillers but cannot be requested. Preordered products are split into a new order and are assigned to the manufacturer to be fulfilled directly or released for fulfiller requests.
DDiscontinuedIt is uncertain whether fulfillers have inventory of this item, though an attempt to locate it can be made. Orders can be requested for 12 days, rather than 2. If there are no requests, the shopper will be emailed and asked if they want to continue searching.
IDigital ContentProducts are available for download from the website. This product is split out as a separate order and instantly resolved. When payment clears, the consumer receives an email with a download link.
SShip to Store OnlyProducts can only be shipped to a fulfillment center and not a customer address. Specify a lead time, which is the amount of time to transfer the item to a fulfillment center for pick-up. Only available for Shopper’s Choice or STS fulfillment processes.
GGift Card (Digital)The product takes the form of a digital gift card.
VServiceProduct is not a physical item but a service (such as assembly).
FGift Card (Physical)Product takes the form of a physical gift card.

Note that there are some limitations on how products can be combined in an order:

  1. Products with “Preorder” Availability
    • The Create Order API doesn’t accept orders that mix preorder products and non-preorder products. These products need to be separated into several payloads at checkout with separate externalOrderIDs prior to submitting them to the API. One payload needs to contain all non-preorder items while the other should contain the preorder items. This will generate two orderIDs in OMS and two order numbers for the customer.
  2. Certified Products in Express Orders
    • Certified fulfillment options within OMS have been used for orders that may need a longer time to be processed due to special product requirements (product customization, fitting parts, etc.). Such orders aren’t candidates to be “expedited” and will negate Express shipping. If certified products are included in an Express order, the order will be created in Kibo OMS but not flagged as “Express.”
  3. Products with “Discontinued” Availability
    • Products with availability “D” cannot be combined with normal items in a cart. These products must be split at the cart or checkout level into their own orders with distinct externalOrderIDs, as their order flow will be different from products that should be processed sooner.
  4. Products with “Split to Merchant” Availability
    • If an order has products with availability “J” and normal products, then the order must be split into two orders. In OMS, a “J” availability product goes to “Waiting for Manufacturer Acceptance” status whereas other products go to the usual fulfillment status depending on their availability.

This example shows a purchase of 5 items with the part number “Product0001” in the color black.

"orderItems": [
    {
      "orderItemID": null,
      "product": {
        "partNumber": "Product0001",
        "productID": null,
        "availability": "Y",
        "name": "Test Product 0001",
        "retailPrice": 2,
        "averageDealerMargin": 0.3,
        "upc": null
      },
      "itemSpecifics": {
        "externalItemID": null,
        "actualPrice": 1,
        "quantity": 5,
        "shipping": null,
        "shippingTax": null,
        "itemTaxOverride": 1,
        "customItemData": {
          "Custom Data Key 2": "Custom Data Value 2",
          "Custom Data Key 3": "Custom Data Value 3",
          "Custom Data Key 1": "Custom Data Value 1"
        },
        "options": {
          "size": "12",
          "color": "black"
        },
        "customData": null
      }
    },
    {
      "orderItemID": null,
      "product": {
        "partNumber": "Product0002",
        "productID": null,
        "availability": "Y",
        "name": "Test Product 0002",
        "retailPrice": 2,
        "averageDealerMargin": 0.3,
        "upc": null
      },
      "itemSpecifics": {
        "externalItemID": "external002",
        "actualPrice": 1,
        "quantity": 5,
        "shipping": 1,
        "shippingTax": 0.1,
        "itemTaxOverride": 1,
        "options": null,
        "customItemData": {
          "Custom Data Key 2": "Custom Data Value 2",
          "Custom Data Key 3": "Custom Data Value 3",
          "Custom Data Key 1": "Custom Data Value 1"
        }
      }
    }
  ],

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

There are a few different configurations that this information can be provided in – see the schema for a full template of these builds. Note that in the configuration that includes “name”, “price” and “description” parameters, these are read-only fields that are automatically populated by legacy OMS. Attempting to manually set these fields will result in invalid input errors. The deliveryMethod and shipType parameters are sufficient when using that particular configuration option.

To override shipping default options for the order being created and specify a particular carrier and service type, include the optional parameters of carrier, carrierType, and shipType with the preferred information. If these values are not provided, then the order will be created with the default carrier. Additionally, all three of these values must be used together in order to successfully submit the request. Providing only one or two values will result in a Bad Request error.

An example of specifying an override is shown below:

"shippingMethod":{
    "shippingType":"standard",
    "deliveryMethod":"SHIP_TO_HOME",
    "carrier":"FEDEX_CROSS_BORDER",
    "carrierType":"INTERNATIONAL",
    "serviceType":"INTERNATIONAL_ECONOMY"
}

This example shows an order with the Standard shipping type being shipped to 123 Elm Lane, San Luis Obispo, CA 93405, US. It does not override the carrier defaults.

"shippingMethod": {
  "shippingType": "standard",
  "shippingClass": "Standard"
},
"shippingAddress": {
  "addressID": null,
  "customerID": null,
  "addressLine1": "123 Elm Ln.",
  "addressLine2": null,
  "addressLine3": null,
  "phone": "111-222-3333",
  "city": "San Luis Obispo",
  "postalCode": "93405",
  "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. There are 11 options for defining the payment method, but the method will always include a valid billing address. See the schema for the full details of these 11 options and other parameters, but note that the following parameters can also be included in orderPayments regardless of which option is chosen:

  • maxAmount
  • transactionID (for pre-authorized payments)
  • authorizationID (for pre-authorized payments)
  • authAmount (for pre-authorized payments)

The maxAmount parameter can be set to null, -1, or a positive number. Both null and -1 specify that there is no maximum amount; null should be used particularly for the payment types TK, LV, VO, CC, CS, NO, TD, PZ, PL, NG, and ST. Use a positive value if there are multiple payment methods and some of them should be limited (such as $5 on giftcard1, $10 on giftcard2, and the rest on a credit card with no limit) or if the payment is a gift card (in which case, maxAmount should be the available balance).

Possible payment types vary depending on implementation and should be verified before placing the call. However, note that even for a no-operation payment method the cardNumber field must be populated (this can be a bogus number). The supported codes and definitions for non-gift card payment types are listed below:

Payment TypeMeaningPayment TypeMeaning
CCCredit CardEBEbay
LVLitleVaultTKKibo Token
VOVantiv OmnichannelNGCredit card from Kibo eCommerce*
CSCyberSourcePLPay4Later
PZPayeezyNONo-Operation
ADADSTDTDBank
PPPayPalSTSecure Trading

*is listed in the schema but not fully supported yet (this feature will be announced in the OMS Release Notes)

 

The supported codes and definitions for gift card payment types are listed below:

Gift CardMeaning
GCGift Card (generic type - specify a subtype or cardIssuer as shown in the schema)
GTGift Tango
GXGiveX
IMBranded gift card
M1Branded gift card (MVP awards)
M2Branded gift card
M3Branded e-gift card
VAVantiv gift card

The supported codes and definitions for card issuers are listed below:

Card IssuerMeaningCard IssuerMeaning
AMAmerican ExpressLSLaser
BCBank CardMSMaestro
CLClutch (use GC as the gift card type)MCMastercard
CUChina Union PaySTSecure Trading
DBDeutsche BankSVSVS (use GC as the gift card type)
DIDiners Club Enroute/International/Carte BlancheSWSwitch
DEEnrouteVIVisa
DCDiscoverVLValueLink (use GC as the gift card type)
JBJapan Credit Bureau

This example lists a standard credit card as the method of payment.

"orderPayments": [
    {
      "orderPaymentID": null,
      "paymentMethod": {
        "billingAddress": {
          "addressID": null,
          "customerID": null,
          "addressLine1": "123 San Luis Obispo Ln.",
          "addressLine2": null,
          "addressLine3": null,
          "phone": "111-222-3333",
          "city": "San Luis Obispo",
          "postalCode": "93405",
          "state": "CA",
          "countryCode": "US",
          "latitude": null,
          "longitude": null,
          "fraudLock": false,
          "active": true
        },
        "paymentType": "CC",
        "cardIssuer": "VI",
        "cardNumber": "411111111111111",
        "cardSecurityCode": "111",
        "cardExpiration": "12/2020",
        "paymentClass": "CreditCard"
      },
      "paymentMethodID": null,
      "maxAmount": null,
      "transactionID": "12123",
      "authorizationID": "48484",
      "paymentType": null,
      "authAmount": 20
    }
  ],

External Fraud

As noted above, the Create Order API schema lists several options for how to define fraudData for the order being created. In the event that the implementation uses an external fraud system instead of one already supported by OMS, refer to the External Fraud Guide for more details.

The Full Request

This is the entire request that will create an order. Remember to put account-specific information under the data points specified by:

  • manufacturerID
  • catalogID

The other content in this sample is the combination of all previously explained sections, with additional parameters defined where necessary such as the gift order details at the end of the request.

{
  "externalOrderID": "8885456-98658-12215",
  "manufacturerID": MFG_ID,
  "catalogID": CATALOG_ID,
  "locale": "en-US",
  "currency": "USD",
  "customer": {
    "customerID": null,
    "firstName": "Test",
    "lastName": "Customer",
    "email": "testemail@kibotest.com",
    "password": null,
    "phone1": "852-658-4578x124",
    "phone2": "8885552147",
    "accountCreated": null
  },
  "orderItems": [
    {
      "orderItemID": null,
      "product": {
        "partNumber": "Product0001",
        "productID": null,
        "availability": "Y",
        "name": "Test Product 0001",
        "retailPrice": 2,
        "averageDealerMargin": 0.3,
        "upc": null
      },
      "itemSpecifics": {
        "externalItemID": null,
        "actualPrice": 1,
        "quantity": 5,
        "shipping": null,
        "shippingTax": null,
        "itemTaxOverride": 1,
        "customItemData": {
          "Custom Data Key 2": "Custom Data Value 2",
          "Custom Data Key 3": "Custom Data Value 3",
          "Custom Data Key 1": "Custom Data Value 1"
        },
        "options": {
          "size": "12",
          "color": "black"
        },
        "customData": null
      }
    },
    {
      "orderItemID": null,
      "product": {
        "partNumber": "Product0002",
        "productID": null,
        "availability": "Y",
        "name": "Test Product 0002",
        "retailPrice": 2,
        "averageDealerMargin": 0.3,
        "upc": null
      },
      "itemSpecifics": {
        "externalItemID": "external002",
        "actualPrice": 1,
        "quantity": 5,
        "shipping": 1,
        "shippingTax": 0.1,
        "itemTaxOverride": 1,
        "options": null,
        "customItemData": {
          "Custom Data Key 2": "Custom Data Value 2",
          "Custom Data Key 3": "Custom Data Value 3",
          "Custom Data Key 1": "Custom Data Value 1"
        }
      }
    }
  ],
  "shippingMethod": {
    "shippingType": "standard",
    "shippingClass": "Standard"
  },
  "shippingAddress": {
    "addressID": null,
    "customerID": null,
    "addressLine1": "123 San Luis Obispo Ln.",
    "addressLine2": null,
    "addressLine3": null,
    "phone": "111-222-3333",
    "city": "San Luis Obispo",
    "postalCode": "93405",
    "state": "CA",
    "countryCode": "US",
    "latitude": null,
    "longitude": null,
    "fraudLock": false,
    "active": false
  },
  "orderPayments": [
    {
      "orderPaymentID": null,
      "paymentMethod": {
        "billingAddress": {
          "addressID": null,
          "customerID": null,
          "addressLine1": "123 San Luis Obispo Ln.",
          "addressLine2": null,
          "addressLine3": null,
          "phone": "111-222-3333",
          "city": "San Luis Obispo",
          "postalCode": "93405",
          "state": "CA",
          "countryCode": "US",
          "latitude": null,
          "longitude": null,
          "fraudLock": false,
          "active": true
        },
        "paymentType": "CC",
        "cardIssuer": "VI",
        "cardNumber": "411111111111111",
        "cardSecurityCode": "111",
        "cardExpiration": "12/2020",
        "paymentClass": "CreditCard"
      },
      "paymentMethodID": null,
      "maxAmount": null,
      "transactionID": "12123",
      "authorizationID": "48484",
      "paymentType": null,
      "authAmount": 20
    }
  ],
  "customerIP": "88.152.11.125",
  "orderID": null,
  "shippingTax": 2,
  "forceItemTaxOverride": true,
  "optInRetailer": true,
  "landingCode": "TestLandingCode",
  "customOrderData": {
    "Custom Data Key 2": "Custom Data Value 2",
    "Custom Data Key 3": "Custom Data Value 3",
    "Custom Data Key 1": "Custom Data Value 1"
  },
  "allowSplit": false,
  "orderGift": {
    "recipient": "John Doe",
    "message": "this is the gift message"
  },
  "orderComment": null,
  "sendEmail":true
}

ProductOMS Dev: Create Order