> ## 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. # 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. ## OpenAPI ````yaml /openapi.yaml post /orders 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: post: tags: - Orders summary: Create an order description: > 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. operationId: createOrder requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OrderCreateRequest' examples: basic: summary: Minimal sale with a Cubbo shipping method value: store_id: 1234 order_number: ORD-0001 shipping_method_id: 12 shipping: first_name: Jaime last_name: Carrera phone: '5555555555' email: buyer@example.com address1: Av. Reforma 123 address2: Piso 4 references: Blue door country: MX city: Ciudad de México province: CDMX zip_code: '06600' products: - sku: SKU-RED-M quantity: 2 shippingLineCode: summary: Carrier picked from your integration's shipping configuration value: store_id: 1234 order_number: ORD-0002 shipping_line_code: Express is_paid: true channel_name: my-webstore channel_order_id: WEB-98765 shipping: first_name: Ana last_name: Pérez phone: '5512345678' email: buyer@example.com address1: Calle Falsa 123 country: MX city: Guadalajara province: Jalisco zip_code: '44100' billing: first_name: Ana last_name: Pérez phone: '5512345678' email: buyer@example.com address1: Calle Falsa 123 country: MX city: Guadalajara province: Jalisco zip_code: '44100' products: - sku: SKU-RED-M quantity: 1 - sku: SKU-BLUE-L quantity: 3 chileCashOnDelivery: summary: >- Chile order with partial cash-on-delivery and carrier insurance value: store_id: 1234 order_number: ORD-0003 shipping_method_id: 45 is_cod: true cod_amount: 30000 has_carrier_insurance: true shipping: first_name: Jaime last_name: Carrera phone: '56900000000' email: buyer@example.com address1: Av Test 123 country: CL city: Santiago province: Región Metropolitana zip_code: '8320000' products: - sku: SKU-RED-M quantity: 1 colombiaCityCode: summary: Colombia, with the DANE code of the city value: store_id: 1234 order_number: ORD-0004 shipping_method_id: 56 shipping: first_name: Ana last_name: Gómez phone: '5555555555' email: buyer@example.com address1: 'Calle 100 # 10-20' country: CO city: Bogotá province: Bogotá, D.C. city_code: '11001' products: - sku: SKU-RED-M quantity: 1 clickAndCollect: summary: Click and collect at a carrier pickup point value: store_id: 1234 order_number: ORD-0004 shipping_method_id: 12 is_click_and_collect: true click_and_collect_service_code: CUBBOCNCEST001 shipping: first_name: Jaime last_name: Carrera phone: '5555555555' email: buyer@example.com address1: Av. Reforma 123 country: MX city: Ciudad de México province: CDMX zip_code: '06600' products: - sku: SKU-RED-M quantity: 1 responses: '200': description: >- Order created. The body is the full order as Cubbo stores it, including its lines and the resolved shipping method. The order is still in its initial status; processing happens asynchronously. When the order was created with SKUs that are not in the store's catalog (only possible with `channel_name`), or with a Colombian `shipping.city_code` Cubbo does not know, the body also carries `warnings`. content: application/json: schema: $ref: '#/components/schemas/OrderCreated' example: id: 987654 store_id: 1234 order_number: ORD-0001 status: initial channel_created_at: '2026-10-12T15:04:05.000Z' order_date: '2026-10-12T15:04:05.000Z' shipping_date: null pending_at: null shipping_email: buyer@example.com shipping_status: null is_paid: true is_cod: false cod_amount: null requires_document_return: false requires_pickup_on_delivery: false has_carrier_insurance: false has_missing_info: false missing_info: null shipping_address_1: Av. Reforma 123 currency: MXN total_price: '598.0' discount_price: '0.0' buyer_shipping_price: null extra_fees_price: null is_pick_and_ship: false is_b2b: false pick_n_ship_status: null return_shipping_labels: [] shipping: first_name: Jaime last_name: Carrera company: null phone: '5555555555' address_1: Av. Reforma 123 address_2: Piso 4 email: buyer@example.com zip_code: '06600' country: MX state: CDMX city: Ciudad de México number: null interior_number: null neighborhood: null references: Blue door city_code: null billing: first_name: null last_name: null company: null phone: null tax_id: null tax_regime: null state_registration: null address_1: null address_2: null number: null interior_number: null neighborhood: null email: null zip_code: null country: null state: null city: null delivery_tracking: - shipping_number: null tracking_url: null cubbo_tracking_url: https://tracking.cubbo.com/t/abc123 service_id: null shipping_status: null package_index: 1 total_packages: 1 proof_of_delivery: null estimated_time_arrival: null delivered_at: null updated_at: '2026-10-12T15:04:05.000Z' is_click_and_collect: false click_and_collect_metadata: null latest_estimated_time_arrival_range: null channel_order_id: null channel_name: openapi channel_shipping_line_code: null warehouse_timezone: America/Mexico_City is_multi_package: false is_first_time_buyer: true is_subscription_renewal: false shipping_method: id: 12 shipping_name: Estafeta Terrestre is_active: true carrier_name: ESTAFETA shipping_type: national delivery_type: Ground country: MX order_lines: - id: 55501 name: Red T-shirt M sku: SKU-RED-M quantity: 2 generated: false price_per_item: '299.0' discount_per_item: '0.0' '401': $ref: '#/components/responses/Unauthorized' '409': $ref: '#/components/responses/DuplicateRequestInFlight' '422': description: >- Validation or business error. `code` identifies the failure when one is defined; `context` carries extra data for some codes (for example the existing `order_id` on `ORDER_ALREADY_EXISTS`). content: application/json: schema: $ref: '#/components/schemas/OrderCreateError' examples: missingParam: summary: A required parameter is missing (any `param!` failure) value: error: Parameter store_id is required code: null context: null invalidParamType: summary: A parameter has the wrong type value: error: '''abc'' is not a valid Integer' code: null context: null codAmountNegative: summary: cod_amount below its minimum value: error: Parameter cod_amount cannot be less than 0 code: null context: null brazilStore: summary: The store ships from Brazil value: error: store is from Brazil, use /brazil/orders endpoint code: '' context: null missingZipCode: value: error: zip_code is required for this warehouse's country code: MISSING_ZIP_CODE context: null carrierInsuranceNotAvailable: value: error: has_carrier_insurance is only available for stores in CL code: CARRIER_INSURANCE_NOT_AVAILABLE context: null codAmountNotAvailable: value: error: >- cod_amount is only available for stores in CL. Cash on delivery elsewhere collects the order total. code: COD_AMOUNT_NOT_AVAILABLE context: null documentReturnNotAvailable: value: error: >- requires_document_return is only available for stores in CL. code: DOCUMENT_RETURN_NOT_AVAILABLE context: null pickupOnDeliveryNotAvailable: value: error: >- requires_pickup_on_delivery is only available for stores in CL. code: PICKUP_ON_DELIVERY_NOT_AVAILABLE context: null pickupOnDeliveryB2b: summary: >- The order resolves to B2B (explicit is_b2b or a B2B-only store) value: error: requires_pickup_on_delivery is a D2C-only service. code: PICKUP_ON_DELIVERY_B2B_UNSUPPORTED context: null pickupOnDeliveryReturnMethodNotConfigured: value: error: >- The dedicated Blue Express return method is not configured. code: PICKUP_ON_DELIVERY_RETURN_METHOD_NOT_CONFIGURED context: null documentReturnAndPickupExclusive: value: error: >- requires_document_return and requires_pickup_on_delivery cannot be combined on the same order. code: DOCUMENT_RETURN_PICKUP_ON_DELIVERY_EXCLUSIVE context: null channelIntegrationNotFound: summary: >- Your API credentials are not linked to an API integration on this store value: error: >- Channel integration for openapi not found, contact support. code: '' context: null orderAlreadyExists: value: error: >- order with order_number ORD-0001 already exists with id 987654 code: ORDER_ALREADY_EXISTS context: order_id: 987654 shippingMethodMissing: summary: Neither shipping_method_id nor shipping_line_code was sent value: error: >- Information is missing, shipping_method_id or shipping_line_code code: '400' context: null skusMissing: value: error: Provide skus for all products code: '' context: null noSkus: value: error: No skus provided code: '' context: null skuNotFound: summary: >- A SKU is not in the store's catalog and the request has no channel_name value: error: skus SKU-UNKNOWN not found in Cubbo code: '' context: null unitCodeRequired: summary: >- The product tracks personalized units, so each line needs a unit_code value: error: >- unit_code is required for sku SKU-RED-M: each unit belongs to one recipient code: UNIT_CODE_REQUIRED context: null personalizedUnitInKit: value: error: >- sku KIT-01 is a kit holding a personalized unit, which cannot be ordered as a kit code: PERSONALIZED_UNIT_IN_KIT context: null invalidUnitCodeLine: value: error: >- unit_code needs a sale line of quantity 1 of a product that requires unit codes (sku SKU-RED-M) code: INVALID_UNIT_CODE_LINE context: null duplicateUnitCode: value: error: unit_code UC-0001 is requested twice code: DUPLICATE_UNIT_CODE context: null discountsExceedValue: summary: >- The discounts are larger than what the products are worth, so the total would be negative value: error: discounts exceed the value of the products code: INVALID_PRODUCT_DISCOUNT context: null cncServiceCodeInvalid: value: error: click_and_collect_service_code is invalid code: '404' context: null cncLocationNotConfirmed: value: error: >- Couldn't confirm cnc location for CUBBOCNCEST001, try requesting a new cnc service code code: '404' context: null cncNoShippingMethod: value: error: >- No shipping method found for click and collect with service code CUBBOCNCEST001, contact support code: '404' context: null shippingLineCodeNotFound: value: error: >- No shipping configuration found with name 'Express' for this integration code: '404' context: null shippingMethodNoCoverage: value: error: >- The shipping method ESTAFETA does not have coverage in this zip code, 06600 code: '404' context: null internationalMethodOnDomesticOrder: value: error: >- The shipping method DHL is international and this order ships within MX. Assign a national shipping method. code: NATIONAL_SHIPPING_METHOD_EXPECTED context: null storeBusinessModelUnset: summary: >- The store is enabled for neither B2B nor D2C; contact support value: error: Store 1234 has neither b2b nor d2c enabled code: store_business_model_unset context: store_id: 1234 b2b: false d2c: false shippingDocumentUrlUnreachable: value: error: >- Information is missing, unable to obtain pdf document from url: https://example.com/label.pdf. response: 404 Not Found code: '400' context: null shippingDocumentTypeInvalid: value: error: >- Information is missing, The document type file is not valid. code: '400' context: null '500': description: >- Unexpected error. Nothing was created; retry later or contact support. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: unexpected error security: - bearerAuth: [] components: schemas: OrderCreateRequest: type: object required: - store_id - order_number - shipping - products properties: store_id: type: integer description: >- Id of the store the order belongs to. Your API credentials must have access to it. example: 1234 order_number: type: string description: Your identifier for the order. Must be unique within the store. example: ORD-0001 shipping_method_id: type: integer description: >- Id of a Cubbo shipping method. Get it from `GET /shipping-methods/quote`: each option in the response has a `shipping_method_id`. Required unless `shipping_line_code` is sent. Coverage for the destination is checked synchronously: by zip code in Mexico, by `shipping.city` in Chile. In Chile a `shipping.city` that cannot be identified does not refuse the order; it is created in `error` until it is corrected. example: 12 shipping_line_code: type: string description: >- 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](/guides/setup#3-configure-shipping-methods). Required unless `shipping_method_id` is sent; ignored when `shipping_method_id` is present. If no active method has that name, Cubbo falls back to the integration's default shipping method when one exists. If the method exists but no carrier can be resolved (no coverage, unknown weight or tariff), the order is still created and lands in an error status for Cubbo to resolve. example: Express is_paid: type: boolean description: Whether the order is already paid. Defaults to `true` when omitted. default: true example: true is_click_and_collect: type: boolean description: >- Set to `true` to deliver to a carrier pickup point. Requires `click_and_collect_service_code`. default: false example: false click_and_collect_service_code: type: - string - 'null' description: >- Pickup point code returned by `GET /carrier-services/pickup-locations`, in the form `CUBBOCNC` + carrier code (`EST`, `CUBBO`, `DHL`, `PUNTOPOST`, `99`) + location id. Ignored (cleared) unless `is_click_and_collect` is `true`. example: CUBBOCNCEST001 channel_name: type: string description: >- Name of the sales channel the order came from, echoed back as `channel_name` on the order. Sending it also lets the order be created when a SKU is missing from the catalog (see the endpoint description). example: my-webstore channel_order_id: type: string description: >- Identifier of the order in your sales channel, echoed back as `channel_order_id`. example: WEB-98765 is_b2b: type: boolean description: >- Business-model classification. Only read for stores enabled for both B2B and D2C: omit it (or send `false`) for a consumer order, send `true` for a B2B order. Stores enabled for a single model always get that model regardless of this value. example: false has_carrier_insurance: type: boolean description: >- Ask the carrier to insure the shipment. Available only for stores with a warehouse in Chile; `true` elsewhere is refused with `CARRIER_INSURANCE_NOT_AVAILABLE`. default: false example: false is_cod: type: boolean description: Cash on delivery; the courier collects payment at the door. default: false example: false cod_amount: type: number minimum: 0 description: >- Amount the courier must collect when it differs from the order total (partial collection). Omit, or send `0`, to collect the order total. A non-zero amount is available only for stores with a warehouse in Chile; elsewhere it is refused with `COD_AMOUNT_NOT_AVAILABLE`. example: 30000 requires_document_return: type: boolean description: >- Ask the carrier to bring back a signed document with the delivery. Available only for stores with a warehouse in Chile; cannot be combined with `requires_pickup_on_delivery`. default: false example: false requires_pickup_on_delivery: type: boolean description: >- Include a prepaid return label inside the outbound package. Available only for consumer (D2C) orders of stores with a warehouse in Chile, and cannot be combined with `requires_document_return`. default: false example: false shipping: $ref: '#/components/schemas/OrderShippingAddress' billing: $ref: '#/components/schemas/OrderBillingAddress' products: type: array minItems: 1 description: Lines of the order. The same SKU may appear more than once. items: $ref: '#/components/schemas/OrderProductLine' shipping_documents: type: array description: >- Optional PDF documents to print and include with the shipment (for example a label or invoice you issued). Each document is fetched from a URL or decoded from base64 at creation time. items: $ref: '#/components/schemas/OrderShippingDocument' OrderCreated: description: The order as `POST /orders` returns it. allOf: - $ref: '#/components/schemas/Order' - type: object properties: warnings: type: array description: >- Present only when the order was created with something it still needs from you. `UNIDENTIFIED_PRODUCT` lists, in `context.skus`, the SKUs not found in the store's catalog; the order waits with missing information until those products exist. `UNRECOGNIZED_CITY_CODE` gives, in `context.city_code`, the Colombian `shipping.city_code` Cubbo does not know; the order waits in `error` until you correct it with `PUT /orders/{id}`. items: $ref: '#/components/schemas/OrderCreateWarning' OrderCreateError: type: object description: Error body of `POST /orders` and `POST /orders/create-and-ship`. required: - error properties: error: type: string description: Human-readable message. example: order with order_number ORD-0001 already exists with id 987654 code: type: - string - 'null' description: >- Machine-readable code. `null` for parameter errors, empty string for business errors without a dedicated code; shipping-method lookups use the legacy codes `"404"` and `"400"`. example: ORDER_ALREADY_EXISTS context: type: - object - 'null' description: >- Extra data for some codes, for example `{order_id}` on `ORDER_ALREADY_EXISTS`. additionalProperties: true example: order_id: 987654 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 OrderShippingAddress: type: object description: Recipient and delivery address. required: - first_name - phone - email - address1 - country - city - province properties: first_name: type: string description: Recipient first name. example: Jaime last_name: type: string description: Recipient last name. example: Carrera phone: type: string description: Recipient phone number, used by the carrier. example: '5555555555' email: type: string format: email description: Recipient email, used for tracking notifications. example: buyer@example.com address1: type: string description: Street and number. example: Av. Reforma 123 address2: type: string description: Additional address line (apartment, floor, building). example: Piso 4 references: type: string description: Delivery hints for the courier. example: Blue door, ring twice number: type: string description: Street number, when kept separate from `address1`. example: '123' interior_number: type: string description: Interior or apartment number. example: 4B country: type: string description: >- Country as an ISO 3166-1 alpha-2 code (a full country name is also recognised). example: MX city: type: string description: City. example: Ciudad de México province: type: string description: State or province. example: CDMX zip_code: type: string description: >- Postal code. Required when the warehouse is in Mexico (`MISSING_ZIP_CODE` otherwise); optional for Chile and Colombia. Used for carrier coverage. example: '06600' city_code: type: string description: >- Colombia only: the DANE (DIVIPOLA) code of the city, 5 digits (a municipality) or 8 (a populated center). When sent, it decides the destination instead of `city` and `province`; a code Cubbo does not know leaves the order in `error` (`UNRECOGNIZED_CITY_CODE`) instead of refusing it. In other countries it is stored and returned as sent, but it does not change the destination. example: '11001' OrderBillingAddress: type: object description: Optional billing contact and address. required: - first_name - last_name - phone - email - address1 - country - city - province properties: first_name: type: string description: Billing first name. example: Jaime last_name: type: string description: Billing last name. example: Carrera phone: type: string description: Billing phone number. example: '5555555555' email: type: string format: email description: Billing email. example: buyer@example.com address1: type: string description: Street and number. example: Av. Reforma 123 address2: type: string description: Additional address line. example: Piso 4 address3: type: string description: Accepted for compatibility; not stored. example: '' interior_number: type: string description: Interior or apartment number. example: 4B country: type: string description: Country as an ISO 3166-1 alpha-2 code. example: MX city: type: string description: City. example: Ciudad de México province: type: string description: State or province. example: CDMX zip_code: type: string description: Postal code. example: '06600' OrderProductLine: type: object required: - sku - quantity properties: sku: type: string description: SKU of a product registered in the store. example: SKU-RED-M quantity: type: integer description: >- Units of this SKU. Lines of drop-shipping products are stored with quantity 0. example: 2 unit_code: type: string description: >- Pins the line to the one stock unit carrying this code. Only valid on a line with `quantity` 1 of a non-kit product that tracks unit codes; mandatory for products that hold personalized units. On a line whose SKU does not exist yet (only with `channel_name`), the quantity and a repeated code are checked on creation, and the rest once the product exists. example: UC-0001 OrderShippingDocument: type: object required: - document_type - data - printing_type properties: document_type: type: string enum: - url - base64 description: How `data` must be read. `file` is not accepted on creation. example: url data: type: string description: Public URL of the PDF, or the base64-encoded PDF content. example: https://example.com/documents/label.pdf printing_type: type: string enum: - label - document - difal_bill - difal_payment_receipt - identifier_label - oxxo_digital_card description: What the document is, which decides when the warehouse prints it. example: label metadata: type: object description: Free-form data stored with the document. additionalProperties: true example: tracking_number: TRACK123 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' OrderCreateWarning: type: object required: - code - message - context properties: code: type: string enum: - UNIDENTIFIED_PRODUCT - UNRECOGNIZED_CITY_CODE example: UNIDENTIFIED_PRODUCT message: type: string example: >- skus SKU-UNKNOWN not found in Cubbo: the order was created with missing information until the products exist context: type: object properties: skus: type: array items: type: string example: - SKU-UNKNOWN city_code: type: string example: '99999' DuplicateRequestInFlightError: type: object required: - error - code properties: error: type: string description: Human-readable message naming the contended order number. example: >- another request for order ORD-0001 is already being processed, retry in 5 seconds code: type: string enum: - DUPLICATE_REQUEST_IN_FLIGHT description: Fixed code for this condition. example: DUPLICATE_REQUEST_IN_FLIGHT transaction_id: type: - string - 'null' description: >- Identifier of the request currently holding the lock; useful when contacting support. example: c0ffee00-0000-4000-8000-000000000001 transaction_key: type: - string - 'null' description: The lock key that was contended. example: api_create_orders:1234:ORD-0001 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 DuplicateRequestInFlight: description: >- Another request for the same order number is still being processed (or a previous one was interrupted; the lock expires on its own within a few minutes). Nothing was created by this request. Wait for the number of seconds in the `Retry-After` header and retry with the same payload; the retry converges on the real outcome. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer example: 5 content: application/json: schema: $ref: '#/components/schemas/DuplicateRequestInFlightError' example: error: >- another request for order ORD-0001 is already being processed, retry in 5 seconds code: DUPLICATE_REQUEST_IN_FLIGHT transaction_id: c0ffee00-0000-4000-8000-000000000001 transaction_key: api_create_orders:1234:ORD-0001 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.