> ## Documentation Index > Fetch the complete documentation index at: https://developers.cubbo.com/llms.txt > Use this file to discover all available pages before exploring further. # Update an order > Replaces the editable parts of an order that has not entered fulfillment yet: shipping and billing addresses, payment flag, shipping method, product lines and client-uploaded shipping documents. After a successful update the order goes back to `initial` and is re-validated and re-processed by Cubbo, so the response shows the order as it was saved, not its final status. - Allowed only while the order is in `unpaid`, `empty`, `error`, `cancelation_window`, `awaiting_fulfillment_request`, `entirely_dropshipping`, `backorder`, `hold` or `pending`. An order still in `initial` has not been processed yet and is refused (retry later). Orders in `processing` or any later status cannot be updated with this endpoint. - On a pick-and-ship store an order that already generated its label cannot be modified. - Only the keys you send are changed. `shipping` and `billing`, when present, replace the whole address block (fields you omit become empty). `products`, when present and non-empty, replaces every order line with the list you send; each line keeps the price it was created with (a price sent here is ignored) and a product new to the order gets no price. - `products` cannot be sent for an order that has a line pinned to a unit code, and it cannot pin one (`unit_code` on a product is refused). - The D2C/B2B classification (`is_b2b`) is immutable: on a store that handles both models a value different from the order's is refused; on a single-model store it is ignored. - When you change `shipping` without sending `shipping_method_id`, an order created through a sales-channel integration with a shipping-method mapping gets its shipping method re-evaluated during re-processing, unless the order ships on the marketplace's own label. - Chile: when you send `shipping_method_id` and `shipping.city` cannot be identified, the update is still saved with the rest of your changes. The order goes back to `error` until `shipping.city` is corrected. - Colombia: unlike the other `shipping` fields, `shipping.city_code` is kept when you leave it out, unless the same update changes `shipping.city` or `shipping.province`; send it as `null` to clear it, and the city and province decide the destination again. A code Cubbo does not know is saved with the rest of your changes and the order goes back to `error` (`UNRECOGNIZED_CITY_CODE`) until it is corrected. - A marketplace order that ships on the marketplace's own label can only move to another marketplace-label shipping method; the refusal carries the code `MARKETPLACE_WITH_EXTERNAL_GUIDE` so you can tell it apart from a fixable validation error. - `shipping_documents`, when present, deletes every document previously uploaded by you (`document_type` other than `file`) and stores the new ones. Documents generated by Cubbo are kept. A label sent as a URL (`document_type: url`) is not downloaded on update: when the order already has its label, the URL is ignored and the order keeps its labels. - When the order's shipping method ships on your own label (an external guide), the order must still have a label after the update. If it has none and you do not send one (as `base64`), or your `shipping_documents` would replace it with none, the update is refused with `MISSING_EXTERNAL_LABEL` and nothing is changed; when the only label you sent was a URL, the code is `LABEL_URL_NOT_SUPPORTED_ON_UPDATE`. Send the label in the same request, or upload it first with `PATCH /orders/{id}/upload-shipping-documents`. A label still being fetched from the URL you sent when creating the order counts as present. - `channel_order_id` and `channel_name` are set when the order is created and cannot be changed here. Sending a value different from the order's own is refused with `UNSUPPORTED_UPDATE_FIELDS`; sending the order's current values (for example the order as returned by `GET /orders`) is accepted. Other keys this endpoint does not list are ignored. - Requires an API user with the "orders update" permission and access to the store. Note that a permission failure inside this action is currently answered with `500 unexpected error` rather than `401`. ## OpenAPI ````yaml /openapi.yaml put /orders/{id} openapi: 3.1.0 info: title: Cubbo Clients API version: '1.0' summary: >- Orders, inventory, replenishments, returns, shipping and webhooks for Cubbo fulfillment. description: > The Cubbo Clients API connects your store, ERP or marketplace with Cubbo's fulfillment network. All endpoints except `POST /auth/token` require a bearer token; see the Authentication guide. Request and response bodies are JSON. Errors are JSON objects with an `error` key. contact: name: Cubbo integrations email: integraciones@cubbo.com servers: - url: https://api.cubbo.com/v1 description: Production security: - bearerAuth: [] tags: - name: Authentication description: Exchange client credentials for a bearer token. - name: Orders description: Create, update, hold, cancel and read sales orders. - name: Shipping labels description: Read the shipping labels generated for an order. - name: Inventory description: Products and stock per store. - name: Lots description: Lot-level inventory for products with expiration or batch tracking. - name: Reports description: Bulk reports for reconciliation. - name: Replenishments description: Inbound shipments to the warehouse. - name: Returns description: Returns and exchanges. - name: Stores description: Store provisioning and settings. - name: Shipping methods description: Available shipping methods, coverage and quotes. - name: Click and collect description: Pickup points and in-store pickup orders. paths: /orders/{id}: put: tags: - Orders summary: Update an order description: > Replaces the editable parts of an order that has not entered fulfillment yet: shipping and billing addresses, payment flag, shipping method, product lines and client-uploaded shipping documents. After a successful update the order goes back to `initial` and is re-validated and re-processed by Cubbo, so the response shows the order as it was saved, not its final status. - Allowed only while the order is in `unpaid`, `empty`, `error`, `cancelation_window`, `awaiting_fulfillment_request`, `entirely_dropshipping`, `backorder`, `hold` or `pending`. An order still in `initial` has not been processed yet and is refused (retry later). Orders in `processing` or any later status cannot be updated with this endpoint. - On a pick-and-ship store an order that already generated its label cannot be modified. - Only the keys you send are changed. `shipping` and `billing`, when present, replace the whole address block (fields you omit become empty). `products`, when present and non-empty, replaces every order line with the list you send; each line keeps the price it was created with (a price sent here is ignored) and a product new to the order gets no price. - `products` cannot be sent for an order that has a line pinned to a unit code, and it cannot pin one (`unit_code` on a product is refused). - The D2C/B2B classification (`is_b2b`) is immutable: on a store that handles both models a value different from the order's is refused; on a single-model store it is ignored. - When you change `shipping` without sending `shipping_method_id`, an order created through a sales-channel integration with a shipping-method mapping gets its shipping method re-evaluated during re-processing, unless the order ships on the marketplace's own label. - Chile: when you send `shipping_method_id` and `shipping.city` cannot be identified, the update is still saved with the rest of your changes. The order goes back to `error` until `shipping.city` is corrected. - Colombia: unlike the other `shipping` fields, `shipping.city_code` is kept when you leave it out, unless the same update changes `shipping.city` or `shipping.province`; send it as `null` to clear it, and the city and province decide the destination again. A code Cubbo does not know is saved with the rest of your changes and the order goes back to `error` (`UNRECOGNIZED_CITY_CODE`) until it is corrected. - A marketplace order that ships on the marketplace's own label can only move to another marketplace-label shipping method; the refusal carries the code `MARKETPLACE_WITH_EXTERNAL_GUIDE` so you can tell it apart from a fixable validation error. - `shipping_documents`, when present, deletes every document previously uploaded by you (`document_type` other than `file`) and stores the new ones. Documents generated by Cubbo are kept. A label sent as a URL (`document_type: url`) is not downloaded on update: when the order already has its label, the URL is ignored and the order keeps its labels. - When the order's shipping method ships on your own label (an external guide), the order must still have a label after the update. If it has none and you do not send one (as `base64`), or your `shipping_documents` would replace it with none, the update is refused with `MISSING_EXTERNAL_LABEL` and nothing is changed; when the only label you sent was a URL, the code is `LABEL_URL_NOT_SUPPORTED_ON_UPDATE`. Send the label in the same request, or upload it first with `PATCH /orders/{id}/upload-shipping-documents`. A label still being fetched from the URL you sent when creating the order counts as present. - `channel_order_id` and `channel_name` are set when the order is created and cannot be changed here. Sending a value different from the order's own is refused with `UNSUPPORTED_UPDATE_FIELDS`; sending the order's current values (for example the order as returned by `GET /orders`) is accepted. Other keys this endpoint does not list are ignored. - Requires an API user with the "orders update" permission and access to the store. Note that a permission failure inside this action is currently answered with `500 unexpected error` rather than `401`. operationId: updateOrder parameters: - name: id in: path required: true description: Cubbo order id. schema: type: integer example: 123456 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OrderUpdateRequest' examples: basic: summary: Mexico, new address and products value: store_id: 1234 is_paid: true shipping_method_id: 77 shipping: first_name: Jane last_name: Buyer phone: '5551234567' address1: Calle Falsa 123 address2: Depto 4 interior_number: '4' country: MX city: Ciudad de Mexico province: CDMX zip_code: '06600' products: - sku: SKU-RED-M quantity: 2 - sku: SKU-BLUE-L quantity: 1 colombiaCityCode: summary: Colombia, correcting the DANE code of the city value: store_id: 1234 shipping_method_id: 56 shipping: first_name: Ana last_name: Gómez phone: '5555555555' address1: 'Calle 100 # 10-20' country: CO city: Bogotá province: Bogotá, D.C. city_code: '11001' products: - sku: SKU-RED-M quantity: 1 responses: '200': description: >- The updated order (with its order lines) as saved, before re-processing. content: application/json: schema: $ref: '#/components/schemas/Order' example: id: 123456 store_id: 1234 order_number: ORD-0001 status: initial is_paid: true shipping_email: buyer@example.com shipping: first_name: Jane last_name: Buyer address_1: Calle Falsa 123 city: Ciudad de Mexico state: CDMX zip_code: '06600' country: MX city_code: null order_lines: - sku: SKU-RED-M quantity: 2 - sku: SKU-BLUE-L quantity: 1 '401': $ref: '#/components/responses/Unauthorized' '409': description: Another request is modifying this order right now. Retry shortly. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: >- Order is being processed by another request. Please try again in a moment. '422': description: >- Validation or business error. The marketplace-label, missing-label and unsupported-field refusals also carry a `code`. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/OrderUpdateLockedError' - $ref: '#/components/schemas/OrderUpdateRefusedError' examples: missingParam: value: error: Parameter store_id is required wrongStore: value: error: Order id 123456 does not belong to store id 1234 notProcessedYet: value: error: >- Order id 123456 is in status initial and has not been processed yet, try again later. notEditable: value: error: >- You can't edit an order if an order it is in processing or further statuses labelAlreadyGenerated: value: error: >- order id 123456 has already generated a label, cannot be modified businessModelImmutable: value: error: An order cannot change between D2C and B2B once it exists pinnedLines: value: error: >- order id 123456 has lines pinned to a unit code, or the request pins one; its products cannot be replaced productNotFound: value: error: Product SKU-RED-M was not found in this store personalizedProductNeedsUnitCode: value: error: >- unit_code is required for sku SKU-CARD: each unit belongs to one recipient personalizedUnitInKit: value: error: >- sku SKU-KIT is a kit holding a personalized unit, which cannot be ordered as a kit shippingMethodNotFound: value: error: Shipping method 77 was not found shippingMethodInactive: value: error: Shipping method 77 (Express) is not active internationalOnDomestic: value: error: >- Shipping method 77 (DHL International) is international and this order ships within MX. Assign a national shipping method. noCoverage: value: error: >- Shipping method 77 (Express) does not have coverage for this order externalLabelLocked: value: error: >- Order 123456 ships on the marketplace's own label (Mercado Envios), so its shipping method cannot be changed to Express: the marketplace would cancel the order and refund the buyer. It can only move to another marketplace-label shipping method. code: MARKETPLACE_WITH_EXTERNAL_GUIDE unsupportedUpdateFields: value: error: >- channel_order_id, channel_name cannot be changed once the order exists; send only the fields this endpoint updates code: UNSUPPORTED_UPDATE_FIELDS missingExternalLabel: value: error: >- Order id 123456 ships with shipping method 77, which requires the client's label, and has none; send it in shipping_documents with printing_type label code: MISSING_EXTERNAL_LABEL labelUrlNotSupportedOnUpdate: value: error: >- A label cannot be sent as a URL when editing an order; send it as base64 (document_type base64) code: LABEL_URL_NOT_SUPPORTED_ON_UPDATE '500': description: >- Unexpected error. Also returned when the order id does not exist or when the API user lacks permission on this order. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: unexpected error security: - bearerAuth: [] components: schemas: OrderUpdateRequest: type: object description: >- Full update of an order. Only the keys present are applied; see the endpoint description for replacement semantics. required: - store_id properties: store_id: type: integer description: Id of the store the order belongs to. Must match the order's store. example: 1234 is_paid: type: - boolean - 'null' description: >- Marks the order as paid or unpaid. Omit or send `null` to leave it unchanged. example: true shipping_method_id: type: - integer - 'null' description: >- Id of the shipping method to assign. Get it from `GET /shipping-methods/quote` (`shipping_method_id` of each option). It must be active and cover the (updated) shipping address; an international method is refused for a destination inside the warehouse's country. In Chile a `shipping.city` that cannot be identified is not refused; the update is saved and the order waits in `error` until it is corrected. example: 77 is_b2b: type: - boolean - 'null' description: >- Order classification. Immutable once the order exists; a value different from the order's is refused on a store handling both D2C and B2B, and ignored on a single-model store. example: false shipping: $ref: '#/components/schemas/OrderUpdateAddress' billing: $ref: '#/components/schemas/OrderUpdateBillingAddress' products: type: array description: >- New list of order lines. When non-empty it replaces every line of the order. Do not send it for orders with lines pinned to a unit code. items: $ref: '#/components/schemas/OrderUpdateProduct' shipping_documents: type: array description: >- Documents to attach. Replaces every document you uploaded before (Cubbo-generated documents are kept). A label sent as a URL is not downloaded on update; send it as `base64`. items: $ref: '#/components/schemas/OrderUpdateShippingDocument' Order: type: object description: > An order as returned by the Orders endpoints. Scalar fields are always available; associations (`shipping_method`, `order_lines`, `invoices`, `store`, `channel_integration`, `return`, `created_by_return`, `order_histories`) are present only when the endpoint includes them. Each endpoint's response description lists the fields it returns. properties: id: type: integer description: Cubbo ID of the order. Use it in path parameters. example: 987654 store_id: type: integer description: Store ID. example: 1234 order_number: type: string description: Your order number, unique within the store. example: ORD-0001 status: $ref: '#/components/schemas/OrderStatus' channel_created_at: type: string format: date-time description: When the order was created in the sales channel. example: '2026-01-10T14:02:11.000Z' order_date: type: - string - 'null' format: date-time description: Order date. example: '2026-01-10T14:02:11.000Z' shipping_date: type: - string - 'null' format: date-time description: When the order was shipped. example: '2026-01-11T18:30:00.000Z' pending_at: type: - string - 'null' format: date-time description: When the order became ready to be fulfilled. example: '2026-01-10T14:05:00.000Z' shipping_email: type: - string - 'null' description: Buyer email. example: buyer@example.com shipping_address_1: type: - string - 'null' description: Shipping street address line 1 (also inside `shipping`). example: Av. Ejemplo 123 shipping_status: oneOf: - $ref: '#/components/schemas/OrderShippingStatus' - type: 'null' description: Carrier-side status of the shipment. is_paid: type: boolean description: Whether the order is paid. Unpaid orders are not fulfilled. example: true is_cod: type: boolean description: Whether the order is cash on delivery. example: false cod_amount: type: - string - 'null' description: Amount to collect on delivery, as a decimal string. example: null requires_document_return: type: boolean description: Whether the carrier must bring back a signed document. example: false requires_pickup_on_delivery: type: boolean description: Whether the carrier must pick something up when delivering. example: false has_carrier_insurance: type: boolean description: Whether the shipment is insured with the carrier. example: false has_missing_info: type: boolean description: Whether the order is blocked because data is missing. example: false missing_info: type: - string - 'null' description: Description of the missing data, if any. example: null currency: type: - string - 'null' description: Currency code of the prices. example: MXN total_price: type: - string - 'null' description: Order total as a decimal string. example: '899.00' discount_price: type: - string - 'null' description: Total discount as a decimal string. example: '0.00' buyer_shipping_price: type: - string - 'null' description: Shipping price paid by the buyer, as a decimal string. example: '0.00' extra_fees_price: type: - string - 'null' description: Extra fees as a decimal string. example: '0.0' is_pick_and_ship: type: boolean description: >- Whether the order is a pick-and-ship order (you pick it up at the warehouse). example: false pick_n_ship_status: type: - string - 'null' description: Pick-and-ship status. enum: - awaiting_pick_up - picked_up - in_warehouse - null example: null is_b2b: type: boolean description: >- Whether the order is a B2B order. In `GET /orders` only present for stores that handle both B2B and D2C. example: false is_first_time_buyer: type: boolean description: Whether this is the buyer's first order in the store. example: true is_subscription_renewal: type: boolean description: Whether the order is a subscription renewal. example: false is_click_and_collect: type: boolean description: Whether the buyer picks the order up at a pickup point. example: false click_and_collect_metadata: oneOf: - $ref: '#/components/schemas/OrderClickAndCollectMetadata' - type: 'null' description: Pickup-point details for click-and-collect orders; null otherwise. is_multi_package: type: boolean description: Whether the shipment has more than one package. example: false shipping: $ref: '#/components/schemas/OrderAddress' billing: $ref: '#/components/schemas/OrderBillingAddressDetails' delivery_tracking: type: array description: Tracking per package. Return labels are excluded. items: $ref: '#/components/schemas/OrderDeliveryTrackingPackage' return_shipping_labels: type: - array - 'null' description: Valid return labels of the order. items: $ref: '#/components/schemas/OrderReturnShippingLabel' proof_of_delivery: oneOf: - $ref: '#/components/schemas/OrderProofOfDelivery' - type: 'null' description: >- Proof of delivery, when the carrier provided one for a shipped or returned order. estimated_time_arrival: type: - string - 'null' format: date-time description: Estimated delivery date. example: '2026-01-13T00:00:00.000Z' latest_estimated_time_arrival_range: oneOf: - $ref: '#/components/schemas/OrderEtaRange' - type: 'null' description: Latest estimated delivery window, or null when no estimate exists. delivered_at: type: - string - 'null' format: date-time description: When the carrier delivered the order. example: null updated_at: type: string format: date-time description: Last update of the order. example: '2026-01-11T18:31:00.000Z' channel_order_id: type: - string - 'null' description: ID of the order in the sales channel. example: '5566778899' channel_name: type: - string - 'null' description: Name of the sales channel the order came from. example: shopify channel_shipping_line_code: type: - string - 'null' description: >- Code of the shipping option chosen at checkout in the sales channel (first shipping line). example: standard warehouse_timezone: type: - string - 'null' description: IANA time zone of the warehouse fulfilling the order. example: America/Mexico_City shipping_method: oneOf: - $ref: '#/components/schemas/OrderShippingMethod' - type: 'null' description: Shipping method assigned to the order. order_lines: type: array description: Lines of the order. items: $ref: '#/components/schemas/OrderLine' invoices: type: array description: NF-e documents attached to the order (Brazil). items: $ref: '#/components/schemas/OrderInvoice' store: oneOf: - $ref: '#/components/schemas/OrderStore' - type: 'null' description: Store the order belongs to. channel_integration: oneOf: - $ref: '#/components/schemas/OrderChannelIntegration' - type: 'null' description: Sales-channel integration the order came from. return: oneOf: - $ref: '#/components/schemas/OrderReturnSummary' - type: 'null' description: >- The return opened for this order, if any. Use `GET /returns/{return_id}` for the full return. created_by_return: oneOf: - $ref: '#/components/schemas/OrderReturnSummary' - type: 'null' description: The return that created this order (for exchanges), if any. order_histories: type: array description: >- Order timeline. Only returned by `GET /orders` with `include_event_history=true`. items: $ref: '#/components/schemas/OrderHistoryEvent' Error: type: object description: Error body returned by every failed request. required: - error properties: error: type: string description: >- Human-readable description of the failure. For `401` responses it is always `Unauthorized`. example: Parameter store_id is required message: type: string description: >- Present on `401` responses only; the reason the request was rejected. example: invalid token code: type: - string - 'null' description: >- Stable machine-readable code, present on some order, return and replenishment errors. example: ORDER_ALREADY_EXISTS context: type: - object - 'null' description: >- Extra data about the failure when available, for example the id of the conflicting order. additionalProperties: true example: order_id: 987654 OrderUpdateLockedError: type: object description: >- Refusal of a shipping-method change on a marketplace order that ships on the marketplace's own label. required: - error - code properties: error: type: string description: Human-readable reason. example: >- Order 123456 ships on the marketplace's own label (Mercado Envios), so its shipping method cannot be changed to Express: the marketplace would cancel the order and refund the buyer. It can only move to another marketplace-label shipping method. code: type: string description: Stable error code. enum: - MARKETPLACE_WITH_EXTERNAL_GUIDE OrderUpdateRefusedError: type: object description: >- An update refused because it cannot be applied as sent. Nothing on the order is changed. required: - error - code properties: error: type: string description: Human-readable reason. example: >- A label cannot be sent as a URL when editing an order; send it as base64 (document_type base64) code: type: string description: > Stable error code. - `UNSUPPORTED_UPDATE_FIELDS`: the request changes `channel_order_id` or `channel_name`, which are set at creation; the message lists them. - `MISSING_EXTERNAL_LABEL`: the order ships on your own label and would be left without one. - `LABEL_URL_NOT_SUPPORTED_ON_UPDATE`: same, and the only label sent was a URL; send it as `base64`. enum: - UNSUPPORTED_UPDATE_FIELDS - MISSING_EXTERNAL_LABEL - LABEL_URL_NOT_SUPPORTED_ON_UPDATE example: MARKETPLACE_WITH_EXTERNAL_GUIDE OrderUpdateAddress: type: object description: >- Shipping recipient and address. Sending this object replaces the whole shipping address; omitted fields are cleared. properties: first_name: type: - string - 'null' description: Recipient first name. example: Jane last_name: type: - string - 'null' description: Recipient last name. example: Buyer phone: type: - string - 'null' description: Recipient phone number. example: '5551234567' email: type: - string - 'null' description: Recipient email. example: buyer@example.com address1: type: - string - 'null' description: Street and number (first address line). example: Calle Falsa 123 address2: type: - string - 'null' description: Second address line (apartment floor: null complement).: null example: Depto 4 address3: type: - string - 'null' description: Accepted for compatibility; not stored. example: null number: type: - string - 'null' description: Street number when your addresses keep it apart from the street name (Brazil).: null example: '123' interior_number: type: - string - 'null' description: Interior or apartment number. example: '4' neighborhood: type: - string - 'null' description: Neighborhood (colonia / bairro). example: Centro references: type: - string - 'null' description: Delivery references for the carrier. example: Blue door, ring twice country: type: - string - 'null' description: Country name or ISO code; normalized to ISO 3166-1 alpha-2. example: MX city: type: - string - 'null' description: City. example: Ciudad de Mexico province: type: - string - 'null' description: State or province. example: CDMX zip_code: type: - string - 'null' description: Postal code. example: '06600' city_code: type: - string - 'null' description: >- Colombia: the DANE code of the city (5 or 8 digits). When sent, it decides the destination instead of `city` and `province`. In other countries it is stored and returned as sent, but it does not change the destination. example: '11001' OrderUpdateBillingAddress: type: object description: >- Billing contact and address. Sending this object replaces the whole billing block; omitted fields are cleared. properties: first_name: type: - string - 'null' description: Billing first name. example: Jane last_name: type: - string - 'null' description: Billing last name. example: Buyer phone: type: - string - 'null' description: Billing phone number. example: '5551234567' email: type: - string - 'null' description: Billing email. example: buyer@example.com company: type: - string - 'null' description: Company name. example: Example S.A. de C.V. address1: type: - string - 'null' description: Street and number (first address line). example: Calle Falsa 123 address2: type: - string - 'null' description: Second address line. example: Depto 4 address3: type: - string - 'null' description: Accepted for compatibility; not stored. example: null number: type: - string - 'null' description: Street number kept apart from the street name (Brazil). example: '123' interior_number: type: - string - 'null' description: Interior or apartment number. example: '4' neighborhood: type: - string - 'null' description: Neighborhood (colonia / bairro). example: Centro country: type: - string - 'null' description: Country name or ISO code; normalized to ISO 3166-1 alpha-2. example: MX city: type: - string - 'null' description: City. example: Ciudad de Mexico province: type: - string - 'null' description: State or province. example: CDMX zip_code: type: - string - 'null' description: Postal code. example: '06600' tax_id: type: - string - 'null' description: Tax id of the buyer (RFC in Mexico; CPF or CNPJ in Brazil). example: 000.000.000-00 tax_regime: type: - string - 'null' description: Tax regime of the buyer as used when the order was created.: null example: FISICA state_registration: type: - string - 'null' description: State registration (Inscricao Estadual) for Brazilian companies. example: ISENTO OrderUpdateProduct: type: object description: One order line of the replacement list. required: - sku - quantity properties: sku: type: string description: SKU of a product in your store. example: SKU-RED-M quantity: type: integer description: Units to ship. example: 2 OrderUpdateShippingDocument: type: object description: A document sent as base64 inside the update body. required: - filename - data - content_type - printing_type - document_type properties: filename: type: string description: File name, including extension. example: label.pdf data: type: string description: >- File contents encoded in base64. A `data:...;base64,` prefix is tolerated. example: JVBERi0xLjQKJcOkw7zDtsOfCg== content_type: type: string description: MIME type of the file. PDF, PNG and JPEG are accepted. enum: - application/pdf - image/png - image/jpeg example: application/pdf printing_type: type: string description: >- How the warehouse must print and use the document. `label` is a shipping label; `document` is any other printable to include in the package. enum: - label - document - difal_bill - difal_payment_receipt - identifier_label - oxxo_digital_card example: label document_type: type: string description: >- Origin of the document. Use `base64` for documents you upload; `file` marks Cubbo-generated documents and is never replaced by later updates. enum: - base64 - url - file example: base64 metadata: type: object description: >- Free-form JSON stored with the document (at most 10 KB), for example the tracking number of a label. additionalProperties: true example: tracking_number: TRACK0000001 carrier: DHL OrderStatus: type: string description: > Fulfillment status of an order. `processing`, `picking` and `packing` all mean the order is being prepared in the warehouse. `holded` means the order is on hold. `packed` is unused. enum: - initial - unpaid - empty - pending - error - cancelation_window - entirely_dropshipping - backorder - processing - picking - packing - packed - shipped - canceled - holded - interrupted - returned - return_arrived - returning - reentered - awaiting_fulfillment_request - awaiting_dropoff - arrived_at_warehouse example: shipped OrderShippingStatus: type: string description: >- Carrier-side status of the shipment, updated from tracking events. `null` until the carrier reports the first event. enum: - shipment_created - awaiting_collection - shipment_collected - shipment_in_transit - shipment_out_for_delivery - shipment_delivered - shipment_partially_delivered - shipment_with_incident - shipment_to_be_self_collected - shipment_canceled - shipment_returned - shipment_not_defined example: shipment_in_transit OrderClickAndCollectMetadata: type: object description: > Pickup-point information for click-and-collect orders. Keys depend on the carrier that operates the pickup point (typically `name`, `address`, `zipcode`, `description`, `carrier_name`, coordinates and a location ID). `pickup_codes` is keyed by package tracking number and holds the short code and QR image the buyer presents at pickup. Internal fields are never included. additionalProperties: true properties: name: type: string description: Pickup point name. example: Pickup point name address: type: string description: Pickup point address. example: Pickup point address zipcode: type: string description: Pickup point postal code. example: '01000' description: type: string description: Human-readable description of the pickup point. example: Punto fisico - Centro carrier_name: type: string description: Carrier operating the pickup point. example: ESTAFETA pickup_codes: type: object description: Pickup codes per package, keyed by the package tracking number. additionalProperties: type: object properties: pickup_short: type: string description: Short pickup code. example: AB12CD pickup_qr_image_url: type: string description: URL of the QR image to present at pickup. example: >- https://api.cubbo.com/rails/active_storage/blobs/redirect/example/pickup_qr.png OrderAddress: type: object description: Shipping contact and address of an order. properties: first_name: type: - string - 'null' description: Recipient first name. example: Ana last_name: type: - string - 'null' description: Recipient last name. example: Example company: type: - string - 'null' description: Company name, if any. example: null phone: type: - string - 'null' description: Recipient phone number. example: '+525500000000' address_1: type: - string - 'null' description: Street address line 1. example: Av. Ejemplo 123 address_2: type: - string - 'null' description: Street address line 2. example: null email: type: - string - 'null' description: Recipient email. example: buyer@example.com zip_code: type: - string - 'null' description: Postal code. example: '01000' country: type: - string - 'null' description: Two-letter country code. example: MX state: type: - string - 'null' description: State or province. example: CDMX city: type: - string - 'null' description: City. example: Ciudad de Mexico city_code: type: - string - 'null' description: >- Colombia: the DANE code of the city that decides the destination, as you sent it in `shipping.city_code`; null when the city and province decide. example: null number: type: - string - 'null' description: Street number. example: '123' interior_number: type: - string - 'null' description: Apartment or interior number. example: null neighborhood: type: - string - 'null' description: Neighborhood (colonia / bairro). example: Centro references: type: - string - 'null' description: Delivery references for the courier. example: Blue door OrderBillingAddressDetails: type: object description: >- Billing contact, fiscal data and address of an order. Fiscal fields are returned in clear text to the store that owns the order. properties: first_name: type: - string - 'null' description: Billing first name. example: Ana last_name: type: - string - 'null' description: Billing last name. example: Example company: type: - string - 'null' description: Company name, if any. example: null phone: type: - string - 'null' description: Billing phone number. example: '+525500000000' tax_id: type: - string - 'null' description: Tax ID of the buyer (CPF or CNPJ in Brazil, RFC in Mexico). example: 000.000.000-00 tax_regime: type: - string - 'null' description: Buyer's tax regime, when provided. example: null state_registration: type: - string - 'null' description: State registration (inscricao estadual, Brazil). example: null address_1: type: - string - 'null' description: Street address line 1. example: Av. Ejemplo 123 address_2: type: - string - 'null' description: Street address line 2. example: null number: type: - string - 'null' description: Street number. example: '123' interior_number: type: - string - 'null' description: Apartment or interior number. example: null neighborhood: type: - string - 'null' description: Neighborhood. example: Centro email: type: - string - 'null' description: Billing email. example: buyer@example.com zip_code: type: - string - 'null' description: Postal code. example: '01000' country: type: - string - 'null' description: Two-letter country code. example: MX state: type: - string - 'null' description: State or province. example: CDMX city: type: - string - 'null' description: City. example: Ciudad de Mexico OrderDeliveryTrackingPackage: type: object description: >- Tracking information for one package of the order. When no label exists yet, a single entry with null tracking fields is returned. properties: shipping_number: type: - string - 'null' description: Carrier tracking number of the package. example: TRK000000001 tracking_url: type: - string - 'null' description: >- Carrier tracking page. For Cubbo pickup-point deliveries this is Cubbo's own tracking page. example: https://carrier.example.com/track/TRK000000001 cubbo_tracking_url: type: - string - 'null' description: Cubbo tracking page for the order. example: https://tracking.example.com/orders/abc123 service_id: type: - string - 'null' description: Carrier service used for the label. example: express shipping_status: oneOf: - $ref: '#/components/schemas/OrderShippingStatus' - type: 'null' description: >- Shipping status of this package (falls back to the order's shipping status). package_index: type: integer description: 1-based index of this package. example: 1 total_packages: type: integer description: Total number of packages of the order. example: 1 OrderReturnShippingLabel: type: object description: A valid return label attached to the order. properties: shipping_number: type: - string - 'null' description: Tracking number of the return label. example: RTN000000001 tracking_url: type: - string - 'null' description: Carrier tracking page of the return label. example: https://carrier.example.com/track/RTN000000001 OrderProofOfDelivery: type: object description: >- Proof of delivery reported by the carrier. Present only for shipped, returning or returned orders that have one. properties: id: type: integer description: Proof of delivery ID. example: 3101 recipient_name: type: - string - 'null' description: Name of the person who received the package. example: Ana Example recipient_relationship: type: - string - 'null' description: >- Relationship of the receiver to the buyer, as reported by the carrier. example: self format: type: - string - 'null' description: Format of the proof files (for example `image`, `pdf`, `base64`). example: image files: type: - array - 'null' description: Files attached to the proof, or null when there are none. items: type: object properties: path: type: string description: Relative download path. example: /rails/active_storage/blobs/redirect/example/pod.jpg filename: type: string description: File name. example: pod.jpg byte_size: type: integer description: Size in bytes. example: 120340 content_type: type: string description: MIME type. example: image/jpeg thumbnail_path: type: - string - 'null' description: Relative path of a 300x300 thumbnail; only for images. example: /rails/active_storage/representations/example/pod.jpg OrderEtaRange: type: object description: >- Latest estimated delivery window, as UTC timestamps of the start and end of the day in the warehouse's time zone. properties: range_begin: type: string format: date-time description: Start of the estimated delivery window. example: '2026-01-13T06:00:00.000Z' range_end: type: string format: date-time description: End of the estimated delivery window. example: '2026-01-14T05:59:59.000Z' OrderShippingMethod: type: object description: >- Shipping method (carrier + service) assigned to the order. `GET /orders` returns only `id`, `carrier_name`, `shipping_name` and `is_cod`. properties: id: type: integer description: Shipping method ID. example: 42 shipping_name: type: string description: Name of the shipping service. example: DHL Express carrier_name: type: string description: Carrier name as presented to your customers. example: DHL capitalized_carrier: type: - string - 'null' description: Carrier name with the first letter capitalized. example: Dhl is_active: type: boolean description: Whether the method is currently available. example: true shipping_type: type: - string - 'null' description: Coverage of the method. enum: - national - international - pickup - null example: national delivery_type: type: - string - 'null' description: Service level. enum: - SameDay - NextDay - Ground - Pickup - International - null example: Ground country: type: string description: Two-letter country code the method operates in. example: MX is_cod: type: boolean description: Whether the method supports cash on delivery. example: false extended_zone: type: boolean description: Whether the carrier delivers to extended zones. example: true po_box_dropoff: type: boolean description: Whether the carrier delivers to PO boxes. example: true provides_pod: type: boolean description: Whether the carrier provides proof of delivery. example: false contract_provider: type: - string - 'null' description: Carrier contract used. example: null enable_multipackage: type: boolean description: Whether multi-package shipments are enabled. example: false non_working_days: type: array items: type: integer description: Weekdays the carrier does not operate (0 = Sunday). example: - 0 - 6 dispatch_carrier_alias: type: - string - 'null' description: Alias used at dispatch. example: null handles_fragile: type: boolean description: Whether the carrier handles fragile goods. example: false multipackage_label_mode: type: string description: How multi-package labels are produced. enum: - per_package - bulk example: bulk generates_label_per_package: type: boolean description: Whether one label is generated per package. example: false carrier_supports_per_box_label: type: boolean description: >- Whether the carrier mints one label per box at packing. Not in use yet. example: false OrderLine: type: object description: A line of an order (one SKU and its quantity). properties: id: type: integer description: Order line ID. example: 5551 name: type: - string - 'null' description: Product name at the time of the order. example: Red T-shirt M sku: type: - string - 'null' description: SKU ordered. example: SKU-RED-M quantity: type: integer description: Units ordered. example: 2 generated: type: boolean description: >- True when Cubbo generated the line automatically (for example a kit component or a promotional insert). example: false price_per_item: type: - string - 'null' description: Unit price as a decimal string. example: '449.5' discount_per_item: type: - string - 'null' description: Unit discount as a decimal string. example: '0.0' product: oneOf: - $ref: '#/components/schemas/OrderLineProduct' - type: 'null' description: >- The product behind the line, when included by the endpoint. `null` while the line's SKU does not exist in the store (an order created with an unknown SKU; see `POST /orders`). stock_units: type: array description: Physical units assigned to the line, when included by the endpoint. items: $ref: '#/components/schemas/OrderStockUnit' OrderInvoice: type: object description: >- An NF-e (Brazilian electronic invoice) attached to an order. Fiscal events (cancellations, corrections) are not listed; only the documents themselves. properties: id: type: integer description: Invoice ID. example: 7801 invoice_type: type: - string - 'null' description: >- Where the invoice was issued. `WEBMANIA` and `BLING` are issued through Cubbo's fiscal integration; `IOTA` and `EXTERNAL` were issued by the client's own system; `WEBMANIA_CTE` / `WEBMANIA_NFSE` are transport and service documents. enum: - WEBMANIA - SELIA_BR - WEBMANIA_CTE - WEBMANIA_NFSE - NATURA - BLING - IOTA - EXTERNAL - null example: WEBMANIA status: type: - string - 'null' description: >- Fiscal status. `PREAPPROVED` means registered and awaiting confirmation from the fiscal provider. enum: - APPROVED - REJECTED - CANCELLED - DENIED - PROCESSING - CONTINGENCY - PREAPPROVED - null example: APPROVED invoiceable_id: type: integer description: ID of the order the invoice belongs to. example: 987654 invoiceable_type: type: string description: Type of the document the invoice belongs to; `Order` here. example: Order operation_nature: type: - string - 'null' description: Nature of the operation (natureza da operacao). example: Venda de mercadoria operation_type: type: - string - 'null' description: >- Direction of the operation, as sent when the invoice was attached: `SAIDA`/`ENTRADA` or `OUTGOING`/`INCOMING`. example: OUTGOING key: type: - string - 'null' description: The 44-digit NF-e access key. example: '00000000000000000000000000000000000000000000' xml_file: oneOf: - $ref: '#/components/schemas/OrderInvoiceFile' - type: 'null' description: The authorized NF-e XML, or null if not yet available. pdf_file: oneOf: - $ref: '#/components/schemas/OrderInvoiceFile' - type: 'null' description: The DANFE (printable invoice) PDF, or null if not yet available. label_pdf_file: oneOf: - $ref: '#/components/schemas/OrderInvoiceFile' - type: 'null' description: >- The DANFE in label format (DANFE etiqueta) PDF, or null if not available. OrderStore: type: object description: Store the order belongs to. properties: id: type: integer description: Store ID. example: 1234 name: type: string description: Store name. example: Example Store OrderChannelIntegration: type: object description: >- The sales-channel integration the order came from. `GET /orders` returns `id` and `channel_type_name`. properties: id: type: integer description: Integration ID. example: 55 channel_type_name: type: string description: >- Sales channel type (for example `shopify`, `vtex`, `woocommerce`, `meli`, `openapi`). example: shopify OrderReturnSummary: type: object description: > Summary of a return embedded in an order (`return` / `created_by_return`). Only the fields below are guaranteed; `GET /orders` may additionally embed the return's `returned_stock_units` (received units, each with its `unit_code`) and, on `return`, the exchange order it created (`created_order`). Fetch the full return with the Returns endpoints. additionalProperties: true properties: id: type: integer description: Return ID. example: 501 status: type: string description: Return status. example: pending return_type: type: string description: Kind of return (for example a simple return or an exchange). example: SIMPLE_RETURN notes: type: - string - 'null' description: Notes attached to the return. example: null created_at: type: string format: date-time description: When the return was created. example: '2026-01-20T10:00:00.000Z' expected_products: type: - array - 'null' description: Products expected back, as product ID and quantity. items: type: object properties: product_id: type: integer description: Product ID. example: 777 quantity: type: integer description: Units expected. example: 1 OrderHistoryEvent: type: object description: >- An event in the order timeline (status change, tracking update, incident). `GET /orders` with `include_event_history=true` returns only `new_status`, `incident_description`, `timestamp` and `origin`. properties: id: type: integer description: Event ID. example: 120001 order_id: type: integer description: Order ID. example: 987654 created_by_id: type: - integer - 'null' description: ID of the user who triggered the event, if any. example: null previous_status: type: - string - 'null' description: Status before the event. example: packing new_status: type: - string - 'null' description: Status after the event (an order status or a shipping status). example: shipped action: type: - string - 'null' description: >- Kind of event (for example `order_status_update`, `tracking_update`, `cancel`). example: order_status_update metadata: type: - object - 'null' description: Additional event data. example: {} origin: type: - string - 'null' description: Who or what produced the event. enum: - cubbo - integration_webhook - shipping_webhook - tracking_watcher - cubbo_user - cubbo_user_import - cubbo_user_api - cubbo_business_rule - awaiting_client_invoice - homolog_invoice_precheck - cubbo_automation - tracking_app - system_auto_coverage_retry - zapier - integration_api - null example: shipping_webhook reference_timestamp: type: - string - 'null' format: date-time description: >- When the event actually happened (for tracking events, the carrier's timestamp). example: '2026-01-11T18:30:00.000Z' timestamp: type: - string - 'null' format: date-time description: Same as `reference_timestamp`. example: '2026-01-11T18:30:00.000Z' incident_description: type: - string - 'null' description: >- Carrier description of the incident; only when `new_status` is `shipment_with_incident`. example: null difal_error_description: type: - string - 'null' description: >- Error message(s) from the DIFAL guide issuer; only for DIFAL error events (Brazil). example: null created_by_cubbo_user: type: boolean description: >- True when the event was triggered by Cubbo staff rather than a user of your account. example: false created_at: type: string format: date-time description: When the event was recorded. example: '2026-01-11T18:31:00.000Z' updated_at: type: string format: date-time description: Last update of the event record. example: '2026-01-11T18:31:00.000Z' OrderLineProduct: type: object description: >- Product of an order line. `GET /orders` and `GET /orders/awaiting-invoice` return the subset shown here. properties: id: type: integer description: Product ID. example: 777 name: type: string description: Product name. example: Red T-shirt M billing_name: type: - string - 'null' description: Name used on invoices. example: T-shirt description: type: - string - 'null' description: Product description (HTML). example: null has_imei: type: boolean description: Whether units of this product carry an IMEI. example: false is_fragile: type: boolean description: Whether the product needs fragile handling. example: false is_kit: type: boolean description: Whether the product is a kit of other products. example: false bar_code: type: - string - 'null' description: Barcode (UPC/EAN). example: '7500000000001' is_dropshipping: type: boolean description: Whether the product is fulfilled by a third party. example: false is_scannable: type: boolean description: Whether units are scanned during picking. example: true price: type: - string - 'null' description: Product price as a decimal string. example: '449.5' weight: type: - number - 'null' description: Product weight. example: 0.3 product_codes: type: array description: SKUs registered for the product. items: type: object properties: id: type: integer description: Product code ID. example: 9001 sku: type: string description: SKU. example: SKU-RED-M OrderStockUnit: type: object description: >- A physical unit assigned to an order line. In `GET /orders` only `id`, `imei` (when the product tracks IMEI) and `unit_code` (when requested by order number, for unit-code products in `packing`/`shipped`) are returned. properties: id: type: integer description: Stock unit ID. example: 31001 status: type: string description: Stock unit status. example: PICKED product_id: type: integer description: Product ID of the unit. example: 777 picked_at: type: - string - 'null' format: date-time description: When the unit was picked. example: '2026-01-11T15:00:00.000Z' created_at: type: string format: date-time description: Creation time. example: '2025-12-01T10:00:00.000Z' updated_at: type: string format: date-time description: Last update time. example: '2026-01-11T15:00:00.000Z' imei: type: object description: IMEI of the unit, only for products that track IMEI. properties: id: type: integer description: IMEI record ID. example: 12 imei: type: string description: The IMEI number. example: '000000000000000' unit_code: type: string description: >- Serial / unit code of the unit, only for products that require unit codes and only when the request filters by `order_number`. example: UC-0001 OrderInvoiceFile: type: object description: A downloadable invoice file. properties: path: type: string description: Relative download path. example: /rails/active_storage/blobs/redirect/example/nfe.xml filename: type: string description: File name. example: nfe.xml byte_size: type: integer description: Size in bytes. example: 10240 content_type: type: string description: MIME type. example: application/xml url: type: string description: Absolute download URL. example: >- https://api.cubbo.com/rails/active_storage/blobs/redirect/example/nfe.xml responses: Unauthorized: description: >- Missing or invalid token, wrong credentials, or no access to the requested store. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalidToken: value: error: Unauthorized message: invalid token noHeader: value: error: Unauthorized message: no authorization header found storeNotAllowed: value: error: Unauthorized message: not allowed to show? this Store securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Token returned by `POST /auth/token`, sent as `Authorization: Bearer `. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.