> ## 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 waiting for an NF-e

> Brazil only. Returns the orders of a store that have been picked (or are about to be) and do not yet
have an approved NF-e, so your fiscal system can issue the invoice and attach it with
`POST /orders/{order_id}/attach-invoice`. Each order
includes its lines, the picked quantities per lot and the replenishment invoices those lots came
from, which lets you reference the inbound NF-e on the outbound one.

- By default (`only_picked_orders=true`) only orders in `packing` are returned. With
  `only_picked_orders=false`, orders in `pending`, `processing`, `picking` and `packing` are included.
- Orders are sorted by the time of their last status change, oldest first.
- Orders with an approved NF-e are excluded. Use `order_ids` to restrict the result to specific orders.
- `picked_sku_quantities` on each line groups the picked units by lot; `related_replenishments` on
  each order lists the replenishment NF-e keys of those lots. Orders whose picked lot codes cannot be
  parsed into a material code are omitted from the page (but still counted in `meta.total_count`).
- `integration_details` carries the raw sales-channel order for AnyMarket integrations and is
  `null` otherwise.




## OpenAPI

````yaml /openapi.yaml get /orders/awaiting-invoice
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/awaiting-invoice:
    get:
      tags:
        - Orders
      summary: List orders waiting for an NF-e
      description: >
        Brazil only. Returns the orders of a store that have been picked (or are
        about to be) and do not yet

        have an approved NF-e, so your fiscal system can issue the invoice and
        attach it with

        `POST /orders/{order_id}/attach-invoice`. Each order

        includes its lines, the picked quantities per lot and the replenishment
        invoices those lots came

        from, which lets you reference the inbound NF-e on the outbound one.


        - By default (`only_picked_orders=true`) only orders in `packing` are
        returned. With
          `only_picked_orders=false`, orders in `pending`, `processing`, `picking` and `packing` are included.
        - Orders are sorted by the time of their last status change, oldest
        first.

        - Orders with an approved NF-e are excluded. Use `order_ids` to restrict
        the result to specific orders.

        - `picked_sku_quantities` on each line groups the picked units by lot;
        `related_replenishments` on
          each order lists the replenishment NF-e keys of those lots. Orders whose picked lot codes cannot be
          parsed into a material code are omitted from the page (but still counted in `meta.total_count`).
        - `integration_details` carries the raw sales-channel order for
        AnyMarket integrations and is
          `null` otherwise.
      operationId: listOrdersAwaitingInvoice
      parameters:
        - name: store_id
          in: query
          required: true
          schema:
            type: integer
          description: ID of the store.
          example: 1234
        - name: only_picked_orders
          in: query
          required: false
          schema:
            type: boolean
            default: true
          description: >-
            When true only `packing` orders are returned; when false, `pending`,
            `processing`, `picking` and `packing`.
          example: true
        - name: order_ids
          in: query
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              type: integer
          description: Restrict the result to these order IDs.
          example:
            - 987654
        - 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
            default: 10
            maximum: 100
          description: Orders per page.
          example: 10
      responses:
        '200':
          description: Orders awaiting an invoice, with pagination metadata.
          content:
            application/json:
              schema:
                type: object
                required:
                  - orders
                  - meta
                properties:
                  orders:
                    type: array
                    items:
                      $ref: '#/components/schemas/OrderAwaitingInvoice'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                orders:
                  - id: 987654
                    store_id: 1234
                    order_number: ORD-0001
                    status: packing
                    order_type: SALE
                    channel_created_at: '2026-01-10T14:02:11.000Z'
                    order_date: '2026-01-10T14:02:11.000Z'
                    shipping_date: null
                    pending_at: '2026-01-10T14:05:00.000Z'
                    shipping_email: buyer@example.com
                    shipping_status: null
                    is_paid: true
                    channel_order_id: '5566778899'
                    is_cod: false
                    currency: BRL
                    total_price: '199.9'
                    discount_price: '0.0'
                    buyer_shipping_price: '15.0'
                    extra_fees_price: '0.0'
                    shipping:
                      first_name: Ana
                      last_name: Example
                      company: null
                      phone: '+5511900000000'
                      address_1: Rua Exemplo
                      address_2: null
                      email: buyer@example.com
                      zip_code: 01000-000
                      country: BR
                      state: SP
                      city: Sao Paulo
                      number: '10'
                      interior_number: null
                      neighborhood: Centro
                      references: null
                    billing:
                      first_name: Ana
                      last_name: Example
                      company: null
                      phone: '+5511900000000'
                      tax_id: 000.000.000-00
                      tax_regime: null
                      state_registration: null
                      address_1: Rua Exemplo
                      address_2: null
                      number: '10'
                      interior_number: null
                      neighborhood: Centro
                      email: buyer@example.com
                      zip_code: 01000-000
                      country: BR
                      state: SP
                      city: Sao Paulo
                    integration_details: null
                    order_lines:
                      - id: 5551
                        name: Red T-shirt M
                        sku: SKU-RED-M
                        quantity: 1
                        generated: false
                        price_per_item: '199.9'
                        discount_per_item: '0.0'
                        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: '7890000000001'
                          is_dropshipping: false
                          is_scannable: true
                          price: '199.9'
                          weight: 0.3
                          product_codes:
                            - id: 9001
                              sku: SKU-RED-M
                        picked_sku_quantities:
                          - lot_id: 301
                            lot_sku: '123456'
                            quantity: 1
                            lot_unique_code: 123456-LOT01
                            replenishment_invoice_key: '00000000000000000000000000000000000000000000'
                            replenishment_id: 2201
                    related_replenishments:
                      - replenishment_id: 2201
                        invoice_key: '00000000000000000000000000000000000000000000'
                meta:
                  current_page: 1
                  next_page: null
                  prev_page: null
                  total_pages: 1
                  first_page: true
                  last_page: true
                  per_page: 10
                  total_count: 1
        '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
                storeNotFound:
                  value:
                    error: Couldn't find Store with 'id'=0
                perPageTooHigh:
                  value:
                    error: Parameter per_page cannot be greater than 100
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - bearerAuth: []
components:
  schemas:
    OrderAwaitingInvoice:
      type: object
      description: >-
        An order that has no approved NF-e yet, with the data needed to issue
        one.
      properties:
        id:
          type: integer
          description: Cubbo ID of the order.
          example: 987654
        store_id:
          type: integer
          description: Store ID.
          example: 1234
        order_number:
          type: string
          description: Your order number.
          example: ORD-0001
        status:
          $ref: '#/components/schemas/OrderStatus'
        order_type:
          $ref: '#/components/schemas/OrderType'
        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: null
        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_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.
          example: true
        channel_order_id:
          type:
            - string
            - 'null'
          description: ID of the order in the sales channel.
          example: '5566778899'
        is_cod:
          type: boolean
          description: Whether the order is cash on delivery.
          example: false
        currency:
          type:
            - string
            - 'null'
          description: Currency code.
          example: BRL
        total_price:
          type:
            - string
            - 'null'
          description: Order total as a decimal string.
          example: '199.9'
        discount_price:
          type:
            - string
            - 'null'
          description: Total discount as a decimal string.
          example: '0.0'
        buyer_shipping_price:
          type:
            - string
            - 'null'
          description: Shipping paid by the buyer, as a decimal string.
          example: '15.0'
        extra_fees_price:
          type:
            - string
            - 'null'
          description: Extra fees as a decimal string.
          example: '0.0'
        shipping:
          $ref: '#/components/schemas/OrderAddress'
        billing:
          $ref: '#/components/schemas/OrderBillingAddressDetails'
        integration_details:
          type:
            - object
            - 'null'
          description: >-
            Raw sales-channel order payload for AnyMarket integrations; null for
            every other channel.
          example: null
        order_lines:
          type: array
          description: Order lines with their product and the picked quantities per lot.
          items:
            allOf:
              - $ref: '#/components/schemas/OrderLine'
              - type: object
                properties:
                  picked_sku_quantities:
                    type: array
                    description: Picked units grouped by lot.
                    items:
                      $ref: '#/components/schemas/OrderAwaitingInvoicePickedSku'
        related_replenishments:
          type: array
          description: Replenishment NF-e keys of the lots picked for this order.
          items:
            type: object
            properties:
              replenishment_id:
                type: integer
                description: Replenishment ID.
                example: 2201
              invoice_key:
                type:
                  - string
                  - 'null'
                description: Access key of the replenishment NF-e.
                example: '00000000000000000000000000000000000000000000'
    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
    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
    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
    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
    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'
    OrderAwaitingInvoicePickedSku:
      type: object
      description: >-
        Picked units of an order line grouped by lot, with the replenishment
        NF-e the lot entered the warehouse with.
      properties:
        lot_id:
          type: integer
          description: Lot ID.
          example: 301
        lot_sku:
          type: string
          description: Material code parsed from the lot code.
          example: '123456'
        quantity:
          type: integer
          description: Units picked from this lot for the line.
          example: 1
        lot_unique_code:
          type: string
          description: Full lot code.
          example: 123456-LOT01
        replenishment_invoice_key:
          type:
            - string
            - 'null'
          description: Access key of the replenishment NF-e that brought this lot in.
          example: '00000000000000000000000000000000000000000000'
        replenishment_id:
          type:
            - integer
            - 'null'
          description: Replenishment ID the lot came from.
          example: 2201
    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
  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.