> ## 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. # Get a return > Returns the current state of one return of your store: its status and type, what the customer declared is coming back (`expected_products`), and the products of the original order that can be received (`return_products`). Use it to follow a return after creating it, or to check a return reported on an order (`returned_order_id` / `returned_order_number`). - For products tracked by unit code (IMEI or serial number), each `return_products` entry also lists the `unit_codes` that shipped on the original order. Products that do not track unit codes never carry that key. - A return that does not exist or does not belong to one of your stores answers 404. ## OpenAPI ````yaml /openapi.yaml get /returns/{return_id} 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: /returns/{return_id}: get: tags: - Returns summary: Get a return description: > Returns the current state of one return of your store: its status and type, what the customer declared is coming back (`expected_products`), and the products of the original order that can be received (`return_products`). Use it to follow a return after creating it, or to check a return reported on an order (`returned_order_id` / `returned_order_number`). - For products tracked by unit code (IMEI or serial number), each `return_products` entry also lists the `unit_codes` that shipped on the original order. Products that do not track unit codes never carry that key. - A return that does not exist or does not belong to one of your stores answers 404. operationId: getReturn parameters: - name: return_id in: path required: true description: >- Numeric id of the return, as returned when it was created or on the order. schema: type: integer example: 98765 responses: '200': description: The return. content: application/json: schema: $ref: '#/components/schemas/ReturnDetail' example: id: 98765 status: PENDING return_type: TO_BE_DETERMINED resolved_at: null notes: Customer changed their mind expected_products: - product_id: 5551 quantity: 1 skus: - SKU-RED-M return_products: - product_id: 5551 name: Red T-shirt M barcode: '7501234567890' quantity: 1 skus: - SKU-RED-M image_url: /rails/active_storage/blobs/redirect/abc123/red-tshirt.png - product_id: 5560 name: Smartphone 128GB barcode: '7509876543210' quantity: 1 skus: - PHONE-BLK-128 image_url: null unit_codes: - IMEI-000000000000001 returned_order_id: 445566 returned_order_number: ORD-0001 created_at: '2026-10-12T15:04:05.123Z' '401': $ref: '#/components/responses/Unauthorized' '404': description: No return with that id in your stores. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: no return found with return_id 98765 '500': $ref: '#/components/responses/InternalServerError' security: - bearerAuth: [] components: schemas: ReturnDetail: type: object description: Response of `GET /returns/{return_id}`. required: - id - status - return_type - resolved_at - notes - expected_products - return_products - returned_order_id - returned_order_number - created_at properties: id: type: integer description: Unique id of the return. example: 98765 status: $ref: '#/components/schemas/ReturnStatus' return_type: $ref: '#/components/schemas/ReturnType' resolved_at: type: - string - 'null' format: date-time description: When the return was resolved; null while pending. example: null notes: type: - string - 'null' description: Reason or comments given when the return was requested. example: Customer changed their mind expected_products: type: - array - 'null' description: Products and quantities declared as coming back, with their SKUs. items: $ref: '#/components/schemas/ReturnProduct' return_products: type: array description: >- Products of the original order that can be received as part of this return. items: $ref: '#/components/schemas/ReturnLine' returned_order_id: type: - integer - 'null' description: Id of the order being returned. example: 445566 returned_order_number: type: - string - 'null' description: Order number of the order being returned. example: ORD-0001 created_at: type: string format: date-time description: When the return was created. example: '2026-10-12T15:04:05.123Z' 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 ReturnStatus: type: string description: > Lifecycle status of a return. - `PENDING`: created and waiting for a decision (review of a customer request, or decision on an order returned by the carrier). - `REQUESTED`: resolved; the customer has the return instructions and the goods are expected back. - `ORDERED`: resolved by creating a new (replacement or resend) order. - `CANCELLED`: cancelled before the goods came back; reserved stock was released. - `ARRIVED_AT_WAREHOUSE`: the package arrived at the warehouse and is waiting to be processed. - `AWAITING_INSPECTION`: the package was opened and is waiting for inspection of its contents. - `RECEIVED`: the goods were checked in and are being re-entered into inventory. - `REENTERED`: the goods were fully re-entered into inventory; the return is complete. - `UNSUCCESSFUL`: closed without receiving anything; every expected product was missing on reception. enum: - PENDING - REQUESTED - ORDERED - CANCELLED - ARRIVED_AT_WAREHOUSE - AWAITING_INSPECTION - RECEIVED - REENTERED - UNSUCCESSFUL example: PENDING ReturnType: type: string description: > What kind of return this is. - `TO_BE_DETERMINED`: requested by the customer or by you, not yet reviewed; the outcome (simple return, exchange, rejection) is decided later. - `SIMPLE_RETURN`: the customer sends the goods back; no replacement is shipped. - `EXCHANGE`: the customer sends the goods back and replacement items (`exchange_products`) are reserved to ship once the return arrives. - `IMMEDIATE_EXCHANGE`: replacement items ship right away, before the return arrives (created from the Cubbo app, not through this API). - `RETURNED_BY_CARRIER`: the carrier could not deliver the order and brought it back; decide it with `POST /returns/{return_id}/decision`. - `UNIDENTIFIED`: a package arrived at the warehouse that could not be matched to an order (created by warehouse staff). enum: - TO_BE_DETERMINED - SIMPLE_RETURN - EXCHANGE - IMMEDIATE_EXCHANGE - RETURNED_BY_CARRIER - UNIDENTIFIED example: TO_BE_DETERMINED ReturnProduct: type: object description: >- A product and quantity declared on a return (expected back, or to be shipped as a replacement). required: - product_id - quantity properties: product_id: type: integer description: Cubbo id of the product. example: 5551 quantity: type: integer description: Number of units. example: 1 skus: type: array description: >- SKUs of the product in your store. Present on the returns endpoints; absent when the return is embedded in an order. items: type: string example: - SKU-RED-M ReturnLine: type: object description: >- A product of the original order that can be received as part of the return (kits are expanded into their components; non-scannable and dropshipping products are omitted). required: - product_id - name - barcode - quantity - skus - image_url properties: product_id: type: integer description: Cubbo id of the product. example: 5551 name: type: string description: Product name. example: Red T-shirt M barcode: type: - string - 'null' description: Product barcode (UPC/EAN). example: '7501234567890' quantity: type: integer description: Quantity of this product on the original order. example: 1 skus: type: array description: SKUs of the product in your store. items: type: string example: - SKU-RED-M image_url: type: - string - 'null' description: >- Relative path of the product image, or null when the product has none. example: /rails/active_storage/blobs/redirect/abc123/red-tshirt.png unit_codes: type: array description: >- Unit codes (IMEI / serial numbers) that shipped on the original order. Only present for products tracked by unit code. items: type: string example: - IMEI-000000000000001 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 `. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.