Create an order

Creates a sales order for a store whose warehouse is in Mexico, Colombia, Chile or the United States, and queues it for processing. Use it for every non-Brazil store; a store served from a Brazil warehouse is refused and must use POST /brazil/orders. The request needs a store, a unique order_number per store, a recipient address, at least one product line and a way to pick the carrier:

• shipping_line_code: the exact name of a shipping method you created in the Cubbo app (Integrations > Open API > Shipping Methods). Cubbo picks the carrier with the configuration assigned to it.

• shipping_method_id: a specific Cubbo shipping method, taken from the shipping_method_id of an option returned by GET /shipping-methods/quote.

• The order is returned immediately in its initial status. Address, coverage, stock and carrier validations run asynchronously; poll GET /orders and read status, has_missing_info and missing_info to learn whether it was accepted.

• Every product is identified by SKU. Without channel_name, an unknown SKU rejects the whole request with 422. With channel_name (an order relayed from a sales channel), the order is created anyway: a line whose SKU is unknown keeps that SKU without a product, and the response lists those SKUs in warnings with the code UNIDENTIFIED_PRODUCT. Processing then leaves the order with missing information (status error; with include_event_history=true, GET /orders shows the code UNIDENTIFIED_PRODUCT in the error event) until the product exists. Creating the product or adding the SKU to an existing product in the Cubbo app processes the order again and the line takes the product; creating it with POST /products without variants does not trigger that reprocess today.

• A line sent without price_per_item takes the product’s price. On a line whose SKU is unknown there is no product price yet, so the line counts as zero in the order total, and so does its discount; once the product exists, the line takes the product’s price and the order total is recomputed (a kit without its own price is worth its components). A product price smaller than the line’s discount is not taken. Discounts larger than what the products are worth are rejected with 422 INVALID_PRODUCT_DISCOUNT.

• A unit_code sent on a line whose SKU is unknown is kept. The line must still have quantity 1, and one SKU cannot name the same code twice: otherwise the request is rejected with 422, as for a known SKU. The rest is checked once the product exists: if the line can never be fulfilled (a kit, or a product that does not track unit codes and has no unit carrying that code), the order waits with missing information, code INVALID_UNIT_CODE_LINE; two lines whose SKUs turn out to be the same product and name the same code give DUPLICATE_UNIT_CODE on the later line. Correct the line by editing the order in the Cubbo app; PUT /orders/{id} does not replace the products of an order with a pinned line.

• zip_code is mandatory when the warehouse is in Mexico (and Brazil); it is optional for Chile and Colombia.

• Chile: when shipping.city cannot be identified (a misspelling, or a province instead of a city), an order sent with shipping_method_id is not refused. It is created and moves to error until you correct shipping.city with PUT /orders/{id} or in the Cubbo app, where the order shows the reason. An order that ships on your own label (Blue Express EX, with the label attached) continues normally. A shipping.city that is identified but not covered by the method is still refused with 422.

• Colombia: carriers deliver by the DANE (DIVIPOLA) code of the destination city. Cubbo finds it from shipping.city and shipping.province, or you send it in shipping.city_code: when present, the code decides the destination and the city and province are not looked up. A 5-digit code (a municipality) stands for its main town; an 8-digit code is a populated center; a code missing its leading zero (4 or 7 digits) is completed. An order whose shipping.city_code Cubbo does not know is not refused: the response lists it in warnings with the code UNRECOGNIZED_CITY_CODE, and the order moves to error with that code (the code you sent is in additional_info.city_code) until you correct it with PUT /orders/{id}. Without city_code, an order sent with shipping_method_id whose city and province cannot be identified is still refused with 422.

• Duplicate protection: an order_number that already exists in the store answers 422 with code ORDER_ALREADY_EXISTS and the existing order_id in context. While another request for the same store_id + order_number is still being processed you get 409 DUPLICATE_REQUEST_IN_FLIGHT with a Retry-After header; retry after that delay and you will converge on the real outcome (200, 422 or ORDER_ALREADY_EXISTS).

• Complementary carrier services (has_carrier_insurance, cod_amount, requires_document_return, requires_pickup_on_delivery) are currently honoured only for stores with a warehouse in Chile; sending true (or a non-zero amount) from any other country is refused with a typed error code rather than silently ignored.

• Click and collect: send is_click_and_collect: true and the click_and_collect_service_code you obtained from GET /carrier-services/pickup-locations. Cubbo replaces the shipping method you sent with the pickup carrier’s method. A full shipping address is still required.

• is_b2b only matters for stores enabled for both B2B and D2C (“mixed”); omit it to create a consumer (D2C) order. Stores enabled for a single model always get that model.

• Error bodies on this endpoint carry an error message plus a machine-readable code (empty string or null when the error has no code) and an optional context object.