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:
application/json

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 (phone) <= 255 characters Phone number with following formats: International E.164 formats: Example: `+33123123123` or `+33 1 23 12 31 23` `+33`: Country code with a `+` prefix `123123123`: Local phone number Spaces between digits are supported, but cleaned on our side. Format with country code, local number, and country ISO2 code: Example: `33;12312313;fr` `33`: Country code (international dialing code) `12312313`: Local phone number `fr`: Country `ISO 3166-1 alpha-2` code (France in this example) The parts are separated by semicolons (`;`).
additional_emails	Array of strings <email> [ items <email > ] Contact's additional email addresses.
additional_phones	Array of strings (Phone) [ items <= 255 characters ] 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

Payload

Content type

application/json

{"delivery": {"type": "curbside",
"address": {"street": "42 rue des allees",
"city": "Paris",
"state": "Ile-de-france",
"postcode": "75004",
"country_code": "FR"
},
"contact": {"first_name": "John",
"last_name": "Doe",
"email": "john.doe@exemple.com",
"phone": "+442033188673",
"additional_emails": ["user@example.com"
],
"additional_phones": ["+442033188673"
]
},
"company_name": "Company Name LTD",
"additional_info": "Additional information regarding the delivery."
},
"shipping_speed": "regular_speed",
"direct_label_request": "cheapest_option",
"contract_insurance": false,
"pickups": [{"company_name": "Company Name LTD",
"address": {"street": "42 rue des allees",
"city": "Paris",
"state": "Ile-de-france",
"postcode": "75004",
"country_code": "FR"
},
"contacts": [{"first_name": "John",
"last_name": "Doe",
"email": "john.doe@exemple.com",
"phone": "+442033188673",
"additional_emails": ["user@example.com"
],
"additional_phones": ["+442033188673"
]
}
],
"items": [{"name": "Vase ming",
"description": "Vase ming XIV",
"quantity": 1,
"current_packing": "not_packed",
"desired_packing": "masterpack",
"measurement_system": "us",
"type": "other.other",
"materials": ["stone",
"glass"
],
"value": {"amount": 15000,
"currency_code": "EUR"
},
"length": 100,
"height": 100,
"width": 100,
"weight": 100
}
],
"additional_info": "Additional information regarding the pickup."
}
]
}

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:
application/json

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 (phone) <= 255 characters Phone number with following formats: International E.164 formats: Example: `+33123123123` or `+33 1 23 12 31 23` `+33`: Country code with a `+` prefix `123123123`: Local phone number Spaces between digits are supported, but cleaned on our side. Format with country code, local number, and country ISO2 code: Example: `33;12312313;fr` `33`: Country code (international dialing code) `12312313`: Local phone number `fr`: Country `ISO 3166-1 alpha-2` code (France in this example) The parts are separated by semicolons (`;`).
additional_emails	Array of strings <email> [ items <email > ] Contact's additional email addresses.
additional_phones	Array of strings (Phone) [ items <= 255 characters ] 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

Payload

Content type

application/json

{"delivery": {"type": "curbside",
"address": {"street": "42 rue des allees",
"city": "Paris",
"state": "Ile-de-france",
"postcode": "75004",
"country_code": "FR"
},
"contact": {"first_name": "John",
"last_name": "Doe",
"email": "john.doe@exemple.com",
"phone": "+442033188673",
"additional_emails": ["user@example.com"
],
"additional_phones": ["+442033188673"
]
},
"company_name": "Company Name LTD",
"additional_info": "Additional information regarding the delivery."
},
"shipping_speed": "regular_speed",
"direct_label_request": "cheapest_option",
"contract_insurance": false,
"pickups": [{"company_name": "Company Name LTD",
"address": {"street": "42 rue des allees",
"city": "Paris",
"state": "Ile-de-france",
"postcode": "75004",
"country_code": "FR"
},
"contacts": [{"first_name": "John",
"last_name": "Doe",
"email": "john.doe@exemple.com",
"phone": "+442033188673",
"additional_emails": ["user@example.com"
],
"additional_phones": ["+442033188673"
]
}
],
"items": [{"name": "Vase ming",
"description": "Vase ming XIV",
"quantity": 1,
"current_packing": "not_packed",
"desired_packing": "masterpack",
"measurement_system": "us",
"type": "other.other",
"materials": ["stone",
"glass"
],
"value": {"amount": 15000,
"currency_code": "EUR"
},
"length": 100,
"height": 100,
"width": 100,
"weight": 100
}
],
"additional_info": "Additional information regarding the pickup."
}
],
"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": {"type": "curbside",
"address": {"street": "42 rue des allees",
"city": "Paris",
"state": "Ile-de-france",
"postcode": "75004",
"country_code": "FR"
},
"contact": {"first_name": "John",
"last_name": "Doe",
"email": "john.doe@exemple.com",
"phone": "+442033188673",
"additional_emails": ["user@example.com"
],
"additional_phones": ["+442033188673"
]
},
"company_name": "Company Name LTD",
"additional_info": "Additional information regarding the delivery."
},
"pickups": [{"company_name": "Company Name LTD",
"address": {"street": "42 rue des allees",
"city": "Paris",
"state": "Ile-de-france",
"postcode": "75004",
"country_code": "FR"
},
"contacts": [{"first_name": "John",
"last_name": "Doe",
"email": "john.doe@exemple.com",
"phone": "+442033188673",
"additional_emails": ["user@example.com"
],
"additional_phones": ["+442033188673"
]
}
],
"items": [{"name": "Vase ming",
"description": "Vase ming XIV",
"quantity": 1,
"current_packing": "not_packed",
"desired_packing": "masterpack",
"measurement_system": "us",
"type": "other.other",
"materials": ["stone",
"glass"
],
"value": {"amount": 15000,
"currency_code": "EUR"
},
"length": 100,
"height": 100,
"width": 100,
"weight": 100
}
],
"additional_info": "Additional information regarding the pickup."
}
],
"share_link": "https://web.convelio.com/sharelinkencoded",
"contract_insurance": false,
"customer_email": "person@example.com",
"price": {"currency_code": "EUR",
"vat_excluded_amount": 10000,
"vat_included_amount": 12000,
"vat_amount": 2000,
"insurance_amount": 700
},
"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": {"type": "curbside",
"address": {"street": "42 rue des allees",
"city": "Paris",
"state": "Ile-de-france",
"postcode": "75004",
"country_code": "FR"
},
"contact": {"first_name": "John",
"last_name": "Doe",
"email": "john.doe@exemple.com",
"phone": "+442033188673",
"additional_emails": ["user@example.com"
],
"additional_phones": ["+442033188673"
]
},
"company_name": "Company Name LTD",
"additional_info": "Additional information regarding the delivery."
},
"pickups": [{"company_name": "Company Name LTD",
"address": {"street": "42 rue des allees",
"city": "Paris",
"state": "Ile-de-france",
"postcode": "75004",
"country_code": "FR"
},
"contacts": [{"first_name": "John",
"last_name": "Doe",
"email": "john.doe@exemple.com",
"phone": "+442033188673",
"additional_emails": ["user@example.com"
],
"additional_phones": ["+442033188673"
]
}
],
"items": [{"name": "Vase ming",
"description": "Vase ming XIV",
"quantity": 1,
"current_packing": "not_packed",
"desired_packing": "masterpack",
"measurement_system": "us",
"type": "other.other",
"materials": ["stone",
"glass"
],
"value": {"amount": 15000,
"currency_code": "EUR"
},
"length": 100,
"height": 100,
"width": 100,
"weight": 100
}
],
"additional_info": "Additional information regarding the pickup."
}
],
"share_link": "https://web.convelio.com/sharelinkencoded",
"contract_insurance": false,
"customer_email": "person@example.com",
"price": {"currency_code": "EUR",
"vat_excluded_amount": 10000,
"vat_included_amount": 12000,
"vat_amount": 2000,
"insurance_amount": 700
},
"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:
application/json

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 (phone) <= 255 characters Phone number with following formats: International E.164 formats: Example: `+33123123123` or `+33 1 23 12 31 23` `+33`: Country code with a `+` prefix `123123123`: Local phone number Spaces between digits are supported, but cleaned on our side. Format with country code, local number, and country ISO2 code: Example: `33;12312313;fr` `33`: Country code (international dialing code) `12312313`: Local phone number `fr`: Country `ISO 3166-1 alpha-2` code (France in this example) The parts are separated by semicolons (`;`).
additional_emails	Array of strings <email> [ items <email > ] Contact's additional email addresses.
additional_phones	Array of strings (Phone) [ items <= 255 characters ] 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

Payload

Content type

application/json

{"delivery": {"contact": {"first_name": "John",
"last_name": "Doe",
"email": "john.doe@exemple.com",
"phone": "+442033188673",
"additional_emails": ["user@example.com"
],
"additional_phones": ["+442033188673"
]
},
"company_name": "Company Name LTD",
"additional_info": "Additional information regarding the 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": {"type": "curbside",
"address": {"street": "42 rue des allees",
"city": "Paris",
"state": "Ile-de-france",
"postcode": "75004",
"country_code": "FR"
},
"contact": {"first_name": "John",
"last_name": "Doe",
"email": "john.doe@exemple.com",
"phone": "+442033188673",
"additional_emails": ["user@example.com"
],
"additional_phones": ["+442033188673"
]
},
"company_name": "Company Name LTD",
"additional_info": "Additional information regarding the delivery."
},
"pickups": [{"company_name": "Company Name LTD",
"address": {"street": "42 rue des allees",
"city": "Paris",
"state": "Ile-de-france",
"postcode": "75004",
"country_code": "FR"
},
"contacts": [{"first_name": "John",
"last_name": "Doe",
"email": "john.doe@exemple.com",
"phone": "+442033188673",
"additional_emails": ["user@example.com"
],
"additional_phones": ["+442033188673"
]
}
],
"items": [{"name": "Vase ming",
"description": "Vase ming XIV",
"quantity": 1,
"current_packing": "not_packed",
"desired_packing": "masterpack",
"measurement_system": "us",
"type": "other.other",
"materials": ["stone",
"glass"
],
"value": {"amount": 15000,
"currency_code": "EUR"
},
"length": 100,
"height": 100,
"width": 100,
"weight": 100
}
],
"additional_info": "Additional information regarding the pickup."
}
],
"share_link": "https://web.convelio.com/sharelinkencoded",
"contract_insurance": false,
"customer_email": "person@example.com",
"price": {"currency_code": "EUR",
"vat_excluded_amount": 10000,
"vat_included_amount": 12000,
"vat_amount": 2000,
"insurance_amount": 700
},
"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:
application/json

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

required

string <email> <= 255 characters

phone

required

string (phone) <= 255 characters

Phone number with following formats:

International E.164 formats:
Example: +33123123123 or +33 1 23 12 31 23
- +33: Country code with a + prefix
- 123123123: Local phone number
Spaces between digits are supported, but cleaned on our side.
Format with country code, local number, and country ISO2 code:
Example: 33;12312313;fr
- 33: Country code (international dialing code)
- 12312313: Local phone number
- fr: Country ISO 3166-1 alpha-2 code (France in this example)
The parts are separated by semicolons (;).

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

Payload

Content type

application/json

{"quote_id": "123e4567-e89b-12d3-a456-426614174000",
"billing_details": {"address": {"street": "42 rue des allees",
"city": "Paris",
"state": "Ile-de-france",
"postcode": "75004",
"country_code": "FR"
},
"name": "Art center",
"email": "art@center.org",
"phone": "+442033188673",
"vat_number": "GB12345697",
"customer_reference_number": "REF123456",
"eori_number": "DE 1234567890 8"
},
"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": [{"company_name": "Company Name LTD",
"address": {"street": "42 rue des allees",
"city": "Paris",
"state": "Ile-de-france",
"postcode": "75004",
"country_code": "FR"
},
"contacts": [{"first_name": "John",
"last_name": "Doe",
"email": "john.doe@exemple.com",
"phone": "+442033188673",
"additional_emails": ["user@example.com"
],
"additional_phones": ["+442033188673"
]
}
],
"items": [{"name": "Vase ming",
"description": "Vase ming XIV",
"quantity": 1,
"current_packing": "not_packed",
"desired_packing": "masterpack",
"measurement_system": "us",
"type": "other.other",
"materials": ["stone",
"glass"
],
"value": {"amount": 15000,
"currency_code": "EUR"
},
"length": 100,
"height": 100,
"width": 100,
"weight": 100
}
],
"additional_info": "Additional information regarding the pickup."
}
],
"delivery": {"type": "curbside",
"address": {"street": "42 rue des allees",
"city": "Paris",
"state": "Ile-de-france",
"postcode": "75004",
"country_code": "FR"
},
"contact": {"first_name": "John",
"last_name": "Doe",
"email": "john.doe@exemple.com",
"phone": "+442033188673",
"additional_emails": ["user@example.com"
],
"additional_phones": ["+442033188673"
]
},
"company_name": "Company Name LTD",
"additional_info": "Additional information regarding the delivery."
},
"price": {"currency_code": "EUR",
"vat_excluded_amount": 10000,
"vat_included_amount": 12000,
"vat_amount": 2000,
"insurance_amount": 700
},
"billing_details": {"address": {"street": "42 rue des allees",
"city": "Paris",
"state": "Ile-de-france",
"postcode": "75004",
"country_code": "FR"
},
"name": "Art center",
"email": "art@center.org",
"phone": "+442033188673",
"vat_number": "GB12345697",
"customer_reference_number": "REF123456",
"eori_number": "DE 1234567890 8"
},
"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

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

{"type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
"title": "Bad Request",
"status": 400,
"detail": "Bad Request."
}

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

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

Payload

Content type

application/json

{"event": "custom_quote_ready",
"created": "2019-08-24T14:15:22Z",
"payload": {"quote_id": "3c071a1d-db86-46a7-9dc8-72ba3fbca992"
}
}

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

Payload

Content type

application/json

{"event": "quote_paid",
"created": "2019-08-24T14:15:22Z",
"payload": {"quote_id": "3c071a1d-db86-46a7-9dc8-72ba3fbca992",
"tracking_link": "https://tracking.convelio.com/example"
}
}

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

Payload

Content type

application/json

{"event": "order_created",
"created": "2019-08-24T14:15:22Z",
"payload": {"quote_id": "3c071a1d-db86-46a7-9dc8-72ba3fbca992",
"order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe"
}
}

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

Payload

Content type

application/json

{"event": "shipment_status_changed",
"created": "2019-08-24T14:15:22Z",
"payload": {"order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
"shipment_status": "string"
}
}

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

Payload

Content type

application/json

{"event": "document_ready",
"created": "2019-08-24T14:15:22Z",
"payload": {"order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
"document_type": "string",
"dashboard_order_link": "http://example.com"
}
}

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

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

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:
application/json

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

Payload

Content type

application/json

{"url": "https://example.com/webhook",
"triggering_event_name": "custom_quote_ready"
}

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:
application/json

url

required

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

URL to receive webhooks.

Responses

Request samples

Payload

Content type

application/json

{"url": "https://example.com/webhook"
}

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

{"type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
"title": "Unauthorized",
"status": 401,
"detail": "Token not found."
}

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.

{"type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
"title": "Forbidden",
"status": 403,
"detail": "Forbidden"
}

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"

{"type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
"title": "Forbidden",
"status": 422,
"detail": "Forbidden",
"validation_messages": {"{field_name}": {"{error_title}": "Invalid delivery type. Valid values are: curbside, white_glove"
}
}
}

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 (phone) <= 255 characters Phone number with following formats: International E.164 formats: Example: `+33123123123` or `+33 1 23 12 31 23` `+33`: Country code with a `+` prefix `123123123`: Local phone number Spaces between digits are supported, but cleaned on our side. Format with country code, local number, and country ISO2 code: Example: `33;12312313;fr` `33`: Country code (international dialing code) `12312313`: Local phone number `fr`: Country `ISO 3166-1 alpha-2` code (France in this example) The parts are separated by semicolons (`;`).
additional_emails	Array of strings <email> [ items <email > ] Contact's additional email addresses.
additional_phones	Array of strings (Phone) [ items <= 255 characters ] Contact's additional phone numbers.

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

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": ["stone",
"glass"
],
"value": {"amount": 15000,
"currency_code": "EUR"
},
"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

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 (phone) <= 255 characters Phone number with following formats: International E.164 formats: Example: `+33123123123` or `+33 1 23 12 31 23` `+33`: Country code with a `+` prefix `123123123`: Local phone number Spaces between digits are supported, but cleaned on our side. Format with country code, local number, and country ISO2 code: Example: `33;12312313;fr` `33`: Country code (international dialing code) `12312313`: Local phone number `fr`: Country `ISO 3166-1 alpha-2` code (France in this example) The parts are separated by semicolons (`;`).
additional_emails	Array of strings <email> [ items <email > ] Contact's additional email addresses.
additional_phones	Array of strings (Phone) [ items <= 255 characters ] 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": {"type": "curbside",
"address": {"street": "42 rue des allees",
"city": "Paris",
"state": "Ile-de-france",
"postcode": "75004",
"country_code": "FR"
},
"contact": {"first_name": "John",
"last_name": "Doe",
"email": "john.doe@exemple.com",
"phone": "+442033188673",
"additional_emails": ["user@example.com"
],
"additional_phones": ["+442033188673"
]
},
"company_name": "Company Name LTD",
"additional_info": "Additional information regarding the delivery."
},
"pickups": [{"company_name": "Company Name LTD",
"address": {"street": "42 rue des allees",
"city": "Paris",
"state": "Ile-de-france",
"postcode": "75004",
"country_code": "FR"
},
"contacts": [{"first_name": "John",
"last_name": "Doe",
"email": "john.doe@exemple.com",
"phone": "+442033188673",
"additional_emails": ["user@example.com"
],
"additional_phones": ["+442033188673"
]
}
],
"items": [{"name": "Vase ming",
"description": "Vase ming XIV",
"quantity": 1,
"current_packing": "not_packed",
"desired_packing": "masterpack",
"measurement_system": "us",
"type": "other.other",
"materials": ["stone",
"glass"
],
"value": {"amount": 15000,
"currency_code": "EUR"
},
"length": 100,
"height": 100,
"width": 100,
"weight": 100
}
],
"additional_info": "Additional information regarding the pickup."
}
],
"share_link": "https://web.convelio.com/sharelinkencoded",
"contract_insurance": false,
"customer_email": "person@example.com",
"price": {"currency_code": "EUR",
"vat_excluded_amount": 10000,
"vat_included_amount": 12000,
"vat_amount": 2000,
"insurance_amount": 700
},
"status": "created",
"customer_reference_number": "CRN123456789",
"additional_info": "Additional information for customs."
}

Order

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 (phone) <= 255 characters Phone number with following formats: International E.164 formats: Example: `+33123123123` or `+33 1 23 12 31 23` `+33`: Country code with a `+` prefix `123123123`: Local phone number Spaces between digits are supported, but cleaned on our side. Format with country code, local number, and country ISO2 code: Example: `33;12312313;fr` `33`: Country code (international dialing code) `12312313`: Local phone number `fr`: Country `ISO 3166-1 alpha-2` code (France in this example) The parts are separated by semicolons (`;`).
additional_emails	Array of strings <email> [ items <email > ] Contact's additional email addresses.
additional_phones	Array of strings (Phone) [ items <= 255 characters ] 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

required

string <email> <= 255 characters

phone

required

string (phone) <= 255 characters

Phone number with following formats:

International E.164 formats:
Example: +33123123123 or +33 1 23 12 31 23
- +33: Country code with a + prefix
- 123123123: Local phone number
Spaces between digits are supported, but cleaned on our side.
Format with country code, local number, and country ISO2 code:
Example: 33;12312313;fr
- 33: Country code (international dialing code)
- 12312313: Local phone number
- fr: Country ISO 3166-1 alpha-2 code (France in this example)
The parts are separated by semicolons (;).

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": [{"company_name": "Company Name LTD",
"address": {"street": "42 rue des allees",
"city": "Paris",
"state": "Ile-de-france",
"postcode": "75004",
"country_code": "FR"
},
"contacts": [{"first_name": "John",
"last_name": "Doe",
"email": "john.doe@exemple.com",
"phone": "+442033188673",
"additional_emails": ["user@example.com"
],
"additional_phones": ["+442033188673"
]
}
],
"items": [{"name": "Vase ming",
"description": "Vase ming XIV",
"quantity": 1,
"current_packing": "not_packed",
"desired_packing": "masterpack",
"measurement_system": "us",
"type": "other.other",
"materials": ["stone",
"glass"
],
"value": {"amount": 15000,
"currency_code": "EUR"
},
"length": 100,
"height": 100,
"width": 100,
"weight": 100
}
],
"additional_info": "Additional information regarding the pickup."
}
],
"delivery": {"type": "curbside",
"address": {"street": "42 rue des allees",
"city": "Paris",
"state": "Ile-de-france",
"postcode": "75004",
"country_code": "FR"
},
"contact": {"first_name": "John",
"last_name": "Doe",
"email": "john.doe@exemple.com",
"phone": "+442033188673",
"additional_emails": ["user@example.com"
],
"additional_phones": ["+442033188673"
]
},
"company_name": "Company Name LTD",
"additional_info": "Additional information regarding the delivery."
},
"price": {"currency_code": "EUR",
"vat_excluded_amount": 10000,
"vat_included_amount": 12000,
"vat_amount": 2000,
"insurance_amount": 700
},
"billing_details": {"address": {"street": "42 rue des allees",
"city": "Paris",
"state": "Ile-de-france",
"postcode": "75004",
"country_code": "FR"
},
"name": "Art center",
"email": "art@center.org",
"phone": "+442033188673",
"vat_number": "GB12345697",
"customer_reference_number": "REF123456",
"eori_number": "DE 1234567890 8"
},
"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)

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)

The type of document.

"airway_bill"

Convelio Public API (2.0)

API key

Example of key by modes

Obtaining your API key

Shipping API

Shipment estimation

Authorizations:

query Parameters

header Parameters

Request Body schema: application/jsonapplication/vnd.convelio-shipping.v2+jsonapplication/json

Responses

Request samples

Response samples

Request a quote

Authorizations:

query Parameters

header Parameters

Request Body schema: application/jsonapplication/vnd.convelio-shipping.v2+jsonapplication/json

Responses

Request samples

Response samples

Get quote

Authorizations:

path Parameters

header Parameters

Responses

Response samples

Update a quote

Authorizations:

path Parameters

header Parameters

Request Body schema: application/jsonapplication/vnd.convelio-shipping.v2+jsonapplication/json

Responses

Request samples

Response samples

Create an Order

query Parameters

header Parameters

Request Body schema: application/jsonapplication/vnd.convelio-shipping.v2+jsonapplication/json

Responses

Request samples

Response samples

Upload a document

Authorizations:

path Parameters

header Parameters

Request Body schema: multipart/form-data

Responses

Request samples

Response samples

Get tracking details

Authorizations:

path Parameters

header Parameters

Responses

Request samples

Response samples

Webhook API

Custom Quote Ready Event Webhook

Request Body schema: application/json

Responses

Request samples

Quote Paid Event Webhook

Authorizations:

Request Body schema: application/json

Responses

Request samples

Order Created Event Webhook

Authorizations:

Request Body schema: application/json

Responses

Request samples

Shipment Status Changed Event Webhook

Authorizations:

Request Body schema: application/json

Responses

Request samples

Document Ready Event Webhook

Authorizations:

Request Body schema: application/json

Request Body schema:
application/json

Request Body schema:
application/json

Request Body schema:
application/json

Request Body schema:
application/json

Request Body schema:
application/json

Request Body schema:
application/json