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

# Convert an order to click and collect

> Changes an order's delivery to pickup at the point identified by `service_code` (obtained
from `GET /orders/{order_id}/pickup-points`) and reprocesses it with the pickup carrier.
On success the full updated order is returned.

- The order must be in a pre-label status (paused orders are allowed) and must not be
  click and collect already.
- Click and collect must be enabled for the store, and the point's carrier must be one
  the store allows. The store's order-editing restrictions apply.
- The pickup option must not cost more than the order's original shipping unless the
  store waived that check. Orders shipped by carriers not billed through Cubbo, or
  international orders, cannot be converted.
- Business rejections answer 422 with a stable `code`. On `ALREADY_CLICK_AND_COLLECT`
  the body also carries the order's current `click_and_collect_metadata` (public fields
  only) so a client retrying after a timeout can tell whether its own conversion won.
- If the conversion succeeds but the order cannot be rendered, the response is still
  200 with `{"converted": true}`; fetch the order to see its new state.
- Unknown orders, orders of other accounts and orders your credential cannot update all
  answer the same 404 body.




## OpenAPI

````yaml /openapi.yaml patch /orders/{order_id}/convert-to-click-and-collect
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/{order_id}/convert-to-click-and-collect:
    patch:
      tags:
        - Click and collect
      summary: Convert an order to click and collect
      description: >
        Changes an order's delivery to pickup at the point identified by
        `service_code` (obtained

        from `GET /orders/{order_id}/pickup-points`) and reprocesses it with the
        pickup carrier.

        On success the full updated order is returned.


        - The order must be in a pre-label status (paused orders are allowed)
        and must not be
          click and collect already.
        - Click and collect must be enabled for the store, and the point's
        carrier must be one
          the store allows. The store's order-editing restrictions apply.
        - The pickup option must not cost more than the order's original
        shipping unless the
          store waived that check. Orders shipped by carriers not billed through Cubbo, or
          international orders, cannot be converted.
        - Business rejections answer 422 with a stable `code`. On
        `ALREADY_CLICK_AND_COLLECT`
          the body also carries the order's current `click_and_collect_metadata` (public fields
          only) so a client retrying after a timeout can tell whether its own conversion won.
        - If the conversion succeeds but the order cannot be rendered, the
        response is still
          200 with `{"converted": true}`; fetch the order to see its new state.
        - Unknown orders, orders of other accounts and orders your credential
        cannot update all
          answer the same 404 body.
      operationId: convertOrderToClickAndCollect
      parameters:
        - name: order_id
          in: path
          required: true
          description: Id of the order
          schema:
            type: integer
            example: 55501
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConvertToClickAndCollectRequest'
            example:
              store_id: 1234
              service_code: CUBBOCNCESTEST001
      responses:
        '200':
          description: >-
            Order converted. The body is the updated order (with `order_lines`
            and `shipping_method`), or `{"converted": true}` if the order could
            not be rendered.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/Order'
                  - $ref: '#/components/schemas/ConvertedWithoutOrder'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: >-
            The order or the claimed store does not exist or is not accessible
            to your credential
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClickAndCollectError'
              examples:
                orderNotFound:
                  value:
                    error: Order not found
                    code: ORDER_NOT_FOUND
                storeNotFound:
                  value:
                    error: store_not_found
        '422':
          description: >-
            Validation error (`error` only) or business rejection (`error` plus
            a stable `code`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClickAndCollectConversionError'
              examples:
                missingServiceCode:
                  value:
                    error: Parameter service_code is required
                invalidStatus:
                  value:
                    error: >-
                      Order cannot be converted to click and collect in status
                      shipped
                    code: INVALID_ORDER_STATUS
                alreadyClickAndCollect:
                  value:
                    error: Order is already click and collect
                    code: ALREADY_CLICK_AND_COLLECT
                    click_and_collect_metadata:
                      carrier_name: Estafeta
                      service_code: CUBBOCNCESTEST001
                storeEditRestricted:
                  value:
                    error: Order editing is currently restricted for this store
                    code: STORE_EDIT_RESTRICTED
                invalidServiceCode:
                  value:
                    error: Invalid click_and_collect_service_code
                    code: INVALID_CNC_SERVICE_CODE
                carrierTemporarilyUnavailable:
                  value:
                    error: This pickup carrier is temporarily unavailable
                    code: CNC_CARRIER_TEMPORARILY_UNAVAILABLE
                notEnabledForStore:
                  value:
                    error: Click and collect is not enabled for this store
                    code: CNC_NOT_ENABLED_FOR_STORE
                carrierNotEnabledForStore:
                  value:
                    error: This pickup carrier is not enabled for this store
                    code: CNC_CARRIER_NOT_ENABLED_FOR_STORE
                shippingMethodNotFound:
                  value:
                    error: >-
                      No shipping method found for click and collect with
                      carrier ESTAFETA
                    code: CNC_SHIPPING_METHOD_NOT_FOUND
                originalNotCubboBilled:
                  value:
                    error: >-
                      This order's shipping carrier doesn't support click and
                      collect conversion
                    code: CNC_ORIGINAL_NOT_CUBBO_BILLED
                originalNotNational:
                  value:
                    error: Click and collect is only available for national orders
                    code: CNC_ORIGINAL_NOT_NATIONAL_SHIPPING
                priceExceedsOriginal:
                  value:
                    error: >-
                      This pickup option would cost more than the original
                      shipping
                    code: CNC_PRICE_EXCEEDS_ORIGINAL
                rateCardUnavailable:
                  value:
                    error: >-
                      Click and collect pricing could not be determined for this
                      order
                    code: CNC_RATE_CARD_UNAVAILABLE
                locationConfirmationFailed:
                  value:
                    error: The pickup point could not be confirmed with the carrier
                    code: CNC_LOCATION_CONFIRMATION_FAILED
                genericIneligible:
                  value:
                    error: Click and collect conversion is not eligible
                    code: CNC_SHIPPING_METHOD_NOT_FOUND
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClickAndCollectUnexpectedError'
              example:
                error: unexpected_error
                timestamp: 1700000000
      security:
        - bearerAuth: []
components:
  schemas:
    ConvertToClickAndCollectRequest:
      type: object
      required:
        - store_id
        - service_code
      properties:
        store_id:
          type: integer
          description: Id of the store that owns the order; must belong to your account
          example: 1234
        service_code:
          type: string
          description: Pickup point identifier from `GET /orders/{order_id}/pickup-points`
          example: CUBBOCNCESTEST001
    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'
    ConvertedWithoutOrder:
      type: object
      description: >-
        Returned when the conversion succeeded but the order could not be
        rendered
      required:
        - converted
      properties:
        converted:
          type: boolean
          description: Always true
          example: true
    ClickAndCollectError:
      type: object
      description: 404 body of the click-and-collect endpoints
      required:
        - error
      properties:
        error:
          type: string
          description: '`Order not found` or `store_not_found`'
          example: Order not found
        code:
          type: string
          description: Present for order lookups
          enum:
            - ORDER_NOT_FOUND
          example: ORDER_NOT_FOUND
    ClickAndCollectConversionError:
      type: object
      description: >-
        422 body of the conversion endpoint. Parameter errors carry only
        `error`; business rejections add a stable `code`.
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable reason
          example: Order is already click and collect
        code:
          type: string
          description: Stable rejection code
          enum:
            - INVALID_ORDER_STATUS
            - ALREADY_CLICK_AND_COLLECT
            - STORE_EDIT_RESTRICTED
            - INVALID_CNC_SERVICE_CODE
            - CNC_CARRIER_TEMPORARILY_UNAVAILABLE
            - CNC_NOT_ENABLED_FOR_STORE
            - CNC_CARRIER_NOT_ENABLED_FOR_STORE
            - CNC_SHIPPING_METHOD_NOT_FOUND
            - CNC_ORIGINAL_NOT_CUBBO_BILLED
            - CNC_ORIGINAL_NOT_NATIONAL_SHIPPING
            - CNC_PRICE_EXCEEDS_ORIGINAL
            - CNC_RATE_CARD_UNAVAILABLE
            - CNC_LOCATION_CONFIRMATION_FAILED
          example: ALREADY_CLICK_AND_COLLECT
        click_and_collect_metadata:
          type:
            - object
            - 'null'
          description: >-
            Only with `ALREADY_CLICK_AND_COLLECT`; the order's current pickup
            selection (public fields only), or null if it carries none
          additionalProperties: true
          example:
            carrier_name: Estafeta
            service_code: CUBBOCNCESTEST001
    ClickAndCollectUnexpectedError:
      type: object
      description: 500 body of the click-and-collect endpoints
      required:
        - error
        - timestamp
      properties:
        error:
          type: string
          description: Always `unexpected_error`
          example: unexpected_error
        timestamp:
          type: integer
          description: Unix timestamp to quote when contacting support
          example: 1700000000
    OrderStatus:
      type: string
      description: >
        Fulfillment status of an order. `processing`, `picking` and `packing`
        all mean the order is being

        prepared in the warehouse. `holded` means the order is on hold. `packed`
        is unused.
      enum:
        - initial
        - unpaid
        - empty
        - pending
        - error
        - cancelation_window
        - entirely_dropshipping
        - backorder
        - processing
        - picking
        - packing
        - packed
        - shipped
        - canceled
        - holded
        - interrupted
        - returned
        - return_arrived
        - returning
        - reentered
        - awaiting_fulfillment_request
        - awaiting_dropoff
        - arrived_at_warehouse
      example: shipped
    OrderShippingStatus:
      type: string
      description: >-
        Carrier-side status of the shipment, updated from tracking events.
        `null` until the carrier reports the first event.
      enum:
        - shipment_created
        - awaiting_collection
        - shipment_collected
        - shipment_in_transit
        - shipment_out_for_delivery
        - shipment_delivered
        - shipment_partially_delivered
        - shipment_with_incident
        - shipment_to_be_self_collected
        - shipment_canceled
        - shipment_returned
        - shipment_not_defined
      example: shipment_in_transit
    OrderClickAndCollectMetadata:
      type: object
      description: >
        Pickup-point information for click-and-collect orders. Keys depend on
        the carrier that operates

        the pickup point (typically `name`, `address`, `zipcode`, `description`,
        `carrier_name`,

        coordinates and a location ID). `pickup_codes` is keyed by package
        tracking number and holds the

        short code and QR image the buyer presents at pickup. Internal fields
        are never included.
      additionalProperties: true
      properties:
        name:
          type: string
          description: Pickup point name.
          example: Pickup point name
        address:
          type: string
          description: Pickup point address.
          example: Pickup point address
        zipcode:
          type: string
          description: Pickup point postal code.
          example: '01000'
        description:
          type: string
          description: Human-readable description of the pickup point.
          example: Punto fisico - Centro
        carrier_name:
          type: string
          description: Carrier operating the pickup point.
          example: ESTAFETA
        pickup_codes:
          type: object
          description: Pickup codes per package, keyed by the package tracking number.
          additionalProperties:
            type: object
            properties:
              pickup_short:
                type: string
                description: Short pickup code.
                example: AB12CD
              pickup_qr_image_url:
                type: string
                description: URL of the QR image to present at pickup.
                example: >-
                  https://api.cubbo.com/rails/active_storage/blobs/redirect/example/pickup_qr.png
    OrderAddress:
      type: object
      description: Shipping contact and address of an order.
      properties:
        first_name:
          type:
            - string
            - 'null'
          description: Recipient first name.
          example: Ana
        last_name:
          type:
            - string
            - 'null'
          description: Recipient last name.
          example: Example
        company:
          type:
            - string
            - 'null'
          description: Company name, if any.
          example: null
        phone:
          type:
            - string
            - 'null'
          description: Recipient phone number.
          example: '+525500000000'
        address_1:
          type:
            - string
            - 'null'
          description: Street address line 1.
          example: Av. Ejemplo 123
        address_2:
          type:
            - string
            - 'null'
          description: Street address line 2.
          example: null
        email:
          type:
            - string
            - 'null'
          description: Recipient email.
          example: buyer@example.com
        zip_code:
          type:
            - string
            - 'null'
          description: Postal code.
          example: '01000'
        country:
          type:
            - string
            - 'null'
          description: Two-letter country code.
          example: MX
        state:
          type:
            - string
            - 'null'
          description: State or province.
          example: CDMX
        city:
          type:
            - string
            - 'null'
          description: City.
          example: Ciudad de Mexico
        city_code:
          type:
            - string
            - 'null'
          description: >-
            Colombia: the DANE code of the city that decides the destination, as
            you sent it in `shipping.city_code`; null when the city and province
            decide.
          example: null
        number:
          type:
            - string
            - 'null'
          description: Street number.
          example: '123'
        interior_number:
          type:
            - string
            - 'null'
          description: Apartment or interior number.
          example: null
        neighborhood:
          type:
            - string
            - 'null'
          description: Neighborhood (colonia / bairro).
          example: Centro
        references:
          type:
            - string
            - 'null'
          description: Delivery references for the courier.
          example: Blue door
    OrderBillingAddressDetails:
      type: object
      description: >-
        Billing contact, fiscal data and address of an order. Fiscal fields are
        returned in clear text to the store that owns the order.
      properties:
        first_name:
          type:
            - string
            - 'null'
          description: Billing first name.
          example: Ana
        last_name:
          type:
            - string
            - 'null'
          description: Billing last name.
          example: Example
        company:
          type:
            - string
            - 'null'
          description: Company name, if any.
          example: null
        phone:
          type:
            - string
            - 'null'
          description: Billing phone number.
          example: '+525500000000'
        tax_id:
          type:
            - string
            - 'null'
          description: Tax ID of the buyer (CPF or CNPJ in Brazil, RFC in Mexico).
          example: 000.000.000-00
        tax_regime:
          type:
            - string
            - 'null'
          description: Buyer's tax regime, when provided.
          example: null
        state_registration:
          type:
            - string
            - 'null'
          description: State registration (inscricao estadual, Brazil).
          example: null
        address_1:
          type:
            - string
            - 'null'
          description: Street address line 1.
          example: Av. Ejemplo 123
        address_2:
          type:
            - string
            - 'null'
          description: Street address line 2.
          example: null
        number:
          type:
            - string
            - 'null'
          description: Street number.
          example: '123'
        interior_number:
          type:
            - string
            - 'null'
          description: Apartment or interior number.
          example: null
        neighborhood:
          type:
            - string
            - 'null'
          description: Neighborhood.
          example: Centro
        email:
          type:
            - string
            - 'null'
          description: Billing email.
          example: buyer@example.com
        zip_code:
          type:
            - string
            - 'null'
          description: Postal code.
          example: '01000'
        country:
          type:
            - string
            - 'null'
          description: Two-letter country code.
          example: MX
        state:
          type:
            - string
            - 'null'
          description: State or province.
          example: CDMX
        city:
          type:
            - string
            - 'null'
          description: City.
          example: Ciudad de Mexico
    OrderDeliveryTrackingPackage:
      type: object
      description: >-
        Tracking information for one package of the order. When no label exists
        yet, a single entry with null tracking fields is returned.
      properties:
        shipping_number:
          type:
            - string
            - 'null'
          description: Carrier tracking number of the package.
          example: TRK000000001
        tracking_url:
          type:
            - string
            - 'null'
          description: >-
            Carrier tracking page. For Cubbo pickup-point deliveries this is
            Cubbo's own tracking page.
          example: https://carrier.example.com/track/TRK000000001
        cubbo_tracking_url:
          type:
            - string
            - 'null'
          description: Cubbo tracking page for the order.
          example: https://tracking.example.com/orders/abc123
        service_id:
          type:
            - string
            - 'null'
          description: Carrier service used for the label.
          example: express
        shipping_status:
          oneOf:
            - $ref: '#/components/schemas/OrderShippingStatus'
            - type: 'null'
          description: >-
            Shipping status of this package (falls back to the order's shipping
            status).
        package_index:
          type: integer
          description: 1-based index of this package.
          example: 1
        total_packages:
          type: integer
          description: Total number of packages of the order.
          example: 1
    OrderReturnShippingLabel:
      type: object
      description: A valid return label attached to the order.
      properties:
        shipping_number:
          type:
            - string
            - 'null'
          description: Tracking number of the return label.
          example: RTN000000001
        tracking_url:
          type:
            - string
            - 'null'
          description: Carrier tracking page of the return label.
          example: https://carrier.example.com/track/RTN000000001
    OrderProofOfDelivery:
      type: object
      description: >-
        Proof of delivery reported by the carrier. Present only for shipped,
        returning or returned orders that have one.
      properties:
        id:
          type: integer
          description: Proof of delivery ID.
          example: 3101
        recipient_name:
          type:
            - string
            - 'null'
          description: Name of the person who received the package.
          example: Ana Example
        recipient_relationship:
          type:
            - string
            - 'null'
          description: >-
            Relationship of the receiver to the buyer, as reported by the
            carrier.
          example: self
        format:
          type:
            - string
            - 'null'
          description: Format of the proof files (for example `image`, `pdf`, `base64`).
          example: image
        files:
          type:
            - array
            - 'null'
          description: Files attached to the proof, or null when there are none.
          items:
            type: object
            properties:
              path:
                type: string
                description: Relative download path.
                example: /rails/active_storage/blobs/redirect/example/pod.jpg
              filename:
                type: string
                description: File name.
                example: pod.jpg
              byte_size:
                type: integer
                description: Size in bytes.
                example: 120340
              content_type:
                type: string
                description: MIME type.
                example: image/jpeg
              thumbnail_path:
                type:
                  - string
                  - 'null'
                description: Relative path of a 300x300 thumbnail; only for images.
                example: /rails/active_storage/representations/example/pod.jpg
    OrderEtaRange:
      type: object
      description: >-
        Latest estimated delivery window, as UTC timestamps of the start and end
        of the day in the warehouse's time zone.
      properties:
        range_begin:
          type: string
          format: date-time
          description: Start of the estimated delivery window.
          example: '2026-01-13T06:00:00.000Z'
        range_end:
          type: string
          format: date-time
          description: End of the estimated delivery window.
          example: '2026-01-14T05:59:59.000Z'
    OrderShippingMethod:
      type: object
      description: >-
        Shipping method (carrier + service) assigned to the order. `GET /orders`
        returns only `id`, `carrier_name`, `shipping_name` and `is_cod`.
      properties:
        id:
          type: integer
          description: Shipping method ID.
          example: 42
        shipping_name:
          type: string
          description: Name of the shipping service.
          example: DHL Express
        carrier_name:
          type: string
          description: Carrier name as presented to your customers.
          example: DHL
        capitalized_carrier:
          type:
            - string
            - 'null'
          description: Carrier name with the first letter capitalized.
          example: Dhl
        is_active:
          type: boolean
          description: Whether the method is currently available.
          example: true
        shipping_type:
          type:
            - string
            - 'null'
          description: Coverage of the method.
          enum:
            - national
            - international
            - pickup
            - null
          example: national
        delivery_type:
          type:
            - string
            - 'null'
          description: Service level.
          enum:
            - SameDay
            - NextDay
            - Ground
            - Pickup
            - International
            - null
          example: Ground
        country:
          type: string
          description: Two-letter country code the method operates in.
          example: MX
        is_cod:
          type: boolean
          description: Whether the method supports cash on delivery.
          example: false
        extended_zone:
          type: boolean
          description: Whether the carrier delivers to extended zones.
          example: true
        po_box_dropoff:
          type: boolean
          description: Whether the carrier delivers to PO boxes.
          example: true
        provides_pod:
          type: boolean
          description: Whether the carrier provides proof of delivery.
          example: false
        contract_provider:
          type:
            - string
            - 'null'
          description: Carrier contract used.
          example: null
        enable_multipackage:
          type: boolean
          description: Whether multi-package shipments are enabled.
          example: false
        non_working_days:
          type: array
          items:
            type: integer
          description: Weekdays the carrier does not operate (0 = Sunday).
          example:
            - 0
            - 6
        dispatch_carrier_alias:
          type:
            - string
            - 'null'
          description: Alias used at dispatch.
          example: null
        handles_fragile:
          type: boolean
          description: Whether the carrier handles fragile goods.
          example: false
        multipackage_label_mode:
          type: string
          description: How multi-package labels are produced.
          enum:
            - per_package
            - bulk
          example: bulk
        generates_label_per_package:
          type: boolean
          description: Whether one label is generated per package.
          example: false
        carrier_supports_per_box_label:
          type: boolean
          description: >-
            Whether the carrier mints one label per box at packing. Not in use
            yet.
          example: false
    OrderLine:
      type: object
      description: A line of an order (one SKU and its quantity).
      properties:
        id:
          type: integer
          description: Order line ID.
          example: 5551
        name:
          type:
            - string
            - 'null'
          description: Product name at the time of the order.
          example: Red T-shirt M
        sku:
          type:
            - string
            - 'null'
          description: SKU ordered.
          example: SKU-RED-M
        quantity:
          type: integer
          description: Units ordered.
          example: 2
        generated:
          type: boolean
          description: >-
            True when Cubbo generated the line automatically (for example a kit
            component or a promotional insert).
          example: false
        price_per_item:
          type:
            - string
            - 'null'
          description: Unit price as a decimal string.
          example: '449.5'
        discount_per_item:
          type:
            - string
            - 'null'
          description: Unit discount as a decimal string.
          example: '0.0'
        product:
          oneOf:
            - $ref: '#/components/schemas/OrderLineProduct'
            - type: 'null'
          description: >-
            The product behind the line, when included by the endpoint. `null`
            while the line's SKU does not exist in the store (an order created
            with an unknown SKU; see `POST /orders`).
        stock_units:
          type: array
          description: Physical units assigned to the line, when included by the endpoint.
          items:
            $ref: '#/components/schemas/OrderStockUnit'
    OrderInvoice:
      type: object
      description: >-
        An NF-e (Brazilian electronic invoice) attached to an order. Fiscal
        events (cancellations, corrections) are not listed; only the documents
        themselves.
      properties:
        id:
          type: integer
          description: Invoice ID.
          example: 7801
        invoice_type:
          type:
            - string
            - 'null'
          description: >-
            Where the invoice was issued. `WEBMANIA` and `BLING` are issued
            through Cubbo's fiscal integration; `IOTA` and `EXTERNAL` were
            issued by the client's own system; `WEBMANIA_CTE` / `WEBMANIA_NFSE`
            are transport and service documents.
          enum:
            - WEBMANIA
            - SELIA_BR
            - WEBMANIA_CTE
            - WEBMANIA_NFSE
            - NATURA
            - BLING
            - IOTA
            - EXTERNAL
            - null
          example: WEBMANIA
        status:
          type:
            - string
            - 'null'
          description: >-
            Fiscal status. `PREAPPROVED` means registered and awaiting
            confirmation from the fiscal provider.
          enum:
            - APPROVED
            - REJECTED
            - CANCELLED
            - DENIED
            - PROCESSING
            - CONTINGENCY
            - PREAPPROVED
            - null
          example: APPROVED
        invoiceable_id:
          type: integer
          description: ID of the order the invoice belongs to.
          example: 987654
        invoiceable_type:
          type: string
          description: Type of the document the invoice belongs to; `Order` here.
          example: Order
        operation_nature:
          type:
            - string
            - 'null'
          description: Nature of the operation (natureza da operacao).
          example: Venda de mercadoria
        operation_type:
          type:
            - string
            - 'null'
          description: >-
            Direction of the operation, as sent when the invoice was attached:
            `SAIDA`/`ENTRADA` or `OUTGOING`/`INCOMING`.
          example: OUTGOING
        key:
          type:
            - string
            - 'null'
          description: The 44-digit NF-e access key.
          example: '00000000000000000000000000000000000000000000'
        xml_file:
          oneOf:
            - $ref: '#/components/schemas/OrderInvoiceFile'
            - type: 'null'
          description: The authorized NF-e XML, or null if not yet available.
        pdf_file:
          oneOf:
            - $ref: '#/components/schemas/OrderInvoiceFile'
            - type: 'null'
          description: The DANFE (printable invoice) PDF, or null if not yet available.
        label_pdf_file:
          oneOf:
            - $ref: '#/components/schemas/OrderInvoiceFile'
            - type: 'null'
          description: >-
            The DANFE in label format (DANFE etiqueta) PDF, or null if not
            available.
    OrderStore:
      type: object
      description: Store the order belongs to.
      properties:
        id:
          type: integer
          description: Store ID.
          example: 1234
        name:
          type: string
          description: Store name.
          example: Example Store
    OrderChannelIntegration:
      type: object
      description: >-
        The sales-channel integration the order came from. `GET /orders` returns
        `id` and `channel_type_name`.
      properties:
        id:
          type: integer
          description: Integration ID.
          example: 55
        channel_type_name:
          type: string
          description: >-
            Sales channel type (for example `shopify`, `vtex`, `woocommerce`,
            `meli`, `openapi`).
          example: shopify
    OrderReturnSummary:
      type: object
      description: >
        Summary of a return embedded in an order (`return` /
        `created_by_return`). Only the fields below are

        guaranteed; `GET /orders` may additionally embed the return's
        `returned_stock_units` (received units,

        each with its `unit_code`) and, on `return`, the exchange order it
        created (`created_order`). Fetch

        the full return with the Returns endpoints.
      additionalProperties: true
      properties:
        id:
          type: integer
          description: Return ID.
          example: 501
        status:
          type: string
          description: Return status.
          example: pending
        return_type:
          type: string
          description: Kind of return (for example a simple return or an exchange).
          example: SIMPLE_RETURN
        notes:
          type:
            - string
            - 'null'
          description: Notes attached to the return.
          example: null
        created_at:
          type: string
          format: date-time
          description: When the return was created.
          example: '2026-01-20T10:00:00.000Z'
        expected_products:
          type:
            - array
            - 'null'
          description: Products expected back, as product ID and quantity.
          items:
            type: object
            properties:
              product_id:
                type: integer
                description: Product ID.
                example: 777
              quantity:
                type: integer
                description: Units expected.
                example: 1
    OrderHistoryEvent:
      type: object
      description: >-
        An event in the order timeline (status change, tracking update,
        incident). `GET /orders` with `include_event_history=true` returns only
        `new_status`, `incident_description`, `timestamp` and `origin`.
      properties:
        id:
          type: integer
          description: Event ID.
          example: 120001
        order_id:
          type: integer
          description: Order ID.
          example: 987654
        created_by_id:
          type:
            - integer
            - 'null'
          description: ID of the user who triggered the event, if any.
          example: null
        previous_status:
          type:
            - string
            - 'null'
          description: Status before the event.
          example: packing
        new_status:
          type:
            - string
            - 'null'
          description: Status after the event (an order status or a shipping status).
          example: shipped
        action:
          type:
            - string
            - 'null'
          description: >-
            Kind of event (for example `order_status_update`, `tracking_update`,
            `cancel`).
          example: order_status_update
        metadata:
          type:
            - object
            - 'null'
          description: Additional event data.
          example: {}
        origin:
          type:
            - string
            - 'null'
          description: Who or what produced the event.
          enum:
            - cubbo
            - integration_webhook
            - shipping_webhook
            - tracking_watcher
            - cubbo_user
            - cubbo_user_import
            - cubbo_user_api
            - cubbo_business_rule
            - awaiting_client_invoice
            - homolog_invoice_precheck
            - cubbo_automation
            - tracking_app
            - system_auto_coverage_retry
            - zapier
            - integration_api
            - null
          example: shipping_webhook
        reference_timestamp:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When the event actually happened (for tracking events, the carrier's
            timestamp).
          example: '2026-01-11T18:30:00.000Z'
        timestamp:
          type:
            - string
            - 'null'
          format: date-time
          description: Same as `reference_timestamp`.
          example: '2026-01-11T18:30:00.000Z'
        incident_description:
          type:
            - string
            - 'null'
          description: >-
            Carrier description of the incident; only when `new_status` is
            `shipment_with_incident`.
          example: null
        difal_error_description:
          type:
            - string
            - 'null'
          description: >-
            Error message(s) from the DIFAL guide issuer; only for DIFAL error
            events (Brazil).
          example: null
        created_by_cubbo_user:
          type: boolean
          description: >-
            True when the event was triggered by Cubbo staff rather than a user
            of your account.
          example: false
        created_at:
          type: string
          format: date-time
          description: When the event was recorded.
          example: '2026-01-11T18:31:00.000Z'
        updated_at:
          type: string
          format: date-time
          description: Last update of the event record.
          example: '2026-01-11T18:31:00.000Z'
    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
    OrderLineProduct:
      type: object
      description: >-
        Product of an order line. `GET /orders` and `GET
        /orders/awaiting-invoice` return the subset shown here.
      properties:
        id:
          type: integer
          description: Product ID.
          example: 777
        name:
          type: string
          description: Product name.
          example: Red T-shirt M
        billing_name:
          type:
            - string
            - 'null'
          description: Name used on invoices.
          example: T-shirt
        description:
          type:
            - string
            - 'null'
          description: Product description (HTML).
          example: null
        has_imei:
          type: boolean
          description: Whether units of this product carry an IMEI.
          example: false
        is_fragile:
          type: boolean
          description: Whether the product needs fragile handling.
          example: false
        is_kit:
          type: boolean
          description: Whether the product is a kit of other products.
          example: false
        bar_code:
          type:
            - string
            - 'null'
          description: Barcode (UPC/EAN).
          example: '7500000000001'
        is_dropshipping:
          type: boolean
          description: Whether the product is fulfilled by a third party.
          example: false
        is_scannable:
          type: boolean
          description: Whether units are scanned during picking.
          example: true
        price:
          type:
            - string
            - 'null'
          description: Product price as a decimal string.
          example: '449.5'
        weight:
          type:
            - number
            - 'null'
          description: Product weight.
          example: 0.3
        product_codes:
          type: array
          description: SKUs registered for the product.
          items:
            type: object
            properties:
              id:
                type: integer
                description: Product code ID.
                example: 9001
              sku:
                type: string
                description: SKU.
                example: SKU-RED-M
    OrderStockUnit:
      type: object
      description: >-
        A physical unit assigned to an order line. In `GET /orders` only `id`,
        `imei` (when the product tracks IMEI) and `unit_code` (when requested by
        order number, for unit-code products in `packing`/`shipped`) are
        returned.
      properties:
        id:
          type: integer
          description: Stock unit ID.
          example: 31001
        status:
          type: string
          description: Stock unit status.
          example: PICKED
        product_id:
          type: integer
          description: Product ID of the unit.
          example: 777
        picked_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the unit was picked.
          example: '2026-01-11T15:00:00.000Z'
        created_at:
          type: string
          format: date-time
          description: Creation time.
          example: '2025-12-01T10:00:00.000Z'
        updated_at:
          type: string
          format: date-time
          description: Last update time.
          example: '2026-01-11T15:00:00.000Z'
        imei:
          type: object
          description: IMEI of the unit, only for products that track IMEI.
          properties:
            id:
              type: integer
              description: IMEI record ID.
              example: 12
            imei:
              type: string
              description: The IMEI number.
              example: '000000000000000'
        unit_code:
          type: string
          description: >-
            Serial / unit code of the unit, only for products that require unit
            codes and only when the request filters by `order_number`.
          example: UC-0001
    OrderInvoiceFile:
      type: object
      description: A downloadable invoice file.
      properties:
        path:
          type: string
          description: Relative download path.
          example: /rails/active_storage/blobs/redirect/example/nfe.xml
        filename:
          type: string
          description: File name.
          example: nfe.xml
        byte_size:
          type: integer
          description: Size in bytes.
          example: 10240
        content_type:
          type: string
          description: MIME type.
          example: application/xml
        url:
          type: string
          description: Absolute download URL.
          example: >-
            https://api.cubbo.com/rails/active_storage/blobs/redirect/example/nfe.xml
  responses:
    Unauthorized:
      description: >-
        Missing or invalid token, wrong credentials, or no access to the
        requested store.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            invalidToken:
              value:
                error: Unauthorized
                message: invalid token
            noHeader:
              value:
                error: Unauthorized
                message: no authorization header found
            storeNotAllowed:
              value:
                error: Unauthorized
                message: not allowed to show? this Store
  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.