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...

test

Order create

Request

Body

Responses

Body

Quick links

Products

Get in Touch

Email

Phone