> ## 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 with selected fields

> A lighter version of `GET /orders`: returns only the order fields you ask for in `fields`, without
order lines, invoices or event history. Use it for high-volume polling (for example status or
tracking sync) where you do not need the full payload.

- `fields` is a list of `Order` field names. Values that are not in the allowed list are ignored; if
  none of the requested fields is valid, or `fields` is omitted, every allowed field is returned.
- Allowed fields: `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`,
  `estimated_time_arrival`, `delivered_at`, `updated_at`, `is_click_and_collect`,
  `click_and_collect_metadata`, `channel_shipping_line_code`, `warehouse_timezone`, `shipping_method`,
  `is_multi_package`, `delivery_tracking`, `is_first_time_buyer`, `is_subscription_renewal`.
- `shipping_method` is the only association available; when requested it is returned with every
  `OrderShippingMethod` field.
- Filters: `status` (exact values, no `processing` expansion), `order_type`, `shipping_email`
  (partial match) and `normalized_shipping_phone_suffix` (the last digits of the buyer's phone,
  at least 3 digits after removing non-digits).
- Sorting is restricted to `sort_by` in `id`, `order_date`, `channel_created_at`, `shipping_date`,
  `updated_at` and `sort` in `asc`, `desc`.




## OpenAPI

````yaml /openapi.yaml get /orders/with-fields
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/with-fields:
    get:
      tags:
        - Orders
      summary: List orders with selected fields
      description: >
        A lighter version of `GET /orders`: returns only the order fields you
        ask for in `fields`, without

        order lines, invoices or event history. Use it for high-volume polling
        (for example status or

        tracking sync) where you do not need the full payload.


        - `fields` is a list of `Order` field names. Values that are not in the
        allowed list are ignored; if
          none of the requested fields is valid, or `fields` is omitted, every allowed field is returned.
        - Allowed fields: `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`,
          `estimated_time_arrival`, `delivered_at`, `updated_at`, `is_click_and_collect`,
          `click_and_collect_metadata`, `channel_shipping_line_code`, `warehouse_timezone`, `shipping_method`,
          `is_multi_package`, `delivery_tracking`, `is_first_time_buyer`, `is_subscription_renewal`.
        - `shipping_method` is the only association available; when requested it
        is returned with every
          `OrderShippingMethod` field.
        - Filters: `status` (exact values, no `processing` expansion),
        `order_type`, `shipping_email`
          (partial match) and `normalized_shipping_phone_suffix` (the last digits of the buyer's phone,
          at least 3 digits after removing non-digits).
        - Sorting is restricted to `sort_by` in `id`, `order_date`,
        `channel_created_at`, `shipping_date`,
          `updated_at` and `sort` in `asc`, `desc`.
      operationId: listOrdersWithFields
      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: fields
          in: query
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
              enum:
                - 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
                - estimated_time_arrival
                - delivered_at
                - updated_at
                - is_click_and_collect
                - click_and_collect_metadata
                - channel_shipping_line_code
                - warehouse_timezone
                - shipping_method
                - is_multi_package
                - delivery_tracking
                - is_first_time_buyer
                - is_subscription_renewal
          description: >-
            Fields to include in each order. Unknown values are ignored; omit to
            receive all allowed fields.
          example:
            - id
            - order_number
            - status
            - shipping_status
            - delivery_tracking
        - 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. Values outside the enum return
            422.
          example:
            - shipped
        - 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. Values outside the enum return
            422.
          example:
            - SALE
        - 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: normalized_shipping_phone_suffix
          in: query
          required: false
          schema:
            type: string
            minLength: 3
          description: >-
            Match orders whose buyer phone ends with these digits. Non-digits
            are stripped; at least 3 digits must remain.
          example: '0000'
        - name: sort_by
          in: query
          required: false
          schema:
            type: string
            enum:
              - id
              - order_date
              - channel_created_at
              - shipping_date
              - updated_at
          description: Field to sort by.
          example: updated_at
        - name: sort
          in: query
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
          description: Sort direction. Defaults to descending when `sort_by` is given.
          example: desc
        - name: page
          in: query
          required: false
          description: Page number, starting at 1.
          schema:
            type: integer
            minimum: 1
            default: 1
          example: 1
        - name: per_page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
          description: Orders per page.
          example: 100
      responses:
        '200':
          description: Orders with only the requested fields, plus pagination metadata.
          content:
            application/json:
              schema:
                type: object
                required:
                  - orders
                  - meta
                properties:
                  orders:
                    type: array
                    description: >-
                      Orders on this page, each limited to the requested
                      `fields`.
                    items:
                      $ref: '#/components/schemas/Order'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                orders:
                  - id: 987654
                    order_number: ORD-0001
                    status: shipped
                    shipping_status: shipment_delivered
                    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_delivered
                        package_index: 1
                        total_packages: 1
                meta:
                  current_page: 1
                  next_page: null
                  prev_page: null
                  total_pages: 1
                  first_page: true
                  last_page: true
                  per_page: 100
                  total_count: 1
        '401':
          description: >-
            Missing or invalid token, or the store does not exist / is not
            accessible with this token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Unauthorized
                  message:
                    type: string
                    example: invalid store
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missingStore:
                  value:
                    error: Parameter store_id is required
                invalidStatus:
                  value:
                    error: Parameter status must be within ["initial", "unpaid", ...]
                invalidSortBy:
                  value:
                    error: >-
                      Parameter sort_by must be within [nil, "id", "order_date",
                      "channel_created_at", "shipping_date", "updated_at"]
                perPageTooHigh:
                  value:
                    error: Parameter per_page cannot be greater than 100
                shortPhoneSuffix:
                  value:
                    error: >-
                      Parameter normalized_shipping_phone_suffix must contain at
                      least 3 digits
        '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:
    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.