Skip to main content

Orders

Karrio's orders API allows you to sync orders with Karrio for fulfilment. You can use the API to create, update, and cancel orders.

ENDPOINTS
GET/v1/orders
POST

/v1/orders

GET

/v1/orders/[id]

POST

/v1/orders/[id]/cancel

Creating an order​

POST /v1/orders

You can create a readonly order in Karrio based on the order data from your OMS.

curl --request POST \
  --url 'https://api.karrio.io/v1/shipments' \
  --header 'Authorization: Token  [API_KEY]' \
  --header 'Content-Type: application/json' \
  --data '{
	"order_id": "345098457777",
	"source": "bigcommerce",
	"shipping_to": {
		"address_line1": "5840 Oak St",
		"city": "Vancouver",
		"company_name": "B corp.",
		"country_code": "CA",
		"person_name": "Jane Doe",
		"phone_number": "+1 514-000-0000",
		"postal_code": "V6M2V9",
		"residential": true,
		"state_code": "BC"
	},
	"shipping_from": {
		"postal_code": "E1C4Z8",
		"city": "Moncton",
		"person_name": "John Doe",
		"company_name": "A corp.",
		"country_code": "CA",
		"phone_number": "+1 514-000-0000",
		"state_code": "NB",
		"address_line1": "125 Church St"
	},
	"line_items": [
		{
			"weight": 1.7,
			"weight_unit": "KG",
			"description": "Blue Jean Coat",
			"quantity": 1,
			"hs_code": "10000001",
			"value_amount": 99.99,
			"value_currency": "USD"
		},
		{
			"weight": 0.75,
			"weight_unit": "KG",
			"description": "Brow Suede Shoes",
			"quantity": 2,
			"hs_code": "10000002",
			"value_amount": 59.95,
			"value_currency": "USD"
		}
	]
}'

Fulfiling an order​

info

You can fulfill an order by creating a shipment for the order.

curl --request POST \
  --url 'https://api.karrio.io/v1/shipments' \
  --header 'Authorization: Token  [API_KEY]' \
  --header 'Content-Type: application/json' \
  --data '{
  "carrier_ids": [
    "ups-account"
  ],
  "label_type": "PDF",
  "metadata": {
    "order_ids": "345098457777"
  },
  "options": {
    "currency": "USD",
    "declared_value": 219.89,
    "preferred_service": "ups_express_saver_ca"
  },
  "parcels": [
    {
      "dimension_unit": "CM",
      "height": 38,
      "is_document": false,
      "items": [
        {
          "description": "Blue Jean Coat",
          "hs_code": "10000001",
          "metadata": {},
          "parent_id": "cdt_549f66b743a147958f084f5b1928e08e",
          "quantity": 1,
          "value_amount": 99.99,
          "value_currency": "USD",
          "weight": 1.7,
          "weight_unit": "KG"
        },
        {
          "description": "Brow Suede Shoes",
          "hs_code": "10000002",
          "metadata": {},
          "parent_id": "cdt_e44ecabf0d904aa9b45d1139d4ce045a",
          "quantity": 2,
          "value_amount": 59.95,
          "value_currency": "USD",
          "weight": 0.75,
          "weight_unit": "KG"
        }
      ],
      "length": 32,
      "package_preset": "canadapost_corrugated_medium_box",
      "weight": 3.2,
      "weight_unit": "KG",
      "width": 46
    }
  ],
  "payment": {
    "paid_by": "sender"
  },
  "recipient": {
    "address_line1": "5840 Oak St",
    "city": "Vancouver",
    "company_name": "B corp.",
    "country_code": "CA",
    "person_name": "Jane Doe",
    "phone_number": "+1 514-000-0000",
    "postal_code": "V6M2V9",
    "residential": true,
    "state_code": "BC",
    "validate_location": false
  },
  "service": "ups_express_saver_ca",
  "shipper": {
    "address_line1": "125 Church St",
    "city": "Moncton",
    "company_name": "A corp.",
    "country_code": "CA",
    "person_name": "John Doe",
    "phone_number": "+1 514-000-0000",
    "postal_code": "E1C4Z8",
    "residential": false,
    "state_code": "NB",
    "validate_location": false
  }
}'
tip

Critical to understanding how Karrio link the shipment to the order. You will notice in the request above that the shipment.parcels array contains items that refer to line_items from the order using the parent_id property.

Karrio can then determine the fulfilment status of an order by checking that all the line_items quantities have been fulfilled by parcels from one or multiple shipments.