Kodaris Customer API

Kodaris offers a robust set of APIs you can use on your account to do anything that can be visually done on both the commerce website and in your customer account portal. For example:

• Orders
• Quotes
• Shiptos
• Employees
• Product Lists
• Notifications
• Documents
• And much more...

This help documentation describes how you can use the Kodaris API to manage and perform actions for your company account. We will cover how the Kodaris API works, how to set up an API user, and how to make authenticated requests to the API.

API Overview

https://www.youtube.com/watch?v=RIN27ldX1YU

Kodaris provides two different APIs you can use based on what type of user you are. Each API is documented via Swagger.

• User API
  • The User API is available for both guest and authenticated users.
  • Responses from this API may change based on whether you are authenticated or not.
  • For example, you can check pricing for products using this API. If you’re not logged in, you’ll see every day pricing. If you are authenticated, you’ll see your specialized account pricing.
• Account API
  • The Account API is available for authenticated customers.
  • You can use this API to fetch orders, place orders, manage employees, etc.

To view User and Account APIs, navigate to your website url + /services in your browser, for example https://commerce.kodaris.com/services. In the dropdown menu in the header, select User or Account to determine which API you’d like to use.

Set Up API User

https://www.youtube.com/watch?v=5ywyLdQ9Lyg

To manage and access your account via the API, you’ll want to set up an API user which will be used to authenticate the API requests you make.

1. Navigate to your account
2. Sign in.
3. Navigate to Employees.
4. Choose Add Employee.
5. Enter the username you would like to use for this API user; it must be a valid email address.
6. Click Add; the new user will be added and you’ll be taken to the user details.
7. Add the permissions this api user should have:
   1. canViewPricing - if this user should view product and order pricing.
   2. viewAllOrders - if this user should see all orders on your account.
   3. viewAllLocations - if this user should see all shiptos on your account.
   4. canPlacePurchaseOrder - if this this user should be able to place a purchase order.
8. Set a password
   1. Sign out of your account
   2. Navigate to the set password page
   3. Enter your API user’s username
   4. Submit the form
   5. An email will be sent to the API user’s inbox with a set password link.
   6. Go to the inbox and click the link in the email.
   7. You’ll be taken to a set password form.
   8. Enter the password for the API user and confirm it.

Your API user is all set. You’ll use the username and password to authenticate your Kodaris API requests in the next section.

Examples

Now that we’ve given a brief overview of how the Kodaris API works and how to set up an API user, let’s dive into a few examples:

• Placing an order.
• Checking the status of an order.
• Checking product pricing.

For each example, we’ll show how you can test the endpoint out in Swagger and also show calling the API from an external system.

Place An Order

In this example we'll show how you can submit an order via the API. The order is placed and processed the same way as when you add items to your cart and check out on the website.

To complete this process using Swagger:

https://www.youtube.com/watch?v=-IcV82i74jw

To complete this process using an external system:

https://www.youtube.com/watch?v=lMjWoBIRVS4

1. Fetch an Auth Token
   • You'll need an authorization token for any API requests you make to the Kodaris API.
   • Fetch one using the endpoint: GET / api/user/customer/authToken
2. Sign In
   • Next sign into your account so you can place orders on your account.
   • Call the endpoint: POST /api/user/customer/loginV2
     • Headers
       • Cookie - set this to the Set-Cookie header you received in the first request.
       • X-CSRF-TOKEN - set this to the auth token you received in the first request.
     • Body
       • userName - the username of your API user.
       • password - the password of your API user.
     • Response
       • A response will be returned indicating whether the login was successful or not.
3. Place an Order
   • Now you can place an order for your account.
   • Send an API request to endpoint: POST /api/account/order
     • Headers
       • Cookie - set this to the Set-Cookie header you received in the first request.
       • X-CSRF-TOKEN - set this to the auth token you received in the first request.
     • Body
       • For the payload, include a JSON object of the order you would like to place. See the example below for a full sample along with comments describing each field.

Sample Payload:

{
  notes: "Please deliver the order between 9AM and 7PM",

    // The purchase order number that will be used to place your order via PO.
    // Based on how your account is configured, the purchase order number may be optional.
    purchaseOrder: "MY-PO-NUMBER",

    // Billing address
    organization: "Kodaris",
    firstName: "John",
    lastName: "Smith",
    phone1: "1234567890",
    email1: "john.smith@kodaris.com",
    address1: "123 Some Address",
    address2: "Suite 2",
    city: "Atlanta",
    state: "GA",
    postalCode: "1234",
    country: "US",

    // The shipto the order should be attached to.
    // You can exclude this field if shipto is optional for your account.
    // If you do not include the shipto, your order will be placed as a one time only order
    deliveryAddressCode: "5043232_11_atlanta",

    // Delivery address; if you provide a shipto to attach the order to, you do not need to
    // provide the delivery address fields as they will be taken off the specified shipto
    // by default. If you are allowed override the shipto, you can include these delivery       // address fields and they will be copied onto the order.
    deliveryOrganization: "Kodaris",
    deliveryAddress1: "123 Some Address",
    deliveryAddress2: "Suite 2",
    deliveryCity: "Atlanta",
    deliveryState: "GA",
    deliveryPostalCode: "1234",
    deliveryCountry: 'US',

    // Delivery contact information
    deliveryFirstName: "John",
    deliveryLastName: "Smith",
    deliveryPhone1: "1234567890",
    deliveryEmail1: "john.smith@kodaris.com",

    // Requested ship date; ensure it is in format: YYYY-MM-DD
    "deliveryDate": "2024-07-14",


    // Order items
    orderItems: [
        {
            code: "509382",
            quantity: 2,
            plainNote: "I really like this item, do you have it in color blue as well?"
        },
        {
            code: "345744",
            quantity: 1
        }
    ]
}

Example

// Get an auth token
var tokenRes = kd.http.fetch({
  method: 'GET',
  url: 'https://commerce.kodaris.com/api/user/customer/authToken',
  headers: {
    'Content-Type': 'application/json',
  },
  includeFullResponse: true
});

// keep our cookie and token for future requests
var cookie = tokenRes.headers['set-cookie'];
var token = JSON.parse(tokenRes.body).data;

// Login to our account
var loginRes = kd.http.fetch({
  method: 'POST',
  url: 'https://commerce.kodaris.com/api/user/customer/loginV2',
  body: {
    userName: 'julie@kodaris.com',
    password: 'wowser'
  },
  headers: {
    'Content-Type': 'application/json',
    'Cookie': cookie,
    'X-CSRF-TOKEN': token
  }
});

// Place an order
var orderRes = kd.http.fetch({
  method: 'POST',
  url: 'https://commerce.kodaris.com/api/account/order',
  body: {
    "orderItems": [
        {
            "code": "CMMT82329",
            "quantity": 2,
            "plainNote": "I really like this item, do you have it in color blue as well?"
        },
        {
            "code": "THR03681",
            "quantity": 1
        }
    ],
    "organization": "Kodaris",
    "firstName": "John",
    "lastName": "Smith",
    "phone1": "1234567890",
    "email1": "john.smith@kodaris.com",
    "address1": "123 Some Address",
    "address2": "Suite 2",
    "city": "Atlanta",
    "state": "GA",
    "postalCode": "1234",
    "country": "US",
    "deliveryAddressCode": "2088_3007_1",
    "deliveryOrganization": "Kodaris",
    "deliveryFirstName": "John",
    "deliveryLastName": "Smith",
    "deliveryPhone1": "1234567890",
    "deliveryEmail1": "john.smith@kodaris.com",
    "deliveryAddress1": "123 Some Address",
    "deliveryAddress2": "Suite 2",
    "deliveryCity": "Atlanta",
    "deliveryState": "GA",
    "deliveryPostalCode": "1234",
    "deliveryCountry": "US",
    "notes": "Please deliver the order between 9AM and 7PM",
    "purchaseOrder": "#16783"
  },
  headers: {
    'Content-Type': 'application/json',
    'Cookie': cookie,
    'X-CSRF-TOKEN': token
  }
});

kd.log('order result', orderRes);

-> response ->
{
  "success" : true,
  "code" : 200,
  "messages" : [],
  "errors" : [],
  "data" : {
    "parentOrderType" : null,
    "remitAddress2" : "",
    "remitAddress1" : "PO Box 2256",
    "companyName" : "Four Presidents",
    "extra5" : null,
    "extraChargeTaxable" : 0,
    "deliveryFirstName" : "John",
    "storePhone" : "(470) 264-4997",
    "state" : "GA",
    "requestedPaymentAmount" : null,
    "billingAddressCode" : "-0000",
    "completed" : "2023-10-12 20:32:25:523",
    "formattedShipping" : "$0.00",
    "invoicedt" : null,
    "subtotal" : 81.4,
    "formattedExtraCharge" : "$0.00",
    "deliveryPostalCode" : "33442",
    "statusDetails" : null,
    "formattedTotalCharge" : "$0.00",
    "storeCity" : "Peachtree City",
    "formattedTotal" : "$81.40",
    "status" : "Received",
    "lastName" : "Smith",
    "city" : "Atlanta",
    "genericTermsUrl" : null,
    "formattedTax" : "$0.00",
    "remitPostalCode" : "30269",
    "remitCity" : "Peachtree City",
    "deliveryCountryName" : "United States",
    "deliveryDate" : null,
    "shippingMethodName" : null,
    "deliveryOrganization" : "Illinois Dr",
    "organization" : "Kodaris",
    "remitEmailAddress" : "sales@kodaris.com",
    "formattedSubtotal" : "$81.40",
    "country" : "US",
    "orderNumber" : 2162,
    "notes" : "John Smith - 1234567890\n\nPlease deliver the order between 9AM and 7PM",
    "postalCode" : "1234",
    "deliveryLastName" : "Smith",
    "extraCharge" : 0,
    "phone1" : "1234567890",
    "email1" : "john.smith@kodaris.com",
    "companyID" : 473,
    "discounts" : [],
    "shipping" : 0,
    "trackingNumber" : null,
    "companyCode" : "2088_3007",
    "displayPricing" : true,
    "remitPhone" : "(470) 264-4997",
    "tax" : 0,
    "firstName" : "John",
    "status" : "Received",
    "customerID" : 959,
    "deliveryAddressCode" : "2088_3007_1",
    "countryName" : "United States",
    "lastModified" : "2023-10-12 20:32:25:524",
    "custno" : "2088",
    "storeEmailAddress" : "sales@kodaris.com",
    "orderItems" : [
      {
        "productGroup" : "",
        "line" : 1,
        "productID" : 9832,
        "orderItemID" : 8030,
        "orderItemUUID" : "31b0a01b-1eb3-4457-9eb0-408888288523",
        "code" : "cmmt82329",
        "seoCode" : "CMMT82329",
        "name" : "5/16 in x 1 1/2 in x 24 ft Acoustical Surfaces Acousti-Gasket Tape",
        "image" : "https://s3.amazonaws.com/commerce.kodaris.com/product/SM-acousti_gaskettape.jpg",
        "quantity" : 2,
        "quantityShipped" : 0,
        "quantityBackOrdered" : 0,
        "binLocation" : null,
        "productUnitCode" : null,
        "size" : null,
        "unitStock" : null,
        "url" : "https://commerce.kodaris.com/product/CMMT82329",
        "plainNote" : "I really like this item, do you have it in color blue as well?",
        "unitPrice" : 38.57,
        "formattedUnitPrice" : "$38.57",
        "total" : 77.14,
        "formattedTotal" : "$77.14"
      },
... omitted for brevity

Check Order Status

In this example, we'll cover how you can retrieve order details for an order in your account.

To complete this process using Swagger:

https://www.youtube.com/watch?v=waOhJ9ik5Rc

To complete this process using an external system:

https://www.youtube.com/watch?v=Dyb2r0Viok0

1. Fetch an Auth Token
   • You'll need an authorization token for any API requests you make to the Kodaris API.
   • Fetch one using the endpoint: GET / api/user/customer/authToken
2. Sign In
   • Next sign into your account so you can see your orders in your account.
   • Call the endpoint: POST /api/user/customer/loginV2
     • Headers
       • Cookie - set this to the Set-Cookie header you received in the first request.
       • X-CSRF-TOKEN - set this to the auth token you received in the first request.
     • Body
       • userName - the username of your API user.
       • password - the password of your API user.
     • Response
       • A response will be returned indicating whether the login was successful or not.
3. Fetch an Order
   • Now you can query for an order by order number on your account.
   • Send an API request to endpoint: POST /api/account/order/search
     • Headers
       • Cookie - set this to the Set-Cookie header you received in the first request.
       • X-CSRF-TOKEN - set this to the auth token you received in the first request.
     • Body
       • page - 0 -> this is what page you would like returned from the search results.
       • size - 10 -> this is how many search results you would like returned.
       • filterFields - this is an array of filters you would like to apply to the order search request. For this example, we want to filter by order number, so we'll apply a filter of:
         • name - orderNumber
         • operation - IS
         • value - [your_order_number]
     • Response
       • A search response will be returned with a list of search results matching your search request.
       • For this example, we are querying by order number so we'll get a single order back that matches our order number we are filtering by.
       • In the order search result, you'll see all the order details including the order status.

Example

// Get an auth token
var tokenRes = kd.http.fetch({
  method: 'GET',
  url: 'https://commerce.kodaris.com/api/user/customer/authToken',
  headers: {
    'Content-Type': 'application/json',
  },
  includeFullResponse: true
});

// keep our cookie and token for future requests
var cookie = tokenRes.headers['set-cookie'];
var token = JSON.parse(tokenRes.body).data;

// Login to our account
var loginRes = kd.http.fetch({
  method: 'POST',
  url: 'https://commerce.kodaris.com/api/user/customer/loginV2',
  body: {
    userName: 'julie+api@kodaris.com',
    password: 'wowser'
  },
  headers: {
    'Content-Type': 'application/json',
    'Cookie': cookie,
    'X-CSRF-TOKEN': token
  }
});

// Fetch our order
var orderRes = kd.http.fetch({
  method: 'POST',
  url: 'https://commerce.kodaris.com/api/account/order/search',
  body: {
    "page": 0,
    "size": 10,
    "filterFields": [
      {
        "name": "orderNumber",
        "operation": "IS",
        "value": "2159"
      }
    ]
  },
  headers: {
    'Content-Type': 'application/json',
    'Cookie': cookie,
    'X-CSRF-TOKEN': token
  }
});

kd.log('order result', orderRes);

-> response ->
{
  "success" : true,
  "code" : 200,
  "messages" : [],
  "errors" : [],
  "data" : [
    "size" : 10,
    "number" : 0,
    "totalElements" : 1,
    "isLast" : true,
    "totalPages" : 1,
    "isFirst" : true,
    "hasPrevious" : false,
    "hasNext" : false,
    "numberOfElements" : 1,
    "offset" : null,
    "content" : [
      {
        "orderID" : 2758,
        "organization" : "Kodaris",
        "firstName" : "John",
        "lastName" : "Smith",
        "webPlacedBy" : "julie@kodaris.com",
        "email1" : "john.smith@kodaris.com",
        "phone1" : "1234567890",
        "address1" : "123 Some Address",
        "address2" : "Suite 2",
        "city" : "Atlanta",
        "state" : "GA",
        "postalCode" : "1234",
        "country" : "US",
        "countryName" : "US",
        "deliveryOrganization" : "Illinois Dr",
        "deliveryFirstName" : "John",
        "deliveryLastName" : "Smith",
        "deliveryEmail1" : "john.smith@kodaris.com",
        "deliveryPhone1" : "1234567890",
        "deliveryAddress1" : "8869 Illinois Drive",
        "deliveryAddress2" : "",
        "deliveryCity" : "Deerfield Beach",
        "deliveryState" : "FL",
        "deliveryPostalCode" : "33442",
        "deliveryCountry" : "US",
        "deliveryCountryName" : "US",
        "completed" : "2023-10-12T15:31:40.974Z",
        "orderNumber" : 2159,
        "status" : "Received",
        "statusDetails" : null,
        "notes" : null,
        "purchaseOrder" : "#16783",
        "extra5" : "",
        "shippingMethod" : "",
        "billingAddressCode" : null,
        "deliveryAddressCode" : "2088_3007_1",
        "trackingNumber" : null,
        "companyID" : 473,
        "companyName" : "Four Presidents",
        "shipto" : "1",
        "arrivedTimestamp" : null,
        "outForDeliveryTimestamp" : null,
        "onTheWayTimestamp" : null,
        "deliveredTimestamp" : null,
        "whse" : "ENG",
        "lastModified" : "2023-10-12T15:31:40.976Z",
        "created" : "2023-10-12T15:31:39.567Z",
        "customerID" : 959,
        "subtotal" : 81.4000015258789,
        "shipping" : 0,
        "extraChargeTaxable" : 0,
        "extraCharge" : 0,
        "tax" : 0,
        "total" : 81.4000015258789
      }
    ],
    "facetFields" : [],
    "statsFields" : null,
    "pivotFields" : null,
    "highlightResults" : null
  }
}

Check Product Pricing

In this example, we'll cover how you can retrieve your account pricing and inventory for a list of products.

To complete this process using Swagger:

https://www.youtube.com/watch?v=M60vmbiHD3M

To complete this process using an external system:

https://www.youtube.com/watch?v=RHjOGCQKjgo

1. Fetch an Auth Token
   • You'll need an authorization token for any API requests you make to the Kodaris API.
   • Fetch one using the endpoint: GET / api/user/customer/authToken
2. Sign In
   • Next sign into your account so you can see your specialized account pricing for products.
   • Call the endpoint: POST /api/user/customer/loginV2
     • Headers
       • Cookie - set this to the Set-Cookie header you received in the first request.
       • X-CSRF-TOKEN - set this to the auth token you received in the first request.
     • Body
       • userName - the username of your API user.
       • password - the password of your API user.
     • Response
       • A response will be returned indicating whether the login was successful or not.
3. Check Pricing
   • Now you can send a lit of products to the API and get back pricing and inventory for those products.
   • Send an API request to endpoint: POST /api/user/product/pricesByCodes
     • Headers
       • Cookie - set this to the Set-Cookie header you received in the first request.
       • X-CSRF-TOKEN - set this to the auth token you received in the first request.
     • Params
       • productCodes - this is a comma delimited list of product codes you would like pricing and inventory for.
       • companyAddressCode - an optional parameter you can pass if you would like to see the pricing for a specific shipto. By default, the endpoint will return pricing for your default shipto.
     • Response
       • A list of objects will be returned for each product you requested pricing for.
       • Each object will contain:
         • code - the code of the product you requested pricing for.
         • calculatedPrice - the price of the product.
         • skuData - the list of warehouses this product is stocked in along with the availability.

Example

// Get an auth token
var tokenRes = kd.http.fetch({
  method: 'GET',
  url: 'https://commerce.kodaris.com/api/user/customer/authToken',
  headers: {
    'Content-Type': 'application/json',
  },
  includeFullResponse: true
});

// keep our cookie and token for future requests
var cookie = tokenRes.headers['set-cookie'];
var token = JSON.parse(tokenRes.body).data;

// Login to our account
var loginRes = kd.http.fetch({
  method: 'POST',
  url: 'https://commerce.kodaris.com/api/user/customer/loginV2',
  body: {
    userName: 'julie+api@kodaris.com',
    password: 'wowser'
  },
  headers: {
    'Content-Type': 'application/json',
    'Cookie': cookie,
    'X-CSRF-TOKEN': token
  }
});

// Fetch our pricing
var pricingRes = kd.http.fetch({
  method: 'GET',
  url: 'https://commerce.kodaris.com/api/user/product/pricesByCodes',
  queryParams: {
    productCodes: "THR03681,1GREEN",
    // companyAddressCode: "2088_3007_2",
    // companyID: 473
  },
  headers: {
    'Content-Type': 'application/json',
    'Cookie': cookie,
    'X-CSRF-TOKEN': token
  },
  includeFullResponse: true
});

kd.log('pricing result', JSON.parse(pricingRes.body));

-> response ->
{
  "success" : true,
  "code" : 200,
  "messages" : [],
  "errors" : [],
  "data" : [
    {
      "code" : "1GREEN",
      "wholeUnit" : "EACH",
      "wholeUnitPrice" : 3.57,
      "calculatedPrice" : 3.57,
      "unitPrice" : 10.57,
      "altPrice" : 0,
      "specialOrder" : true,
      "canPurchase" : true,
      "canPurchaseMessage" : null,
      "unitStock" : "EACH",
      "unitSell" : "EACH",
      "priceBreaks" : [],
      "unitConversions" : [],
      "warehousesAvailability" : {
        "GYP" : 57,
        "Eng" : 25
      },
      "leadTimes" : [],
      "skuData" : [
        {
          "code" : "GYP",
          "name" : "Denver, CO",
          "availability" : 57,
          "leadTimeInDays" : null,
          "status" : "O",
          "availableToOrder" : false
        },
        {
          "code" : "Eng",
          "name" : "El Paso, TX",
          "availability" : 25,
          "leadTimeInDays" : null,
          "status" : "O",
          "availableToOrder" : false
        }
      }
    ],
... omitted for brevity
}