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 here — or go directly to 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.
customerIPstringThe IP address of the customer placing the order.

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 are defined in the API request as shown below:

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

The customer details can also 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
},

Primary Elements

These rest of the Create Order API call is primarily made up of the Order Items, Shipping Method, and Order Payments sections.

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

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.

This example shows a purchase of 5 items with the part number “Product0001” in the color black. See the schema for a full list of possible parameters and values.

"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

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": "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. 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": "123San 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": -1,
      "transactionID": "12123",
      "authorizationID": "48484",
      "paymentType": null,
      "authAmount": 20
    }
  ],

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": "123San 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": "123San 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": -1,
      "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
}

Megan MayfieldOMS Dev: Create Order