---
title: "Create or Update Return"
method: POST
path: "/v1/integrations/returns"
tags: ["Returns"]
---

# Create or Update Return

`POST /v1/integrations/returns`

## Request body

- FulfillmentIntegrationsBundleApiResourceReturnInput
  - `warehouse` string, required — Code of the warehouse that will process this return.
  - `rma` string, required — Return Merchandise Authorization (RMA) number; must be unique per return and is used as the upsert key.
  - `order_key` string, nullable — Order key of the original outbound order this return relates to. Optional; supply to link the return to a known order.
  - `store_id` integer, required — Identifier of the store this return belongs to.
  - `return_reason` 'reason_exchange' | 'reason_changed_mind' | 'reason_undeliverable' | 'reason_unknown' | 'reason_incorrect_product', required
  - `note` string, nullable — Optional free-text note attached to the return for internal reference.
  - `tracking_number` string, nullable — Carrier tracking number of the parcel returning to the warehouse; optional, supply when known to enable inbound matching. Mutually exclusive with tracking_numbers.
  - `tracking_numbers` string[] — Carrier tracking numbers of the parcels returning to the warehouse; optional, supply when known to enable inbound matching. Mutually exclusive with tracking_number.
  - `items` FulfillmentIntegrationsBundleApiResourceReturnItemInput[], required
    - `sku` string, required — Stock Keeping Unit (SKU) of the returned product; must match an existing product.
    - `expected_quantity` integer, required — Quantity of this SKU the customer is expected to return; must be a positive integer.
    - `desired_action` 'received_back_into_inventory' | 'damaged_not_resellable', required
  - `custom_data` FulfillmentAccountApiBundleInputReturnReturnIntegrationDataRecordInput[] — Free-form key/value metadata stored on the return; not interpreted by fulfillment logic and returned as-is in return reads.
    - `name` string, required
    - `value` object, nullable, required
  - `references_to_related_order` FulfillmentAccountApiBundleInputReturnReferencesToRelatedOrderInput
    - `order_number` string, nullable, required — Order number to look up among existing orders' references; null disables the lookup.
    - `search_in_all_stores` boolean, required — When true, searches for the related order across all stores. When false, searches only within the store associated with the return.

## Response `200`

Success

- object
  - `status` integer, required
  - `data` object, required
    - `message` string, required
    - `id` integer, required

---

[API](https://skmtc.dev/shipmonk/apis/shipmonk-api.md) · [All operations](https://skmtc.dev/shipmonk/apis/shipmonk-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/shipmonk/shipmonk-api/revisions/9c1d10357491/schema)