Create shipment for order
create_shipment_for_orderBuy a shipment (label) for an existing order and link it to that order. A purchase spends account balance.
Without rate_id it quotes the order, waits until every carrier answered and buys the cheapest priced rate. To buy the rate the user chose, pass rate_id with its quotation_id; it is bought only after checking it belongs to this order. With auto_select=false it never buys, even with a rate_id. Purchase fields (package_type, consignment_note, contacts) follow create_shipment; never fabricate contacts or addresses. When the server enforces confirmation, a call without _confirm: true is not executed and answers status confirmation_required; _preview: true returns the plan without executing.
Purchases are deduplicated per rate as in create_shipment; after WRITE_OUTCOME_UNKNOWN, check list_order_labels or list_shipments before retrying. The label is generated asynchronously, so label_url and tracking_number on the packages can still be empty; check get_shipment later.
Use create_shipment instead for a standalone shipment with no order, and create_external_shipment for a label bought outside Skydropx. Returns the shipment under data, packages and addresses in included. When nothing is bought: status: 'pending' with a quotation_id (carriers still pricing: call again with it), the rates to choose from (auto_select=false), or an mcp_next_step to call once the user confirms.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"order_id": "<order_id>"
},
"name": "create_shipment_for_order"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| carrier | No | Restrict auto-select to this carrier name/code | |
| rate_id | No | Id of the rate the user chose, from the rates this tool (auto_select=false) or get_quotation returned in this conversation. Requires quotation_id. | |
| _confirm | No | Explicit confirmation for actions that spend money or destroy state, when the server enforces confirmation | |
| _preview | No | Dry run: return the plan without executing anything | |
| order_id | Yes | Id of the existing order to ship, from list_orders / get_order / create_order in this conversation (never a shipment or quotation id). The label is linked to it. | |
| packages | No | Per-package content, packaging and protection; the amount to collect stays as quoted | |
| products | No | Line items; required on international routes and where the origin country demands them | |
| protected | No | Insure the label at purchase: the protection is charged with it and needs declared_value. Quote with package_protected first so the user sees its price. | |
| address_to | No | Override DESTINATION (recipient) contact/address details | |
| mandate_id | No | Agent mandate this action is taken under (audited server-side) | |
| auto_select | No | Purchase automatically (default true). false never purchases. | |
| address_from | No | Override ORIGIN (sender) contact/address details — must match the quotation's address_from party, never the recipient | |
| package_type | No | Packaging code — you MUST take it from a `list_packagings` result in THIS conversation (match the user's plain words, e.g. 'caja de cartón', against that catalog). Never invent or reuse a remembered code. | |
| quotation_id | No | The quotation_id returned together with the rates by this tool or get_quotation | |
| office_pickup | No | The sender drops the parcel off at a carrier branch (no home pickup). Only for a rate whose `office_pickup` is true; requires office_pickup_point_id. | |
| declared_value | No | Value to insure, in the account's currency; required (above 0) when `protected` is true | |
| nfe_access_key | No | Nota Fiscal access key when one was already issued (BR) | |
| idempotency_key | No | Client-generated key forwarded as an Idempotency-Key header. It does NOT by itself guarantee deduplication: after a WRITE_OUTCOME_UNKNOWN error, check the current state (e.g. list_shipments / get_shipment) before retrying. | |
| office_delivery | No | Entrega en sucursal / ocurre: the recipient collects at a carrier branch instead of home delivery. Only for a rate whose `office_delivery` is true (see the quotation's `mcp_office`); requires office_delivery_point_id. A rate with `office_delivery_only` cannot be bought without it. | |
| package_content | No | What is being shipped, in the user's plain words (e.g. 'Zapatillas') | |
| printing_format | No | Label format: standard or thermal. Omitted, the account's saved preference applies. Thermal on a carrier without thermal labels is refused with a validation error, whether sent here or coming from a saved thermal preference: send standard for such a carrier. | |
| cash_on_delivery | No | Accepted but not applied here: cash on delivery is taken from the quotation, so set it (with declared_amount) on quote_shipment. | |
| consignment_note | No | Carta-porte SAT code — you MUST take it from a `list_consignment_notes` search in THIS conversation (search with the user's plain words, e.g. 'zapatillas'). Never invent or reuse a remembered code. | |
| shipment_purpose | No | Purpose of the shipment. REQUIRED for international shipments | |
| fiscal_document_mode | No | Fiscal document mode (BR flows) | |
| include_order_detail | No | true asks for an order-detail PDF with the label; when one is generated its link is attributes.order_detail_url (default false) | |
| customs_payment_payer | No | Who pays customs. REQUIRED for international shipments | |
| office_pickup_point_id | No | Origin branch id chosen by the user from list_office_points(rate_id, direction: 'pickup') for THIS rate | |
| recipient_pays_shipping | No | Accepted but not applied here: taken from the quotation, so set it on quote_shipment. | |
| office_delivery_point_id | No | Destination branch id chosen by the user from list_office_points(rate_id, direction: 'delivery') for THIS rate |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | The purchased shipment; absent when nothing was bought | |
| note | No | Present when the rates are partial | |
| rates | No | Priced rates for the user to choose | |
| status | No | 'pending' while carriers are still pricing | |
| message | No | ||
| complete | No | Whether every carrier answered (auto_select=false) | |
| included | No | Sideloaded JSON:API records (id, type, attributes) referenced from relationships; absent when nothing is sideloaded | |
| order_id | No | The order; present when nothing was bought | |
| purchased | No | false when nothing was bought | |
| quotation_id | No | Quotation to re-read with get_quotation or pass back | |
| mcp_next_step | No | Server-added hint naming the next tool to call; absent when there is no next step |