API documentation

Kurier API Documentation

Kurier’s endpoints offer an easy integration to your system that allows you to create new shipments, get the shipping rates, label, and tracking information in an expedient and secure approach. In this document, you can find detailed information of each of our endpoints to help you integrate and best use our services.

Technology

Kurier’s endpoints are created using AWS as REST endpoints, which allow communication between your system and our services. These endpoints help to ensure that the information requested is delivered quickly and efficiently, while making the most of available resources.

Endpoints Overview

As a Kurier partner, you can request new shipments, shipping rates, and tracking updates through the following endpoints:

- Rating
- Shipment
- Tracking

The following diagram shows the workflow of the endpoints calls.

Authentication

In order to make use of our services, Kurier will provide you with an access and secret key that should be provided along with your request

Access Key

your_access_key

Secret Key

your_secret_key

AWS Endpoint: Rating

This endpoint will allow your system to quote a shipment with the required fields described below. The required information is used to receive multiple shipping rates for a specific shipment, which returns an object including rate ids that can then be used to generate shipment.

Type

your_access_key

Label Endpoint URL

https://kurier-integration-ab12ec1e2355.herokuapp.com/api/schema/docs/#tag/services/operation/services_carrier_rates_create

Authentication

TOKEN

Format

JSON

Rating Request Elements: The rating POST request requires the following fields.

Element	Type	Description
shipment	object	Shipment information
shipment/shipment_date	date-time	Shipping date
shipment/sender_address	object	Sender address information
sender_address/street1	string(50)	Sender’s address line 1
sender_address/street2	string(50)	Sender’s address line 2
sender_address/city	string(50)	Sender’s address city
sender_address/state	string(2)	Sender’s address 2-letter state code
sender_address/zip	string(11)	Sender’s address zip code
sender_address/country	string(2)	Sender’s address 2-letter country
sender_address/company	string(50)	Sender’s company or organization name
sender_address/name	string(50)	Sender’s name
sender_address/email	string(254)	Sender’s email
sender_address/phone	string(15)	Sender’s phone number
shipment/recipient_address	object	Recipient address information
recipient_address/street1	string(50)	Recipient's address line 1
recipient_address/street2	string(50)	Recipient's address line 2
recipient_address/city	string(50)	Recipient's address city
recipient_address/state	string(2)	Recipient’s address 2-letter state code
recipient_address/zip	string(11)	Recipient's address zip code
recipient_address/country	string(2)	Recipient's address 2-letter country
recipient_address/company	string(50)	Recipient's company or organization name
recipient_address/name	string(50)	Recipient's name
recipient_address/email	string(254)	Recipient's email
recipient_address/phone	string(15)	Recipient's phone number
shipment/delivery_instructions	string	Additional delivery instructions
shipment/parcel	object	Parcel information
parcel/items	array of objects	List of items
item/description	string	Description of the item
item/origin_country	string(2)	Item’s origin country
item/sku_code	string	Item’s SKU code
item/hs_code	string	Item’s HS code
item/unit_weight	object	Unit weight information
unit_weight/unit	"kg" “g” "oz" "lb"	Unit used for unit weight value
unit_weight/value	int	Weight value of item
item/unit_value	object	Unit value information
unit_value/currency	“USD” “MXN”	Currency used for Item/unit_value/amount
unit_value/amount	decimal	Value of one unit of the item
item/quantity	integer	Number of items
parcel/dimensions	object	Parcel’s dimensions information
dimension/length	decimal	Length value of parcel
dimension/width	decimal	Width value of parcel
dimension/height	decimal	Height value of parcel
dimension/unit	“mm” “cm” “in” “ft” “m”	Unit used for height, length, and width
weight	object	Weight object
weight/unit	“kg” “g” “oz” “lb”	Unit used for Weight/value
weight/value	decimal	Weight value of parcel
shipment/is_signature_required	boolean	1 if signature is required 0 if not
service	“Express” “Standard” “Econ”	Type of shipment service
promised_delivery_date	date-time	Expected date of shipment arrival

Sample request

 {
{
  "shipment": {
    "shipment_date": "2019-08-24T14:15:22Z",
    "sender_address": {
      "street1": "string",
      "street2": "string",
      "city": "string",
      "state": "st",
      "zip": "string",
      "country": "st",
      "company": "string",
      "name": "string",
      "email": "user@example.com",
      "phone": "string"
    },
    "recipient_address": {
      "street1": "string",
      "street2": "string",
      "city": "string",
      "state": "st",
      "zip": "string",
      "country": "st",
      "company": "string",
      "name": "string",
      "email": "user@example.com",
      "phone": "string"
    },
    "delivery_instructions": "string",
    "parcel": {
      "items": [
        {
          "description": "string",
          "origin_country": "st",
          "sku_code": "string",
          "hs_code": "string",
          "unit_weight": {
            "unit": "kg",
            "value": "string"
          },
          "unit_value": {
            "currency": "USD",
            "amount": "string"
          },
          "quantity": 0
        }
      ],
      "dimensions": {
        "length": "string",
        "width": "string",
        "height": "string",
        "unit": "mm"
      },
      "weight": {
        "unit": "kg",
        "value": "string"
      }
    },
    "is_signature_required": true
  },
  "service": "Express",
  "promised_delivery_date": "2019-08-24T14:15:22Z"
}

Expected Response Elements

Kurier’s endpoints offer an easy integration to your system that allows you to create new shipments, get the shipping rates, label, and tracking information in an expedient and secure approach. In this document, you can find detailed information of each of our endpoints to help you integrate and best use our services.

Element	Type	Description
promised_delivery_date	date-time	Expected date of shipment arrival
shipment_id	string(50)	Identifier of the shipment for which a label is being created
rates	list of Rates	List of rates
rate/amount	string	Rate value of this shipment
rate/rate_id	string	Identifier of the rate being purchased
rate/currency	string	ISO 4217 currency code
rate/eta_date	datetime	Estimated time of arrival
rate/service	string	Name of service

Sample response

{
"promised_delivery_date": "2019-08-24T14:15:22Z",
"shipment_id": "string",
"account_id": 0,
"rates": [
{
"amount": "string",
"rate_id": "string",
"currency": "string",
"eta_date": "2019-08-24T14:15:22Z",
"service": "string"
}
]
}

AWS Endpoint: Create a Label

Previously created rates can be used to create a label using the create label endpoint. Please see below for elements of the label request.

Type	POST
Label Endpoint URL	https://kurier-integration-ab12ec1e2355.herokuapp.com/api/schema/docs/#tag/services/operation/services_carrier_labels_create
Authentication	Token
Format	JSON

Create a Shipment Request Elements: The create a shipment POST request requires the following fields:

Element	Type	Description
shipment	object	Shipment information
shipment/shipment_date	date-time	Shipping date
shipment/sender_address	object	Sender address information
sender_address/street1	string(50)	Sender’s address line 1
sender_address/street2	string(50)	Sender’s address line 2
sender_address/city	string(50)	Sender’s address city
sender_address/state	string(2)	Sender’s address 2-letter state code
sender_address/zip	string(11)	Sender’s address zip code
sender_address/country	string(2)	Sender’s address 2-letter country
sender_address/company	string(50)	Sender’s company or organization name
sender_address/name	string(50)	Sender’s name
sender_address/email	string(254)	Sender’s email
sender_address/phone	string(15)	Sender’s phone number
shipment/recipient_address	object	Recipient address information
recipient_address/street1	string(50)	Recipient's address line 1
recipient_address/street2	string(50)	Recipient's address line 2
recipient_address/city	string(50)	Recipient's address city
recipient_address/state	string(2)	Recipient’s address 2-letter state code
recipient_address/zip	string(11)	Recipient's address zip code
recipient_address/country	string(2)	Recipient's address 2-letter country
recipient_address/company	string(50)	Recipient's company or organization name
recipient_address/name	string(50)	Recipient's name
recipient_address/email	string(254)	Recipient's email
recipient_address/phone	string(15)	Recipient's phone number
shipment/delivery_instructions	string	Additional delivery instructions
shipment/parcel	object	Parcel information
parcel/items	array of objects	List of items
item/description	string	Description of the item
item/origin_country	string(2)	Item’s origin country
item/sku_code	string	Item’s SKU code
item/hs_code	string	Item’s HS code
item/unit_weight	object	Unit weight information
unit_weight/unit	"kg" “g” "oz" "lb"	Unit used for unit weight value
unit_weight/value	int	Weight value of item
item/unit_value	object	Unit value information
unit_value/currency	“USD” “MXN”	Currency used for Item/unit_value/amount
unit_value/amount	decimal	Value of one unit of the item
item/quantity	integer	Number of items
parcel/dimensions	object	Parcel’s dimensions information
dimension/length	decimal	Length value of parcel
dimension/width	decimal	Width value of parcel
dimension/height	decimal	Height value of parcel
dimension/unit	“mm” “cm” “in” “ft” “m”	Unit used for height, length, and width
weight	object	Weight object
weight/unit	“kg” “g” “oz” “lb”	Unit used for Weight/value
weight/value	decimal	Weight value of parcel
shipment/is_signature_required	boolean	1 if signature is required 0 if not
service	“Express” “Standard” “Econ”	Type of shipment service
image_format	string	Type of image format
promised_delivery_date	date-time	Expected date of shipment arrival

Sample request

 {
  "shipment": {
    "shipment_date": "2019-08-24T14:15:22Z",
    "sender_address": {
      "street1": "string",
      "street2": "string",
      "city": "string",
      "state": "st",
      "zip": "string",
      "country": "st",
      "company": "string",
      "name": "string",
      "email": "user@example.com",
      "phone": "string"
    },
    "recipient_address": {
      "street1": "string",
      "street2": "string",
      "city": "string",
      "state": "st",
      "zip": "string",
      "country": "st",
      "company": "string",
      "name": "string",
      "email": "user@example.com",
      "phone": "string"
    },
    "delivery_instructions": "string",
    "parcel": {
      "items": [
        {
          "description": "string",
          "origin_country": "st",
          "sku_code": "string",
          "hs_code": "string",
          "unit_weight": {
            "unit": "kg",
            "value": "string"
          },
          "unit_value": {
            "currency": "USD",
            "amount": "string"
          },
          "quantity": 0
        }
      ],
      "dimensions": {
        "length": "string",
        "width": "string",
        "height": "string",
        "unit": "mm"
      },
      "weight": {
        "unit": "kg",
        "value": "string"
      }
    },
    "is_signature_required": true
  },
  "service": "Standard",
  "image_format": "string",
  "promised_delivery_date": "2019-08-24T14:15:22Z"
}

Expected Response Elements

Element	Type	Description
promised_delivery_date	date-time	Expected date of shipment arrival
shipment_id	string(50)	Shipment ID
image	object	Image information
image/format	string	Requested image format: one of: PDF_4x6, ZPL
image/content	string	Base64-encoded image
tracking_number	string	Tracking number for the parcel
label_id	string	Identifier of the label
rates	object	List of rates
rate/amount	string	Rate value of this shipment
rate/rate_id	string	Identifier of the rate being purchased
rate/currency	string	ISO 4217 currency code
rate/eta_date	string	Estimated time of arrival
rate/service	string	Name of service
shipment_id	string	Identifier of the shipment for which a label is being created
messages	object	List of messages or empty list if not applicable

Sample Response:

 {
  "promised_delivery_date": "2019-08-24T14:15:22Z",
  "image": {
    "format": "string",
    "content": "string"
  },
  "tracking_number": "string",
  "label_id": "string",
  "rate": {
    "amount": "string",
    "rate_id": "string",
    "currency": "string",
    "eta_date": "2019-08-24T14:15:22Z",
    "service": "string"
  },
  "shipment_id": "string",
  "account_id": 0,
  "messages": "string"
}

AWS Endpoint: Tracking

This endpoint provides comprehensive tracking history for a shipment, allowing you to obtain complete traceability of each delivery. The traceability records are consistently sorted in descending order by the date of each operation, providing a clear view of the shipment's progress from start to finish.

Type	POST
Tracking Endpoint URL	https:/</ID>.execute-api.<region>.amazonaws.com/kurier/shippo/tracking
Authentication	Token
Format	JSON

Tracking Request Elements: The tracking POST request requires the following fields.

Element	Type	Description

Sample request

 [
  {
    "tracking_number": "string",
    "eta": "2019-08-24T14:15:22Z",
    "status": "string",
    "receipient_location": {
      "city": "string",
      "state": "string",
      "zip": "string",
      "country": "string"
    }
  }
]

Expected Response Elements

Element	Type	Description
promised_delivery_date	date-time	Expected date of shipment arrival
shipment_id	string(50)	Shipment ID
image	object	Image information
image/format	string	Requested image format: one of: PDF_4x6, ZPL
image/content	string	Base64-encoded image
tracking_number	string	Tracking number for the parcel
label_id	string	Identifier of the label
rates	object	List of rates
rate/amount	string	Rate value of this shipment
rate/rate_id	string	Identifier of the rate being purchased
rate/currency	string	ISO 4217 currency code
rate/eta_date	string	Estimated time of arrival
rate/service	string	Name of service
shipment_id	string	Identifier of the shipment for which a label is being created
messages	object	List of messages or empty list if not applicable

Sample response

 {
  "tracking_number": "string",
  "eta": "2019-08-24T14:15:22Z",
  "status": "string",
  "receipient_location": {
    "city": "string",
    "state": "string",
    "zip": "string",
    "country": "string"
  }
}

Error Codes

Rating Errors

Code	Message
authentication_failed	The account authentication failed. Please insert valid credentials.
dimension_invalid	The dimensions provided are invalid. Please make sure that length, width, and height are integers within this range [].
weight_invalid	The weight provided is invalid. Please make sure that the weight is within this range [].
send_address_invalid	The sender address is invalid or missing information. Please update the sender address.
recip_address_invalid	The recipient address is invalid or missing information. Please update the recipient address.

Create Shipment Errors

Code	Message
authentication_failed	The account authentication failed. Please insert valid credentials.
shipment_date_invalid	The requested shipment date is not valid. Please double check the date inserted.
dimension_invalid	The dimensions provided are invalid. Please make sure that length, width, and height are integers within this range [].
weight_invalid	The weight provided is invalid. Please make sure that the weight is within this range [].
send_address_invalid	The sender address is invalid or missing information. Please update the sender address.
recip_address_invalid	The recipient address is invalid or missing information. Please update the recipient address.
rate_id_invalid	The rate_id provided is invalid. Please provide a valid rate ID.

Tracking Errors

Code	Message
authentication_failed	The account authentication failed. Please insert valid credentials.
trackingNum_invalid	The tracking number provided is invalid. Please insert a valid tracking number.

Our API Documentation