Skip to main content
POST

Authorizations

Authorization
string
header
required

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

Body

application/json

Request body of POST /brazil/orders. shipping, billing, buyer_shipping_price and a shipping method are required for SALE/DONATION and ignored for removal types.

store_id
integer
required

Id of the Brazil store the order belongs to.

Example:

1234

order_number
string
required

Your identifier for the order. Must be unique within the store.

Example:

"ORD-BR-0001"

products
object[]
required

Lines of the order.

Minimum array length: 1
order_type
enum<string>
default:SALE

Kind of order. SALE and DONATION ship to your customer; the REMOVE_* types return stock to you. STOCK_TRANSFER_OUT passes the parameter check but is reserved for Cubbo's stock-transfer feature; do not use it.

Available options:
SALE,
DONATION,
REMOVE_STOCK,
REMOVE_DAMAGED_STOCK,
REMOVE_EXPIRED_STOCK,
REMOVE_LOST_STOCK,
STOCK_TRANSFER_OUT
Example:

"SALE"

shipping_method_id
integer

Id of a Cubbo shipping method. Get it from GET /shipping-methods/quote: each option in the response has a shipping_method_id. For SALE/DONATION one of shipping_method_id or shipping_line_code is required; ignored for removal types.

Example:

12

shipping_line_code
string

Exact name of a shipping method you created in the Cubbo app, under Integrations, your Open API integration, Shipping Methods (field Integration Delivery Method). It must match character by character: the comparison is case-sensitive and does not trim spaces. Cubbo uses the shipping configuration assigned to that method to pick the carrier. See Set up your integration. Alternative to shipping_method_id. Ignored for removal types.

Example:

"Express"

is_paid
boolean
default:true

Whether the order is already paid. Defaults to true when omitted.

Example:

true

is_b2b
boolean

Business-model classification, read only for stores enabled for both B2B and D2C; omit for a consumer order.

Example:

false

buyer_shipping_price
number

Shipping cost charged to the buyer, added to the order total and to the NF-e. Required for SALE/DONATION (send 0.0 when free); optional for removal types, where it defaults to 0.0 but is still added to the total when sent.

Example:

15.9

shipping
object

Recipient and delivery address (required for SALE/DONATION).

billing
object

Fiscal data of the buyer, used to issue the NF-e (required for SALE/DONATION).

shipping_documents
object[]

Optional PDF documents to print and include with the shipment.

client_invoice
object

Removal types only. Register an NF-e you issued yourself by its numbers. Requires manual NF-e entry to be enabled for your store by Cubbo support; otherwise the request is refused with 422. Send either this or invoice_xml, not both.

invoice_xml
string

Removal types only. Base64-encoded XML of the authorized NF-e you issued yourself. Accepted for any Brazil removal order.

Example:

"PG5mZT48L25mZT4="

Response

Order created. Same payload as POST /orders. A REMOVE_LOST_STOCK order is returned already in status shipped.

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.

id
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.

is_multi_package
boolean

Whether the shipment has more than one package.

Example:

false

shipping
object

Shipping contact and address of an order.

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.

delivery_tracking
object[]

Tracking per package. Return labels are excluded.

return_shipping_labels
object[] | null

Valid return labels of the order.

proof_of_delivery
object | null

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

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.

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.

order_lines
object[]

Lines of the order.

invoices
object[]

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

store
object | null

Store the order belongs to.

channel_integration
object | null

Sales-channel integration the order came from.

return
object | null

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

created_by_return
object | null

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

order_histories
object[]

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