---
title: "POST /api/v3/orders/multibox"
method: POST
path: "/api/v3/orders/multibox"
tags: ["orders"]
---

# POST /api/v3/orders/multibox

`POST /api/v3/orders/multibox`

Create a multibox order that groups multiple packages (children) under a single parent order (master). All children share the same origin, destination, sender and recipient. Useful when a single shipment contains multiple parcels that must travel together.

Minimum 1 child, maximum 20 children per order.

## Request body

- MultiboxRequest — Request payload for creating a multibox order. A multibox order groups multiple packages (children) under a single parent order (master), sharing origin, destination, sender and recipient.
  - `deliveryType` 'SMD' | 'NXD' | 'SPT' | '99M' | 'CO2' | 'RET' | 'ECO' | 'P2P' | 'NAL' | 'XBD', required — Delivery type code. Supported values: SMD (SameDay), NXD (NextDay), SPT (Sprint, auto-converted to NXD), 99M, CO2, RET, ECO, P2P, NAL, XBD.
  - `packageSize` 'xs' | 's' | 'm' | 'l' | 'xl' | 'xxl' — General package size for the order.
  - `origin` MultiboxLocation — Location for origin or destination of a multibox order.
    - `address` string, required — Full address. Minimum 10 characters, maximum 300.
    - `country` 'MEX' | 'CHL' | 'COL' | 'PER', required — Country code in ISO 3-letter format.
    - `zipcode` string — Postal code.
    - `lat` number, double — Latitude. If 0.0, the system will geocode the address automatically.
    - `lng` number, double — Longitude. If 0.0, the system will geocode the address automatically.
    - `locationId` string — Previously registered location identifier.
    - `references` string — Additional address references.
  - `destination` MultiboxLocation — Location for origin or destination of a multibox order.
    - `address` string, required — Full address. Minimum 10 characters, maximum 300.
    - `country` 'MEX' | 'CHL' | 'COL' | 'PER', required — Country code in ISO 3-letter format.
    - `zipcode` string — Postal code.
    - `lat` number, double — Latitude. If 0.0, the system will geocode the address automatically.
    - `lng` number, double — Longitude. If 0.0, the system will geocode the address automatically.
    - `locationId` string — Previously registered location identifier.
    - `references` string — Additional address references.
  - `sender` MultiboxPerson — Person information for sender or recipient.
    - `firstName` string, required — First name.
    - `lastName` string, required — Last name.
    - `email` string, email, required — Email address. Must be a valid email.
    - `phone` string, required — Phone number including country code (e.g. +525555555544).
  - `recipient` MultiboxPerson — Person information for sender or recipient.
    - `firstName` string, required — First name.
    - `lastName` string, required — Last name.
    - `email` string, email, required — Email address. Must be a valid email.
    - `phone` string, required — Phone number including country code (e.g. +525555555544).
  - `options` MultiboxOptions — Additional delivery options.
    - `notes` string — Special instructions or notes for the delivery.
  - `internalKey` string — Unique internal key for the order. If already used, the error INTERNAL_KEY_ALREADY_EXISTS is returned.
  - `children` MultiboxChild[], required — Array of child packages. Minimum 1, maximum 20.
    - `internalKey` string — Internal key to individually identify the child package.
    - `items` MultiboxItem[], required — Items contained in the child package.
      - `weight` number, required — Weight in grams.
      - `height` number — Height in centimeters.
      - `width` number — Width in centimeters.
      - `length` number — Length/depth in centimeters.
      - `size` 'xs' | 's' | 'm' | 'l' | 'xl' | 'xxl', required — Package size category. Use the endpoint GET /api/v3/shipping/rates/sizes to calculate it from dimensions.

## Response `200`

Multibox order created successfully

- MultiboxResponse — Successful response for multibox order creation.
  - `traceId` string — Trace identifier for support and debugging.
  - `message` string — Descriptive result message.
  - `data` object
    - `master` string — Tracking ID of the parent (master) order.
    - `children` MultiboxChildResponse[] — List of created child packages.
      - `tracking_id` string — Unique tracking ID of the child package.
      - `internal_key` string — Internal key associated with the child package (same as sent in the request).
      - `client_id` string — Client identifier that owns the order.
  - `errors` MultiboxErrorItem[] — Empty array on success.
    - `code` 'GENERIC_INVALID_PARAMETERS' | 'INTERNAL_KEY_ALREADY_EXISTS' | 'CUSTOMER_INACTIVE' | 'ORGANIZATION_INACTIVE' | 'CUSTOMER_HAS_NO_CREDIT' | 'CUSTOMER_DELIVERY_TYPE_NOT_ACTIVE' | 'GEOCODING_SERVICE_ERROR' | 'COVERAGE_SERVICE_ERROR' | 'SHIPPING_RATES_SERVICE_ERROR' | 'TRACKING_ID_SERVICE_ERROR' | 'STATE_MACHINE_ERROR_RESPONSE' | 'CUSTOMERS_V3_SERVICE_ERROR' | 'FAILED_TO_CREATE_REQUEST' | 'FAILED_TO_SEND_REQUEST' | 'FAILED_TO_DECODE_RESPONSE' | 'JWT_EXPIRED' | 'FAILED_TO_RETRIEVE_USER_DATA' | 'GENERIC_500_ERROR', required — Error code identifier.
    - `message` string, required — Human-readable error description.
    - `field` string — Field name that caused the error (only present for validation errors).

## Other responses

- `400` — Invalid request body. The JSON payload could not be parsed.
- `401` — Authentication error. JWT is missing, malformed, or expired.
- `422` — Validation or business rule error. The request fields do not meet the required validations or a business rule was not satisfied.
- `500` — Internal server error. An unexpected error occurred during order processing.

---

[API](https://skmtc.net/99minutos/apis/api-version-3.md) · [All operations](https://skmtc.net/99minutos/apis/api-version-3/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/99minutos/api-version-3/versions/3eca3996fd97/schema)