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.
Version 2.0 Call https://integration.shopatron.com/api/v2/createOrder/ Supported Formats JSON HTTP Method POST Schema https://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:
Parameter Type Description externalOrderID string A client-generated unique identifier for the order. The minimum length is 1 and the maximum length is 100. manufacturerID integer A unique identifier for a manufacturer. The minimum value is “1”. catalogID integer The catalog number for the manufacturer. The minimum value is “0”. locale enum An Internet Engineering Task Force code indicating the location and language of the order. 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. See below for more details about how to build this object. orderItems array The items included in the order. See below for more details about how to build this object. shippingMethod object The method by which to ship the order. See below for more details about how to build this object. shippingAddress object The address that the order will be shipped to. See below for more details about how to build this object. orderPayments array The payment method and data used to purchase the order. See below for more details about how to build this object. customerIP string The IP address of the customer placing the order. sendEmail boolean Whether 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:
Parameter Type Description orderID integer A unique identifier for the order. This ID is set by OMS when created in the system, so it is best to treat it as read-only and not try to set this parameter. Use externalOrderID for denoting preferred IDs outside of internal OMS. The minimum value is “1”. 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 region in relation to the currency of the order. This is only used when “currency=EUR,” in order to distinguish the type of euro based on locale. If this parameter is not provided in the request body, then “locale” is referenced instead because they are usually the same value. Note that “en-CA” should not be used for this value – while orders can be created in this locale, it will cause errors down the line such as blank packing slips. orderGift object Gift information for the order. See the schema for the list of parameters associated with this object. shippingTax 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. customerOrderDate object A hash of custom data to be associated with order, used for many purposes. Custom data is key/value information that may vary in use depending on implementation needs. 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.
Primary Elements The required elements of Customer, Order Items, Shipping Method, and Order Payments have their own parameters. These are listed in detail in the Create Order Schema, but examples also follow below. 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 Code Meaning IETF Code Meaning IETF Code Meaning en-US US English de-DE German nl-NL Dutch en-GB British English el-GR Greek nb-NO or no-NO Norwegian en-HL Hong Kong English fr-CA Canadian French ru-RU Russian en-IN Indian English fr-FR French sv-SE Swedish es-ES Spanish it-IT Italian zh-cmn-CN Mandarin es-MX Mexican Spanish ja-JP Japanese zh-HANT Traditional Chinese ko-KR Korean zh-yue-CN Cantonese
Likewise, ISO codes are used to refer to denote the currencies that orders are made in.
ISO Code Currency ISO Code Currency ISO Code Currency USD US Dollar RUB Russian Ruble UAH Ukrainian Hryvnia CAD Canadian Dollar MEX Mexican Peso HUF Hungarian Forint GBP Pound Sterling MXN Mexican Peso IDR Indonesian Rupiah CHF Swiss Franc EUR Euro IRR Iranian Rial NOK Norwegian Krone DKK Danish Krone KWD Kuwaiti Dinar SEK Swedish Krona SGD Singapore Dollar TWD New Taiwan Dollar HKD Hong Kong Dollar PLN Poland Zloty QAR Qatari Rial CNY Yuan Renminbi RON Romanian Leu SAR Saudi Riyal JPY Yen ARS Argentine Peso THB Thai Baht NZD New Zealand Dollar BRL Brazil Real AED UAE Dirham KRW South Korean Won HRK Croatian Kuna AUD Australian Dollar INR Indian Rupee CZK Czech 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
}, The schema for the Customer API with parameter details can be found here . However, note that the customerID (and customerCustomDataID, if provided, as this is an ID designating the custom data record and not the customer themselves) are internal identifiers that are actually set within OMS. They are read-only in practice, though not noted as such in the schema – if an API request includes either of these fields and assigns a value to them instead of “null”, then it will be ignored by the API.
Order Items
The following snippet shows the JSON array attached to this example call. Although there are a number of properties, the crucial elements about line items include the Part Number, Price and Quantity, Name, and Availability (explained below). 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.
Tax is generally calculated here at the line item-level, and then all items’ tax values are added together for the total order tax amount. For all currencies, the tax rate must be no higher than 20% for both individual line items and the overall order total. If even a single item has a rate greater than 20% then the order creation will fail with a validation error – even if the total order rate comes out to be under 20%. This is the default behavior for all currencies, but can be bypassed with a catalog configuration called “SKIP_INTERNATIONAL_TAX.” If this configuration needs to be changed or alternative tax limits applied, refer to the Kibo project team for assistance. On the other hand, VAT tax rates are determined by currency and vary depending on which country the order was shipped from.
The supported codes and definitions for the Availability parameter are listed below. Note that some cases require the order to be split into more than one order if there are products with different availabilities. OMS does not automatically perform this splitting on order creation – instead, this must be done on the client side because OMS will need to receive an External Order ID for each child order and then appropriate shipping for all items. However, this does not apply to onBlocks configurations – in onBlocks, OMS stores all of the necessary information and can perform the splitting upon order placement.
Availability Meaning Description Y Yes Product is in stock. This can proceed through the normal fulfillment process. N No Product 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. L Limited Product is in stock but has limited availability. This will follow the normal fulfillment process. M Manufacturer Ship Only Orders 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. J Split to Merchant Order is immediately assigned to the manufacturer for shipment. Split to Merchant products that are bought in conjunction with products of another availability must be split into a separate order, so that all products behave according to their availability. P Preorder Product will be available soon. These orders appear to fulfillers but cannot be requested. Preorders are assigned to the manufacturer to be fulfilled directly or released for fulfiller requests. Preorder products that are bought in conjunction with products of another availability must be split into a separate order, so that all products behave according to their availability. D Discontinued It 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. I Digital Content Product is available for download from the website. Digital Content products that are bought in conjunction with products of another availability must be split into a separate order, so that all products behave according to their availability. Digital Content orders are instantly resolved. When payment clears, the consumer receives an email with a download link. S Ship to Store Only Products 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. G Gift Card (Digital) The product takes the form of a digital gift card. V Service Product is not a physical item but a service (such as assembly). F Gift 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:
Products with “Preorder” AvailabilityThe 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. Certified Products in Express OrdersCertified 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.” Products with “Discontinued” AvailabilityProducts 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. Products with “Split to Merchant” AvailabilityIf 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 and Address
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 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 (which supports up to 250 characters per addressLine1, addressLine2, and addressLine3). 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. The supported codes and definitions for non-gift card payment types are listed below:
Payment Type Meaning Payment Type Meaning CC Credit Card EB Ebay LV LitleVault TK Kibo Token VO Vantiv Omnichannel NG Credit card sent from Kibo eCommerce in a cross-product integration CS CyberSource PL Pay4Later PZ Payeezy NO No-Operation AD ADS TD TDBank PP PayPal ST Secure Trading
The supported codes and definitions for gift card payment types are listed below:
Gift Card Meaning GC Gift Card (generic type – specify a subtype or cardIssuer as shown in the schema) GT Gift Tango GX GiveX IM Branded gift card M1 Branded gift card (MVP awards) M2 Branded gift card M3 Branded e-gift card VA Vantiv gift card
The supported codes and definitions for card issuers are listed below:
Card Issuer Meaning Card Issuer Meaning AM American Express LS Laser BC Bank Card MS Maestro CL Clutch (use GC as the gift card type) MC Mastercard CU China Union Pay ST Secure Trading DB Deutsche Bank SV SVS (use GC as the gift card type) DI Diners Club Enroute/International/Carte Blanche SW Switch DE Enroute VI Visa DC Discover VL ValueLink (use GC as the gift card type) JB Japan Credit Bureau
If using a no-operation payment, note that the cardNumber field must still be populated even if the card is not actually exposed – in this case, the field can be set to a bogus number. There are several different types of no-operation payment subtypes defined below with their supported currency types, but there are also custom subtypes that are only used by specific implementations and not listed here for public use. All of these gateways must be configured by Kibo Professional Services if needed.
Subtype Meaning Supported Currencies AM Amazon USD AX American Express USD CA Mastercard USD DR Digital River USD DS Discover USD FX Fedex Crossborder USD (Note that while orders can be placed in different currencies to Crossborder, it is converted to USD before being sent by Fedex GC Gift Card All Currencies HI Historic Order Import USD KI Kibo All Currencies KL Kibo All Currencies MA Macy USD PC Physical Check USD PY PayPal USD SR Style Rewards All Currencies SV SVS Gift Cards USD TR Transfer USD VI Visa USD
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:
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
}
The response will list all order details, including the OMS-assigned Order ID that can be used in future calls to retrieve order information, search for orders, add notes, etc.