API Documentation

Use the CanaryShip API to create orders, generate labels, retrieve tracking events, and connect shipping operations into your systems.

CanaryTags™ shipment visibility data can be integrated with CanaryShip workflows where enabled.

v2.3.0-dev

Overview

Registration
Authentication Overview

Registration

Before you start working with this documentation, make sure you have a system account. If you don’t, please contact your system administrator to set up your account. Registration is done through invitation email. Once you receive the email, you have to enter a secure password.

Authentication Overview

Basic Authentication

Basic Authentication is a simple method of authentication that allows you to access our API endpoints by providing your username and password. To authenticate using Basic Auth, you need to include your credentials in the Authorization header of your API requests.

Example

Here's an example of how to authenticate using Basic Auth.

Please note that:

The username and password are the same as one could use to access the system web panel.
The username and password are case-sensitive.
API is available only to the users of the Shipper.

When making a request to an API endpoint that requires authentication, include your credentials in the Authorization header in the following format:

Authorization: Basic [base64 encoded username:password]

Bearer Authentication & API Key

API key is a unique identifier that is used to authenticate requests to the API. It is a long string of characters. The API key is generated by the system, and it automatically becomes unique for the Shipper.

Shippers → Shipper → API Key

You can find it after logging in to the system in section of your Shipper, as shown below:

Not all users have access to this property. If it’s not visible, please contact your supervisor or the Application Administrators team.

When making a request to an API endpoint that requires authentication, include your API key within one of 3 ways:

• Send it as Bear token in the Authorization header:

Authorization: Bearer <api_key>

• Send it as a query parameter:

?api_key=<api_key>
?param1=123&api_key=<api_key>

• Invoke parameter into request body:

{
  "api_key": "<api_key>",
  // ...
  // other request parameters from payload
  // ...
}

IP Whitelisting

In order to use the API in Live mode (production mode), all clients must provide the Application Administrators team with a list of their systems' IP addresses for whitelisting. Without that, the use of the API in Live mode will be impossible.

Shipping Solutions

get https://logistics-demo.xmlship.com/api/external/dictionaries/shipping-solutions

This API endpoint retrieves a list of all available shipping solutions.
Use the shipping solution's code from the response to identify and reference a specific shipping solution when processing a parcel.

Request

Security: Bearer Auth

Authorization: Bearer Token authentication required. Add Authorization: Bearer <token> to your requests header to authorize.

Responses

Validation error

Body

Auth

Token :

Loading...

JSON Code rendered dynamically...

Order show - API Documentation

Order show

get https://logistics-demo.xmlship.com/api/external/orders/{identifier}

This API endpoint allows you to retrieve order information by its identifier.

Request

Security: Bearer Auth

Authorization: Bearer Token authentication required. Add Authorization: Bearer <token> to your requests header to authorize.

Params

identifier string path

required

- one of: shipper_order_reference, system_order_reference, platform_order_reference, extra1_order_reference.

Responses

Body

Auth

Token :

Loading...

Order create - API Documentation

Order create

post https://logistics-demo.xmlship.com/api/external/orders

This API endpoint allows you to create a new order in the system by submitting relevant order details.

Request

Security: Bearer Auth

Authorization: Bearer Token authentication required. Add Authorization: Bearer <token> to your requests header to authorize.

Body

is_test boolean

Indicates the environment where an order should be created. false for live mode, true for testing purposes.

currency string

required

Currency of the order. \ ISO 4217 currency code. Currency that has been used to pay for the order. \ This is the general order currency and applies to all monetary fields.

weight_unit string | null

Unit used for weight fields across all order items. \ Might be set as a default in Shippers → Profile → Parcel Defaults.

Allowed values: "kg", "lb", "g"

dimensions_unit string | null

Unit used for dimension fields across all order items. \ Might be set as a default in Shippers → Profile → Parcel Defaults.

Allowed values: "m", "in", "cm", "mm"

shipper_order_reference string

required

A unique client reference that identifies the order. \ Each order must have a unique reference that must not be reused. \

platform_order_reference string | null

A unique platform reference that identifies the order. \ Each order must have a unique reference that must not be reused. \

extra1_order_reference string | null

An extra reference that identifies the order.

shipping_solution_code string

required

Shipping solution code. \ Defines the service level that will be used to fulfill the order. \ The list of available codes can be found in Shippers → Profile → Shipping solutions.

hs_skip_steps array | null

List of HS service steps to forcibly skip during order processing. Available steps: replace_hs_codes, denied_parties_check, update_duty_and_taxes, restriction_screening, suggest_and_replace_description

shipping_cost number | null

Cost of shipping. \ The currency should be selected before shipping_cost is used.

value number | null

Total declared value of the order. \ The currency should be selected before value is used.

description string | null

Brief description of the order contents.

incoterm string | null

Taxes and duties handling term. \

Allowed values: "DDP", "DDU", "DAP"

order_created_at string | null

The date and time when the order was originally created on the merchant's platform.

origin_address object

### Origin (sender) address.

name string | null

Sender's name.

company_name string | null

Sender's company name.

address_line_1 string | null

Sender's address line 1.

address_line_2 string | null

Sender's address line 2.

address_line_3 string | null

Sender's address line 3.

city string | null

Sender's city.

state string | null

Sender's state or region.

zip string | null

Sender's ZIP / postal code.

country string | null

Sender's country. \ Should be in ISO 3166-1 alpha-2 code.

phone string | null

Sender's phone number.

email string | null

Sender's email address.

vat string | null

Sender's VAT number.

eori string | null

Sender's EORI number.

ioss string | null

Sender's IOSS number.

gst string | null

Sender's GST number.

ukims string | null

Sender's UKIMS number.

house_number string | null

Sender's house number (applicable for DE and NL).

destination_address object

required

### Destination (recipient, consignee) address.

name string

required

Consignee's name.

company_name string | null

Consignee's company name (if business delivery).

address_line_1 string

required

Consignee's address line 1.

address_line_2 string | null

Consignee's address line 2.

address_line_3 string | null

Consignee's address line 3.

city string

required

Consignee's city.

state string | null

Consignee's state or region.

zip string | null

Consignee's ZIP / postal code.

country string

required

Consignee's country. \ Should be in ISO 3166-1 alpha-2 code.

phone string | null

Consignee's phone number.

email string | null

Consignee's email address.

vat string | null

Consignee's VAT number.

ioss string | null

Consignee's IOSS number.

eori string | null

Consignee's EORI number.

gst string | null

Consignee's GST number.

ukims string | null

Consignee's UKIMS number.

house_number string | null

Consignee's house number (applicable for DE and NL).

purchaser_abn string | null

Consignee's ABN number.

merchant_arn string | null

Consignee's ARN number.

payment_date string | null

Consignee's payment date.

payment_reference_identity string | null

Consignee's payment reference identity.

tax_identity string | null

Consignee's tax identity.

national_identity string | null

Consignee's national identity.

order_items array

required

### Order items

items object

quantity number

required

The number of units of this item included in the order. \ Required for each item entry.

description string

required

Description of the item. \ Required for each item entry. Used for customs declarations on non-domestic shipments.

total_value number

required

The total value of all units of this item. \ The currency should be selected before order_items.*.total_value is used. \ Required for each item entry.

weight number | null

The weight of a single item. \ Ensure the weight unit weight_unit is specified before using this field, unless a default unit has been preset.

length number | null

The length of a single item. \ Ensure the dimension unit dimensions_unit is specified before using this field, unless a default unit has been preset.

width number | null

The width of a single item. \ Ensure the dimension unit dimensions_unit is specified before using this field, unless a default unit has been preset.

height number | null

The height of a single item. \ Ensure the dimension unit dimensions_unit is specified before using this field, unless a default unit has been preset.

country_of_origin string | null

The country where the item was manufactured. \ Used for customs declarations. Should be in ISO 3166-1 alpha-2 code.

hs_code string | null

The Harmonized System (HS) code for the item. \ A standardized numerical method of classifying traded products, used by customs authorities to assess duties and taxes.

sku string | null

The Stock Keeping Unit (SKU) — a unique code that identifies the product.

url string | null

The product page URL.

image_url string | null

The product image URL.

tax_value number | null

The tax value applied to a single item.

duty_value number | null

The duty value applied to a single item.

Responses

Body

Auth

Token :

Body

{
  "is_test": false,
  "currency": "GBP",
  "weight_unit": "kg",
  "dimensions_unit": "cm",
  "shipper_order_reference": "ORD-0001",
  "platform_order_reference": "#O-0001",
  "extra1_order_reference": "NUM-001",
  "shipping_solution_code": "GSS",
  "hs_skip_steps": [
    "replace_hs_codes",
    "denied_parties_check"
  ],
  "shipping_cost": 12.5,
  "value": 100,
  "description": "Office supplies",
  "incoterm": "DDP",
  "order_created_at": "2024-09-20 21:19:41",
  "origin_address": {
    "name": "John Doe",
    "company_name": "Doe Inc.",
    "address_line_1": "29-31 Catherine Pl",
    "address_line_2": null,
    "address_line_3": null,
    "city": "London",
    "state": null,
    "zip": "SW1E 6DY",
    "country": "GB",
    "phone": "+44 11 2233 4444",
    "email": "sender@example.com",
    "vat": "GB123456789",
    "eori": "GB123456789",
    "ioss": "IM1234567890",
    "gst": null,
    "ukims": "NBN123456789",
    "house_number": null
  },
  "destination_address": {
    "name": "Jon Snow",
    "company_name": "Winterfell Inc.",
    "address_line_1": "1 Castle Black",
    "address_line_2": null,
    "address_line_3": null,
    "city": "Winterfell",
    "state": "North",
    "zip": "W1N 4LL",
    "country": "GB",
    "phone": "+44 11 2233 4444",
    "email": "jon.snow@winterfell.north.seven-kingdoms.uk",
    "vat": null,
    "ioss": null,
    "eori": null,
    "gst": null,
    "ukims": null,
    "house_number": "4",
    "purchaser_abn": null,
    "merchant_arn": null,
    "payment_date": null,
    "payment_reference_identity": null,
    "tax_identity": null,
    "national_identity": null
  },
  "order_items": [
    {
      "quantity": 10,
      "description": "Candles",
      "total_value": 100,
      "weight": 1.2,
      "length": 30,
      "width": 20,
      "height": 20,
      "country_of_origin": "GB",
      "hs_code": "3406000000",
      "sku": "SU1233456",
      "url": "https://example.com/product/SU1233456",
      "image_url": "https://example.com/product/SU1233456/main.png",
      "tax_value": 20,
      "duty_value": 5
    }
  ]
}

Loading...

Parcel create - API Documentation

Parcel create

post https://logistics-demo.xmlship.com/api/external/parcels

This API endpoint allows you to register a new parcel in the system by submitting relevant parcel details. Upon successful registration, the endpoint returns a unique identifier for the parcel and a shipping label that can be used to ship the parcel.

Request

Security: Bearer Auth

Authorization: Bearer Token authentication required. Add Authorization: Bearer <token> to your requests header to authorize.

Body

is_test boolean

Indicates the environment where a parcel should be created. false for live mode, true for testing purposes.

currency string | null

Currency of parcel. \ 4217 currency code. Currency that has been used to pay for the order that is shipped in this parcel. This is the general parcel currency and applies to all monetary fields. \ Can be set as a default in Shippers → Profile → Parcel Defaults.

Allowed values: "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BRL", "BSD", "BTN", "BWP", "BYR", "BZD", "CAD", "CDF", "CHF", "CLF", "CLP", "CNY", "COP", "CRC", "CUC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LTL", "LVL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRO", "MUR", "MVR", "MWK", "MXN", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLL", "SOS", "SRD", "SSP", "STD", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "UYU", "UZS", "VND", "VUV", "WST", "XAF", "XAG", "XAU", "XCD", "XDR", "XOF", "XPF", "YER", "ZAR", "ZMK", "ZMW", "BYN", "GGP", "IMP", "JEP", "ZWL", "SLE", "VES", "MRU", "CNH", "STN", "XCG"

consignee_use_address_successors boolean

When value is true, and permitted for the Shipper, the system will apply the destination address successors logic to identify the appropriate destination address for parcel delivery. Conversely, if disabled and not permitted, the system will default to using the destination address supplied in the request. Can be set as a default in Shippers → Profile → Usage of destination address successors logic type.

shipping object

### Shipping information required to register a parcel.

type string | null

Parcel type. \ Determines parcel type e.g. return or direct \ Defaults to direct if not specified. \

Allowed values: "direct", "return"

shipping_solution_code string

required

Shipping solution code. \ Required for successful parcel creation. Defines the service level that will be used to ship the parcel. \ The list of available codes can be found in Shippers → Profile → Shipping solutions. \ Can be set as a default in Shippers → Profile → Parcel Defaults.

pudo_point string | null

Identification of PUDO point (Pick Up Drop Off). If you don't know the list of PUDO points we recommend contacting the Administrator.

hs_skip_steps array | null

List of HS service steps to forcibly skip during parcel processing. Available steps: replace_hs_codes, denied_parties_check, update_duty_and_taxes, restriction_screening, suggest_and_replace_description

label_format string | null

Format of the requested shipping label. \ \ Can be set as a default in Shippers → Profile → Parcel Defaults. \

Allowed values: "zpl200", "zpl300", "pdf", "png"

label_type string | null

Label type indicates whether a system or a last-mile carrier label should be returned. The possibility of choosing a last-mile carrier label might not be allowed. \ \ Where to check allowed modes: Shippers → Profile → External connections to the system. \ \ If the system option is selected, the system will generate a system label and return it, irrespective of any existing errors. This feature is useful for quickly creating parcels and later relabeling them with a last-mile label. \ If the last_mile option is selected, the system will perform complex validation and processing. If no errors occur, the system will generate a last-mile label and return it.

Allowed values: "system", "last_mile"

shipping_cost number | null

Cost of shipping. \ \ The currency should be selected before shipping.shipping_cost is used.

collection_date object | null

Parcel collection information, applicable only to certain carriers.

delivery_date object | null

Parcel delivery information, applicable only to certain carriers.

package object

### Information that identifies a package.

order_reference string | null

Order number associated with the parcel. Please note that multiple parcels may share the same order reference.

physical_tag string | null

Physical Tag id attached to the parcel.

shipper_tracking_number string | null

The tracking number used for offline generation of system labels. The generation pattern should be provided by the Administrator. If not specified, the system will generate it automatically.

shipper_reference string

required

A unique client reference that identifies the parcel. \ Each parcel should have a unique reference that must not be reused for any other parcel. If the reference is reused, the system may either attempt to recreate the parcel or return an error.

original_tracking_number string | null

Original tracking number associated with the parcel.

original_order_number string | null

Original Order number associated with the parcel.

category string | null

The product category is used to classify items based on their intended purpose or nature.

Allowed values: "commercial_goods", "gifts", "documents", "clothing", "personal_items", "commercial_sample", "returned_goods", "intercompany_transfer", "repair", "humanitarian_donations", "dangerous_goods", "other"

tags array | null

Tags are used to categorize parcels based on specific criteria or attributes from system settings.

dangerous_goods string | null

Indicates whether the parcel contains dangerous goods.

incoterm string | null

An Incoterm (International Commercial Term) is a standardized term used in international trade that defines the responsibilities of buyers and sellers regarding the delivery of goods. It specifies who is responsible for transportation, insurance, customs clearance, and the risks involved in shipping.

Allowed values: "DDP", "DDU", "DAP"

description string | null

Brief summary or detailed explanation of the contents of a package.

delivery_instruction string | null

Specific guidelines or requests provided by the sender or recipient regarding how a parcel should be delivered.

non_delivery_instruction string | null

Guidelines provided by the sender or recipient regarding how a parcel should be handled in the event of a delivery failure.

Allowed values: "return_to_sender", "abandoned", "return_to_parcel_shop", "redirect"

proof_of_delivery_signature string | null

Proof of Delivery (POD) is a document or digital confirmation that verifies a parcel has been successfully delivered to the recipient.

value number | null

The parcel value represents the total market worth of all items contained within the package. \ The currency should be selected before package.value is used.

cash_on_delivery string | null

This determines if the shipment requires payment upon delivery, known as Cash on Delivery (COD) service.

weight object | null

Overall weight of the parcel.

dimensions object | null

Dimensions of the parcel. \ Ensure the dimension unit package.dimensions.unit is specified before using the dimension values package.dimensions.length, package.dimensions.width, and package.dimensions.height, unless a default unit has been preset.

origin_address object

### Origin (sender) address.

name string | null

Sender's name.

company_name string | null

Sender's company name.

address_line_1 string | null

Sender's address line 1.

address_line_2 string | null

Sender's address line 2.

address_line_3 string | null

Sender's address line 3.

house_number string | null

Consignee's house number (applicable for DE and NL).

city string | null

Sender's city.

state string | null

Sender's state.

zip string | null

Sender's ZIP code.

country string | null

Sender's country. \ Should be in ISO 3166-1 alpha-2 code.

Allowed values: "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", "IC", "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", "XK", "YE", "YT", "ZA", "ZM", "ZW", "UK"

phone string | null

Sender's phone number.

email string | null

Sender's email.

vat string | null

Sender's VAT number.

ioss string | null

Sender's IOSS number.

eori string | null

Sender's EORI number.

ukims string | null

Sender's UKIMS number.

gst string | null

Sender's GST number.

destination_address object

### Destination (recipient, consignee) address.

name string | null

Consignee's name.

company_name string | null

Consignee's company name (if business delivery).

address_line_1 string | null

Consignee's address line 1.

address_line_2 string | null

Consignee's address line 2.

address_line_3 string | null

Consignee's address line 3.

house_number string | null

Consignee's house number (applicable for DE and NL).

city string | null

Consignee's city.

state string | null

Consignee's state.

zip string | null

Consignee's ZIP code.

country string | null

Consignee's country. \ Should be in ISO 3166-1 alpha-2 code.

phone string | null

Consignee's phone number.

email string | null

Consignee's email.

vat string | null

Consignee's VAT number.

eori string | null

Sender's EORI number.

gst string | null

Consignee's GST number.

purchaser_abn string | null

Consignee's ABN number.

merchant_arn string | null

Consignee's ARN number.

payment_date string | null

Consignee's payment date.

payment_reference_identity string | null

Consignee's payment reference identity.

tax_identity string | null

Consignee's tax identity.

national_identity string | null

Consignee's national identity.

return_address object

### Return address If no specific return address is provided, the sender's address will automatically be designated as the return address for the shipment.

name string | null

Return address name.

company_name string | null

Return address company name.

address_line_1 string | null

Return address, address line 1.

address_line_2 string | null

Return address, address line 2.

address_line_3 string | null

Return address, address line 3.

house_number string | null

Consignee's house number (applicable for DE and NL).

city string | null

Return address city.

state string | null

Return address state.

zip string | null

Return address ZIP code.

country string | null

Return address country. \ Should be in ISO 3166-1 alpha-2 code.

phone string | null

Return address phone number.

email string | null

Return address email.

vat string | null

Return address VAT number.

ioss string | null

Return address IOSS number.

eori string | null

Return address EORI number.

gst string | null

Return address GST number.

parcel_items array | null

### Parcel items

Responses

Body

Auth

Token :

Body

{
  "is_test": false,
  "currency": "GBP",
  "consignee_use_address_successors": true,
  "shipping": {
    "type": "direct",
    "shipping_solution_code": "",
    "pudo_point": null,
    "hs_skip_steps": [
      "replace_hs_codes",
      "denied_parties_check",
      "update_duty_and_taxes",
      "restriction_screening",
      "suggest_and_replace_description"
    ],
    "label_format": "pdf",
    "label_type": "system",
    "shipping_cost": null,
    "collection_date": {
      "date": "2024-12-31",
      "time_from": "09:00",
      "time_to": "09:00"
    },
    "delivery_date": {
      "date": "2024-12-31",
      "time_from": "09:00",
      "time_to": "09:00"
    }
  },
  "package": {
    "order_reference": "Shopify#123456",
    "physical_tag": "UN9YNK",
    "shipper_tracking_number": null,
    "shipper_reference": "T123456",
    "original_tracking_number": null,
    "original_order_number": "Shopify#123456",
    "category": "commercial_goods",
    "tags": null,
    "dangerous_goods": false,
    "incoterm": "DDP",
    "description": "Clothing",
    "delivery_instruction": "Leave at the front door",
    "non_delivery_instruction": "return_to_sender",
    "proof_of_delivery_signature": false,
    "value": 100,
    "cash_on_delivery": false,
    "weight": {
      "value": 0.8,
      "unit": "kg"
    },
    "dimensions": {
      "length": 30,
      "width": 22,
      "height": 0.5,
      "unit": "cm"
    }
  },
  "origin_address": {
    "name": "John Doe",
    "company_name": "Doe Inc.",
    "address_line_1": "29-31 Catherine Pl",
    "address_line_2": null,
    "address_line_3": null,
    "house_number": null,
    "city": "London",
    "state": null,
    "zip": "SW1E 6DY",
    "country": "GB",
    "phone": "+44 11 2233 4444",
    "email": "sender@example.com",
    "vat": "GB123456789",
    "ioss": "IM1234567890",
    "eori": "GB123456789",
    "ukims": "NBN123456789",
    "gst": null
  },
  "destination_address": {
    "name": "Jon Snow",
    "company_name": "Winterfell Inc.",
    "address_line_1": "1 Castle Black",
    "address_line_2": null,
    "address_line_3": null,
    "house_number": null,
    "city": "Winterfell",
    "state": "North",
    "zip": "W1N 4LL",
    "country": "GB",
    "phone": "+44 11 2233 4444",
    "email": "jon.snow@winterfell.north.seven-kingdoms.uk",
    "vat": null,
    "eori": "GB123456789",
    "gst": null,
    "purchaser_abn": null,
    "merchant_arn": null,
    "payment_date": null,
    "payment_reference_identity": null,
    "tax_identity": null,
    "national_identity": null
  },
  "return_address": {
    "name": "John Doe",
    "company_name": "Doe Inc.",
    "address_line_1": "29-31 Catherine Pl",
    "address_line_2": null,
    "address_line_3": null,
    "house_number": null,
    "city": "London",
    "state": null,
    "zip": "SW1E 6DY",
    "country": "GB",
    "phone": null,
    "email": null,
    "vat": null,
    "ioss": null,
    "eori": null,
    "gst": null
  },
  "parcel_items": null
}

Loading...

Parcel cancel - API Documentation

Parcel cancel

delete https://logistics-demo.xmlship.com/api/external/parcels

This API endpoint allows you to cancel a registered parcel, which will send a command to the system not to proceed with the shipping process. If the parcel has already been sent, the cancellation option will not be available, and the API will return an error.

Request

Security: Bearer Auth

Authorization: Bearer Token authentication required. Add Authorization: Bearer <token> to your requests header to authorize.

Params

is_test string,null query

Indicates the environment where a parcel was created.

parcel_unique_identifier string query

required

A parcel identifier can be one of the following unique parcel identifiers system_tracking_number, shipper_tracking_number, shipper_reference, last_mile_carrier_tracking_number.

Responses

Body

Auth

Token :

Loading...

Parcel return - API Documentation

Parcel return

post https://logistics-demo.xmlship.com/api/external/parcels/return

This API endpoint allows you to return a registered parcel, which will send a command to the system to proceed with the shipping return process.

Request

Security: Bearer Auth

Authorization: Bearer Token authentication required. Add Authorization: Bearer <token> to your requests header to authorize.

Body

is_test string | null

Indicates the environment where a parcel was created.

parcel_unique_identifier string

required

A parcel identifier can be one of the following unique parcel identifiers system_tracking_number, shipper_tracking_number, shipper_reference, last_mile_carrier_tracking_number.

Responses

Body

Auth

Token :

Body

Loading...

Parcel show - API Documentation

Parcel show

get https://logistics-demo.xmlship.com/api/external/parcels/{identifier}

This API endpoint allows you to get the parcel's information by one of the list of parcel identifiers. A parcel identifier can be one of the following unique parcel identifiers: `system_tracking_number`, `shipper_tracking_number`, `last_mile_carrier_tracking_number`, `extra1_last_mile_carrier_tracking_number`

Request

Security: Bearer Auth

Authorization: Bearer Token authentication required. Add Authorization: Bearer <token> to your requests header to authorize.

Params

identifier string path

required

- identifier of the parcel. Any tracking number or shipper reference. Example: 0AdLIrYeeHKx5YRnNmGPt9SrrXuOKVOPw9mH47TLr

Responses

Body

Auth

Token :

Loading...

Parcel Group create - API Documentation

Parcel Group create

post https://logistics-demo.xmlship.com/api/external/parcels-groups

This API endpoint enables consolidation of parcels into a group for subsequent processing at the first-mile hub.

Request

Security: Bearer Auth

Authorization: Bearer Token authentication required. Add Authorization: Bearer <token> to your requests header to authorize.

Body

is_test boolean

Indicates the environment where a parcel group should to be created. true for live mode, false for testing purposes.

title string

required

The title of the parcel group. Should be unique.

currency string

required

The currency of the parcel group. \ Using for summaries and calculations.

carrier_solution string

required

The carrier solution of the parcel group. \ Using for determining the carrier and service of the parcels group. \

physical_tag string | null

The physical tag of the parcel group.

customs_broker string | null

The carrier solution of the parcel group. \ Using for determining the carrier and service of the parcels group. \

Allowed values: "acp"

type string

required

The type of the parcel group. \ Using for grouping parcels.

Allowed values: "bag", "pallet", "shipment"

close string

required

Indicates whether the parcel group should be closed after creation. \ If true, the parcel group will be closed and no more parcels can be added to it. As well documents will be created. \ Examples: true, false, 1, 0

label_format string

required

The label format of the parcel group. \ Using for labels generation.

Allowed values: "zpl200", "zpl300", "pdf", "png"

tracking_numbers array

The tracking numbers of the parcels that should be added to the group. \ Should be an array of strings.

items string

Responses

Body

Auth

Token :

Body

Loading...

Parcel Group update - API Documentation

Parcel Group update

patch https://logistics-demo.xmlship.com/api/external/parcels-groups/{tracking_number}

This API endpoint allows updating a parcel group or adding items to a parcel group.

Request

Security: Bearer Auth

Authorization: Bearer Token authentication required. Add Authorization: Bearer <token> to your requests header to authorize.

Params

tracking_number string path

required

- the system tracking number of the parcel group. Example: XLD234578662245

Body

is_test boolean

Indicates the environment where a parcel group should to be updated. true for live mode, false for testing purposes. \ Examples: true, false, 1, 0

close string

required

physical_tag string | null

The physical tag of the parcel group.

tracking_numbers array

The tracking numbers of the parcels that should be added to the group. \ Should be an array of strings.

items string

Responses

Body

Auth

Token :

Body

Loading...

Parcel Group show - API Documentation

Parcel Group show

get https://logistics-demo.xmlship.com/api/external/parcels-groups/{tracking_number}

This API endpoint allows retrieval of information about a parcel group.

Request

Security: Bearer Auth

Authorization: Bearer Token authentication required. Add Authorization: Bearer <token> to your requests header to authorize.

Params

tracking_number string path

required

- the system tracking number of the parcel group

Responses

Body

Auth

Token :

Loading...

Get tracking by cursor - API Documentation

Get tracking by cursor

get https://logistics-demo.xmlship.com/api/external/tracking/v1/by-cursor

Retrieves a paginated list of tracking events, with a cursor value included in the response to fetch the next page of results. Pagination is driven by the `next_cursor` value in the response. To access the next page, submit a new request using the `next_cursor` value as the cursor parameter. <details> <summary>Tracking Events</summary> The list of tracking events below is not final and may be expanded in the future. | Code | Name | Description | -------- | ------- |------- | | **not_mapped** | Not mapped | A new unknown event has been received, which needs to be matched with an existing system event (mapped) | | **ignored** | Ignored | If a carrier event is mapped to Ignored, such events will be ignored by the system. Example - the carrier sends the “manifest data received” event. This is a virtual event that does not indicate the physical path of the package. Usually such events are mapped to Ignored | | **registered_by_system** | Registered by system | The system was able to successfully write data to the database, generate a system label and system tracking number | | **registered_by_last_mile_carrier** | Registered by last mile carrier | The status into which the parcel falls after successful registration of the last-mile carrier label and tracking number. | | **print_label_last_mile** | Label printed | The status that the package receives after clicking on the "print label" button, this status can only be activated in the database | | **ready_for_shipper_collection** | Ready for shipper collection | Parcel is added to the Parcel group for Shipper and the group is closed | | **cancel_shipper_collection** | Shipper collection cancelled | Shipper Parcel group is canceled | | **in_transit_to_first_mile_hub** | In transit to first mile hub | The parcel was sent to first-mile hub | | **duties_and_taxes_payment_required** | Duties and taxes payment required | The status appears when a payment system is configured, and when the recipient of the parcel needs to pay duties and taxes | | **duties_and_taxes_payment_not_required** | Duties and taxes payment refused | The recipient of the parcel refuses to pay duties and taxes | | **duties_and_taxes_payment_received** | Duties and taxes payment received | Recipient of the parcel has paid duties and taxes and the parcel can move on | | **accepted** | Accepted | Successful scan of the parcel in the first-mile hub. End of the First Mile. | | **departed_from_origin_country** | Departed from origin country | The parcel received a scan at the exit from the warehouse and is on its way to the destination country | | **arrived_at_sorting_hub** | Arrived at sorting hub | The parcel has arrived at the sorting facility on its way to the destination country | | **received_by_customs** | Received by customs | The parcel was scanned at customs. Import to destination country | | **customs_cleared** | Customs cleared | The parcel was scanned at customs and marked "available for import" | | **held_by_customs** | Held by customs | The parcel was scanned at customs and is "on hold" | | **received_by_local_carrier** | Received by local carrier | The parcel was received by the carrier in the destination country | | **in_transit_by_local_carrier** | In transit by local carrier | The parcel is on the way, arrived at the intermediate point | | **arrived_at_carrier_hub** | Arrived at carrier hub | The parcel arrived at the carrier's hub | | **carrier_delivery_scheduled** | Carrier delivery scheduled | Delivery of the parcel to the recipient is scheduled | | **out_for_delivery** | Out for delivery | The parcel was scanned before leaving for the recipient | | **delivery_attempted** | Delivery attempted | An unsuccessful delivery of the parcel was attempted (for example, the recipient was not at home) | | **delivery_failed** | Delivery failed | Delivery was not successful | | **delivery_awaiting_collection** | Delivery awaiting collection | The parcel has been scanned at its destination and is awaiting the recipient | | **delivered** | Delivered | The parcel was successfully delivered to the recipient | | **duties_and_taxes_payment_expired** | Duties and taxes payment expired | Appears when the recipient of the parcel has not paid duties and taxes on time | | **duties_and_taxes_payment_rejected** | Duties and taxes payment rejected | Appears when payment of duties and taxes has failed | | **return_to_sender_requested** | Return to sender requested | The parcel cannot be delivered. Was sent to the first mile hub or sender | | **return_to_sender_delivered** | Return to sender delivered | The parcel sent back has been received by the first mile hub or sender | | **lost** | Lost | Parcel lost | | **destroyed** | Destroyed | Parcel destroyed | </details>

Request

Security: Bearer Auth

Authorization: Bearer Token authentication required. Add Authorization: Bearer <token> to your requests header to authorize.

Params

is_test boolean query

Indicates the environment where a tracking should be retrieved. true for live mode, false for testing purposes. \ Examples: true, false, 1, 0

cursor string query

required

The cursor value is used to retrieve the next results page. Use 0 value to retrieve the data from the beginning cursor.

Responses

Body

Auth

Token :

Loading...

Get tracking by identifiers - API Documentation

Get tracking by identifiers

get https://logistics-demo.xmlship.com/api/external/tracking/v1/by-identifiers

This API endpoint allows you to get the tracking information by the list of parcel identifiers. A parcel identifier can be one of the following unique parcel identifiers: `system_tracking_number`, `shipper_tracking_number`, `last_mile_carrier_tracking_number`, `extra1_last_mile_carrier_tracking_number` \ \ Max items per request limit: `100`. <details> <summary>Tracking Events</summary> The list of tracking events below is not final and may be expanded in the future. | Code | Name | Description | | -------- | ------- |------- | | **not_mapped** | Not mapped | A new unknown event has been received, which needs to be matched with an existing system event (mapped) | | **ignored** | Ignored | If a carrier event is mapped to Ignored, such events will be ignored by the system. Example - the carrier sends the “manifest data received” event. This is a virtual event that does not indicate the physical path of the package. Usually such events are mapped to Ignored | | **registered_by_system** | Registered by system | The system was able to successfully write data to the database, generate a system label and system tracking number | | **registered_by_last_mile_carrier** | Registered by last mile carrier | The status into which the parcel falls after successful registration of the last-mile carrier label and tracking number. | | **print_label_last_mile** | Label printed | The status that the package receives after clicking on the "print label" button, this status can only be activated in the database | | **ready_for_shipper_collection** | Ready for shipper collection | Parcel is added to the Parcel group for Shipper and the group is closed | | **cancel_shipper_collection** | Shipper collection cancelled | Shipper Parcel group is canceled | | **in_transit_to_first_mile_hub** | In transit to first mile hub | The parcel was sent to first-mile hub | | **duties_and_taxes_payment_required** | Duties and taxes payment required | The status appears when a payment system is configured, and when the recipient of the parcel needs to pay duties and taxes | | **duties_and_taxes_payment_not_required** | Duties and taxes payment refused | The recipient of the parcel refuses to pay duties and taxes | | **duties_and_taxes_payment_received** | Duties and taxes payment received | Recipient of the parcel has paid duties and taxes and the parcel can move on | | **accepted** | Accepted | Successful scan of the parcel in the first-mile hub. End of the First Mile. | | **departed_from_origin_country** | Departed from origin country | The parcel received a scan at the exit from the warehouse and is on its way to the destination country | | **arrived_at_sorting_hub** | Arrived at sorting hub | The parcel has arrived at the sorting facility on its way to the destination country | | **received_by_customs** | Received by customs | The parcel was scanned at customs. Import to destination country | | **customs_cleared** | Customs cleared | The parcel was scanned at customs and marked "available for import" | | **held_by_customs** | Held by customs | The parcel was scanned at customs and is "on hold" | | **received_by_local_carrier** | Received by local carrier | The parcel was received by the carrier in the destination country | | **in_transit_by_local_carrier** | In transit by local carrier | The parcel is on the way, arrived at the intermediate point | | **arrived_at_carrier_hub** | Arrived at carrier hub | The parcel arrived at the carrier's hub | | **carrier_delivery_scheduled** | Carrier delivery scheduled | Delivery of the parcel to the recipient is scheduled | | **out_for_delivery** | Out for delivery | The parcel was scanned before leaving for the recipient | | **delivery_attempted** | Delivery attempted | An unsuccessful delivery of the parcel was attempted (for example, the recipient was not at home) | | **delivery_failed** | Delivery failed | Delivery was not successful | | **delivery_awaiting_collection** | Delivery awaiting collection | The parcel has been scanned at its destination and is awaiting the recipient | | **delivered** | Delivered | The parcel was successfully delivered to the recipient | | **duties_and_taxes_payment_expired** | Duties and taxes payment expired | Appears when the recipient of the parcel has not paid duties and taxes on time | | **duties_and_taxes_payment_rejected** | Duties and taxes payment rejected | Appears when payment of duties and taxes has failed | | **return_to_sender_requested** | Return to sender requested | The parcel cannot be delivered. Was sent to the first mile hub or sender | | **return_to_sender_delivered** | Return to sender delivered | The parcel sent back has been received by the first mile hub or sender | | **lost** | Lost | Parcel lost | | **destroyed** | Destroyed | Parcel destroyed | </details>

Request

Security: Bearer Auth

Authorization: Bearer Token authentication required. Add Authorization: Bearer <token> to your requests header to authorize.

Params

is_test boolean query

Indicates the environment where a tracking should be retrieved. true for live mode, false for testing purposes. \

identifiers string query

required

The comma-separated list of parcel identifiers to search for.

Responses

Body

Auth

Token :

Loading...

Get tracking by date range - API Documentation

Get tracking by date range

get https://logistics-demo.xmlship.com/api/external/tracking/v1/by-date-range

This API endpoint allows you to get tracking information by specifying a date and time range. The selected range is the time range during which the system confirmed events, not the time when they occurred. This eliminates the "events in the past" issue and allows clients to iterate through the date ranges in a strictly forward direction. \ \ The maximum request interval is `1 hour`. \ \ Tracking events per page is `250`. <details> <summary>Tracking Events</summary> The list of tracking events below is not final and may be expanded in the future. | Code | Name | Description | | -------- | ------- |------- | | **not_mapped** | Not mapped | A new unknown event has been received, which needs to be matched with an existing system event (mapped) | | **ignored** | Ignored | If a carrier event is mapped to Ignored, such events will be ignored by the system. Example - the carrier sends the “manifest data received” event. This is a virtual event that does not indicate the physical path of the package. Usually such events are mapped to Ignored | | **registered_by_system** | Registered by system | The system was able to successfully write data to the database, generate a system label and system tracking number | | **registered_by_last_mile_carrier** | Registered by last mile carrier | The status into which the parcel falls after successful registration of the last-mile carrier label and tracking number. | | **print_label_last_mile** | Label printed | The status that the package receives after clicking on the "print label" button, this status can only be activated in the database | | **ready_for_shipper_collection** | Ready for shipper collection | Parcel is added to the Parcel group for Shipper and the group is closed | | **cancel_shipper_collection** | Shipper collection cancelled | Shipper Parcel group is canceled | | **in_transit_to_first_mile_hub** | In transit to first mile hub | The parcel was sent to first-mile hub | | **duties_and_taxes_payment_required** | Duties and taxes payment required | The status appears when a payment system is configured, and when the recipient of the parcel needs to pay duties and taxes | | **duties_and_taxes_payment_not_required** | Duties and taxes payment refused | The recipient of the parcel refuses to pay duties and taxes | | **duties_and_taxes_payment_received** | Duties and taxes payment received | Recipient of the parcel has paid duties and taxes and the parcel can move on | | **accepted** | Accepted | Successful scan of the parcel in the first-mile hub. End of the First Mile. | | **departed_from_origin_country** | Departed from origin country | The parcel received a scan at the exit from the warehouse and is on its way to the destination country | | **arrived_at_sorting_hub** | Arrived at sorting hub | The parcel has arrived at the sorting facility on its way to the destination country | | **received_by_customs** | Received by customs | The parcel was scanned at customs. Import to destination country | | **customs_cleared** | Customs cleared | The parcel was scanned at customs and marked "available for import" | | **held_by_customs** | Held by customs | The parcel was scanned at customs and is "on hold" | | **received_by_local_carrier** | Received by local carrier | The parcel was received by the carrier in the destination country | | **in_transit_by_local_carrier** | In transit by local carrier | The parcel is on the way, arrived at the intermediate point | | **arrived_at_carrier_hub** | Arrived at carrier hub | The parcel arrived at the carrier's hub | | **carrier_delivery_scheduled** | Carrier delivery scheduled | Delivery of the parcel to the recipient is scheduled | | **out_for_delivery** | Out for delivery | The parcel was scanned before leaving for the recipient | | **delivery_attempted** | Delivery attempted | An unsuccessful delivery of the parcel was attempted (for example, the recipient was not at home) | | **delivery_failed** | Delivery failed | Delivery was not successful | | **delivery_awaiting_collection** | Delivery awaiting collection | The parcel has been scanned at its destination and is awaiting the recipient | | **delivered** | Delivered | The parcel was successfully delivered to the recipient | | **duties_and_taxes_payment_expired** | Duties and taxes payment expired | Appears when the recipient of the parcel has not paid duties and taxes on time | | **duties_and_taxes_payment_rejected** | Duties and taxes payment rejected | Appears when payment of duties and taxes has failed | | **return_to_sender_requested** | Return to sender requested | The parcel cannot be delivered. Was sent to the first mile hub or sender | | **return_to_sender_delivered** | Return to sender delivered | The parcel sent back has been received by the first mile hub or sender | | **lost** | Lost | Parcel lost | | **destroyed** | Destroyed | Parcel destroyed | </details>

Request

Security: Bearer Auth

Authorization: Bearer Token authentication required. Add Authorization: Bearer <token> to your requests header to authorize.

Params

is_test boolean query

Indicates the environment where a tracking should be retrieved. true for live mode, false for testing purposes. \

date_time_from string query

required

Start of the date-time range

date_time_to string query

required

End of the date-time range. \ The maximum request interval is 60 minutes.

page integer query

The page number to retrieve.

Responses

Body

Auth

Token :

Loading...

OrdersCreateRequest - API Documentation

OrdersCreateRequest

object

Order create request

Properties

Property	Type	Required	Description
is_test	boolean	optional	Indicates the environment where an order should be created. `false` for live mode, `true` for testing purposes.
currency	string	required	Currency of the order. \ ISO 4217 currency code. Currency that has been used to pay for the order. \ This is the general order currency and applies to all monetary fields.
weight_unit	string or null	optional	Unit used for weight fields across all order items. \ Might be set as a default in `Shippers → Profile → Parcel Defaults`. Allowed: `"kg"` `"lb"` `"g"`
dimensions_unit	string or null	optional	Unit used for dimension fields across all order items. \ Might be set as a default in `Shippers → Profile → Parcel Defaults`. Allowed: `"m"` `"in"` `"cm"` `"mm"`
shipper_order_reference	string	required	A unique client reference that identifies the order. \ Each order must have a unique reference that must not be reused. \
platform_order_reference	string or null	optional	A unique platform reference that identifies the order. \ Each order must have a unique reference that must not be reused. \
extra1_order_reference	string or null	optional	An extra reference that identifies the order.
shipping_solution_code	string	required	Shipping solution code. \ Defines the service level that will be used to fulfill the order. \ The list of available codes can be found in `Shippers → Profile → Shipping solutions`.
hs_skip_steps	array or null	optional	List of HS service steps to forcibly skip during order processing. Available steps: replace_hs_codes, denied_parties_check, update_duty_and_taxes, restriction_screening, suggest_and_replace_description
shipping_cost	number or null	optional	Cost of shipping. \ The `currency` should be selected before `shipping_cost` is used.
value	number or null	optional	Total declared value of the order. \ The `currency` should be selected before `value` is used.
description	string or null	optional	Brief description of the order contents.
incoterm	string or null	optional	Taxes and duties handling term. \ Allowed: `"DDP"` `"DDU"` `"DAP"`
order_created_at	string or null	optional	The date and time when the order was originally created on the merchant's platform.
origin_address	object	optional	### Origin (sender) address.
name	string or null	optional	Sender's name.
company_name	string or null	optional	Sender's company name.
address_line_1	string or null	optional	Sender's address line 1.
address_line_2	string or null	optional	Sender's address line 2.
address_line_3	string or null	optional	Sender's address line 3.
city	string or null	optional	Sender's city.
state	string or null	optional	Sender's state or region.
zip	string or null	optional	Sender's ZIP / postal code.
country	string or null	optional	Sender's country. \ Should be in ISO 3166-1 alpha-2 code.
phone	string or null	optional	Sender's phone number.
email	string or null	optional	Sender's email address.
vat	string or null	optional	Sender's VAT number.
eori	string or null	optional	Sender's EORI number.
ioss	string or null	optional	Sender's IOSS number.
gst	string or null	optional	Sender's GST number.
ukims	string or null	optional	Sender's UKIMS number.
house_number	string or null	optional	Sender's house number (applicable for `DE` and `NL`).
destination_address	object	required	### Destination (recipient, consignee) address.
name	string	required	Consignee's name.
company_name	string or null	optional	Consignee's company name (if business delivery).
address_line_1	string	required	Consignee's address line 1.
address_line_2	string or null	optional	Consignee's address line 2.
address_line_3	string or null	optional	Consignee's address line 3.
city	string	required	Consignee's city.
state	string or null	optional	Consignee's state or region.
zip	string or null	optional	Consignee's ZIP / postal code.
country	string	required	Consignee's country. \ Should be in ISO 3166-1 alpha-2 code.
phone	string or null	optional	Consignee's phone number.
email	string or null	optional	Consignee's email address.
vat	string or null	optional	Consignee's VAT number.
ioss	string or null	optional	Consignee's IOSS number.
eori	string or null	optional	Consignee's EORI number.
gst	string or null	optional	Consignee's GST number.
ukims	string or null	optional	Consignee's UKIMS number.
house_number	string or null	optional	Consignee's house number (applicable for `DE` and `NL`).
purchaser_abn	string or null	optional	Consignee's ABN number.
merchant_arn	string or null	optional	Consignee's ARN number.
payment_date	string or null	optional	Consignee's payment date.
payment_reference_identity	string or null	optional	Consignee's payment reference identity.
tax_identity	string or null	optional	Consignee's tax identity.
national_identity	string or null	optional	Consignee's national identity.
order_items[ ]	array	required	### Order items
quantity	number	required	The number of units of this item included in the order. \ Required for each item entry.
description	string	required	Description of the item. \ Required for each item entry. Used for customs declarations on non-domestic shipments.
total_value	number	required	The total value of all units of this item. \ The `currency` should be selected before `order_items.*.total_value` is used. \ Required for each item entry.
weight	number or null	optional	The weight of a single item. \ Ensure the weight unit `weight_unit` is specified before using this field, unless a default unit has been preset.
length	number or null	optional	The length of a single item. \ Ensure the dimension unit `dimensions_unit` is specified before using this field, unless a default unit has been preset.
width	number or null	optional	The width of a single item. \ Ensure the dimension unit `dimensions_unit` is specified before using this field, unless a default unit has been preset.
height	number or null	optional	The height of a single item. \ Ensure the dimension unit `dimensions_unit` is specified before using this field, unless a default unit has been preset.
country_of_origin	string or null	optional	The country where the item was manufactured. \ Used for customs declarations. Should be in ISO 3166-1 alpha-2 code.
hs_code	string or null	optional	The Harmonized System (HS) code for the item. \ A standardized numerical method of classifying traded products, used by customs authorities to assess duties and taxes.
sku	string or null	optional	The Stock Keeping Unit (SKU) — a unique code that identifies the product.
url	string or null	optional	The product page URL.
image_url	string or null	optional	The product image URL.
tax_value	number or null	optional	The tax value applied to a single item.
duty_value	number or null	optional	The duty value applied to a single item.

Example

{
  "is_test": false,
  "currency": "GBP",
  "weight_unit": "kg",
  "dimensions_unit": "cm",
  "shipper_order_reference": "ORD-0001",
  "platform_order_reference": "#O-0001",
  "extra1_order_reference": "NUM-001",
  "shipping_solution_code": "GSS",
  "hs_skip_steps": [
    "replace_hs_codes",
    "denied_parties_check"
  ],
  "shipping_cost": 12.5,
  "value": 100,
  "description": "Office supplies",
  "incoterm": "DDP",
  "order_created_at": "2024-09-20 21:19:41",
  "origin_address": {
    "name": "John Doe",
    "company_name": "Doe Inc.",
    "address_line_1": "29-31 Catherine Pl",
    "address_line_2": null,
    "address_line_3": null,
    "city": "London",
    "state": null,
    "zip": "SW1E 6DY",
    "country": "GB",
    "phone": "+44 11 2233 4444",
    "email": "sender@example.com",
    "vat": "GB123456789",
    "eori": "GB123456789",
    "ioss": "IM1234567890",
    "gst": null,
    "ukims": "NBN123456789",
    "house_number": null
  },
  "destination_address": {
    "name": "Jon Snow",
    "company_name": "Winterfell Inc.",
    "address_line_1": "1 Castle Black",
    "address_line_2": null,
    "address_line_3": null,
    "city": "Winterfell",
    "state": "North",
    "zip": "W1N 4LL",
    "country": "GB",
    "phone": "+44 11 2233 4444",
    "email": "jon.snow@winterfell.north.seven-kingdoms.uk",
    "vat": null,
    "ioss": null,
    "eori": null,
    "gst": null,
    "ukims": null,
    "house_number": "4",
    "purchaser_abn": null,
    "merchant_arn": null,
    "payment_date": null,
    "payment_reference_identity": null,
    "tax_identity": null,
    "national_identity": null
  },
  "order_items": [
    {
      "quantity": 10,
      "description": "Candles",
      "total_value": 100,
      "weight": 1.2,
      "length": 30,
      "width": 20,
      "height": 20,
      "country_of_origin": "GB",
      "hs_code": "3406000000",
      "sku": "SU1233456",
      "url": "https://example.com/product/SU1233456",
      "image_url": "https://example.com/product/SU1233456/main.png",
      "tax_value": 20,
      "duty_value": 5
    }
  ]
}

ParcelsCreateRequest - API Documentation

ParcelsCreateRequest

object

Parcel create request

Properties

Property	Type	Required	Description
is_test	boolean	optional	Indicates the environment where a parcel should be created. `false` for live mode, `true` for testing purposes.
currency	string or null	optional	Currency of parcel. \ 4217 currency code. Currency that has been used to pay for the order that is shipped in this parcel. This is the general parcel currency and applies to all monetary fields. \ Can be set as a default in `Shippers → Profile → Parcel Defaults`. Allowed: `"AED"` `"AFN"` `"ALL"` `"AMD"` `"ANG"` `"AOA"` `"ARS"` `"AUD"` `"AWG"` `"AZN"` `"BAM"` `"BBD"` `"BDT"` `"BGN"` `"BHD"` `"BIF"` `"BMD"` `"BND"` `"BOB"` `"BRL"` `"BSD"` `"BTN"` `"BWP"` `"BYR"` `"BZD"` `"CAD"` `"CDF"` `"CHF"` `"CLF"` `"CLP"` `"CNY"` `"COP"` `"CRC"` `"CUC"` `"CUP"` `"CVE"` `"CZK"` `"DJF"` `"DKK"` `"DOP"` `"DZD"` `"EGP"` `"ERN"` `"ETB"` `"EUR"` `"FJD"` `"FKP"` `"GBP"` `"GEL"` `"GHS"` `"GIP"` `"GMD"` `"GNF"` `"GTQ"` `"GYD"` `"HKD"` `"HNL"` `"HRK"` `"HTG"` `"HUF"` `"IDR"` `"ILS"` `"INR"` `"IQD"` `"IRR"` `"ISK"` `"JMD"` `"JOD"` `"JPY"` `"KES"` `"KGS"` `"KHR"` `"KMF"` `"KPW"` `"KRW"` `"KWD"` `"KYD"` `"KZT"` `"LAK"` `"LBP"` `"LKR"` `"LRD"` `"LSL"` `"LTL"` `"LVL"` `"LYD"` `"MAD"` `"MDL"` `"MGA"` `"MKD"` `"MMK"` `"MNT"` `"MOP"` `"MRO"` `"MUR"` `"MVR"` `"MWK"` `"MXN"` `"MYR"` `"MZN"` `"NAD"` `"NGN"` `"NIO"` `"NOK"` `"NPR"` `"NZD"` `"OMR"` `"PAB"` `"PEN"` `"PGK"` `"PHP"` `"PKR"` `"PLN"` `"PYG"` `"QAR"` `"RON"` `"RSD"` `"RUB"` `"RWF"` `"SAR"` `"SBD"` `"SCR"` `"SDG"` `"SEK"` `"SGD"` `"SHP"` `"SLL"` `"SOS"` `"SRD"` `"SSP"` `"STD"` `"SVC"` `"SYP"` `"SZL"` `"THB"` `"TJS"` `"TMT"` `"TND"` `"TOP"` `"TRY"` `"TTD"` `"TWD"` `"TZS"` `"UAH"` `"UGX"` `"USD"` `"UYU"` `"UZS"` `"VND"` `"VUV"` `"WST"` `"XAF"` `"XAG"` `"XAU"` `"XCD"` `"XDR"` `"XOF"` `"XPF"` `"YER"` `"ZAR"` `"ZMK"` `"ZMW"` `"BYN"` `"GGP"` `"IMP"` `"JEP"` `"ZWL"` `"SLE"` `"VES"` `"MRU"` `"CNH"` `"STN"` `"XCG"`
consignee_use_address_successors	boolean	optional	When value is `true`, and permitted for the Shipper, the system will apply the destination address successors logic to identify the appropriate destination address for parcel delivery. Conversely, if disabled and not permitted, the system will default to using the destination address supplied in the request. Can be set as a default in `Shippers → Profile → Usage of destination address successors logic type`.
shipping	object	optional	### Shipping information required to register a parcel.
type	string or null	optional	Parcel type. \ Determines parcel type e.g. return or direct \ Defaults to `direct` if not specified. \ Allowed: `"direct"` `"return"`
shipping_solution_code	string	required	Shipping solution code. \ Required for successful parcel creation. Defines the service level that will be used to ship the parcel. \ The list of available codes can be found in `Shippers → Profile → Shipping solutions`. \ Can be set as a default in `Shippers → Profile → Parcel Defaults`.
pudo_point	string or null	optional	Identification of PUDO point (Pick Up Drop Off). If you don't know the list of PUDO points we recommend contacting the Administrator.
hs_skip_steps	array or null	optional	List of HS service steps to forcibly skip during parcel processing. Available steps: replace_hs_codes, denied_parties_check, update_duty_and_taxes, restriction_screening, suggest_and_replace_description
label_format	string or null	optional	Format of the requested shipping label. \ \ Can be set as a default in `Shippers → Profile → Parcel Defaults`. \ Allowed: `"zpl200"` `"zpl300"` `"pdf"` `"png"`
label_type	string or null	optional	Label type indicates whether a system or a last-mile carrier label should be returned. The possibility of choosing a last-mile carrier label might not be allowed. \ \ Where to check allowed modes: `Shippers → Profile → External connections to the system`. \ \ If the `system` option is selected, the system will generate a system label and return it, irrespective of any existing errors. This feature is useful for quickly creating parcels and later relabeling them with a last-mile label. \ If the `last_mile` option is selected, the system will perform complex validation and processing. If no errors occur, the system will generate a last-mile label and return it. Allowed: `"system"` `"last_mile"`
shipping_cost	number or null	optional	Cost of shipping. \ \ The `currency` should be selected before `shipping.shipping_cost` is used.
collection_date	object or null	optional	Parcel collection information, applicable only to certain carriers.
delivery_date	object or null	optional	Parcel delivery information, applicable only to certain carriers.
package	object	optional	### Information that identifies a package.
order_reference	string or null	optional	Order number associated with the parcel. Please note that multiple parcels may share the same order reference.
physical_tag	string or null	optional	Physical Tag id attached to the parcel.
shipper_tracking_number	string or null	optional	The tracking number used for offline generation of system labels. The generation pattern should be provided by the Administrator. If not specified, the system will generate it automatically.
shipper_reference	string	required	A unique client reference that identifies the parcel. \ Each parcel should have a unique reference that must not be reused for any other parcel. If the reference is reused, the system may either attempt to recreate the parcel or return an error.
original_tracking_number	string or null	optional	Original tracking number associated with the parcel.
original_order_number	string or null	optional	Original Order number associated with the parcel.
category	string or null	optional	The product category is used to classify items based on their intended purpose or nature. Allowed: `"commercial_goods"` `"gifts"` `"documents"` `"clothing"` `"personal_items"` `"commercial_sample"` `"returned_goods"` `"intercompany_transfer"` `"repair"` `"humanitarian_donations"` `"dangerous_goods"` `"other"`
tags	array or null	optional	Tags are used to categorize parcels based on specific criteria or attributes from system settings.
dangerous_goods	string or null	optional	Indicates whether the parcel contains dangerous goods.
incoterm	string or null	optional	An Incoterm (International Commercial Term) is a standardized term used in international trade that defines the responsibilities of buyers and sellers regarding the delivery of goods. It specifies who is responsible for transportation, insurance, customs clearance, and the risks involved in shipping. Allowed: `"DDP"` `"DDU"` `"DAP"`
description	string or null	optional	Brief summary or detailed explanation of the contents of a package.
delivery_instruction	string or null	optional	Specific guidelines or requests provided by the sender or recipient regarding how a parcel should be delivered.
non_delivery_instruction	string or null	optional	Guidelines provided by the sender or recipient regarding how a parcel should be handled in the event of a delivery failure. Allowed: `"return_to_sender"` `"abandoned"` `"return_to_parcel_shop"` `"redirect"`
proof_of_delivery_signature	string or null	optional	Proof of Delivery (POD) is a document or digital confirmation that verifies a parcel has been successfully delivered to the recipient.
value	number or null	optional	The parcel value represents the total market worth of all items contained within the package. \ The `currency` should be selected before `package.value` is used.
cash_on_delivery	string or null	optional	This determines if the shipment requires payment upon delivery, known as Cash on Delivery (COD) service.
weight	object or null	optional	Overall weight of the parcel.
dimensions	object or null	optional	Dimensions of the parcel. \ Ensure the dimension unit `package.dimensions.unit` is specified before using the dimension values `package.dimensions.length`, `package.dimensions.width`, and `package.dimensions.height`, unless a default unit has been preset.
origin_address	object	optional	### Origin (sender) address.
name	string or null	optional	Sender's name.
company_name	string or null	optional	Sender's company name.
address_line_1	string or null	optional	Sender's address line 1.
address_line_2	string or null	optional	Sender's address line 2.
address_line_3	string or null	optional	Sender's address line 3.
house_number	string or null	optional	Consignee's house number (applicable for `DE` and `NL`).
city	string or null	optional	Sender's city.
state	string or null	optional	Sender's state.
zip	string or null	optional	Sender's ZIP code.
country	string or null	optional	Sender's country. \ Should be in ISO 3166-1 alpha-2 code. Allowed: `"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"` `"IC"` `"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"` `"XK"` `"YE"` `"YT"` `"ZA"` `"ZM"` `"ZW"` `"UK"`
phone	string or null	optional	Sender's phone number.
email	string or null	optional	Sender's email.
vat	string or null	optional	Sender's VAT number.
ioss	string or null	optional	Sender's IOSS number.
eori	string or null	optional	Sender's EORI number.
ukims	string or null	optional	Sender's UKIMS number.
gst	string or null	optional	Sender's GST number.
destination_address	object	optional	### Destination (recipient, consignee) address.
name	string or null	optional	Consignee's name.
company_name	string or null	optional	Consignee's company name (if business delivery).
address_line_1	string or null	optional	Consignee's address line 1.
address_line_2	string or null	optional	Consignee's address line 2.
address_line_3	string or null	optional	Consignee's address line 3.
house_number	string or null	optional	Consignee's house number (applicable for `DE` and `NL`).
city	string or null	optional	Consignee's city.
state	string or null	optional	Consignee's state.
zip	string or null	optional	Consignee's ZIP code.
country	string or null	optional	Consignee's country. \ Should be in ISO 3166-1 alpha-2 code. Allowed: `"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"` `"IC"` `"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"` `"XK"` `"YE"` `"YT"` `"ZA"` `"ZM"` `"ZW"` `"UK"`
phone	string or null	optional	Consignee's phone number.
email	string or null	optional	Consignee's email.
vat	string or null	optional	Consignee's VAT number.
eori	string or null	optional	Sender's EORI number.
gst	string or null	optional	Consignee's GST number.
purchaser_abn	string or null	optional	Consignee's ABN number.
merchant_arn	string or null	optional	Consignee's ARN number.
payment_date	string or null	optional	Consignee's payment date.
payment_reference_identity	string or null	optional	Consignee's payment reference identity.
tax_identity	string or null	optional	Consignee's tax identity.
national_identity	string or null	optional	Consignee's national identity.
return_address	object	optional	### Return address If no specific return address is provided, the sender's address will automatically be designated as the return address for the shipment.
name	string or null	optional	Return address name.
company_name	string or null	optional	Return address company name.
address_line_1	string or null	optional	Return address, address line 1.
address_line_2	string or null	optional	Return address, address line 2.
address_line_3	string or null	optional	Return address, address line 3.
house_number	string or null	optional	Consignee's house number (applicable for `DE` and `NL`).
city	string or null	optional	Return address city.
state	string or null	optional	Return address state.
zip	string or null	optional	Return address ZIP code.
country	string or null	optional	Return address country. \ Should be in ISO 3166-1 alpha-2 code. Allowed: `"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"` `"IC"` `"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"` `"XK"` `"YE"` `"YT"` `"ZA"` `"ZM"` `"ZW"` `"UK"`
phone	string or null	optional	Return address phone number.
email	string or null	optional	Return address email.
vat	string or null	optional	Return address VAT number.
ioss	string or null	optional	Return address IOSS number.
eori	string or null	optional	Return address EORI number.
gst	string or null	optional	Return address GST number.
parcel_items	array or null	optional	### Parcel items

Example

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

{
  "is_test": false,
  "currency": "GBP",
  "consignee_use_address_successors": true,
  "shipping": {
    "type": "direct",
    "shipping_solution_code": "",
    "pudo_point": null,
    "hs_skip_steps": [
      "replace_hs_codes",
      "denied_parties_check",
      "update_duty_and_taxes",
      "restriction_screening",
      "suggest_and_replace_description"
    ],
    "label_format": "pdf",
    "label_type": "system",
    "shipping_cost": null,
    "collection_date": {
      "date": "2024-12-31",
      "time_from": "09:00",
      "time_to": "09:00"
    },
    "delivery_date": {
      "date": "2024-12-31",
      "time_from": "09:00",
      "time_to": "09:00"
    }
  },
  "package": {
    "order_reference": "Shopify#123456",
    "physical_tag": "UN9YNK",
    "shipper_tracking_number": null,
    "shipper_reference": "T123456",
    "original_tracking_number": null,
    "original_order_number": "Shopify#123456",
    "category": "commercial_goods",
    "tags": null,
    "dangerous_goods": false,
    "incoterm": "DDP",
    "description": "Clothing",
    "delivery_instruction": "Leave at the front door",
    "non_delivery_instruction": "return_to_sender",
    "proof_of_delivery_signature": false,
    "value": 100,
    "cash_on_delivery": false,
    "weight": {
      "value": 0.8,
      "unit": "kg"
    },
    "dimensions": {
      "length": 30,
      "width": 22,
      "height": 0.5,
      "unit": "cm"
    }
  },
  "origin_address": {
    "name": "John Doe",
    "company_name": "Doe Inc.",
    "address_line_1": "29-31 Catherine Pl",
    "address_line_2": null,
    "address_line_3": null,
    "house_number": null,
    "city": "London",
    "state": null,
    "zip": "SW1E 6DY",
    "country": "GB",
    "phone": "+44 11 2233 4444",
    "email": "sender@example.com",
    "vat": "GB123456789",
    "ioss": "IM1234567890",
    "eori": "GB123456789",
    "ukims": "NBN123456789",
    "gst": null
  },
  "destination_address": {
    "name": "Jon Snow",
    "company_name": "Winterfell Inc.",
    "address_line_1": "1 Castle Black",
    "address_line_2": null,
    "address_line_3": null,
    "house_number": null,
    "city": "Winterfell",
    "state": "North",
    "zip": "W1N 4LL",
    "country": "GB",
    "phone": "+44 11 2233 4444",
    "email": "jon.snow@winterfell.north.seven-kingdoms.uk",
    "vat": null,
    "eori": "GB123456789",
    "gst": null,
    "purchaser_abn": null,
    "merchant_arn": null,
    "payment_date": null,
    "payment_reference_identity": null,
    "tax_identity": null,
    "national_identity": null
  },
  "return_address": {
    "name": "John Doe",
    "company_name": "Doe Inc.",
    "address_line_1": "29-31 Catherine Pl",
    "address_line_2": null,
    "address_line_3": null,
    "house_number": null,
    "city": "London",
    "state": null,
    "zip": "SW1E 6DY",
    "country": "GB",
    "phone": null,
    "email": null,
    "vat": null,
    "ioss": null,
    "eori": null,
    "gst": null
  },
  "parcel_items": null
}

ParcelsGroupsCreateRequest - API Documentation

ParcelsGroupsCreateRequest

object

Properties

Property	Type	Required	Description
is_test	boolean	optional	Indicates the environment where a parcel group should to be created. `true` for live mode, `false` for testing purposes.
title	string	required	The title of the parcel group. Should be unique.
currency	string	required	The currency of the parcel group. \ Using for summaries and calculations. Allowed: `"AED"` `"AFN"` `"ALL"` `"AMD"` `"ANG"` `"AOA"` `"ARS"` `"AUD"` `"AWG"` `"AZN"` `"BAM"` `"BBD"` `"BDT"` `"BGN"` `"BHD"` `"BIF"` `"BMD"` `"BND"` `"BOB"` `"BRL"` `"BSD"` `"BTN"` `"BWP"` `"BYR"` `"BZD"` `"CAD"` `"CDF"` `"CHF"` `"CLF"` `"CLP"` `"CNY"` `"COP"` `"CRC"` `"CUC"` `"CUP"` `"CVE"` `"CZK"` `"DJF"` `"DKK"` `"DOP"` `"DZD"` `"EGP"` `"ERN"` `"ETB"` `"EUR"` `"FJD"` `"FKP"` `"GBP"` `"GEL"` `"GHS"` `"GIP"` `"GMD"` `"GNF"` `"GTQ"` `"GYD"` `"HKD"` `"HNL"` `"HRK"` `"HTG"` `"HUF"` `"IDR"` `"ILS"` `"INR"` `"IQD"` `"IRR"` `"ISK"` `"JMD"` `"JOD"` `"JPY"` `"KES"` `"KGS"` `"KHR"` `"KMF"` `"KPW"` `"KRW"` `"KWD"` `"KYD"` `"KZT"` `"LAK"` `"LBP"` `"LKR"` `"LRD"` `"LSL"` `"LTL"` `"LVL"` `"LYD"` `"MAD"` `"MDL"` `"MGA"` `"MKD"` `"MMK"` `"MNT"` `"MOP"` `"MRO"` `"MUR"` `"MVR"` `"MWK"` `"MXN"` `"MYR"` `"MZN"` `"NAD"` `"NGN"` `"NIO"` `"NOK"` `"NPR"` `"NZD"` `"OMR"` `"PAB"` `"PEN"` `"PGK"` `"PHP"` `"PKR"` `"PLN"` `"PYG"` `"QAR"` `"RON"` `"RSD"` `"RUB"` `"RWF"` `"SAR"` `"SBD"` `"SCR"` `"SDG"` `"SEK"` `"SGD"` `"SHP"` `"SLL"` `"SOS"` `"SRD"` `"SSP"` `"STD"` `"SVC"` `"SYP"` `"SZL"` `"THB"` `"TJS"` `"TMT"` `"TND"` `"TOP"` `"TRY"` `"TTD"` `"TWD"` `"TZS"` `"UAH"` `"UGX"` `"USD"` `"UYU"` `"UZS"` `"VND"` `"VUV"` `"WST"` `"XAF"` `"XAG"` `"XAU"` `"XCD"` `"XDR"` `"XOF"` `"XPF"` `"YER"` `"ZAR"` `"ZMK"` `"ZMW"` `"BYN"` `"GGP"` `"IMP"` `"JEP"` `"ZWL"` `"SLE"` `"VES"` `"MRU"` `"CNH"` `"STN"` `"XCG"`
carrier_solution	string	required	The carrier solution of the parcel group. \ Using for determining the carrier and service of the parcels group. \
physical_tag	string or null	optional	The physical tag of the parcel group.
customs_broker	string or null	optional	The carrier solution of the parcel group. \ Using for determining the carrier and service of the parcels group. \ Allowed: `"acp"`
type	string	required	The type of the parcel group. \ Using for grouping parcels. Allowed: `"bag"` `"pallet"` `"shipment"`
close	string	required	Indicates whether the parcel group should be closed after creation. \ If `true`, the parcel group will be closed and no more parcels can be added to it. As well documents will be created. \ Examples: `true`, `false`, `1`, `0`
label_format	string	required	The label format of the parcel group. \ Using for labels generation. Allowed: `"zpl200"` `"zpl300"` `"pdf"` `"png"`
tracking_numbers[ ]	array	optional	The tracking numbers of the parcels that should be added to the group. \ Should be an array of strings.

Example

{
  "is_test": false,
  "title": "Parcel Group 123456",
  "currency": "GBP",
  "carrier_solution": "SMP",
  "physical_tag": "UN9YNK",
  "customs_broker": "SMP",
  "type": "pallet",
  "close": true,
  "label_format": "pdf",
  "tracking_numbers": [
    "000000233722"
  ]
}

ParcelsGroupsUpdateRequest - API Documentation

ParcelsGroupsUpdateRequest

object

Properties

Property	Type	Required	Description
is_test	boolean	optional	Indicates the environment where a parcel group should to be updated. `true` for live mode, `false` for testing purposes. \ Examples: `true`, `false`, `1`, `0`
close	string	required	Indicates whether the parcel group should be closed after creation. \ If `true`, the parcel group will be closed and no more parcels can be added to it. As well documents will be created. \ Examples: `true`, `false`, `1`, `0`
physical_tag	string or null	optional	The physical tag of the parcel group.
tracking_numbers[ ]	array	optional	The tracking numbers of the parcels that should be added to the group. \ Should be an array of strings.

Example

{
  "is_test": false,
  "close": true,
  "physical_tag": "UN9YNK",
  "tracking_numbers": [
    "000000233722"
  ]
}

ParcelsReturnRequest - API Documentation

ParcelsReturnRequest

object

Properties

Property	Type	Required	Description
is_test	string or null	optional	Indicates the environment where a parcel was created.
parcel_unique_identifier	string	required	A parcel identifier can be one of the following unique parcel identifiers `system_tracking_number`, `shipper_tracking_number`, `shipper_reference`, `last_mile_carrier_tracking_number`.

Example

{
  "is_test": null,
  "parcel_unique_identifier": "string"
}