Create Order - CrossBorderly API

{
  "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"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Request validation failed",
    "message_es": "La validación de la solicitud falló",
    "details": {
      "errors": [
        {
          "field": "receiver.nationalId",
          "message": "National ID is required for Ecuador shipments"
        }
      ]
    },
    "requestId": "req_abc123"
  }
}

{
  "success": false,
  "error": {
    "code": "PARCEL_DUPLICATE_TRACKING",
    "message": "A parcel with this tracking number already exists",
    "message_es": "Ya existe un paquete con este número de seguimiento",
    "requestId": "req_abc123"
  }
}

POST

api

orders

create

{
  "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"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Request validation failed",
    "message_es": "La validación de la solicitud falló",
    "details": {
      "errors": [
        {
          "field": "receiver.nationalId",
          "message": "National ID is required for Ecuador shipments"
        }
      ]
    },
    "requestId": "req_abc123"
  }
}

{
  "success": false,
  "error": {
    "code": "PARCEL_DUPLICATE_TRACKING",
    "message": "A parcel with this tracking number already exists",
    "message_es": "Ya existe un paquete con este número de seguimiento",
    "requestId": "req_abc123"
  }
}

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

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.

string

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

string

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

string

Customer-facing reference number (max 100 characters).

object

required

Sender (shipper) information.

Show Sender fields

string

required

Full name of sender (max 255 chars)

string

Company name (optional)

string

required

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

string

Email address for notifications

object

required

Show Address fields

string

required

Street address line 1

string

Street address line 2

string

required

City name

string

State/province for US/CA

string

Postal code

string

required

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

object

required

Receiver (consignee) information.

Show Receiver fields

string

required

Full name of receiver

string

required

Phone number with country code

string

Email for tracking notifications

string

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

string

Type of ID: cedula, ruc, passport, dni

object

required

Show Address fields

string

required

Street address

string

required

City name

string

Province (for LATAM countries)

string

Postal code

string

required

2-letter ISO country code

string

Special delivery instructions (max 500 chars)

object

required

Package dimensions and value.

Show Parcel fields

number

Weight in pounds. Either weightLbs or weightKg required.

number

Weight in kilograms.

number

Length in centimeters

number

Width in centimeters

number

Height in centimeters

number

required

Declared customs value

string

default:"USD"

Currency code (USD, EUR, etc.)

object

Customs declaration information.

Show Customs fields

string

Content description for customs

string

Harmonized System code

array

Product line items (for checksum validation).

Show Product fields

string

Product description

integer

required

Quantity of this item

number

required

FOB value per unit

string

HS code for this product

string

Your product SKU

Response

boolean

Whether the request succeeded

object

The created parcel details

Show Parcel fields

string

Unique parcel ID

string

Assigned tracking number

string

Current status (typically LABEL_GENERATED)

string

URL to download the shipping label

string

ISO 8601 timestamp

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"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Request validation failed",
    "message_es": "La validación de la solicitud falló",
    "details": {
      "errors": [
        {
          "field": "receiver.nationalId",
          "message": "National ID is required for Ecuador shipments"
        }
      ]
    },
    "requestId": "req_abc123"
  }
}

{
  "success": false,
  "error": {
    "code": "PARCEL_DUPLICATE_TRACKING",
    "message": "A parcel with this tracking number already exists",
    "message_es": "Ya existe un paquete con este número de seguimiento",
    "requestId": "req_abc123"
  }
}

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 Overview Void Order

​Request Body

​Response

​Country-Specific Requirements

Request Body

Response

Country-Specific Requirements