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

Create Order

The Create Order PerfectSync API is the final call made in the order creation flow of the Customer Care UI. This is triggered when all product, payment, and shipping information has been provided and confirmed by the customer. Sending this API call will enter the order into the front-end and OMS systems to begin the fulfillment process. Note that this is a different API than the Create Order API used for implementations without PerfectSync, which has its own guide.

Version1.0
Callhttps://integration.shopatron.com/api/snap/v1/order
Supported FormatsJSON
HTTP MethodPOST
Schemahttps://integration.shopatron.com/api/snap/v1/order.json

The .json address above can be used to access the schema within Postman.

Example

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

  • Standard Ship-to-Home order with one item
  • Purchased by customer “Joe Shmoe” with a TK payment (Kibo Token)

This guide will demonstrate how to put together each section of the request.

Header

Note that all PerfectSync integration APIs use Basic Authorization, a Base64 encoded string of the username and password combination separated by a colon. This authorization will be included in the header for every API call, along with the following:

Header NameDescriptionData Type
Kibo-Manufacturer-IdThis contains the Kibo OMS manufacturer identifierInteger
Kibo-Catalog-IdThis contains the Kibo OMS product catalog identifierInteger
Kibo-Currency-CodeThe product catalog currency ISO codeString
Kibo-LocaleThe product catalog locale ISO codeString

Required Parameters

The minimum required parameters, besides those provided in the header as explained in the PerfectSync Overview, are:

ParameterTypeDescription
paymentMethodsarrayA list of payment methods used to pay for the order.
billingAddressobjectThe address that the payment is billed to.
shippingAddressobjectThe street address that the shipment is being delivered to.
orderItemsarrayA list of items included in the order.
shippingMethodobjectThe shipping method that the order is being delivered through.
customerobjectThe customer details of the person purchasing the order.

See the sections below for more information on the data that makes up these parameters.

Optional Parameters

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

ParameterTypeDescription
orderIDstringOrder ID, if generated before order creation.
totalItemTaxnumberItem tax override.
shippingTaxnumberShipping tax override.
promotionCodesarrayA list of promotion codes applied to the order.
customDataobjectA map of string to strings to be passed into the OMS.
isTestOrderbooleanUsed when testing orders.

Customer

The customer details include the first name, last name, and contact information of the purchaser. This information is either entered for a new customer or received from the OMS system, which remembers existing customers.

The required parameters for a customer object are listed below.

ParameterTypeDescription
firstNamestringThe first name of the customer.
lastNamestringThe last name of the customer.
phonestringThe phone number of the customer.
emailstringThe email address of the customer.

The customer data used in this example is shown below.

"customer": {
        "firstName": "Joe",
        "lastName": "Shmoe",
        "email": "xenobc@gmail.com",
        "phone": "8055500123"
    },

Order Items

The Order Item block contains specific details about the products that are included in the new order, including identifiers and descriptions, pricing information, and any additions or variants. This block can be repeated for as many items as necessary.

The required and optional parameters for an order item object are listed below. UPC, SKU, itemTax, imageURL, and productAdditions are all optional.

ParameterTypeDescription
productIDstringThe product identifier of the item.
namestringThe name of the product.
descriptionstringA short description of the product.
upcstringThe Universal Product Code of the item.
skustringThe Stock Keeping Unit code of the item.
quantityintegerThe quantity of the item.
pricenumberThe item price.
currencystringThe ISO currency code (e.g. “USD”).
itemTaxnumberThe item tax override.
imageUrlstringAn image thumbnail URL.
productAdditionsarrayA list of product additions for this order item.

If applicable to the order, a productAdditions object within the array requires the following data points:

ParameterTypeDescription
pricenumberThe price of the addition.
namestringThe display name of the addition.
additionIDstringA product addition identifier.

The order item data used in this example is shown below.

"orderItems": [{
        "productID": "CASIO02039",
        "name": "Smart Outdoor Watch",
        "description": "Casio has been developing watches since the 1970s, and later developed PDAs and cellular phones from the 1990s into the 2000s. Leveraging its technology and experience with both watches and information devices, Casio continues to develop wrist devices that deliver true value to users in new ways.",
        "imageUrl": "url.com/images/image.png",
        "quantity": 1,
        "price": 500.0,
        "itemTax": 37.5,
        "currency": "USD",
        "productAdditions": [{
            "additionID": "000",
            "name": "None",
            "price": 0.0
        }]
    }],

Payment Information

Both the paymentMethods and billingAddress objects provide detailed information about the payment of the order.

The required and optional parameters for the billingAddress object are listed here. The state, postalCode, and address lines 2 and 3 are all optional.

ParameterTypeDescription
firstNamestringThe first name of the recipient.
lastNamestringThe last name of the recipient.
phonestringThe phone number of the recipient.
addressLine1stringThe first line of the street address.
addressLine2stringThe second line of the street address.
addressLine3stringThe third line of the street address.
citystringThe city that the street address is located in.
statestringThe state that the street address is located in.
postalCodestringThe postal code for the street address.
countryCodestringThe country code for the street address.

The required parameters for a paymentMethod objects that make up the paymentMethods array are listed here.

ParameterTypeDescription
amountnumberThe amount that the payment is authorized for.
paymentMethodTokenstringThe Kibo payment method token.
paymentAuthorizationTokenstringThe Kibo payment authorization token.
paymentTypeenumThe payment type code, as used in the usual Create Order REST API call.

The payment data used in this example is shown below.

"billingAddress": {
        "firstName": "Joe",
        "lastName": "Shmoe",
        "addressLine1": "1234 Fake St",
        "addressLine2": "",
        "city": "San Luis Obispo",
        "state": "CA",
        "postalCode": "93405",
        "countryCode": "US",
        "phone": "8055500123"
    },
"paymentMethods": [{
        "paymentType": "TK",
        "paymentMethodToken": "WD5AclEajuiV/xgGjLMj7sS+UlmrLYAJdBdu4ojC2ou9fdMZ8XSBuTZphwdZNm9HbXsQh/M/dt2zesMinM4/977+6uKoHlILUK5A4aVxACs=",
        "paymentAuthorizationToken": "9bdcd******3188ea2a5d02ad779",
        "amount": 537.5
    }],

Shipping Information

Both the shippingAddress and shippingMethod objects provide information about the shipping destination and the selected shipping method that was chosen by the user.

The required and optional parameters for the shippingAddress object are listed here. The state, postalCode, and address lines 2 and 3 are all optional.

ParameterTypeDescription
firstNamestringThe first name of the recipient.
lastNamestringThe last name of the recipient.
phonestringThe phone number of the recipient.
addressLine1stringThe first line of the street address.
addressLine2stringThe second line of the street address.
addressLine3stringThe third line of the street address.
citystringThe city that the street address is located in.
statestringThe state that the street address is located in.
postalCodestringThe postal code for the street address.
countryCodestringThe country code for the street address.

The required and optional parameters for the shippingMethod object are listed below. Only the shippingType and deliveryMethod are required.

ParameterTypeDescription
shippingTypeenumThe shipping method (“REGULAR”, “EXPRESS_1_DAY”, “EXPRESS_2_DAY”, or “EXPRESS_3_DAY”).
deliveryMethodenumThe delivery method (“SHIP_TO_HOME”, “DIGITAL”, “IN_STORE_PICKUP”, “SHIP_TO_STORE”, or “SHIP_TO_STORE_PLUS”).
namestringThe name of the shipping method.
descriptionstringThe description of the shipping method.
locationIDstringThe pick-up location ID for an in-store pickup order.
pricenumberThe price of shipping.
currencystringThe ISO currency code (e.g. “USD”).

The shipping data used in this example is shown below.

"shippingAddress": {
        "firstName": "",
        "lastName": "",
        "addressLine1": "1234 Fake St",
        "addressLine2": "",
        "city": "San Luis Obispo",
        "state": "CA",
        "postalCode": "93405",
        "countryCode": "US",
        "phone": "8055500123"
    },
"shippingMethod": {
        "name": "UPS - Standard Ground",
        "description": "UPS - Standard Ground",
        "shippingType": "REGULAR",
        "deliveryMethod": "SHIP_TO_HOME"
    },

The Full Request

This is the entire request that will create an order.

{
    "customer": {
        "firstName": "Joe",
        "lastName": "Shmoe",
        "email": "xenobc@gmail.com",
        "phone": "8055500123"
    },
    "shippingAddress": {
        "firstName": "",
        "lastName": "",
        "addressLine1": "1234 Fake St",
        "addressLine2": "",
        "city": "San Luis Obispo",
        "state": "CA",
        "postalCode": "93405",
        "countryCode": "US",
        "phone": "8055500123"
    },
    "billingAddress": {
        "firstName": "Joe",
        "lastName": "Shmoe",
        "addressLine1": "1234 Fake St",
        "addressLine2": "",
        "city": "San Luis Obispo",
        "state": "CA",
        "postalCode": "93405",
        "countryCode": "US",
        "phone": "8055500123"
    },
    "shippingMethod": {
        "name": "UPS - Standard Ground",
        "description": "UPS - Standard Ground",
        "shippingType": "REGULAR",
        "deliveryMethod": "SHIP_TO_HOME"
    },
    "paymentMethods": [{
        "paymentType": "TK",
        "paymentMethodToken": "WD5AclEajuiV/xgGjLMj7sS+UlmrLYAJdBdu4ojC2ou9fdMZ8XSBuTZphwdZNm9HbXsQh/M/dt2zesMinM4/977+6uKoHlILUK5A4aVxACs=",
        "paymentAuthorizationToken": "9bdcd******3188ea2a5d02ad779",
        "amount": 537.5
    }],
    "orderItems": [{
        "productID": "CASIO02039",
        "name": "Smart Outdoor Watch",
        "description": "Casio has been developing watches since the 1970s, and later developed PDAs and cellular phones from the 1990s into the 2000s. Leveraging its technology and experience with both watches and information devices, Casio continues to develop wrist devices that deliver true value to users in new ways.",
        "imageUrl": "url.com/images/image.png",
        "quantity": 1,
        "price": 500.0,
        "itemTax": 37.5,
        "currency": "USD",
        "productAdditions": [{
            "additionID": "000",
            "name": "None",
            "price": 0.0
        }]
    }],
    "totalItemTax": 37.5,
    "customData": {
        "SalesLocationID": "",
        "SalesPersonID": "",
        "Test": ""
    },
    "isTestOrder": true
}

The Full Response

The response will provide an overall summary of the order, not including the order items. This summary focuses on the payment totals and date of the order placement, as well as provides the new Order ID that can be used for future reference.

{
    "orderID": "0000025906",
    "createDate": "2016-07-05T23:31:00.000Z",
    "orderTotal": 537.5,
    "orderSubtotal": 500.0,
    "discountTotal": 0.0,
    "taxTotal": 37.5,
    "currency": "USD",
    "promotions": []
}