Convelio logo
API docs by Redocly

Convelio Public API (2.0)

Download OpenAPI specification:Download

Convelio API Team: api@convelio.com URL: https://www.convelio.com License: MIT Terms of Service

This document describes the current version of the Shipping API.

The Convelio API is organized around REST. Our API has predictable resource-oriented urls, accept and return json-encoded requests and responses. It also use standard HTTP response codes, authentication, and verbs.

You can use the Convelio API in sandbox mode, which does not affect your live data or interact with the live api. The API key you use to authenticate the request determine whether the request is live mode or sandbox mode.

API key

Convelio authenticates your API requests using your account’s API key. If you do not include your key when making an API request, or use one that is incorrect, Convelio returns an error.

Your API key has a Secret type, prefixed by sk, and should be kept confidential and only stored on your own servers. Your account’s secret API key can perform any API request to Convelio without restriction.

There are also two modes for your API key: live and test.

  • live key can only be used on our production server.
  • test key can only be used on our sandbox server.

Example of key by modes

Type \ Mode Test Live
Secret sk_test_0000000000000000000000000 sk_live_0000000000000000000000000

Obtaining your API key

To get your API key, please send your request at api@convelio.com.

Shipping API

Shipping API allow you to request a shipping estimate from our system

Shipment estimation

Use this endpoint to obtain a first estimation for a shipment.

Authorizations:
secret_token
query Parameters
currency
string (CurrencyCode)
Default: "EUR"
Enum: "EUR" "USD" "GBP"

Currency to use for the response. Accepted currencies are EUR, USD and GBP.

header Parameters
Content-Type
string
Default: application/json
Enum: "application/json" "application/vnd.convelio-shipping.v2+json"

Content-Type header should be sent and should be application/vnd.convelio-shipping.v2+json

Accept
string
Default: application/json
Enum: "*/*" "application/json"

Accept header should be sent and should be application/json

Request Body schema:
required
object (delivery)

Delivery details.

type
required
string (delivery-type)
Enum: "curbside" "white_glove"

Delivery options for the shipment. 2 possible values:

  • curbside: Our drivers will unload the items and deliver them in front of the building at the scheduled time.
  • white_glove: Our drivers will unload, unpack, check and install the product in the chosen room at the scheduled time. For a white-glove delivery, all the packages must fit in the staircase or in the elevator.
required
object (address)
street
string <= 255 characters

Address's street.

city
string <= 255 characters

Address's city.

state
string <= 255 characters

Address's state.

postcode
string <= 255 characters

Address's postcode.

country_code
required
string (country-code)
Enum: "AD" "AE" "AF" "AG" "AI" "AL" "AM" "AO" "AQ" "AR" "AS" "AT" "AU" "AW" "AX" "AZ" "BA" "BB" "BD" "BE" "BF" "BG" "BH" "BI" "BJ" "BL" "BM" "BN" "BO" "BQ" "BR" "BS" "BT" "BV" "BW" "BY" "BZ" "CA" "CC" "CD" "CF" "CG" "CH" "CI" "CK" "CL" "CM" "CN" "CO" "CR" "CU" "CV" "CW" "CX" "CY" "CZ" "DE" "DJ" "DK" "DM" "DO" "DZ" "EC" "EE" "EG" "EH" "ER" "ES" "ET" "FI" "FJ" "FK" "FM" "FO" "FR" "GA" "GB" "GD" "GE" "GF" "GG" "GH" "GI" "GL" "GM" "GN" "GP" "GQ" "GR" "GS" "GT" "GU" "GW" "GY" "HK" "HM" "HN" "HR" "HT" "HU" "ID" "IE" "IL" "IM" "IN" "IO" "IQ" "IR" "IS" "IT" "JE" "JM" "JO" "JP" "KE" "KG" "KH" "KI" "KM" "KN" "KP" "KR" "KW" "KY" "KZ" "LA" "LB" "LC" "LI" "LK" "LR" "LS" "LT" "LU" "LV" "LY" "MA" "MC" "MD" "ME" "MF" "MG" "MH" "MK" "ML" "MM" "MN" "MO" "MP" "MQ" "MR" "MS" "MT" "MU" "MV" "MW" "MX" "MY" "MZ" "NA" "NC" "NE" "NF" "NG" "NI" "NL" "NO" "NP" "NR" "NU" "NZ" "OM" "PA" "PE" "PF" "PG" "PH" "PK" "PL" "PM" "PN" "PR" "PS" "PT" "PW" "PY" "QA" "RE" "RO" "RS" "RU" "RW" "SA" "SB" "SC" "SD" "SE" "SG" "SH" "SI" "SJ" "SK" "SL" "SM" "SN" "SO" "SR" "SS" "ST" "SV" "SX" "SY" "SZ" "TC" "TD" "TF" "TG" "TH" "TJ" "TK" "TL" "TM" "TN" "TO" "TR" "TT" "TV" "TW" "TZ" "UA" "UG" "UM" "US" "UY" "UZ" "VA" "VC" "VE" "VG" "VI" "VN" "VU" "WF" "WS" "YE" "YT" "ZA" "ZM" "ZW"

The country code according to iso-3166-1-alpha-2

object (contact)
first_name
required
string <= 255 characters

Contact's first name.

last_name
required
string <= 255 characters

Contact's last name.

email
required
string <email> <= 255 characters

Contact's main email.

phone
required
string <= 255 characters

Contact's main phone number.

additional_emails
Array of strings <email> [ items <email > ]

Contact's additional email addresses.

additional_phones
Array of strings

Contact's additional phone numbers.

company_name
string <= 255 characters

Delivery company name.

additional_info
string

Additional information regarding the delivery.

shipping_speed
string (speed-shipment-estimation)
Value: "regular_speed"

Freight speed. Possible values:

  • regular speed: Our standard air freight speed option.
direct_label_request
string (direct-label-request)
Enum: "cheapest_option" "direct_label_only" "direct_label_excluded"

Direct label request. Possible values:

  • cheapest_option: API will return direct label prices if available and if direct label is the cheapest option.
  • direct_label_only: API will always consider the direct label option if available and return direct label prices accordingly.
  • direct_label_excluded: API will never consider the direct label option and therefore will never return direct label prices.
contract_insurance
boolean (contract-insurance)

You can add an Ad Valorem insurance that will compensate your prejudice in the event of damage, theft or loss (up to the declared value of your items and shipping costs, in case of total loss).

Array of objects (Pickup)
Array
company_name
string <= 255 characters

The company name.

required
object (address)
Array of objects (Contact) non-empty

Pickup contact details.

required
Array of Item (object) or MultiPartItem (object) non-empty

Pickup items.

additional_info
string

Additional information regarding the pickup.

Responses

Request samples

Content type
{
  • "delivery": {
    },
  • "shipping_speed": "regular_speed",
  • "direct_label_request": "cheapest_option",
  • "contract_insurance": false,
  • "pickups": [
    ]
}

Response samples

Content type
application/json
{
  • "currency_code": "EUR",
  • "vat_excluded_amount": 10000,
  • "vat_included_amount": 12000,
  • "vat_amount": 2000,
  • "insurance_amount": 700
}

Request a quote

Get a quote from Convelio. An operations representative will get in contact with you if necessary.

Authorizations:
secret_token
query Parameters
currency
string (CurrencyCode)
Default: "EUR"
Enum: "EUR" "USD" "GBP"

Currency to use for the response. Accepted currencies are EUR, USD and GBP.

header Parameters
Content-Type
string
Default: application/json
Enum: "application/json" "application/vnd.convelio-shipping.v2+json"

Content-Type header should be sent and should be application/vnd.convelio-shipping.v2+json

Accept
string
Default: application/json
Enum: "*/*" "application/json"

Accept header should be sent and should be application/json

Request Body schema:
required
object (delivery)

Delivery details.

type
required
string (delivery-type)
Enum: "curbside" "white_glove"

Delivery options for the shipment. 2 possible values:

  • curbside: Our drivers will unload the items and deliver them in front of the building at the scheduled time.
  • white_glove: Our drivers will unload, unpack, check and install the product in the chosen room at the scheduled time. For a white-glove delivery, all the packages must fit in the staircase or in the elevator.
required
object (address)
street
string <= 255 characters

Address's street.

city
string <= 255 characters

Address's city.

state
string <= 255 characters

Address's state.

postcode
string <= 255 characters

Address's postcode.

country_code
required
string (country-code)
Enum: "AD" "AE" "AF" "AG" "AI" "AL" "AM" "AO" "AQ" "AR" "AS" "AT" "AU" "AW" "AX" "AZ" "BA" "BB" "BD" "BE" "BF" "BG" "BH" "BI" "BJ" "BL" "BM" "BN" "BO" "BQ" "BR" "BS" "BT" "BV" "BW" "BY" "BZ" "CA" "CC" "CD" "CF" "CG" "CH" "CI" "CK" "CL" "CM" "CN" "CO" "CR" "CU" "CV" "CW" "CX" "CY" "CZ" "DE" "DJ" "DK" "DM" "DO" "DZ" "EC" "EE" "EG" "EH" "ER" "ES" "ET" "FI" "FJ" "FK" "FM" "FO" "FR" "GA" "GB" "GD" "GE" "GF" "GG" "GH" "GI" "GL" "GM" "GN" "GP" "GQ" "GR" "GS" "GT" "GU" "GW" "GY" "HK" "HM" "HN" "HR" "HT" "HU" "ID" "IE" "IL" "IM" "IN" "IO" "IQ" "IR" "IS" "IT" "JE" "JM" "JO" "JP" "KE" "KG" "KH" "KI" "KM" "KN" "KP" "KR" "KW" "KY" "KZ" "LA" "LB" "LC" "LI" "LK" "LR" "LS" "LT" "LU" "LV" "LY" "MA" "MC" "MD" "ME" "MF" "MG" "MH" "MK" "ML" "MM" "MN" "MO" "MP" "MQ" "MR" "MS" "MT" "MU" "MV" "MW" "MX" "MY" "MZ" "NA" "NC" "NE" "NF" "NG" "NI" "NL" "NO" "NP" "NR" "NU" "NZ" "OM" "PA" "PE" "PF" "PG" "PH" "PK" "PL" "PM" "PN" "PR" "PS" "PT" "PW" "PY" "QA" "RE" "RO" "RS" "RU" "RW" "SA" "SB" "SC" "SD" "SE" "SG" "SH" "SI" "SJ" "SK" "SL" "SM" "SN" "SO" "SR" "SS" "ST" "SV" "SX" "SY" "SZ" "TC" "TD" "TF" "TG" "TH" "TJ" "TK" "TL" "TM" "TN" "TO" "TR" "TT" "TV" "TW" "TZ" "UA" "UG" "UM" "US" "UY" "UZ" "VA" "VC" "VE" "VG" "VI" "VN" "VU" "WF" "WS" "YE" "YT" "ZA" "ZM" "ZW"

The country code according to iso-3166-1-alpha-2

required
object (contact)
first_name
required
string <= 255 characters

Contact's first name.

last_name
required
string <= 255 characters

Contact's last name.

email
required
string <email> <= 255 characters

Contact's main email.

phone
required
string <= 255 characters

Contact's main phone number.

additional_emails
Array of strings <email> [ items <email > ]

Contact's additional email addresses.

additional_phones
Array of strings

Contact's additional phone numbers.

company_name
string <= 255 characters

Delivery company name.

additional_info
string

Additional information regarding the delivery.

shipping_speed
required
string (shipping-speed)
Enum: "regular_speed" "express"

Freight speed. Possible values:

  • regular_speed: Our standard air freight speed option.
  • express: After our standard-service pick up and packing, your goods take our priority flights and will be delivered in a shorter time.
direct_label_request
string (direct-label-request)
Enum: "cheapest_option" "direct_label_only" "direct_label_excluded"

Direct label request. Possible values:

  • cheapest_option: API will return direct label prices if available and if direct label is the cheapest option.
  • direct_label_only: API will always consider the direct label option if available and return direct label prices accordingly.
  • direct_label_excluded: API will never consider the direct label option and therefore will never return direct label prices.
contract_insurance
boolean (contract-insurance)

You can add an Ad Valorem insurance that will compensate your prejudice in the event of damage, theft or loss (up to the declared value of your items and shipping costs, in case of total loss).

required
Array of objects (pickup)
Array
company_name
string <= 255 characters

The company name.

required
object (address)
required
Array of objects (Contact) non-empty

Pickup contact details.

required
Array of Item (object) or MultiPartItem (object) non-empty

Pickup items.

additional_info
string

Additional information regarding the pickup.

customer_email
string <email> <= 255 characters

Add a customer email address to receive the quote by email.

customer_reference_number
string <= 255 characters
additional_info
string <= 8000 characters

Responses

Request samples

Content type
{
  • "delivery": {
    },
  • "shipping_speed": "regular_speed",
  • "direct_label_request": "cheapest_option",
  • "contract_insurance": false,
  • "pickups": [
    ],
  • "customer_email": "person@example.com",
  • "customer_reference_number": "string",
  • "additional_info": "string"
}

Response samples

Content type
application/json
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "quote_reference_number": "QVO-001",
  • "shipping_speed": "regular_speed",
  • "direct_label_request": "cheapest_option",
  • "delivery": {
    },
  • "pickups": [
    ],
  • "share_link": "https://web.convelio.com/sharelinkencoded",
  • "contract_insurance": false,
  • "customer_email": "person@example.com",
  • "price": {
    },
  • "status": "created",
  • "customer_reference_number": "CRN123456789",
  • "additional_info": "Additional information for customs."
}

Get quote

Retrieve a quote by its ID.

Authorizations:
secret_token
path Parameters
quoteId
required
string

Quote ID

header Parameters
Content-Type
string
Default: application/json
Enum: "application/json" "application/vnd.convelio-shipping.v2+json"

Content-Type header should be sent and should be application/vnd.convelio-shipping.v2+json

Accept
string
Default: application/json
Enum: "*/*" "application/json"

Accept header should be sent and should be application/json

Responses

Response samples

Content type
application/json
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "quote_reference_number": "QVO-001",
  • "shipping_speed": "regular_speed",
  • "direct_label_request": "cheapest_option",
  • "delivery": {
    },
  • "pickups": [
    ],
  • "share_link": "https://web.convelio.com/sharelinkencoded",
  • "contract_insurance": false,
  • "customer_email": "person@example.com",
  • "price": {
    },
  • "status": "created",
  • "customer_reference_number": "CRN123456789",
  • "additional_info": "Additional information for customs."
}

Update a quote

Update a quote from Convelio.

Authorizations:
secret_token
path Parameters
quoteId
required
string

Quote ID

header Parameters
Content-Type
string
Default: application/json
Enum: "application/json" "application/vnd.convelio-shipping.v2+json"

Content-Type header should be sent and should be application/vnd.convelio-shipping.v2+json

Accept
string
Default: application/json
Enum: "*/*" "application/json"

Accept header should be sent and should be application/json

Request Body schema:
object (delivery-update)

Delivery details update.

object (contact)
first_name
required
string <= 255 characters

Contact's first name.

last_name
required
string <= 255 characters

Contact's last name.

email
required
string <email> <= 255 characters

Contact's main email.

phone
required
string <= 255 characters

Contact's main phone number.

additional_emails
Array of strings <email> [ items <email > ]

Contact's additional email addresses.

additional_phones
Array of strings

Contact's additional phone numbers.

company_name
string <= 255 characters

Delivery company name.

additional_info
string

Additional information regarding the delivery.

customer_reference_number
string <= 255 characters
customer_email
string <email> <= 255 characters

Add a customer email address to receive the quote by email.

additional_info
string <= 8000 characters

Additional information regarding the whole booking.

Responses

Request samples

Content type
{
  • "delivery": {
    },
  • "customer_reference_number": "string",
  • "customer_email": "person@example.com",
  • "additional_info": "Additional information for customs."
}

Response samples

Content type
application/json
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "quote_reference_number": "QVO-001",
  • "shipping_speed": "regular_speed",
  • "direct_label_request": "cheapest_option",
  • "delivery": {
    },
  • "pickups": [
    ],
  • "share_link": "https://web.convelio.com/sharelinkencoded",
  • "contract_insurance": false,
  • "customer_email": "person@example.com",
  • "price": {
    },
  • "status": "created",
  • "customer_reference_number": "CRN123456789",
  • "additional_info": "Additional information for customs."
}

Create an Order

Create an order for given Quote ID.

query Parameters
currency
string (CurrencyCode)
Default: "EUR"
Enum: "EUR" "USD" "GBP"

Currency to use for the response. Accepted currencies are EUR, USD and GBP.

header Parameters
Content-Type
string
Default: application/json
Enum: "application/json" "application/vnd.convelio-shipping.v2+json"

Content-Type header should be sent and should be application/vnd.convelio-shipping.v2+json

Accept
string
Default: application/json
Enum: "*/*" "application/json"

Accept header should be sent and should be application/json

Request Body schema:
quote_id
required
string <uuid>

Quote ID, which is the base of the Order

object (billing-details)

Required when no default billing details are set. Please, contact Convelio.

required
object (address)
street
string <= 255 characters

Address's street.

city
string <= 255 characters

Address's city.

state
string <= 255 characters

Address's state.

postcode
string <= 255 characters

Address's postcode.

country_code
required
string (country-code)
Enum: "AD" "AE" "AF" "AG" "AI" "AL" "AM" "AO" "AQ" "AR" "AS" "AT" "AU" "AW" "AX" "AZ" "BA" "BB" "BD" "BE" "BF" "BG" "BH" "BI" "BJ" "BL" "BM" "BN" "BO" "BQ" "BR" "BS" "BT" "BV" "BW" "BY" "BZ" "CA" "CC" "CD" "CF" "CG" "CH" "CI" "CK" "CL" "CM" "CN" "CO" "CR" "CU" "CV" "CW" "CX" "CY" "CZ" "DE" "DJ" "DK" "DM" "DO" "DZ" "EC" "EE" "EG" "EH" "ER" "ES" "ET" "FI" "FJ" "FK" "FM" "FO" "FR" "GA" "GB" "GD" "GE" "GF" "GG" "GH" "GI" "GL" "GM" "GN" "GP" "GQ" "GR" "GS" "GT" "GU" "GW" "GY" "HK" "HM" "HN" "HR" "HT" "HU" "ID" "IE" "IL" "IM" "IN" "IO" "IQ" "IR" "IS" "IT" "JE" "JM" "JO" "JP" "KE" "KG" "KH" "KI" "KM" "KN" "KP" "KR" "KW" "KY" "KZ" "LA" "LB" "LC" "LI" "LK" "LR" "LS" "LT" "LU" "LV" "LY" "MA" "MC" "MD" "ME" "MF" "MG" "MH" "MK" "ML" "MM" "MN" "MO" "MP" "MQ" "MR" "MS" "MT" "MU" "MV" "MW" "MX" "MY" "MZ" "NA" "NC" "NE" "NF" "NG" "NI" "NL" "NO" "NP" "NR" "NU" "NZ" "OM" "PA" "PE" "PF" "PG" "PH" "PK" "PL" "PM" "PN" "PR" "PS" "PT" "PW" "PY" "QA" "RE" "RO" "RS" "RU" "RW" "SA" "SB" "SC" "SD" "SE" "SG" "SH" "SI" "SJ" "SK" "SL" "SM" "SN" "SO" "SR" "SS" "ST" "SV" "SX" "SY" "SZ" "TC" "TD" "TF" "TG" "TH" "TJ" "TK" "TL" "TM" "TN" "TO" "TR" "TT" "TV" "TW" "TZ" "UA" "UG" "UM" "US" "UY" "UZ" "VA" "VC" "VE" "VG" "VI" "VN" "VU" "WF" "WS" "YE" "YT" "ZA" "ZM" "ZW"

The country code according to iso-3166-1-alpha-2

name
required
string <= 255 characters
email
required
string <email> <= 255 characters
phone
required
string <= 255 characters
vat_number
required
string <= 255 characters
customer_reference_number
string <= 255 characters
eori_number
string <= 255 characters
customer_reference_number
string <= 255 characters

Responses

Request samples

Content type
{
  • "quote_id": "123e4567-e89b-12d3-a456-426614174000",
  • "billing_details": {
    },
  • "customer_reference_number": "REF123456"
}

Response samples

Content type
application/json
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "order_reference_number": "CVO-288",
  • "contract_insurance": false,
  • "shipping_speed": "regular_speed",
  • "pickups": [
    ],
  • "delivery": {
    },
  • "price": {
    },
  • "billing_details": {
    },
  • "tracking_link": "https://tracking.convelio.com/example",
  • "dashboard_order_link": "https://web.convelio.com/dashboard/order/288",
  • "customer_reference_number": "REF123456"
}

Upload a document

Upload an order document. Allowed formats: jpg, jpeg, png, pdf. The maximum allowed file size is 2MB. This endpoint value for the Content-Type header is multipart/form-data.

Authorizations:
secret_token
path Parameters
orderId
required
string

Order ID

header Parameters
ContentType
string
Default: multipart/form-data
Accept
string
Default: application/json
Enum: "*/*" "application/json"

Accept header should be sent and should be application/json

Request Body schema: multipart/form-data
file
required
string

The document file to upload.

type
required
string (document-type)
Enum: "airway_bill" "art_declaration" "atf" "atf_exemption_document" "atr" "bill_of_lading" "certificate_of_insurance" "certificate_of_origin" "cites_permits" "commercial_invoice" "courier_label" "cultural_export_licence" "dau" "dhl_poa" "dle" "eur1" "export_declaration" "import_declaration" "item_pictures" "items_pictures_at_collection" "lacey_act" "letter_of_instruction" "packing_list" "pictures_at_delivery" "poa_other_agent_for_export" "poa_other_agent_for_import" "portside_poa" "proforma_invoice" "prolongations" "proof_of_delivery" "proof_of_export" "proof_of_id_importer" "proof_of_residence_importer" "shipping_label" "t1_form" "t2_form" "tax_id_form" "temporary_regulations"

The type of document.

Responses

Request samples 

curl --location --request POST 'https://api.sandbox.convelio.com/v2/shipping/order/421e1e90-c5fe-4d1e-8b27-141b5ee9f1ea/document' \
  --header 'Content-Type: multipart/form-data' \
  --header 'Authorization: token {TOKEN}' \
  --form 'file=@/home/username/file.pdf' \
  --form 'type=art_declaration'

Response samples

Content type
application/json
{}

Get tracking details

Get tracking details for a given Order ID.

Authorizations:
secret_token
path Parameters
orderId
required
string

Order ID

header Parameters
Content-Type
string
Default: application/json
Enum: "application/json" "application/vnd.convelio-shipping.v2+json"

Content-Type header should be sent and should be application/vnd.convelio-shipping.v2+json

Accept
string
Default: application/json
Enum: "*/*" "application/json"

Accept header should be sent and should be application/json

Responses

Request samples 

curl --location
  --request GET 'https://api.sandbox.convelio.com/v2/shipping/order/{order_id}/tracking \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: token {TOKEN}'

Response samples

Content type
application/json
{
  • "order_reference_number": 123456789,
  • "tracking_number": "CTN56321478",
  • "shipment_status": "shipment_created",
  • "estimated_delivery_date": "2021-10-10T00:00:00+00:00",
  • "last_status_update": "2021-06-14T16:04:44+00:00"
}

Webhook API

The Webhook API allows an API partner to create and manage webhooks.

Custom Quote Ready Event Webhook

Sent when a price is available for a custom quote.

Request Body schema: application/json
event
string
Value: "custom_quote_ready"
created
string <date-time>
object
quote_id
string <uuid>

The Quote ID.

Responses

Request samples

Content type
application/json
{
  • "event": "custom_quote_ready",
  • "created": "2019-08-24T14:15:22Z",
  • "payload": {
    }
}

Quote Paid Event Webhook

Sent when a quote was paid

Authorizations:
convelio_signature
Request Body schema: application/json
event
string
Value: "quote_paid"
created
string <date-time>
object
quote_id
string <uuid>

The Quote ID.

tracking_link
string <uri>

Link to follow the progress of the shipping order.

Responses

Request samples

Content type
application/json
{}

Order Created Event Webhook

Sent when an order is created through the API.

Authorizations:
convelio_signature
Request Body schema: application/json
event
string
Value: "order_created"
created
string <date-time>
object
quote_id
string <uuid>

The Quote ID.

order_id
string <uuid>

The Order ID.

Responses

Request samples

Content type
application/json
{
  • "event": "order_created",
  • "created": "2019-08-24T14:15:22Z",
  • "payload": {
    }
}

Shipment Status Changed Event Webhook

Sent when a new shipment status is published.

Authorizations:
convelio_signature
Request Body schema: application/json
event
string
Value: "shipment_status_changed"
created
string <date-time>
object
order_id
string <uuid>

The Order ID.

shipment_status
string

Shipment status

Responses

Request samples

Content type
application/json
{
  • "event": "shipment_status_changed",
  • "created": "2019-08-24T14:15:22Z",
  • "payload": {
    }
}

Document Ready Event Webhook

Sent when a new document is available.

Authorizations:
convelio_signature
Request Body schema: application/json
event
string
Value: "document_ready"
created
string <date-time>
object
order_id
string <uuid>

The Order ID.

document_type
string

The type of document.

dashboard_order_link
string <uri>

Link to see the details of the shipping order.

Responses

Request samples

Content type
application/json
{
  • "event": "document_ready",
  • "created": "2019-08-24T14:15:22Z",
  • "payload": {
    }
}

List registered webhooks

List all webhooks.

Authorizations:
secret_token
header Parameters
Content-Type
string
Default: application/json
Enum: "application/json" "application/vnd.convelio-shipping.v2+json"

Content-Type header should be sent and should be application/vnd.convelio-shipping.v2+json

Accept
string
Default: application/json
Enum: "*/*" "application/json"

Accept header should be sent and should be application/json

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create webhook

Create a webhook.

Deliveries:

To acknowledge receipt of a webhook delivery, return a 204 OK response with an empty body. To send a negative acknowledgment for the message, return any other status code. Webhook deliveries are signed with the API secret token. HTTP header name: X-Convelio-signature

Retry policy:

If a webhook delivery fails, Convelio will retry the delivery for up to 7 days. Retry attempts will start after 60 seconds and will increase exponentially.
Authorizations:
secret_token
header Parameters
Content-Type
string
Default: application/json
Enum: "application/json" "application/vnd.convelio-shipping.v2+json"

Content-Type header should be sent and should be application/vnd.convelio-shipping.v2+json

Accept
string
Default: application/json
Enum: "*/*" "application/json"

Accept header should be sent and should be application/json

Request Body schema:
url
required
string <uri> (webhook-url) <= 255 characters ^https?:\/\/(?:www\.)?[-a-zA-Z0-9@:%._\+~#=]{...

URL to receive webhooks.

triggering_event_name
required
string (triggering-event-name)
Enum: "custom_quote_ready" "quote_paid" "order_created" "shipment_status_changed" "document_ready"

Responses

Request samples

Content type
{}

Response samples

Content type
application/json
{
  • "id": "df35ed86-2151-437d-839e-ef650313a067",
  • "url": "https://example.com/webhook",
  • "triggering_event_name": "custom_quote_ready",
  • "creation_date": "2020-01-01T00:00:00Z"
}

Get webhook

Get a webhook.

Authorizations:
secret_token
path Parameters
webhookId
required
string

Webhook ID

header Parameters
Content-Type
string
Default: application/json
Enum: "application/json" "application/vnd.convelio-shipping.v2+json"

Content-Type header should be sent and should be application/vnd.convelio-shipping.v2+json

Accept
string
Default: application/json
Enum: "*/*" "application/json"

Accept header should be sent and should be application/json

Responses

Response samples

Content type
application/json
{
  • "id": "df35ed86-2151-437d-839e-ef650313a067",
  • "url": "https://example.com/webhook",
  • "triggering_event_name": "custom_quote_ready",
  • "creation_date": "2020-01-01T00:00:00Z"
}

Update webhook

Update a webhook.

Authorizations:
secret_token
path Parameters
webhookId
required
string

Webhook ID

header Parameters
Content-Type
string
Default: application/json
Enum: "application/json" "application/vnd.convelio-shipping.v2+json"

Content-Type header should be sent and should be application/vnd.convelio-shipping.v2+json

Accept
string
Default: application/json
Enum: "*/*" "application/json"

Accept header should be sent and should be application/json

Request Body schema:
url
required
string <uri> (webhook-url) <= 255 characters ^https?:\/\/(?:www\.)?[-a-zA-Z0-9@:%._\+~#=]{...

URL to receive webhooks.

Responses

Request samples

Content type
{}

Response samples

Content type
application/json
{
  • "id": "df35ed86-2151-437d-839e-ef650313a067",
  • "url": "https://example.com/webhook",
  • "triggering_event_name": "custom_quote_ready",
  • "creation_date": "2020-01-01T00:00:00Z"
}

Delete webhook

Delete a webhook.

Authorizations:
secret_token
path Parameters
webhookId
required
string

Webhook ID

header Parameters
Content-Type
string
Default: application/json
Enum: "application/json" "application/vnd.convelio-shipping.v2+json"

Content-Type header should be sent and should be application/vnd.convelio-shipping.v2+json

Accept
string
Default: application/json
Enum: "*/*" "application/json"

Accept header should be sent and should be application/json

Responses

Response samples

Content type
application/json
{}

Error responses

HttpError

type
required
string

A URL to a page with more details regarding the problem. The primary identifier for the problem. It's typically an absolute URL that leads to an HTML page containing human-readable documentation regarding the problem.

title
required
string

Short human-readable summary of the problem.

status
required
integer >= 100

The HTTP status code. It's always the same as the status code in the HTTP header. It's only included for the convenience of the consumer.

detail
required
string

Human-readable description of this specific problem.

{}

HttpUnprocessableEntityError

type
required
string

A URL to a page with more details regarding the problem. The primary identifier for the problem. It's typically an absolute URL that leads to an HTML page containing human-readable documentation regarding the problem.

title
required
string

Short human-readable summary of the problem.

status
required
integer >= 100

The HTTP status code. It's always the same as the status code in the HTTP header. It's only included for the convenience of the consumer.

detail
required
string

Human-readable description of this specific problem.

object

Validation messages are only returned when your request have a body and the body is invalid.

required
object

The name of the field which is wrong in your request. Example: "delivery_type"

{error_title}
string

The title of the error. Example: "deliveryTypeInvalid"

{}

Models

Address

street
string <= 255 characters

Address's street.

city
string <= 255 characters

Address's city.

state
string <= 255 characters

Address's state.

postcode
string <= 255 characters

Address's postcode.

country_code
required
string (country-code)
Enum: "AD" "AE" "AF" "AG" "AI" "AL" "AM" "AO" "AQ" "AR" "AS" "AT" "AU" "AW" "AX" "AZ" "BA" "BB" "BD" "BE" "BF" "BG" "BH" "BI" "BJ" "BL" "BM" "BN" "BO" "BQ" "BR" "BS" "BT" "BV" "BW" "BY" "BZ" "CA" "CC" "CD" "CF" "CG" "CH" "CI" "CK" "CL" "CM" "CN" "CO" "CR" "CU" "CV" "CW" "CX" "CY" "CZ" "DE" "DJ" "DK" "DM" "DO" "DZ" "EC" "EE" "EG" "EH" "ER" "ES" "ET" "FI" "FJ" "FK" "FM" "FO" "FR" "GA" "GB" "GD" "GE" "GF" "GG" "GH" "GI" "GL" "GM" "GN" "GP" "GQ" "GR" "GS" "GT" "GU" "GW" "GY" "HK" "HM" "HN" "HR" "HT" "HU" "ID" "IE" "IL" "IM" "IN" "IO" "IQ" "IR" "IS" "IT" "JE" "JM" "JO" "JP" "KE" "KG" "KH" "KI" "KM" "KN" "KP" "KR" "KW" "KY" "KZ" "LA" "LB" "LC" "LI" "LK" "LR" "LS" "LT" "LU" "LV" "LY" "MA" "MC" "MD" "ME" "MF" "MG" "MH" "MK" "ML" "MM" "MN" "MO" "MP" "MQ" "MR" "MS" "MT" "MU" "MV" "MW" "MX" "MY" "MZ" "NA" "NC" "NE" "NF" "NG" "NI" "NL" "NO" "NP" "NR" "NU" "NZ" "OM" "PA" "PE" "PF" "PG" "PH" "PK" "PL" "PM" "PN" "PR" "PS" "PT" "PW" "PY" "QA" "RE" "RO" "RS" "RU" "RW" "SA" "SB" "SC" "SD" "SE" "SG" "SH" "SI" "SJ" "SK" "SL" "SM" "SN" "SO" "SR" "SS" "ST" "SV" "SX" "SY" "SZ" "TC" "TD" "TF" "TG" "TH" "TJ" "TK" "TL" "TM" "TN" "TO" "TR" "TT" "TV" "TW" "TZ" "UA" "UG" "UM" "US" "UY" "UZ" "VA" "VC" "VE" "VG" "VI" "VN" "VU" "WF" "WS" "YE" "YT" "ZA" "ZM" "ZW"

The country code according to iso-3166-1-alpha-2

{
  • "street": "42 rue des allees",
  • "city": "Paris",
  • "state": "Ile-de-france",
  • "postcode": "75004",
  • "country_code": "FR"
}

Contact

first_name
required
string <= 255 characters

Contact's first name.

last_name
required
string <= 255 characters

Contact's last name.

email
required
string <email> <= 255 characters

Contact's main email.

phone
required
string <= 255 characters

Contact's main phone number.

additional_emails
Array of strings <email> [ items <email > ]

Contact's additional email addresses.

additional_phones
Array of strings

Contact's additional phone numbers.

{
  • "first_name": "John",
  • "last_name": "Doe",
  • "email": "john.doe@exemple.com",
  • "phone": "+442033188673",
  • "additional_emails": [
    ],
  • "additional_phones": [
    ]
}

Item

name
string <= 255 characters
description
required
string <= 255 characters
quantity
integer multiple of 1 >= 1
Default: 1

Item quantity.

current_packing
required
string (packing-type)
Enum: "not_packed" "wood_crated"
  • not_packed: Your product is not protected by any kind of bubble warp or cardboard.
  • wood_crated: Your product is fully covered in bubble warp and fragile corners are covered with cardboard. Also, you placed adapted protections inside the wooden crate to prevent your product from moving too much and to protect it even further. Last but not least, the wood crate is put on pallet.
desired_packing
string (desired-packing)
Enum: "masterpack" "cardboard_box_stdo_c1" "cardboard_box_stdo_c2" "cardboard_box_stdo_c3" "cardboard_box_stdo_c4" "cardboard_box_stdo_c5" "cardboard_box_stdo_c6" "cardboard_box_stdo_fp1" "cardboard_box_stdo_fp2" "cardboard_box_stdo_t1" "cardboard_box_stdo_j1" "cardboard_box_stdo_f1" "cardboard_box_stdo_largetube" "cardboard_box_stdo_2c1" "cardboard_box_stdo_3c1" "cardboard_box_stdo_2c2" "cardboard_box_stdo_3c2" "cardboard_box_stdo_2c3" "cardboard_box_stdo_3c3" "cardboard_box_stdo_2c4" "cardboard_box_stdo_3c4" "cardboard_box_stdo_2c5" "cardboard_box_stdo_3c5" "cardboard_box_stdo_2c6" "cardboard_box_stdo_3c6" "cardboard_box_stdo_2fp1" "cardboard_box_stdo_3fp1" "cardboard_box_stdo_2fp2" "cardboard_box_stdo_3fp2" "woodcrate_nsdp_pp" "woodcrate_nsdp_g" "woodcrate_nsdp_ppg" "woodcrate_nsdp_cw" "woodcrate_nsdp_tf" "woodcrate_nsdp_tfw" "woodcrate_nsdp_af" "woodcrate_nsdo_scs" "woodcrate_nsdo_scl"

Leave empty by default.

  • masterpack: Convelio will soft-wrap the item and place it into a cardboard box.
measurement_system
string (measurement-system)
Default: "metric"
Enum: "us" "metric"

Unit system used for the pickup.

type
string (item-type)

Available options:

  • fine_art.painting: Fine art painting
  • fine_art.picture: Fine art picture
  • fine_art.sculpture: Fine art sculpture
  • fine_art.other: Other types of fine art
  • furniture.chair: Furniture chair
  • furniture.mirror: Furniture mirror
  • furniture.table: Furniture table
  • furniture.other: Other types of furniture
  • lamp.chandelier: Lamp chandelier
  • lamp.sconce: Lamp sconce
  • lamp.other: Other types of lamps
  • other.other: Items of another nature
materials
Array of strings (item-materials)

Available options:

  • glass: Glass, crystal or mirror
  • stone: Marble or other stone
  • ceramic: Ceramic or terracotta
  • plaster_concrete: Concrete or plaster
  • resin: Resin or any polymers
  • none: The item does not contain any of the other materials

Invalid values will be matched to none

required
object (commercial-value)

Item commercial value.

amount
required
integer >= 0

Item commercial value amount. The amount is a positive integer or zero. A positive integer representing the price of the quote in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). The minimum amount is $0.50 US or equivalent in charge currency. The amount value supports up to eight digits (e.g., a value of 99999999 for a USD charge of $999,999.99).

currency_code
required
string (currency-code)
Enum: "EUR" "USD" "GBP"

The currency code, according to ISO 4217

length
required
integer multiple of 1 >= 1

Item length in cm or inch, depending on the measurement system used.

height
required
integer multiple of 1 >= 1

Item height in cm or inch, depending on the measurement system used.

width
required
integer multiple of 1 >= 1

Item width in cm or inch, depending on the measurement system used.

weight
integer multiple of 1 >= 1

Item weight in kg or lbs, depending on the measurement system used.

{
  • "name": "Vase ming",
  • "description": "Vase ming XIV",
  • "quantity": 1,
  • "current_packing": "not_packed",
  • "desired_packing": "masterpack",
  • "measurement_system": "us",
  • "type": "other.other",
  • "materials": [
    ],
  • "value": {
    },
  • "length": 100,
  • "height": 100,
  • "width": 100,
  • "weight": 100
}

Price

currency_code
string (Money)

Shipping estimate price's currency code. Accepted currencies are EUR, USD and GBP.

vat_excluded_amount
integer

Amount is a positive integer or zero. Estimated price of the shipping excluding taxes. A positive integer representing the price of the quote in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). The minimum amount is $0.50 US or equivalent in charge currency. The amount value supports up to eight digits (e.g., a value of 99999999 for a USD charge of $999,999.99).

vat_included_amount
integer

Amount is a positive integer or zero. Estimated price of the shipping including taxes. A positive integer representing the price of the quote in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). The minimum amount is $0.50 US or equivalent in charge currency. The amount value supports up to eight digits (e.g., a value of 99999999 for a USD charge of $999,999.99).

vat_amount
integer

Amount is a positive integer or zero. Estimated price of the taxes. A positive integer representing the price of the quote in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). The minimum amount is $0.50 US or equivalent in charge currency. The amount value supports up to eight digits (e.g., a value of 99999999 for a USD charge of $999,999.99).

insurance_amount
integer

Amount is a positive integer or zero. Estimated price of the insurance including taxes. A positive integer representing the price of the quote in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). The minimum amount is $0.50 US or equivalent in charge currency. The amount value supports up to eight digits (e.g., a value of 99999999 for a USD charge of $999,999.99).

{
  • "currency_code": "EUR",
  • "vat_excluded_amount": 10000,
  • "vat_included_amount": 12000,
  • "vat_amount": 2000,
  • "insurance_amount": 700
}

Quote

id
string <uuid>

ID of the Quote.

quote_reference_number
string

This QVO number is a direct reference to the quote and is used to communicate with Convelio's operational and support teams.

shipping_speed
string (shipping-speed)
Enum: "regular_speed" "express"

Freight speed. Possible values:

  • regular_speed: Our standard air freight speed option.
  • express: After our standard-service pick up and packing, your goods take our priority flights and will be delivered in a shorter time.
direct_label_request
string (direct-label-request)
Enum: "cheapest_option" "direct_label_only" "direct_label_excluded"

Direct label request. Possible values:

  • cheapest_option: API will return direct label prices if available and if direct label is the cheapest option.
  • direct_label_only: API will always consider the direct label option if available and return direct label prices accordingly.
  • direct_label_excluded: API will never consider the direct label option and therefore will never return direct label prices.
object (delivery)

Delivery details.

type
required
string (delivery-type)
Enum: "curbside" "white_glove"

Delivery options for the shipment. 2 possible values:

  • curbside: Our drivers will unload the items and deliver them in front of the building at the scheduled time.
  • white_glove: Our drivers will unload, unpack, check and install the product in the chosen room at the scheduled time. For a white-glove delivery, all the packages must fit in the staircase or in the elevator.
required
object (address)
street
string <= 255 characters

Address's street.

city
string <= 255 characters

Address's city.

state
string <= 255 characters

Address's state.

postcode
string <= 255 characters

Address's postcode.

country_code
required
string (country-code)
Enum: "AD" "AE" "AF" "AG" "AI" "AL" "AM" "AO" "AQ" "AR" "AS" "AT" "AU" "AW" "AX" "AZ" "BA" "BB" "BD" "BE" "BF" "BG" "BH" "BI" "BJ" "BL" "BM" "BN" "BO" "BQ" "BR" "BS" "BT" "BV" "BW" "BY" "BZ" "CA" "CC" "CD" "CF" "CG" "CH" "CI" "CK" "CL" "CM" "CN" "CO" "CR" "CU" "CV" "CW" "CX" "CY" "CZ" "DE" "DJ" "DK" "DM" "DO" "DZ" "EC" "EE" "EG" "EH" "ER" "ES" "ET" "FI" "FJ" "FK" "FM" "FO" "FR" "GA" "GB" "GD" "GE" "GF" "GG" "GH" "GI" "GL" "GM" "GN" "GP" "GQ" "GR" "GS" "GT" "GU" "GW" "GY" "HK" "HM" "HN" "HR" "HT" "HU" "ID" "IE" "IL" "IM" "IN" "IO" "IQ" "IR" "IS" "IT" "JE" "JM" "JO" "JP" "KE" "KG" "KH" "KI" "KM" "KN" "KP" "KR" "KW" "KY" "KZ" "LA" "LB" "LC" "LI" "LK" "LR" "LS" "LT" "LU" "LV" "LY" "MA" "MC" "MD" "ME" "MF" "MG" "MH" "MK" "ML" "MM" "MN" "MO" "MP" "MQ" "MR" "MS" "MT" "MU" "MV" "MW" "MX" "MY" "MZ" "NA" "NC" "NE" "NF" "NG" "NI" "NL" "NO" "NP" "NR" "NU" "NZ" "OM" "PA" "PE" "PF" "PG" "PH" "PK" "PL" "PM" "PN" "PR" "PS" "PT" "PW" "PY" "QA" "RE" "RO" "RS" "RU" "RW" "SA" "SB" "SC" "SD" "SE" "SG" "SH" "SI" "SJ" "SK" "SL" "SM" "SN" "SO" "SR" "SS" "ST" "SV" "SX" "SY" "SZ" "TC" "TD" "TF" "TG" "TH" "TJ" "TK" "TL" "TM" "TN" "TO" "TR" "TT" "TV" "TW" "TZ" "UA" "UG" "UM" "US" "UY" "UZ" "VA" "VC" "VE" "VG" "VI" "VN" "VU" "WF" "WS" "YE" "YT" "ZA" "ZM" "ZW"

The country code according to iso-3166-1-alpha-2

object (contact)
first_name
required
string <= 255 characters

Contact's first name.

last_name
required
string <= 255 characters

Contact's last name.

email
required
string <email> <= 255 characters

Contact's main email.

phone
required
string <= 255 characters

Contact's main phone number.

additional_emails
Array of strings <email> [ items <email > ]

Contact's additional email addresses.

additional_phones
Array of strings

Contact's additional phone numbers.

company_name
string <= 255 characters

Delivery company name.

additional_info
string

Additional information regarding the delivery.

Array of objects (Pickup)
Array
company_name
string <= 255 characters

The company name.

required
object (address)
Array of objects (Contact) non-empty

Pickup contact details.

required
Array of Item (object) or MultiPartItem (object) non-empty

Pickup items.

additional_info
string

Additional information regarding the pickup.

share_link
string <uri>

Instant quote sharelink.

contract_insurance
boolean (contract-insurance)

You can add an Ad Valorem insurance that will compensate your prejudice in the event of damage, theft or loss (up to the declared value of your items and shipping costs, in case of total loss).

customer_email
string <email> <= 255 characters

Add a customer email address to receive the quote by email.

object (price)
currency_code
string (Money)

Shipping estimate price's currency code. Accepted currencies are EUR, USD and GBP.

vat_excluded_amount
integer

Amount is a positive integer or zero. Estimated price of the shipping excluding taxes. A positive integer representing the price of the quote in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). The minimum amount is $0.50 US or equivalent in charge currency. The amount value supports up to eight digits (e.g., a value of 99999999 for a USD charge of $999,999.99).

vat_included_amount
integer

Amount is a positive integer or zero. Estimated price of the shipping including taxes. A positive integer representing the price of the quote in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). The minimum amount is $0.50 US or equivalent in charge currency. The amount value supports up to eight digits (e.g., a value of 99999999 for a USD charge of $999,999.99).

vat_amount
integer

Amount is a positive integer or zero. Estimated price of the taxes. A positive integer representing the price of the quote in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). The minimum amount is $0.50 US or equivalent in charge currency. The amount value supports up to eight digits (e.g., a value of 99999999 for a USD charge of $999,999.99).

insurance_amount
integer

Amount is a positive integer or zero. Estimated price of the insurance including taxes. A positive integer representing the price of the quote in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). The minimum amount is $0.50 US or equivalent in charge currency. The amount value supports up to eight digits (e.g., a value of 99999999 for a USD charge of $999,999.99).

status
string (quote-status)
Enum: "created" "processing"
  • created: The API successfully returned an instant shipping price and the quote has been created in Convelio's system.
  • processing: The API could not return an instant shipping price for some reason (geography, over-sized item, high commercial value) and Convelio's Operational team is working on providing a Custom Quote within 24h.
customer_reference_number
string <= 255 characters
additional_info
string <= 8000 characters
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "quote_reference_number": "QVO-001",
  • "shipping_speed": "regular_speed",
  • "direct_label_request": "cheapest_option",
  • "delivery": {
    },
  • "pickups": [
    ],
  • "share_link": "https://web.convelio.com/sharelinkencoded",
  • "contract_insurance": false,
  • "customer_email": "person@example.com",
  • "price": {
    },
  • "status": "created",
  • "customer_reference_number": "CRN123456789",
  • "additional_info": "Additional information for customs."
}

Order

id
string <uuid>

Order ID.

order_reference_number
string
contract_insurance
boolean (contract-insurance)

You can add an Ad Valorem insurance that will compensate your prejudice in the event of damage, theft or loss (up to the declared value of your items and shipping costs, in case of total loss).

shipping_speed
string (shipping-speed)
Enum: "regular_speed" "express"

Freight speed. Possible values:

  • regular_speed: Our standard air freight speed option.
  • express: After our standard-service pick up and packing, your goods take our priority flights and will be delivered in a shorter time.
Array of objects (Pickup)
Array
company_name
string <= 255 characters

The company name.

required
object (address)
Array of objects (Contact) non-empty

Pickup contact details.

required
Array of Item (object) or MultiPartItem (object) non-empty

Pickup items.

additional_info
string

Additional information regarding the pickup.

object (delivery)

Delivery details.

type
required
string (delivery-type)
Enum: "curbside" "white_glove"

Delivery options for the shipment. 2 possible values:

  • curbside: Our drivers will unload the items and deliver them in front of the building at the scheduled time.
  • white_glove: Our drivers will unload, unpack, check and install the product in the chosen room at the scheduled time. For a white-glove delivery, all the packages must fit in the staircase or in the elevator.
required
object (address)
street
string <= 255 characters

Address's street.

city
string <= 255 characters

Address's city.

state
string <= 255 characters

Address's state.

postcode
string <= 255 characters

Address's postcode.

country_code
required
string (country-code)
Enum: "AD" "AE" "AF" "AG" "AI" "AL" "AM" "AO" "AQ" "AR" "AS" "AT" "AU" "AW" "AX" "AZ" "BA" "BB" "BD" "BE" "BF" "BG" "BH" "BI" "BJ" "BL" "BM" "BN" "BO" "BQ" "BR" "BS" "BT" "BV" "BW" "BY" "BZ" "CA" "CC" "CD" "CF" "CG" "CH" "CI" "CK" "CL" "CM" "CN" "CO" "CR" "CU" "CV" "CW" "CX" "CY" "CZ" "DE" "DJ" "DK" "DM" "DO" "DZ" "EC" "EE" "EG" "EH" "ER" "ES" "ET" "FI" "FJ" "FK" "FM" "FO" "FR" "GA" "GB" "GD" "GE" "GF" "GG" "GH" "GI" "GL" "GM" "GN" "GP" "GQ" "GR" "GS" "GT" "GU" "GW" "GY" "HK" "HM" "HN" "HR" "HT" "HU" "ID" "IE" "IL" "IM" "IN" "IO" "IQ" "IR" "IS" "IT" "JE" "JM" "JO" "JP" "KE" "KG" "KH" "KI" "KM" "KN" "KP" "KR" "KW" "KY" "KZ" "LA" "LB" "LC" "LI" "LK" "LR" "LS" "LT" "LU" "LV" "LY" "MA" "MC" "MD" "ME" "MF" "MG" "MH" "MK" "ML" "MM" "MN" "MO" "MP" "MQ" "MR" "MS" "MT" "MU" "MV" "MW" "MX" "MY" "MZ" "NA" "NC" "NE" "NF" "NG" "NI" "NL" "NO" "NP" "NR" "NU" "NZ" "OM" "PA" "PE" "PF" "PG" "PH" "PK" "PL" "PM" "PN" "PR" "PS" "PT" "PW" "PY" "QA" "RE" "RO" "RS" "RU" "RW" "SA" "SB" "SC" "SD" "SE" "SG" "SH" "SI" "SJ" "SK" "SL" "SM" "SN" "SO" "SR" "SS" "ST" "SV" "SX" "SY" "SZ" "TC" "TD" "TF" "TG" "TH" "TJ" "TK" "TL" "TM" "TN" "TO" "TR" "TT" "TV" "TW" "TZ" "UA" "UG" "UM" "US" "UY" "UZ" "VA" "VC" "VE" "VG" "VI" "VN" "VU" "WF" "WS" "YE" "YT" "ZA" "ZM" "ZW"

The country code according to iso-3166-1-alpha-2

object (contact)
first_name
required
string <= 255 characters

Contact's first name.

last_name
required
string <= 255 characters

Contact's last name.

email
required
string <email> <= 255 characters

Contact's main email.

phone
required
string <= 255 characters

Contact's main phone number.

additional_emails
Array of strings <email> [ items <email > ]

Contact's additional email addresses.

additional_phones
Array of strings

Contact's additional phone numbers.

company_name
string <= 255 characters

Delivery company name.

additional_info
string

Additional information regarding the delivery.

object (price)
currency_code
string (Money)

Shipping estimate price's currency code. Accepted currencies are EUR, USD and GBP.

vat_excluded_amount
integer

Amount is a positive integer or zero. Estimated price of the shipping excluding taxes. A positive integer representing the price of the quote in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). The minimum amount is $0.50 US or equivalent in charge currency. The amount value supports up to eight digits (e.g., a value of 99999999 for a USD charge of $999,999.99).

vat_included_amount
integer

Amount is a positive integer or zero. Estimated price of the shipping including taxes. A positive integer representing the price of the quote in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). The minimum amount is $0.50 US or equivalent in charge currency. The amount value supports up to eight digits (e.g., a value of 99999999 for a USD charge of $999,999.99).

vat_amount
integer

Amount is a positive integer or zero. Estimated price of the taxes. A positive integer representing the price of the quote in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). The minimum amount is $0.50 US or equivalent in charge currency. The amount value supports up to eight digits (e.g., a value of 99999999 for a USD charge of $999,999.99).

insurance_amount
integer

Amount is a positive integer or zero. Estimated price of the insurance including taxes. A positive integer representing the price of the quote in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). The minimum amount is $0.50 US or equivalent in charge currency. The amount value supports up to eight digits (e.g., a value of 99999999 for a USD charge of $999,999.99).

object (billing-details)
required
object (address)
street
string <= 255 characters

Address's street.

city
string <= 255 characters

Address's city.

state
string <= 255 characters

Address's state.

postcode
string <= 255 characters

Address's postcode.

country_code
required
string (country-code)
Enum: "AD" "AE" "AF" "AG" "AI" "AL" "AM" "AO" "AQ" "AR" "AS" "AT" "AU" "AW" "AX" "AZ" "BA" "BB" "BD" "BE" "BF" "BG" "BH" "BI" "BJ" "BL" "BM" "BN" "BO" "BQ" "BR" "BS" "BT" "BV" "BW" "BY" "BZ" "CA" "CC" "CD" "CF" "CG" "CH" "CI" "CK" "CL" "CM" "CN" "CO" "CR" "CU" "CV" "CW" "CX" "CY" "CZ" "DE" "DJ" "DK" "DM" "DO" "DZ" "EC" "EE" "EG" "EH" "ER" "ES" "ET" "FI" "FJ" "FK" "FM" "FO" "FR" "GA" "GB" "GD" "GE" "GF" "GG" "GH" "GI" "GL" "GM" "GN" "GP" "GQ" "GR" "GS" "GT" "GU" "GW" "GY" "HK" "HM" "HN" "HR" "HT" "HU" "ID" "IE" "IL" "IM" "IN" "IO" "IQ" "IR" "IS" "IT" "JE" "JM" "JO" "JP" "KE" "KG" "KH" "KI" "KM" "KN" "KP" "KR" "KW" "KY" "KZ" "LA" "LB" "LC" "LI" "LK" "LR" "LS" "LT" "LU" "LV" "LY" "MA" "MC" "MD" "ME" "MF" "MG" "MH" "MK" "ML" "MM" "MN" "MO" "MP" "MQ" "MR" "MS" "MT" "MU" "MV" "MW" "MX" "MY" "MZ" "NA" "NC" "NE" "NF" "NG" "NI" "NL" "NO" "NP" "NR" "NU" "NZ" "OM" "PA" "PE" "PF" "PG" "PH" "PK" "PL" "PM" "PN" "PR" "PS" "PT" "PW" "PY" "QA" "RE" "RO" "RS" "RU" "RW" "SA" "SB" "SC" "SD" "SE" "SG" "SH" "SI" "SJ" "SK" "SL" "SM" "SN" "SO" "SR" "SS" "ST" "SV" "SX" "SY" "SZ" "TC" "TD" "TF" "TG" "TH" "TJ" "TK" "TL" "TM" "TN" "TO" "TR" "TT" "TV" "TW" "TZ" "UA" "UG" "UM" "US" "UY" "UZ" "VA" "VC" "VE" "VG" "VI" "VN" "VU" "WF" "WS" "YE" "YT" "ZA" "ZM" "ZW"

The country code according to iso-3166-1-alpha-2

name
required
string <= 255 characters
email
required
string <email> <= 255 characters
phone
required
string <= 255 characters
vat_number
string <= 255 characters
customer_reference_number
string <= 255 characters
eori_number
string <= 255 characters
tracking_link
string <uri>

Link to follow the progress of the shipping order.

dashboard_order_link
string <uri>

Link to see the details of the shipping order.

customer_reference_number
string <= 255 characters

Customer/partner provided reference number.

{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "order_reference_number": "CVO-288",
  • "contract_insurance": false,
  • "shipping_speed": "regular_speed",
  • "pickups": [
    ],
  • "delivery": {
    },
  • "price": {
    },
  • "billing_details": {
    },
  • "tracking_link": "https://tracking.convelio.com/example",
  • "dashboard_order_link": "https://web.convelio.com/dashboard/order/288",
  • "customer_reference_number": "REF123456"
}

OrderTracking

order_reference_number
required
integer

The Order reference number.

tracking_number
required
string

The Order tracking number.

shipment_status
required
string (shipment-status)
Enum: "shipment_created" "picked_up" "packing_in_progress" "export_in_progress" "freight_in_transit" "import_in_progress" "out_for_delivery" "shipment_completed" "on_hold" "canceled"

The shipment status of the tracked order. Possible values:

  • shipment_created: The Order has been booked and our team is planning collection at the pickup location.
  • picked_up: The items have been collected at the pickup location.
  • packing_in_progress: The items are being packed at one of our crating center for more safety.
  • export_in_progress: The shipment has left our crating center to be sent abroad.
  • freight_in_transit: The shipment is on its way to the delivery location.
  • import_in_progress: The shipment has arrived at country of destination.
  • out_for_delivery: The shipment has arrived the destination facility and the carrier is about to deliver the shipment.
  • shipment_completed: Home, sweet home! The shipment has been delivered to the delivery location.
  • on_hold: The shipment has temporarily been paused.
  • canceled: The shipment has been canceled for some reason.
estimated_delivery_date
string <date-time>

The estimated delivery date for the tracked order. The estimated delivery date becomes available once the shipment has been taken care of by our suppliers. Otherwise, this field will be ommitted from the response.

last_status_update
required
string <date-time>

Last shipment status update time.

{
  • "order_reference_number": 123456789,
  • "tracking_number": "CTN56321478",
  • "shipment_status": "shipment_created",
  • "estimated_delivery_date": "2021-10-10T00:00:00+00:00",
  • "last_status_update": "2021-06-14T16:04:44+00:00"
}

Webhook

id
string <uuid>

Identifier of the webhook

url
required
string <uri> (webhook-url) <= 255 characters ^https?:\/\/(?:www\.)?[-a-zA-Z0-9@:%._\+~#=]{...

URL to receive webhooks.

triggering_event_name
required
string (triggering-event-name)
Enum: "custom_quote_ready" "quote_paid" "order_created" "shipment_status_changed" "document_ready"
creation_date
string <date-time>
{
  • "id": "df35ed86-2151-437d-839e-ef650313a067",
  • "url": "https://example.com/webhook",
  • "triggering_event_name": "custom_quote_ready",
  • "creation_date": "2020-01-01T00:00:00Z"
}

Enums

DeliveryType

string (DeliveryType)
Default: "curbside"
Enum: "curbside" "white_glove"

Delivery options for the shipment. 2 possible values:

  • curbside: Our drivers will unload the items and deliver them in front of the building at the scheduled time.
  • white_glove: Our drivers will unload, unpack, check and install the product in the chosen room at the scheduled time. For a white-glove delivery, all the packages must fit in the staircase or in the elevator.
"curbside"

CountryCode

string (CountryCode)
Enum: "AD" "AE" "AF" "AG" "AI" "AL" "AM" "AO" "AQ" "AR" "AS" "AT" "AU" "AW" "AX" "AZ" "BA" "BB" "BD" "BE" "BF" "BG" "BH" "BI" "BJ" "BL" "BM" "BN" "BO" "BQ" "BR" "BS" "BT" "BV" "BW" "BY" "BZ" "CA" "CC" "CD" "CF" "CG" "CH" "CI" "CK" "CL" "CM" "CN" "CO" "CR" "CU" "CV" "CW" "CX" "CY" "CZ" "DE" "DJ" "DK" "DM" "DO" "DZ" "EC" "EE" "EG" "EH" "ER" "ES" "ET" "FI" "FJ" "FK" "FM" "FO" "FR" "GA" "GB" "GD" "GE" "GF" "GG" "GH" "GI" "GL" "GM" "GN" "GP" "GQ" "GR" "GS" "GT" "GU" "GW" "GY" "HK" "HM" "HN" "HR" "HT" "HU" "ID" "IE" "IL" "IM" "IN" "IO" "IQ" "IR" "IS" "IT" "JE" "JM" "JO" "JP" "KE" "KG" "KH" "KI" "KM" "KN" "KP" "KR" "KW" "KY" "KZ" "LA" "LB" "LC" "LI" "LK" "LR" "LS" "LT" "LU" "LV" "LY" "MA" "MC" "MD" "ME" "MF" "MG" "MH" "MK" "ML" "MM" "MN" "MO" "MP" "MQ" "MR" "MS" "MT" "MU" "MV" "MW" "MX" "MY" "MZ" "NA" "NC" "NE" "NF" "NG" "NI" "NL" "NO" "NP" "NR" "NU" "NZ" "OM" "PA" "PE" "PF" "PG" "PH" "PK" "PL" "PM" "PN" "PR" "PS" "PT" "PW" "PY" "QA" "RE" "RO" "RS" "RU" "RW" "SA" "SB" "SC" "SD" "SE" "SG" "SH" "SI" "SJ" "SK" "SL" "SM" "SN" "SO" "SR" "SS" "ST" "SV" "SX" "SY" "SZ" "TC" "TD" "TF" "TG" "TH" "TJ" "TK" "TL" "TM" "TN" "TO" "TR" "TT" "TV" "TW" "TZ" "UA" "UG" "UM" "US" "UY" "UZ" "VA" "VC" "VE" "VG" "VI" "VN" "VU" "WF" "WS" "YE" "YT" "ZA" "ZM" "ZW"

The country code according to iso-3166-1-alpha-2

"FR"

ShippingSpeedShipmentEstimation

string (ShippingSpeedShipmentEstimation)
Default: "regular_speed"
Value: "regular_speed"

Freight speed. Possible values:

  • regular speed: Our standard air freight speed option.
"regular_speed"

DirectLabelRequest

string (DirectLabelRequest)
Default: "cheapest_option"
Enum: "cheapest_option" "direct_label_only" "direct_label_excluded"

Direct label request. Possible values:

  • cheapest_option: API will return direct label prices if available and if direct label is the cheapest option.
  • direct_label_only: API will always consider the direct label option if available and return direct label prices accordingly.
  • direct_label_excluded: API will never consider the direct label option and therefore will never return direct label prices.
"cheapest_option"

PackingType

string (PackingType)
Enum: "not_packed" "wood_crated"
  • not_packed: Your product is not protected by any kind of bubble warp or cardboard.
  • wood_crated: Your product is fully covered in bubble warp and fragile corners are covered with cardboard. Also, you placed adapted protections inside the wooden crate to prevent your product from moving too much and to protect it even further. Last but not least, the wood crate is put on pallet.
"not_packed"

DesiredPacking

string (DesiredPacking)
Enum: "masterpack" "cardboard_box_stdo_c1" "cardboard_box_stdo_c2" "cardboard_box_stdo_c3" "cardboard_box_stdo_c4" "cardboard_box_stdo_c5" "cardboard_box_stdo_c6" "cardboard_box_stdo_fp1" "cardboard_box_stdo_fp2" "cardboard_box_stdo_t1" "cardboard_box_stdo_j1" "cardboard_box_stdo_f1" "cardboard_box_stdo_largetube" "cardboard_box_stdo_2c1" "cardboard_box_stdo_3c1" "cardboard_box_stdo_2c2" "cardboard_box_stdo_3c2" "cardboard_box_stdo_2c3" "cardboard_box_stdo_3c3" "cardboard_box_stdo_2c4" "cardboard_box_stdo_3c4" "cardboard_box_stdo_2c5" "cardboard_box_stdo_3c5" "cardboard_box_stdo_2c6" "cardboard_box_stdo_3c6" "cardboard_box_stdo_2fp1" "cardboard_box_stdo_3fp1" "cardboard_box_stdo_2fp2" "cardboard_box_stdo_3fp2" "woodcrate_nsdp_pp" "woodcrate_nsdp_g" "woodcrate_nsdp_ppg" "woodcrate_nsdp_cw" "woodcrate_nsdp_tf" "woodcrate_nsdp_tfw" "woodcrate_nsdp_af" "woodcrate_nsdo_scs" "woodcrate_nsdo_scl"

Leave empty by default.

  • masterpack: Convelio will soft-wrap the item and place it into a cardboard box.
"masterpack"

ShippingSpeed

string (ShippingSpeed)
Enum: "regular_speed" "express"

Freight speed. Possible values:

  • regular_speed: Our standard air freight speed option.
  • express: After our standard-service pick up and packing, your goods take our priority flights and will be delivered in a shorter time.
"regular_speed"

Quote Status

string (Quote Status)
Enum: "created" "processing"
  • created: The API successfully returned an instant shipping price and the quote has been created in Convelio's system.
  • processing: The API could not return an instant shipping price for some reason (geography, over-sized item, high commercial value) and Convelio's Operational team is working on providing a Custom Quote within 24h.
"created"

DocumentType

string (DocumentType)
Enum: "airway_bill" "art_declaration" "atf" "atf_exemption_document" "atr" "bill_of_lading" "certificate_of_insurance" "certificate_of_origin" "cites_permits" "commercial_invoice" "courier_label" "cultural_export_licence" "dau" "dhl_poa" "dle" "eur1" "export_declaration" "import_declaration" "item_pictures" "items_pictures_at_collection" "lacey_act" "letter_of_instruction" "packing_list" "pictures_at_delivery" "poa_other_agent_for_export" "poa_other_agent_for_import" "portside_poa" "proforma_invoice" "prolongations" "proof_of_delivery" "proof_of_export" "proof_of_id_importer" "proof_of_residence_importer" "shipping_label" "t1_form" "t2_form" "tax_id_form" "temporary_regulations"

The type of document.

"airway_bill"