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

# List orders

> Returns a paginated list of a store's orders with their order lines, invoices (NF-e, Brazil only),
shipping method, delivery tracking and, optionally, the order's event history. Use it to sync order
status and tracking into your own systems. Filter by status, order type, order number, buyer email
or date ranges.

- Results are paginated: `page` (default 1) and `per_page` (default 10, capped at 100). The `meta`
  object tells you whether more pages exist.
- Filtering `status` by `processing` also returns orders in `picking` and `packing`, since all three
  mean "being prepared in the warehouse".
- `order_number` accepts a single string or an array of strings (`order_number[]=ORD-0001&order_number[]=ORD-0002`).
  When you filter by order number, stock units of products that use unit codes also expose their
  `unit_code` while the order is `packing` or `shipped`.
- `sort_by` accepts any order field (for example `created_at`, `channel_created_at`, `shipping_date`,
  `updated_at`), or `shipping_methods.<field>` / `stores.<field>`; an unknown field returns 422
  `Field not found`. `sort` is `desc` unless you pass `asc`. Without `sort_by` the order of results is not guaranteed.
- `include_event_history=true` adds `order_histories` to every order (status changes, tracking
  updates and incidents).
- `is_b2b` is only present for stores that handle both B2B and D2C orders.
- Each order in this list carries the subset of `Order` fields listed in the response schema
  description; the full `Order` object is returned by the create and update endpoints.




## OpenAPI

````yaml /openapi.yaml get /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:
    get:
      tags:
        - Orders
      summary: List orders
      description: >
        Returns a paginated list of a store's orders with their order lines,
        invoices (NF-e, Brazil only),

        shipping method, delivery tracking and, optionally, the order's event
        history. Use it to sync order

        status and tracking into your own systems. Filter by status, order type,
        order number, buyer email

        or date ranges.


        - Results are paginated: `page` (default 1) and `per_page` (default 10,
        capped at 100). The `meta`
          object tells you whether more pages exist.
        - Filtering `status` by `processing` also returns orders in `picking`
        and `packing`, since all three
          mean "being prepared in the warehouse".
        - `order_number` accepts a single string or an array of strings
        (`order_number[]=ORD-0001&order_number[]=ORD-0002`).
          When you filter by order number, stock units of products that use unit codes also expose their
          `unit_code` while the order is `packing` or `shipped`.
        - `sort_by` accepts any order field (for example `created_at`,
        `channel_created_at`, `shipping_date`,
          `updated_at`), or `shipping_methods.<field>` / `stores.<field>`; an unknown field returns 422
          `Field not found`. `sort` is `desc` unless you pass `asc`. Without `sort_by` the order of results is not guaranteed.
        - `include_event_history=true` adds `order_histories` to every order
        (status changes, tracking
          updates and incidents).
        - `is_b2b` is only present for stores that handle both B2B and D2C
        orders.

        - Each order in this list carries the subset of `Order` fields listed in
        the response schema
          description; the full `Order` object is returned by the create and update endpoints.
      operationId: listOrders
      parameters:
        - name: store_id
          in: query
          required: true
          schema:
            type: integer
          description: ID of the store whose orders you want to list.
          example: 1234
        - name: status
          in: query
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              $ref: '#/components/schemas/OrderStatus'
          description: >-
            Only return orders in these statuses. `processing` implicitly
            includes `picking` and `packing`.
          example:
            - pending
            - processing
        - name: order_type
          in: query
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              $ref: '#/components/schemas/OrderType'
          description: Only return orders of these types.
          example:
            - SALE
        - name: order_number
          in: query
          required: false
          schema:
            oneOf:
              - type: string
              - type: array
                items:
                  type: string
          description: >-
            Exact order number, or an array of order numbers. Enables
            `unit_code` exposure on stock units.
          example: ORD-0001
        - name: shipping_email
          in: query
          required: false
          schema:
            type: string
          description: Case-insensitive partial match on the buyer's shipping email.
          example: buyer@example.com
        - name: shipping_date[from]
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: >-
            Lower bound of the shipping date range. Required when
            `shipping_date[to]` is sent.
          example: '2026-01-01T00:00:00Z'
        - name: shipping_date[to]
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: >-
            Upper bound of the shipping date range. Required when
            `shipping_date[from]` is sent.
          example: '2026-01-31T23:59:59Z'
        - name: channel_created_at[from]
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: >-
            Lower bound of the range on the date the order was created in the
            sales channel. Required when `channel_created_at[to]` is sent.
          example: '2026-01-01T00:00:00Z'
        - name: channel_created_at[to]
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: >-
            Upper bound of the range on the date the order was created in the
            sales channel. Required when `channel_created_at[from]` is sent.
          example: '2026-01-31T23:59:59Z'
        - name: sort_by
          in: query
          required: false
          schema:
            type: string
          description: >-
            Field to sort by. Any order field, or `shipping_methods.<field>` /
            `stores.<field>`. Unknown fields return 422.
          example: channel_created_at
        - name: sort
          in: query
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
          description: Sort direction. Any value other than `asc` sorts descending.
          example: desc
        - name: page
          in: query
          required: false
          description: Page number, starting at 1.
          schema:
            type: integer
            default: 1
          example: 1
        - name: per_page
          in: query
          required: false
          schema:
            type: integer
            default: 10
            maximum: 100
          description: Orders per page. Values above 100 are capped at 100.
          example: 50
        - name: include_event_history
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: >-
            When true, each order includes `order_histories` with its status and
            tracking events.
          example: false
      responses:
        '200':
          description: Orders matching the filters, with pagination metadata.
          content:
            application/json:
              schema:
                type: object
                required:
                  - orders
                  - meta
                properties:
                  orders:
                    type: array
                    description: >
                      Orders on this page. Each item is an `Order` limited to:
                      `id`, `store_id`, `order_number`, `status`,

                      `channel_created_at`, `order_date`, `shipping_date`,
                      `pending_at`, `shipping_email`, `shipping_status`,

                      `is_paid`, `channel_order_id`, `channel_name`, `is_cod`,
                      `cod_amount`, `has_carrier_insurance`,

                      `requires_document_return`, `requires_pickup_on_delivery`,
                      `currency`, `total_price`, `shipping`,

                      `billing`, `delivery_tracking`, `return_shipping_labels`,
                      `estimated_time_arrival`, `delivered_at`,

                      `updated_at`, `is_click_and_collect`,
                      `click_and_collect_metadata`,
                      `latest_estimated_time_arrival_range`,

                      `channel_shipping_line_code`, `warehouse_timezone`,
                      `is_first_time_buyer`, `is_subscription_renewal`,

                      `is_multi_package`, `is_b2b` (mixed B2B/D2C stores only),
                      plus the associations `shipping_method`

                      (`id`, `carrier_name`, `shipping_name`, `is_cod`),
                      `order_lines` (`id`, `name`, `sku`, `quantity`,

                      `generated`, `price_per_item`, `product`, `stock_units`),
                      `invoices`, `store` (`id`, `name`),

                      `channel_integration` (`id`, `channel_type_name`),
                      `return`, `created_by_return` and, when

                      `include_event_history=true`, `order_histories`
                      (`new_status`, `incident_description`, `timestamp`,
                      `origin`).
                    items:
                      $ref: '#/components/schemas/Order'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                orders:
                  - id: 987654
                    store_id: 1234
                    order_number: ORD-0001
                    status: shipped
                    channel_created_at: '2026-01-10T14:02:11.000Z'
                    order_date: '2026-01-10T14:02:11.000Z'
                    shipping_date: '2026-01-11T18:30:00.000Z'
                    pending_at: '2026-01-10T14:05:00.000Z'
                    shipping_email: buyer@example.com
                    shipping_status: shipment_in_transit
                    is_paid: true
                    channel_order_id: '5566778899'
                    channel_name: shopify
                    is_cod: false
                    cod_amount: null
                    has_carrier_insurance: false
                    requires_document_return: false
                    requires_pickup_on_delivery: false
                    currency: MXN
                    total_price: '899.00'
                    shipping:
                      first_name: Ana
                      last_name: Example
                      company: null
                      phone: '+525500000000'
                      address_1: Av. Ejemplo 123
                      address_2: null
                      email: buyer@example.com
                      zip_code: '01000'
                      country: MX
                      state: CDMX
                      city: Ciudad de Mexico
                      number: '123'
                      interior_number: null
                      neighborhood: Centro
                      references: Blue door
                      city_code: null
                    billing:
                      first_name: Ana
                      last_name: Example
                      company: null
                      phone: '+525500000000'
                      tax_id: null
                      tax_regime: null
                      state_registration: null
                      address_1: Av. Ejemplo 123
                      address_2: null
                      number: '123'
                      interior_number: null
                      neighborhood: Centro
                      email: buyer@example.com
                      zip_code: '01000'
                      country: MX
                      state: CDMX
                      city: Ciudad de Mexico
                    delivery_tracking:
                      - shipping_number: TRK000000001
                        tracking_url: https://carrier.example.com/track/TRK000000001
                        cubbo_tracking_url: https://tracking.example.com/orders/abc123
                        service_id: express
                        shipping_status: shipment_in_transit
                        package_index: 1
                        total_packages: 1
                    return_shipping_labels: []
                    estimated_time_arrival: '2026-01-13T00:00:00.000Z'
                    delivered_at: null
                    updated_at: '2026-01-11T18:31:00.000Z'
                    is_click_and_collect: false
                    click_and_collect_metadata: null
                    latest_estimated_time_arrival_range:
                      range_begin: '2026-01-13T06:00:00.000Z'
                      range_end: '2026-01-14T05:59:59.000Z'
                    channel_shipping_line_code: standard
                    warehouse_timezone: America/Mexico_City
                    is_first_time_buyer: true
                    is_subscription_renewal: false
                    is_multi_package: false
                    shipping_method:
                      id: 42
                      carrier_name: DHL
                      shipping_name: DHL Express
                      is_cod: false
                    order_lines:
                      - id: 5551
                        name: Red T-shirt M
                        sku: SKU-RED-M
                        quantity: 2
                        generated: false
                        price_per_item: '449.5'
                        product:
                          id: 777
                          name: Red T-shirt M
                          billing_name: T-shirt
                          description: null
                          has_imei: false
                          is_fragile: false
                          is_kit: false
                          bar_code: '7500000000001'
                          is_dropshipping: false
                          is_scannable: true
                          price: '449.5'
                          weight: 0.3
                          product_codes:
                            - id: 9001
                              sku: SKU-RED-M
                        stock_units:
                          - id: 31001
                          - id: 31002
                    invoices: []
                    store:
                      id: 1234
                      name: Example Store
                    channel_integration:
                      id: 55
                      channel_type_name: shopify
                    return: null
                    created_by_return: null
                meta:
                  current_page: 1
                  next_page: 2
                  prev_page: null
                  total_pages: 7
                  first_page: true
                  last_page: false
                  per_page: 10
                  total_count: 63
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missingStore:
                  value:
                    error: Parameter store_id is required
                invalidDate:
                  value:
                    error: '''abc'' is not a valid DateTime'
                unknownSortField:
                  value:
                    error: 'Field not found: foo'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - bearerAuth: []
components:
  schemas:
    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
    OrderType:
      type: string
      description: >
        Kind of order. `SALE` is a regular sale; `DONATION` ships goods without
        a sale; `REMOVE_STOCK`,

        `REMOVE_DAMAGED_STOCK`, `REMOVE_EXPIRED_STOCK` and `REMOVE_LOST_STOCK`
        withdraw stock from the

        warehouse; `STOCK_TRANSFER_OUT` moves stock to another store; `C2C` is a
        consumer-to-consumer

        shipment created by Cubbo and cannot be created through the API.
      enum:
        - SALE
        - DONATION
        - REMOVE_STOCK
        - REMOVE_DAMAGED_STOCK
        - REMOVE_EXPIRED_STOCK
        - REMOVE_LOST_STOCK
        - STOCK_TRANSFER_OUT
        - C2C
      example: SALE
    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'
    PaginationMeta:
      type: object
      description: Paging information returned next to list results.
      properties:
        current_page:
          type: integer
          example: 1
        next_page:
          type:
            - integer
            - 'null'
          example: 2
        prev_page:
          type:
            - integer
            - 'null'
          example: null
        total_pages:
          type: integer
          example: 7
        first_page:
          type: boolean
          example: true
        last_page:
          type: boolean
          example: false
        per_page:
          type: integer
          example: 50
        total_count:
          type: integer
          example: 312
    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
    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
    InternalServerError:
      description: >-
        Unexpected error. Retry with backoff; if it persists, send the timestamp
        to Cubbo support.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: 'unexpected error, timestamp: 1760000000'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Token returned by `POST /auth/token`, sent as `Authorization: Bearer
        <token>`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.