curl --request PUT \
  --url https://api.cubbo.com/v1/orders/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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
    }
  ]
}
'

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

Orders

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.

PUT

orders

{id}

curl --request PUT \
  --url https://api.cubbo.com/v1/orders/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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
    }
  ]
}
'

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

Authorizations

Authorization

string

header

required

Token returned by POST /auth/token, sent as Authorization: Bearer <token>.

Path Parameters

integer

required

Cubbo order id.

Body

application/json

Full update of an order. Only the keys present are applied; see the endpoint description for replacement semantics.

store_id

integer

required

Id of the store the order belongs to. Must match the order's store.

Example:

1234

is_paid

boolean | null

Marks the order as paid or unpaid. Omit or send null to leave it unchanged.

Example:

true

shipping_method_id

integer | null

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

boolean | null

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

object

Shipping recipient and address. Sending this object replaces the whole shipping address; omitted fields are cleared.

Show child attributes

billing

object

Billing contact and address. Sending this object replaces the whole billing block; omitted fields are cleared.

Show child attributes

products

object[]

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.

Show child attributes

shipping_documents

object[]

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.

Show child attributes

Response

The updated order (with its order lines) as saved, before re-processing.

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.

integer

Cubbo ID of the order. Use it in path parameters.

Example:

987654

store_id

integer

Store ID.

Example:

1234

order_number

string

Your order number, unique within the store.

Example:

"ORD-0001"

status

enum<string>

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.

Available options:

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"

channel_created_at

string<date-time>

When the order was created in the sales channel.

Example:

"2026-01-10T14:02:11.000Z"

order_date

string<date-time> | null

Order date.

Example:

"2026-01-10T14:02:11.000Z"

shipping_date

string<date-time> | null

When the order was shipped.

Example:

"2026-01-11T18:30:00.000Z"

pending_at

string<date-time> | null

When the order became ready to be fulfilled.

Example:

"2026-01-10T14:05:00.000Z"

shipping_email

string | null

Buyer email.

Example:

"buyer@example.com"

shipping_address_1

string | null

Shipping street address line 1 (also inside shipping).

Example:

"Av. Ejemplo 123"

shipping_status

enum<string> | null

Carrier-side status of the shipment.

Available options:

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"

is_paid

boolean

Whether the order is paid. Unpaid orders are not fulfilled.

Example:

true

is_cod

boolean

Whether the order is cash on delivery.

Example:

false

cod_amount

string | null

Amount to collect on delivery, as a decimal string.

Example:

null

requires_document_return

boolean

Whether the carrier must bring back a signed document.

Example:

false

requires_pickup_on_delivery

boolean

Whether the carrier must pick something up when delivering.

Example:

false

has_carrier_insurance

boolean

Whether the shipment is insured with the carrier.

Example:

false

has_missing_info

boolean

Whether the order is blocked because data is missing.

Example:

false

missing_info

string | null

Description of the missing data, if any.

Example:

null

currency

string | null

Currency code of the prices.

Example:

"MXN"

total_price

string | null

Order total as a decimal string.

Example:

"899.00"

discount_price

string | null

Total discount as a decimal string.

Example:

"0.00"

buyer_shipping_price

string | null

Shipping price paid by the buyer, as a decimal string.

Example:

"0.00"

extra_fees_price

string | null

Extra fees as a decimal string.

Example:

"0.0"

is_pick_and_ship

boolean

Whether the order is a pick-and-ship order (you pick it up at the warehouse).

Example:

false

pick_n_ship_status

enum<string> | null

Pick-and-ship status.

Available options:

awaiting_pick_up,

picked_up,

in_warehouse,

null

Example:

null

is_b2b

boolean

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

boolean

Whether this is the buyer's first order in the store.

Example:

true

is_subscription_renewal

boolean

Whether the order is a subscription renewal.

Example:

false

is_click_and_collect

boolean

Whether the buyer picks the order up at a pickup point.

Example:

false

click_and_collect_metadata

object | null

Pickup-point details for click-and-collect orders; null otherwise.

Show child attributes

is_multi_package

boolean

Whether the shipment has more than one package.

Example:

false

shipping

object

Shipping contact and address of an order.

Show child attributes

billing

object

Billing contact, fiscal data and address of an order. Fiscal fields are returned in clear text to the store that owns the order.

Show child attributes

delivery_tracking

object[]

Tracking per package. Return labels are excluded.

Show child attributes

return_shipping_labels

object[] | null

Valid return labels of the order.

Show child attributes

proof_of_delivery

object | null

Proof of delivery, when the carrier provided one for a shipped or returned order.

Show child attributes

estimated_time_arrival

string<date-time> | null

Estimated delivery date.

Example:

"2026-01-13T00:00:00.000Z"

latest_estimated_time_arrival_range

object | null

Latest estimated delivery window, or null when no estimate exists.

Show child attributes

delivered_at

string<date-time> | null

When the carrier delivered the order.

Example:

null

updated_at

string<date-time>

Last update of the order.

Example:

"2026-01-11T18:31:00.000Z"

channel_order_id

string | null

ID of the order in the sales channel.

Example:

"5566778899"

channel_name

string | null

Name of the sales channel the order came from.

Example:

"shopify"

channel_shipping_line_code

string | null

Code of the shipping option chosen at checkout in the sales channel (first shipping line).

Example:

"standard"

warehouse_timezone

string | null

IANA time zone of the warehouse fulfilling the order.

Example:

"America/Mexico_City"

shipping_method

object | null

Shipping method assigned to the order.

Show child attributes

order_lines

object[]

Lines of the order.

Show child attributes

invoices

object[]

NF-e documents attached to the order (Brazil).

Show child attributes

store

object | null

Store the order belongs to.

Show child attributes

channel_integration

object | null

Sales-channel integration the order came from.

Show child attributes

return

object | null

The return opened for this order, if any. Use GET /returns/{return_id} for the full return.

Show child attributes

created_by_return

object | null

The return that created this order (for exchanges), if any.

Show child attributes

order_histories

object[]

Order timeline. Only returned by GET /orders with include_event_history=true.

Show child attributes

Authentication

Orders

Click and collect

Inventory

Lots

Shipping labels

Replenishments

Reports

Returns

Shipping methods

Stores

Webhooks

Update an order

Authorizations

Path Parameters

Body

Response