> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crbtrack.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Order

> Create a new shipping order and generate a label

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

<ParamField body="idempotencyKey" type="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.
</ParamField>

<ParamField body="trackingNumber" type="string">
  Optional custom tracking number (10-30 characters). If not provided, the system generates one automatically.
</ParamField>

<ParamField body="externalOrderId" type="string">
  Your internal order ID for reference (max 100 characters).
</ParamField>

<ParamField body="customerReference" type="string">
  Customer-facing reference number (max 100 characters).
</ParamField>

<ParamField body="sender" type="object" required>
  Sender (shipper) information.

  <Expandable title="Sender fields">
    <ParamField body="sender.fullName" type="string" required>
      Full name of sender (max 255 chars)
    </ParamField>

    <ParamField body="sender.companyName" type="string">
      Company name (optional)
    </ParamField>

    <ParamField body="sender.phone" type="string" required>
      Phone number with country code (e.g., +1 305-555-0123)
    </ParamField>

    <ParamField body="sender.email" type="string">
      Email address for notifications
    </ParamField>

    <ParamField body="sender.address" type="object" required>
      <Expandable title="Address fields">
        <ParamField body="sender.address.line1" type="string" required>
          Street address line 1
        </ParamField>

        <ParamField body="sender.address.line2" type="string">
          Street address line 2
        </ParamField>

        <ParamField body="sender.address.city" type="string" required>
          City name
        </ParamField>

        <ParamField body="sender.address.state" type="string">
          State/province for US/CA
        </ParamField>

        <ParamField body="sender.address.zipCode" type="string">
          Postal code
        </ParamField>

        <ParamField body="sender.address.country" type="string" required>
          2-letter ISO country code (e.g., US, MX, EC)
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="receiver" type="object" required>
  Receiver (consignee) information.

  <Expandable title="Receiver fields">
    <ParamField body="receiver.fullName" type="string" required>
      Full name of receiver
    </ParamField>

    <ParamField body="receiver.phone" type="string" required>
      Phone number with country code
    </ParamField>

    <ParamField body="receiver.email" type="string">
      Email for tracking notifications
    </ParamField>

    <ParamField body="receiver.nationalId" type="string">
      National ID number (Cédula, RUC, DNI, etc.). **Required for some countries.**
    </ParamField>

    <ParamField body="receiver.idType" type="string">
      Type of ID: `cedula`, `ruc`, `passport`, `dni`
    </ParamField>

    <ParamField body="receiver.address" type="object" required>
      <Expandable title="Address fields">
        <ParamField body="receiver.address.line1" type="string" required>
          Street address
        </ParamField>

        <ParamField body="receiver.address.city" type="string" required>
          City name
        </ParamField>

        <ParamField body="receiver.address.province" type="string">
          Province (for LATAM countries)
        </ParamField>

        <ParamField body="receiver.address.zipCode" type="string">
          Postal code
        </ParamField>

        <ParamField body="receiver.address.country" type="string" required>
          2-letter ISO country code
        </ParamField>

        <ParamField body="receiver.address.deliveryInstructions" type="string">
          Special delivery instructions (max 500 chars)
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="parcelDetails" type="object" required>
  Package dimensions and value.

  <Expandable title="Parcel fields">
    <ParamField body="parcelDetails.weightLbs" type="number">
      Weight in pounds. Either `weightLbs` or `weightKg` required.
    </ParamField>

    <ParamField body="parcelDetails.weightKg" type="number">
      Weight in kilograms.
    </ParamField>

    <ParamField body="parcelDetails.lengthCm" type="number">
      Length in centimeters
    </ParamField>

    <ParamField body="parcelDetails.widthCm" type="number">
      Width in centimeters
    </ParamField>

    <ParamField body="parcelDetails.heightCm" type="number">
      Height in centimeters
    </ParamField>

    <ParamField body="parcelDetails.declaredValue" type="number" required>
      Declared customs value
    </ParamField>

    <ParamField body="parcelDetails.currency" type="string" default="USD">
      Currency code (USD, EUR, etc.)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="customsInfo" type="object">
  Customs declaration information.

  <Expandable title="Customs fields">
    <ParamField body="customsInfo.description" type="string">
      Content description for customs
    </ParamField>

    <ParamField body="customsInfo.hsCode" type="string">
      Harmonized System code
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="products" type="array">
  Product line items (for checksum validation).

  <Expandable title="Product fields">
    <ParamField body="products[].description" type="string">
      Product description
    </ParamField>

    <ParamField body="products[].quantity" type="integer" required>
      Quantity of this item
    </ParamField>

    <ParamField body="products[].unitFobValue" type="number" required>
      FOB value per unit
    </ParamField>

    <ParamField body="products[].hsCode" type="string">
      HS code for this product
    </ParamField>

    <ParamField body="products[].sku" type="string">
      Your product SKU
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Whether the request succeeded
</ResponseField>

<ResponseField name="parcel" type="object">
  The created parcel details

  <Expandable title="Parcel fields">
    <ResponseField name="parcel.id" type="string">
      Unique parcel ID
    </ResponseField>

    <ResponseField name="parcel.trackingNumber" type="string">
      Assigned tracking number
    </ResponseField>

    <ResponseField name="parcel.status" type="string">
      Current status (typically `LABEL_GENERATED`)
    </ResponseField>

    <ResponseField name="parcel.labelUrl" type="string">
      URL to download the shipping label
    </ResponseField>

    <ResponseField name="parcel.createdAt" type="string">
      ISO 8601 timestamp
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="warnings" type="array">
  Optional validation warnings (request still succeeds)
</ResponseField>

<RequestExample>
  ```json Example Request theme={null}
  {
    "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"
      }
    ]
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 201 - Created theme={null}
  {
    "success": true,
    "parcel": {
      "id": "cl123abc456def",
      "trackingNumber": "CBECUSD123456789",
      "status": "LABEL_GENERATED",
      "labelUrl": "https://labels.crbtrack.com/CBECUSD123456789.pdf",
      "createdAt": "2024-12-21T10:30:00Z"
    }
  }
  ```

  ```json 400 - Validation Error theme={null}
  {
    "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"
    }
  }
  ```

  ```json 409 - Duplicate theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>

## Country-Specific Requirements

<AccordionGroup>
  <Accordion title="🇪🇨 Ecuador">
    * **National ID**: Required (Cédula or RUC)
    * **Postal Code**: Must match province
    * **Province**: Required
  </Accordion>

  <Accordion title="🇲🇽 Mexico">
    * **National ID**: RFC optional
    * **State**: Required
    * **Postal Code**: 5 digits required
  </Accordion>

  <Accordion title="🇨🇴 Colombia">
    * **National ID**: Cédula required
    * **City**: Must be valid Colombian city
  </Accordion>
</AccordionGroup>