Create Order - CrossBorderly API

Creates a new parcel order with sender and receiver information. Upon success, a tracking number is assigned and a shipping label is generated.

Request Body

idempotencyKey

string

required

Unique key (8-64 characters) to prevent duplicate orders. Use your order ID or a UUID.Requests with the same key within 24 hours return the original response.

trackingNumber

string

Optional custom tracking number (10-30 characters). If not provided, the system generates one automatically.

externalOrderId

string

Your internal order ID for reference (max 100 characters).

customerReference

string

Customer-facing reference number (max 100 characters).

sender

object

required

Sender (shipper) information.

Show Sender fields

sender.fullName

string

required

Full name of sender (max 255 chars)

sender.companyName

string

Company name (optional)

sender.phone

string

required

Phone number with country code (e.g., +1 305-555-0123)

sender.email

string

Email address for notifications

sender.address

object

required

Show Address fields

sender.address.line1

string

required

Street address line 1

sender.address.line2

string

Street address line 2

sender.address.city

string

required

City name

sender.address.state

string

State/province for US/CA

sender.address.zipCode

string

Postal code

sender.address.country

string

required

2-letter ISO country code (e.g., US, MX, EC)

receiver

object

required

Receiver (consignee) information.

Show Receiver fields

receiver.fullName

string

required

Full name of receiver

receiver.phone

string

required

Phone number with country code

receiver.email

string

Email for tracking notifications

receiver.nationalId

string

National ID number (Cédula, RUC, DNI, etc.). Required for some countries.

receiver.idType

string

Type of ID: cedula, ruc, passport, dni

receiver.address

object

required

Show Address fields

receiver.address.line1

string

required

Street address

receiver.address.city

string

required

City name

receiver.address.province

string

Province (for LATAM countries)

receiver.address.zipCode

string

Postal code

receiver.address.country

string

required

2-letter ISO country code

receiver.address.deliveryInstructions

string

Special delivery instructions (max 500 chars)

parcelDetails

object

required

Package dimensions and value.

Show Parcel fields

parcelDetails.weightLbs

number

Weight in pounds. Either weightLbs or weightKg required.

parcelDetails.weightKg

number

Weight in kilograms.

parcelDetails.lengthCm

number

Length in centimeters

parcelDetails.widthCm

number

Width in centimeters

parcelDetails.heightCm

number

Height in centimeters

parcelDetails.declaredValue

number

required

Declared customs value

parcelDetails.currency

string

default:"USD"

Currency code (USD, EUR, etc.)

customsInfo

object

Customs declaration information.

Show Customs fields

customsInfo.description

string

Content description for customs

customsInfo.hsCode

string

Harmonized System code

products

array

Product line items (for checksum validation).

Show Product fields

products[].description

string

Product description

products[].quantity

integer

required

Quantity of this item

products[].unitFobValue

number

required

FOB value per unit

products[].hsCode

string

HS code for this product

products[].sku

string

Your product SKU

Response

success

boolean

Whether the request succeeded

parcel

object

The created parcel details

Show Parcel fields

parcel.id

string

Unique parcel ID

parcel.trackingNumber

string

Assigned tracking number

parcel.status

string

Current status (typically LABEL_GENERATED)

parcel.labelUrl

string

URL to download the shipping label

parcel.createdAt

string

ISO 8601 timestamp

warnings

array

Optional validation warnings (request still succeeds)

{
  "idempotencyKey": "order-2024-12-001",
  "sender": {
    "fullName": "John Smith",
    "phone": "+1 305-555-0123",
    "email": "john@example.com",
    "address": {
      "line1": "1234 Shipping Way",
      "city": "Miami",
      "state": "FL",
      "zipCode": "33101",
      "country": "US"
    }
  },
  "receiver": {
    "fullName": "María García",
    "phone": "+593 99 123 4567",
    "email": "maria@example.com",
    "nationalId": "1234567890",
    "idType": "cedula",
    "address": {
      "line1": "Av. 9 de Octubre 123",
      "city": "Guayaquil",
      "province": "Guayas",
      "zipCode": "090101",
      "country": "EC",
      "deliveryInstructions": "Dejar en recepción"
    }
  },
  "parcelDetails": {
    "weightLbs": 2.5,
    "lengthCm": 30,
    "widthCm": 20,
    "heightCm": 15,
    "declaredValue": 149.99,
    "currency": "USD"
  },
  "customsInfo": {
    "description": "Electronics - Phone Accessories",
    "hsCode": "8517.62"
  },
  "products": [
    {
      "description": "Phone Case",
      "quantity": 2,
      "unitFobValue": 25.00,
      "sku": "CASE-001"
    },
    {
      "description": "Screen Protector",
      "quantity": 3,
      "unitFobValue": 33.33,
      "sku": "PROT-002"
    }
  ]
}

{
  "success": true,
  "parcel": {
    "id": "cl123abc456def",
    "trackingNumber": "CBECUSD123456789",
    "status": "LABEL_GENERATED",
    "labelUrl": "https://labels.crbtrack.com/CBECUSD123456789.pdf",
    "createdAt": "2024-12-21T10:30:00Z"
  }
}

Country-Specific Requirements

🇪🇨 Ecuador

National ID: Required (Cédula or RUC)
Postal Code: Must match province
Province: Required

🇲🇽 Mexico

National ID: RFC optional
State: Required
Postal Code: 5 digits required

🇨🇴 Colombia

National ID: Cédula required
City: Must be valid Colombian city

API Reference

Documentation Index

​Request Body

​Response

​Country-Specific Requirements

Request Body

Response

Country-Specific Requirements