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

Calculate Shipping

During the create order flow of the Customer Care UI, the user is prompted to supply a shipping destination and select a shipping method during the checkout process. This information is then sent to the Calculate Shipping API, which calculates the total shipping cost for the provided scenario.

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

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

Example

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

  • Standard Ship-to-Home order with one item
  • A total shipping cost of $0.00 USD

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 shown below. There are no additional optional parameters.

ParameterTypeDescription
orderItemsarrayA list of items included in the order.
shipToAddressobjectThe street address where the shipment will be delivered.
shippingMethodobjectThe shipping method that the order is being delivered through.
calculationTypeenumThe type of order this is (“NEW_ORDER” or “EXISTING_ORDER”.

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

Order Items

The Order Item block contains specific details about the products. This can be repeated for as many items in the order 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": "VRX33151",
        "name": "18K Yellow Gold and Stainless Steel Datejust Automatic",
        "imageUrl": "https://staging-web-tourneau.demandware.net/on/demandware.static/-/Sites-master-catalog/default/dwb159e2d1/images/large/VRX33151.png",
        "quantity": 1,
        "price": 3650.0,
        "currency": "USD",
        "productAdditions": [{
            "additionID": "000",
            "name": "None",
            "price": 0.0
        }]
    }],

Shipping Information

Both the shipToAddress and shippingMethod objects provide detailed information about the shipping destination and delivery method that the user selected.

The required and optional parameters for the shipToAddress 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.

"shipToAddress": {
        "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 calculate shipping.

{
    "orderItems": [{
        "productID": "VRX33151",
        "name": "18K Yellow Gold and Stainless Steel Datejust Automatic",
        "imageUrl": "https://staging-web-tourneau.demandware.net/on/demandware.static/-/Sites-master-catalog/default/dwb159e2d1/images/large/VRX33151.png",
        "quantity": 1,
        "price": 3650.0,
        "currency": "USD",
        "productAdditions": [{
            "additionID": "000",
            "name": "None",
            "price": 0.0
        }]
    }],
    "shipToAddress": {
        "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"
    },
    "calculationType": "NEW_ORDER"
}

The Full Response

The response will only return the total shipping cost.

 {
    "totalShippingCost":0.0
}