0

API Documentation

Getting started with the API

To get the link to create API keys, reach out to your Kotis contact. Note that API keys should be saved securely and shared with the minimum number of people possible to reduce unauthorized access.

Creating an API key

"Live" checkbox - Checking this box will create a live API key. If you want to generate a test key that won't impact anything in production, leave this box unchecked. Test keys can be marked as live later when you're ready to use them. Please note that once a key is switched to Live mode, it cannot be reverted to a test key.

"Notes" - This is an optional field best used to track the purpose of each key, helping you maintain your list of keys and remove inactive ones.

Check inventory

#GET https://kwf.kotisdesign.com/api/v1/skus/quantity
#set 'Authorization' header to api key

#success response
{
  "data": [
    {
      "id": "33315",
      "type": "skus",
      "attributes": {
        "physical_quantity": 0,
        "available_quantity": 0,
        "sku": "107529-1-L"
      }
    },
    {
      "id": "33316",
      "type": "skus",
      "attributes": {
        "physical_quantity": 0,
        "available_quantity": 0,
        "sku": "107529-1-M"
      }
    },
    {
      "id": "33317",
      "type": "skus",
      "attributes": {
        "physical_quantity": 0,
        "available_quantity": 0,
        "sku": "107529-1-S"
      }
    }
  ],
  "jsonapi": {
    "version": "1.0"
  }
}

Create an order

#POST https://kwf.kotisdesign.com/api/v1/orders/create
#set 'Authorization' header to api key
#set 'Content-Type' header to 'application/json'

#example JSON
{
  "email": "test@example.com",
  "shipping_method": "Economy",
  "order_id": "",
  "skus": [
    {"quantity": "3",
    "sku": "107529-1-S"},
    {"quantity": "1",
    "sku": "107529-4-OSFA"}
  ],
  "address": {
      "name": "Test Person",
      "attention": "",
      "address1": "123 First Street",
      "address2": "",
      "city": "Seattle",
      "state": "WA",
      "zip": "98102",
      "country": "",
      "phone": "",
      "address_type": ""
  }
}

#success response
{
  "status": "success",
  "order_num": "5134691"
}

#failure response
{
  "errors": [
    {
      "title": "Invalid Order",
      "detail": "Sku 1 does not exist, Sku 2 does not exist"
    }
  ]
}

Check order status (including tracking)

#GET https://kwf.kotisdesign.com/api/v1/orders/status?order_numbers=12345,23719201
#set 'Authorization' header to api key

#success response
{
    "data": [
        {
            "id": "12345",
            "type": "orders",
            "attributes": { "status": "shipped" },
            "relationships": {
                "shipments": {
                    "data": [
                        {
                            "type": "shipments",
                            "id": "543416"
                        },
                        {
                            "type": "shipments",
                            "id": "544568"
                        }
                    ]
                }
            }
        },
        {
            "id": "23719201",
            "type": "orders",
            "relationships": {
                "shipments": {
                    "data": [
                        {
                            "type": "shipments",
                            "id": "767586"
                        }
                    ]
                }
            }
        }
    ],
    "included": [
        {
            "id": "543416",
            "type": "shipments",
            "attributes": {
                "tracking_numbers": "1Z8424330419842539",
                "shipment_date": "2018-10-02T14:50:24-07:00",
                "delivery_status": "delivered"
            }
        },
        {
            "id": "544568",
            "type": "shipments",
            "attributes": {
                "tracking_numbers": "1Z8424330402599594",
                "shipment_date": "2018-10-05T15:18:28-07:00",
                "delivery_status": "out_for_delivery"
            }
        },
        {
            "id": "767586",
            "type": "shipments",
            "attributes": {
                "tracking_numbers": "9405537897842130146579",
                "shipment_date": "2019-11-12T07:48:06-08:00",
                "status": "in_transit"
            }
        }
    ],
    "jsonapi": {
        "version": "1.0"
    }
}

#response with invalid orders
{
    "data": [],
    "jsonapi": {
        "version": "1.0"
    }
}

#invalid key
{
    "errors": [
        {
            "title": "Invalid Api Key",
            "detail": ""
        }
    ]
}

#possible shipment 'delivery_status' values are:
# "unknown", "pre_transit", "in_transit", "out_for_delivery", "delivered",
# "available_for_pickup", "return_to_sender", "failure", "cancelled" or "error"

#possible order status values are:
# "pending", "partially_shipped", "shipped", "delivered", "cancelled"

Create redemption codes

#POST https://stores.kotisdesign.com/api/v1/redemption_codes/create
#set 'Authorization' header to api key
{
  "portal_slug": "YOUR_PORTAL_SLUG",
  "number_to_create": "5000"
}

All keys are required. If the API_KEY is not associated with an active Portal the API will return an error. This API endpoint incorporates a daily_limit of 5,000 and yearly_limit of 50,000. When a portal is near its daily / yearly limit and the value of number_to_create key is greater than the limit, a message is returned with the allowed number to create.

Reply

Content aside

  • 1 yr agoLast active
  • 174Views
  • 1 Following