> ## 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 for a Brazil store > Creates an order for a store served from a Brazil warehouse. Brazil orders carry the fiscal data Cubbo needs to issue the NF-e (Nota Fiscal Eletrônica, the Brazilian electronic invoice): per-line prices, the buyer's shipping cost and a billing block with the buyer's tax id (CPF for a natural person, CNPJ for a company). `order_type` selects what kind of order you get; it defaults to `SALE`. - `SALE` and `DONATION` share the full contract: recipient, billing, shipping method, `buyer_shipping_price` and a `price_per_item` on every line. A donation is only different fiscally (the NF-e is issued with a donation purpose). - The four removal types (`REMOVE_STOCK`, `REMOVE_DAMAGED_STOCK`, `REMOVE_EXPIRED_STOCK`, `REMOVE_LOST_STOCK`) return stock to you. Cubbo synthesizes the recipient from the warehouse, the billing data from your store's fiscal registration and the shipping method from the warehouse's pickup method, so `shipping`, `billing`, `shipping_method_id` and `shipping_line_code` are optional and ignored. `price_per_item` becomes optional (falls back to the product's registered price), `quantity` must be at least 1, and you may hand in your own NF-e with `invoice_xml` or `client_invoice`. - `REMOVE_LOST_STOCK` is applied synchronously and all-or-nothing: units already recorded as lost are written off and the order comes back already `shipped`. It is available only to stores that have opted out of Cubbo issuing their removal NF-es (ask Cubbo support). - `STOCK_TRANSFER_OUT` is accepted by the parameter check but is reserved for Cubbo's stock-transfer feature; do not send it. `C2C` is refused. - Sale orders are validated asynchronously (CEP, CPF/CNPJ length, NCM, totals); check `status`, `has_missing_info` and `missing_info` on `GET /orders`. - Duplicate protection: an existing `order_number` in the store answers 422; a request still in progress for the same `order_number` answers 409 `DUPLICATE_REQUEST_IN_FLIGHT`. - Error bodies on this endpoint are `{"error": ""}` with no code, except removal orders that fail field validation, which return `{"errors": [...]}`. ## OpenAPI ````yaml /openapi.yaml post /brazil/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: /brazil/orders: post: tags: - Orders summary: Create an order for a Brazil store description: > Creates an order for a store served from a Brazil warehouse. Brazil orders carry the fiscal data Cubbo needs to issue the NF-e (Nota Fiscal Eletrônica, the Brazilian electronic invoice): per-line prices, the buyer's shipping cost and a billing block with the buyer's tax id (CPF for a natural person, CNPJ for a company). `order_type` selects what kind of order you get; it defaults to `SALE`. - `SALE` and `DONATION` share the full contract: recipient, billing, shipping method, `buyer_shipping_price` and a `price_per_item` on every line. A donation is only different fiscally (the NF-e is issued with a donation purpose). - The four removal types (`REMOVE_STOCK`, `REMOVE_DAMAGED_STOCK`, `REMOVE_EXPIRED_STOCK`, `REMOVE_LOST_STOCK`) return stock to you. Cubbo synthesizes the recipient from the warehouse, the billing data from your store's fiscal registration and the shipping method from the warehouse's pickup method, so `shipping`, `billing`, `shipping_method_id` and `shipping_line_code` are optional and ignored. `price_per_item` becomes optional (falls back to the product's registered price), `quantity` must be at least 1, and you may hand in your own NF-e with `invoice_xml` or `client_invoice`. - `REMOVE_LOST_STOCK` is applied synchronously and all-or-nothing: units already recorded as lost are written off and the order comes back already `shipped`. It is available only to stores that have opted out of Cubbo issuing their removal NF-es (ask Cubbo support). - `STOCK_TRANSFER_OUT` is accepted by the parameter check but is reserved for Cubbo's stock-transfer feature; do not send it. `C2C` is refused. - Sale orders are validated asynchronously (CEP, CPF/CNPJ length, NCM, totals); check `status`, `has_missing_info` and `missing_info` on `GET /orders`. - Duplicate protection: an existing `order_number` in the store answers 422; a request still in progress for the same `order_number` answers 409 `DUPLICATE_REQUEST_IN_FLIGHT`. - Error bodies on this endpoint are `{"error": ""}` with no code, except removal orders that fail field validation, which return `{"errors": [...]}`. operationId: createBrazilOrder requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BrazilOrderCreateRequest' examples: sale: summary: Sale to a natural person (CPF) value: store_id: 1234 order_number: ORD-BR-0001 shipping_method_id: 12 buyer_shipping_price: 15.9 shipping: first_name: Ana last_name: Silva phone: '5511999999999' email: buyer@example.com address1: Av. Paulista number: '1234' interior_number: Apto 45 neighborhood: Bela Vista country: BR city: São Paulo province: SP zip_code: '01310100' billing: first_name: Ana last_name: Silva phone: '5511999999999' email: buyer@example.com address1: Av. Paulista number: '1234' neighborhood: Bela Vista country: BR city: São Paulo province: SP zip_code: '01310100' tax_id: 000.000.000-00 tax_regime: PHYSICAL products: - sku: SKU-RED-M quantity: 2 price_per_item: 59.9 discount_per_item: 5 legalPerson: summary: Sale to a company (CNPJ) value: store_id: 1234 order_number: ORD-BR-0002 shipping_line_code: Express buyer_shipping_price: 0 is_b2b: true shipping: first_name: Carlos last_name: Souza phone: '5511888888888' email: buyer@example.com address1: Rua das Flores number: '10' neighborhood: Centro country: BR city: Campinas province: SP zip_code: '13010000' billing: first_name: Carlos last_name: Souza phone: '5511888888888' email: buyer@example.com address1: Rua das Flores number: '10' neighborhood: Centro country: BR city: Campinas province: SP zip_code: '13010000' tax_id: 00.000.000/0000-00 tax_regime: LEGAL company: Example Comércio LTDA state_registration: '000000000' products: - sku: SKU-RED-M quantity: 10 price_per_item: 49.9 removal: summary: Stock removal with your own NF-e value: store_id: 1234 order_number: REM-0001 order_type: REMOVE_STOCK products: - sku: SKU-RED-M quantity: 10 - sku: SKU-BLUE-L quantity: 4 price_per_item: 12.5 client_invoice: key: '00000000000000000000000000000000000000000000' serie: '1' number: '987' responses: '200': description: >- Order created. Same payload as `POST /orders`. A `REMOVE_LOST_STOCK` order is returned already in status `shipped`. content: application/json: schema: $ref: '#/components/schemas/Order' example: id: 987656 store_id: 1234 order_number: ORD-BR-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. Paulista currency: BRL total_price: '125.7' discount_price: '10.0' buyer_shipping_price: '15.9' extra_fees_price: null is_pick_and_ship: false is_b2b: false pick_n_ship_status: null return_shipping_labels: [] shipping: first_name: Ana last_name: Silva company: null phone: '5511999999999' address_1: Av. Paulista address_2: null email: buyer@example.com zip_code: '01310100' country: BR state: SP city: São Paulo number: '1234' interior_number: Apto 45 neighborhood: Bela Vista references: null billing: first_name: Ana last_name: Silva company: null phone: '5511999999999' tax_id: 000.000.000-00 tax_regime: PHYSICAL state_registration: null address_1: Av. Paulista address_2: null number: '1234' interior_number: null neighborhood: Bela Vista email: buyer@example.com zip_code: '01310100' country: BR state: SP city: São Paulo delivery_tracking: - shipping_number: null tracking_url: null cubbo_tracking_url: https://tracking.cubbo.com/t/def456 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/Sao_Paulo is_multi_package: false is_first_time_buyer: true is_subscription_renewal: false shipping_method: id: 12 shipping_name: Correios PAC is_active: true carrier_name: CORREIOS shipping_type: national delivery_type: Ground country: BR order_lines: - id: 55502 name: Red T-shirt M sku: SKU-RED-M quantity: 2 generated: false price_per_item: '59.9' discount_per_item: '5.0' '401': $ref: '#/components/responses/Unauthorized' '409': $ref: '#/components/responses/DuplicateRequestInFlight' '422': description: >- Validation or business error. The body is `{"error": ""}` (no code). A removal order that fails Cubbo's order validation (for example a warehouse with no pickup shipping method) returns `{"errors": [{field, code, additional_info}]}` instead. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/OrderFieldValidationError' examples: missingParam: value: error: Parameter buyer_shipping_price is required invalidOrderType: value: error: >- Parameter order_type must be within ["SALE", "DONATION", "REMOVE_STOCK", "REMOVE_DAMAGED_STOCK", "REMOVE_EXPIRED_STOCK", "REMOVE_LOST_STOCK", "STOCK_TRANSFER_OUT"] invalidTaxRegime: value: error: Parameter tax_regime must be within ["PHYSICAL", "LEGAL"] legalPersonMissingCompany: value: error: billing[company] is required for legal person legalPersonMissingStateRegistration: value: error: billing[state_registration] is required for legal person removalQuantityTooLow: value: error: Parameter quantity cannot be less than 1 discountGreaterThanPrice: value: error: Product discount can't be greater than price discountWithoutPrice: value: error: discount_per_item requires price_per_item channelIntegrationNotFound: value: error: >- Channel integration for openapi not found, contact support. shippingMethodMissing: value: error: >- Information is missing, shipping_method_id or shipping_line_code orderAlreadyExists: value: error: >- Order with order_number 'ORD-BR-0001' already exist with id 987656 skuNotFound: value: error: skus SKU-UNKNOWN not found in Cubbo skusMissing: value: error: Provide skus for all products shippingLineCodeNotFound: value: error: >- No shipping configuration found with name 'Express' for this integration shippingMethodNoCoverage: value: error: >- The shipping method CORREIOS does not have coverage in this zip code, 01310100 internationalMethodOnDomesticOrder: value: error: >- The shipping method DHL is international and this order ships within BR. Assign a national shipping method. storeBusinessModelUnset: value: error: Store 1234 has neither b2b nor d2c enabled shippingDocumentUrlUnreachable: value: error: >- Information is missing, unable to obtain pdf document from url: https://example.com/label.pdf. response: 404 Not Found removalLineWithoutSku: value: error: each product must carry a sku or a product_id removalStoreWithoutWarehouse: value: error: store 1234 has no warehouse to remove stock from removalLostStockNotAllowed: summary: >- REMOVE_LOST_STOCK on a store that expects Cubbo to issue its removal NF-e value: error: >- Orders::CreateRemovalOrder -> lost-stock removal is not available for store 1234 removalInsufficientStock: summary: >- REMOVE_EXPIRED_STOCK / REMOVE_DAMAGED_STOCK asks for more than the warehouse holds value: error: >- not enough EXPIRED stock in warehouse 7 -> SKU-RED-M: requested 4, 1 available removalInsufficientLostStock: value: error: >- Orders::LostStockRemovalService -> insufficient LOST stock for product 4321 on order 987657 (found 1 of 2) clientInvoiceNotAllowed: summary: >- client_invoice sent but manual NF-e entry is not enabled for the store value: error: >- Store issues fiscal invoices; manual client invoice is not allowed removalValidationFailed: summary: Removal order failed field validation value: errors: - field: shipping_method code: MISSING_SHIPPING_METHOD additional_info: {} '500': description: >- Unexpected error (including an unknown `store_id`). Nothing was created. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: unexpected error security: - bearerAuth: [] components: schemas: BrazilOrderCreateRequest: type: object description: >- 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. required: - store_id - order_number - products properties: store_id: type: integer description: Id of the Brazil store the order belongs to. example: 1234 order_number: type: string description: Your identifier for the order. Must be unique within the store. example: ORD-BR-0001 order_type: type: string enum: - SALE - DONATION - REMOVE_STOCK - REMOVE_DAMAGED_STOCK - REMOVE_EXPIRED_STOCK - REMOVE_LOST_STOCK - STOCK_TRANSFER_OUT default: SALE description: >- 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. example: SALE 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`. For `SALE`/`DONATION` one of `shipping_method_id` or `shipping_line_code` is required; ignored for removal types. 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). Alternative to `shipping_method_id`. Ignored for removal types. example: Express is_paid: type: boolean description: Whether the order is already paid. Defaults to `true` when omitted. default: true example: true is_b2b: type: boolean description: >- Business-model classification, read only for stores enabled for both B2B and D2C; omit for a consumer order. example: false buyer_shipping_price: type: number description: >- 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: $ref: '#/components/schemas/BrazilOrderShippingAddress' billing: $ref: '#/components/schemas/BrazilOrderBillingAddress' products: type: array minItems: 1 description: Lines of the order. items: $ref: '#/components/schemas/BrazilOrderProductLine' shipping_documents: type: array description: Optional PDF documents to print and include with the shipment. items: $ref: '#/components/schemas/OrderShippingDocument' client_invoice: $ref: '#/components/schemas/BrazilClientInvoice' description: >- 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: type: string description: >- Removal types only. Base64-encoded XML of the authorized NF-e you issued yourself. Accepted for any Brazil removal order. example: PG5mZT48L25mZT4= Order: type: object description: > An order as returned by the Orders endpoints. Scalar fields are always available; associations (`shipping_method`, `order_lines`, `invoices`, `store`, `channel_integration`, `return`, `created_by_return`, `order_histories`) are present only when the endpoint includes them. Each endpoint's response description lists the fields it returns. properties: id: type: integer description: Cubbo ID of the order. Use it in path parameters. example: 987654 store_id: type: integer description: Store ID. example: 1234 order_number: type: string description: Your order number, unique within the store. example: ORD-0001 status: $ref: '#/components/schemas/OrderStatus' channel_created_at: type: string format: date-time description: When the order was created in the sales channel. example: '2026-01-10T14:02:11.000Z' order_date: type: - string - 'null' format: date-time description: Order date. example: '2026-01-10T14:02:11.000Z' shipping_date: type: - string - 'null' format: date-time description: When the order was shipped. example: '2026-01-11T18:30:00.000Z' pending_at: type: - string - 'null' format: date-time description: When the order became ready to be fulfilled. example: '2026-01-10T14:05:00.000Z' shipping_email: type: - string - 'null' description: Buyer email. example: buyer@example.com shipping_address_1: type: - string - 'null' description: Shipping street address line 1 (also inside `shipping`). example: Av. Ejemplo 123 shipping_status: oneOf: - $ref: '#/components/schemas/OrderShippingStatus' - type: 'null' description: Carrier-side status of the shipment. is_paid: type: boolean description: Whether the order is paid. Unpaid orders are not fulfilled. example: true is_cod: type: boolean description: Whether the order is cash on delivery. example: false cod_amount: type: - string - 'null' description: Amount to collect on delivery, as a decimal string. example: null requires_document_return: type: boolean description: Whether the carrier must bring back a signed document. example: false requires_pickup_on_delivery: type: boolean description: Whether the carrier must pick something up when delivering. example: false has_carrier_insurance: type: boolean description: Whether the shipment is insured with the carrier. example: false has_missing_info: type: boolean description: Whether the order is blocked because data is missing. example: false missing_info: type: - string - 'null' description: Description of the missing data, if any. example: null currency: type: - string - 'null' description: Currency code of the prices. example: MXN total_price: type: - string - 'null' description: Order total as a decimal string. example: '899.00' discount_price: type: - string - 'null' description: Total discount as a decimal string. example: '0.00' buyer_shipping_price: type: - string - 'null' description: Shipping price paid by the buyer, as a decimal string. example: '0.00' extra_fees_price: type: - string - 'null' description: Extra fees as a decimal string. example: '0.0' is_pick_and_ship: type: boolean description: >- Whether the order is a pick-and-ship order (you pick it up at the warehouse). example: false pick_n_ship_status: type: - string - 'null' description: Pick-and-ship status. enum: - awaiting_pick_up - picked_up - in_warehouse - null example: null is_b2b: type: boolean description: >- Whether the order is a B2B order. In `GET /orders` only present for stores that handle both B2B and D2C. example: false is_first_time_buyer: type: boolean description: Whether this is the buyer's first order in the store. example: true is_subscription_renewal: type: boolean description: Whether the order is a subscription renewal. example: false is_click_and_collect: type: boolean description: Whether the buyer picks the order up at a pickup point. example: false click_and_collect_metadata: oneOf: - $ref: '#/components/schemas/OrderClickAndCollectMetadata' - type: 'null' description: Pickup-point details for click-and-collect orders; null otherwise. is_multi_package: type: boolean description: Whether the shipment has more than one package. example: false shipping: $ref: '#/components/schemas/OrderAddress' billing: $ref: '#/components/schemas/OrderBillingAddressDetails' delivery_tracking: type: array description: Tracking per package. Return labels are excluded. items: $ref: '#/components/schemas/OrderDeliveryTrackingPackage' return_shipping_labels: type: - array - 'null' description: Valid return labels of the order. items: $ref: '#/components/schemas/OrderReturnShippingLabel' proof_of_delivery: oneOf: - $ref: '#/components/schemas/OrderProofOfDelivery' - type: 'null' description: >- Proof of delivery, when the carrier provided one for a shipped or returned order. estimated_time_arrival: type: - string - 'null' format: date-time description: Estimated delivery date. example: '2026-01-13T00:00:00.000Z' latest_estimated_time_arrival_range: oneOf: - $ref: '#/components/schemas/OrderEtaRange' - type: 'null' description: Latest estimated delivery window, or null when no estimate exists. delivered_at: type: - string - 'null' format: date-time description: When the carrier delivered the order. example: null updated_at: type: string format: date-time description: Last update of the order. example: '2026-01-11T18:31:00.000Z' channel_order_id: type: - string - 'null' description: ID of the order in the sales channel. example: '5566778899' channel_name: type: - string - 'null' description: Name of the sales channel the order came from. example: shopify channel_shipping_line_code: type: - string - 'null' description: >- Code of the shipping option chosen at checkout in the sales channel (first shipping line). example: standard warehouse_timezone: type: - string - 'null' description: IANA time zone of the warehouse fulfilling the order. example: America/Mexico_City shipping_method: oneOf: - $ref: '#/components/schemas/OrderShippingMethod' - type: 'null' description: Shipping method assigned to the order. order_lines: type: array description: Lines of the order. items: $ref: '#/components/schemas/OrderLine' invoices: type: array description: NF-e documents attached to the order (Brazil). items: $ref: '#/components/schemas/OrderInvoice' store: oneOf: - $ref: '#/components/schemas/OrderStore' - type: 'null' description: Store the order belongs to. channel_integration: oneOf: - $ref: '#/components/schemas/OrderChannelIntegration' - type: 'null' description: Sales-channel integration the order came from. return: oneOf: - $ref: '#/components/schemas/OrderReturnSummary' - type: 'null' description: >- The return opened for this order, if any. Use `GET /returns/{return_id}` for the full return. created_by_return: oneOf: - $ref: '#/components/schemas/OrderReturnSummary' - type: 'null' description: The return that created this order (for exchanges), if any. order_histories: type: array description: >- Order timeline. Only returned by `GET /orders` with `include_event_history=true`. items: $ref: '#/components/schemas/OrderHistoryEvent' Error: type: object description: Error body returned by every failed request. required: - error properties: error: type: string description: >- Human-readable description of the failure. For `401` responses it is always `Unauthorized`. example: Parameter store_id is required message: type: string description: >- Present on `401` responses only; the reason the request was rejected. example: invalid token code: type: - string - 'null' description: >- Stable machine-readable code, present on some order, return and replenishment errors. example: ORDER_ALREADY_EXISTS context: type: - object - 'null' description: >- Extra data about the failure when available, for example the id of the conflicting order. additionalProperties: true example: order_id: 987654 OrderFieldValidationError: type: object description: Field-level validation errors of an order. required: - errors properties: errors: type: array items: type: object required: - field - code properties: field: type: string description: Order field the error refers to. example: shipping_method code: type: string description: >- Validation code, for example `NATIONAL_SHIPPING_METHOD_EXPECTED`, `MISSING_SHIPPING_FIELD`, `SHIPPING_METHOD_HAS_NO_COVERAGE`, `UNRECOGNIZED_CITY_OR_STATE`, `UNRECOGNIZED_CITY_CODE`. example: NATIONAL_SHIPPING_METHOD_EXPECTED additional_info: type: object description: Extra details for the code, often empty. additionalProperties: true example: {} BrazilOrderShippingAddress: type: object description: Recipient and delivery address (required for `SALE`/`DONATION`). required: - first_name - phone - email - address1 - number - neighborhood - country - city - province - zip_code properties: first_name: type: string description: Recipient first name. example: Ana last_name: type: string description: Recipient last name. example: Silva phone: type: string description: Recipient phone number. example: '5511999999999' email: type: string format: email description: Recipient email. example: buyer@example.com address1: type: string description: Street name (logradouro). example: Av. Paulista address2: type: string description: Additional address line (complemento). example: Bloco B address3: type: string description: Accepted for compatibility; not stored. example: '' number: type: string description: Street number. example: '1234' interior_number: type: string description: Apartment or suite. example: Apto 45 neighborhood: type: string description: Neighborhood (bairro). example: Bela Vista country: type: string description: Country as an ISO 3166-1 alpha-2 code. example: BR city: type: string description: City. example: São Paulo province: type: string description: State (UF), for example `SP`. example: SP zip_code: type: string description: >- CEP (postal code), digits only. Validated against the Correios database asynchronously. example: '01310100' BrazilOrderBillingAddress: type: object description: >- Fiscal data of the buyer, used to issue the NF-e (required for `SALE`/`DONATION`). required: - first_name - last_name - phone - email - address1 - number - neighborhood - country - city - province - zip_code - tax_id properties: first_name: type: string description: Buyer first name. example: Ana last_name: type: string description: Buyer last name. example: Silva phone: type: string description: Buyer phone number. example: '5511999999999' email: type: string format: email description: Buyer email. example: buyer@example.com address1: type: string description: Street name (logradouro). example: Av. Paulista address2: type: string description: Additional address line (complemento). example: Bloco B address3: type: string description: Accepted for compatibility; not stored. example: '' number: type: string description: Street number. example: '1234' interior_number: type: string description: Apartment or suite. example: Apto 45 neighborhood: type: string description: Neighborhood (bairro). example: Bela Vista country: type: string description: Country as an ISO 3166-1 alpha-2 code. example: BR city: type: string description: City. example: São Paulo province: type: string description: State (UF). example: SP zip_code: type: string description: CEP (postal code). example: '01310100' tax_id: type: string description: >- Buyer tax id: CPF (11 digits) when `tax_regime` is `PHYSICAL`, CNPJ (14 digits) when `LEGAL`. Length is validated asynchronously (`BILLING_TAX_ID_WRONG_LENGTH`). example: 000.000.000-00 tax_regime: type: string enum: - PHYSICAL - LEGAL default: PHYSICAL description: Natural person (`PHYSICAL`, CPF) or company (`LEGAL`, CNPJ). example: PHYSICAL company: type: string description: Company legal name. Required when `tax_regime` is `LEGAL`. example: Example Comércio LTDA state_registration: type: string description: >- State registration (Inscrição Estadual). Required when `tax_regime` is `LEGAL`. example: '000000000' BrazilOrderProductLine: 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. Must be at least 1 for removal types. example: 2 price_per_item: type: number minimum: 0 description: >- Unit price that reaches the NF-e. Required for `SALE`/`DONATION`; optional for removal types, where it falls back to the product's registered price. Use a nominal value rather than `0` on a donation. example: 59.9 discount_per_item: type: number minimum: 0 description: >- Unit discount. Must not exceed `price_per_item`, and requires `price_per_item` to be sent. example: 5 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 BrazilClientInvoice: type: object required: - key - serie - number properties: key: type: string pattern: ^[0-9]{44}$ description: NF-e access key (chave de acesso), 44 digits. example: '00000000000000000000000000000000000000000000' serie: type: string description: NF-e series. example: '1' number: type: string description: NF-e number. example: '987' 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' 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 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.