---
title: "Return status change"
method: POST
path: "returnStatusChange"
tags: ["Webhooks"]
---

# Return status change

`POST returnStatusChange` (webhook)

## Supported Return Webhooks
All return-related webhooks are closely tied to the status of the return. Each webhook is triggered by a specific status transition, marking important stages in the return process.

- Return created (`status`: `status_created`)
- Return in progress (`status`: `in_progress`)
- Return en route (`status`: `en_route`)
- Return returned (`status`: `returned`)

## Payload Structure (JSON Schema)
The payload of each return-related webhook matches the structure of a single return object as returned by the `GET /v1/integrations/returns-list` endpoint. While the `GET /v1/integrations/returns-list` endpoint responds with an array of return objects (`returns-list` field), each webhook delivers the full data of one return in the same format. This allows for easy reuse of the return model across both API responses and webhook events.

## Payload

- FulfillmentIntegrationsBundleApiResourceReturnOutput
  - `id` integer, required — Unique numeric identifier of the return.
  - `warehouse` string, required — Code of the warehouse handling this return.
  - `order_key` string, nullable, required — External order key of the original order this return relates to; null when no linked order exists.
  - `store_id` integer, nullable, required — Identifier of the store the return belongs to; null if the return is not linked to a store.
  - `rma` string, required — Return Merchandise Authorization (RMA) number identifying this return.
  - `tracking_number` string, nullable, required — Primary carrier tracking number of the return shipment; null if not yet known. Set to the most recently added of tracking_numbers.
  - `tracking_numbers` string[], required — All carrier tracking numbers associated with the return shipment; empty when none are known.
  - `status` 'status_created' | 'in_progress' | 'en_route' | 'returned' | 'arrived' | 'not_arrived' | 'grading_completed', required
  - `return_reason` 'reason_exchange' | 'reason_changed_mind' | 'reason_undeliverable' | 'reason_unknown' | 'reason_incorrect_product', required
  - `note` string, nullable, required — Optional free-text note attached to the return; null when no note was provided.
  - `created_at` string, date-time, required — ISO 8601 timestamp when the return record was created.
  - `updated_at` string, date-time, required — ISO 8601 timestamp when the return record was last updated.
  - `received_at` string, date-time, nullable, required — ISO 8601 timestamp when the return was physically received at the warehouse; null until received.
  - `items` FulfillmentIntegrationsBundleCratePublicApiReturnItemOutput[], required — Line items included in the return, each with expected and received quantities.
    - `product` FulfillmentIntegrationsBundleCrateReturnOrReceivingItemProductPublicApiOutput, required
      - `id` integer, required — Server-assigned numeric identifier of the product.
      - `sku` string, required — Stock Keeping Unit (SKU), the client's unique product code.
      - `name` string, required — Human-readable name of the product.
    - `expected_quantity` integer, required — Total number of units of this product expected to be received.
    - `received_quantity` integer, required — Total number of units of this product received so far across all batches.
    - `receiving_details` FulfillmentIntegrationsBundleCrateReturnItemDetailsPublicApiOutput[], required — Per-unit receiving records for this return item, capturing lot, quantities, timestamps, and final disposition.
      - `lot` FulfillmentIntegrationsBundleCrateReturnOrReceivingItemLotPublicApiOutput, required
        - `lot_number` string, nullable, required — Lot/batch number assigned by the supplier, or null if not provided.
        - `expiration_date` string, date-time, nullable, required — Lot expiration date in ISO 8601 format (YYYY-MM-DD), or null if not applicable.
      - `expected_quantity` integer, required — Number of units expected in this lot/batch entry.
      - `received_quantity` integer, required — Number of units actually received in this lot/batch entry.
      - `received_at` string, date-time, nullable, required — Timestamp when this batch was received at the warehouse, in ISO 8601 format. Null if not yet received.
      - `type_scoped_id` integer, nullable, required — Identifier unique within records of the same type; combine with the type field for a globally unique reference. Null for return_unit records, which are identified by their unit_uuid.
      - `type` 'receive' | 'return_unit', required
      - `unit_uuid` string, nullable, required — UUID of the return unit this record originates from; only present for unit-sourced records.
      - `final_disposition` 'reworked' | 'returned_to_inventory' | 'return_to_merchant' | 'dispose' | 'donate' | 'other', required
    - `desired_action` 'received_back_into_inventory' | 'damaged_not_resellable', required
  - `custom_data` FulfillmentCommonBundleApiResourceIntegrationDataOutput[], required — List of custom name/value pairs attached to the return by the source integration.
    - `name` string, required — Key of the custom data entry.
    - `value` object, required — Value of the custom data entry; may be any JSON-serializable structure.
  - `source` 'shipmonk' | 'loop' | 'returnly' | 'deposco' | 'happy_returns_loop' | 'happy_returns', required

## Acknowledgement `200`

Return a 2xx status to indicate that the data was received successfully

## Other responses

- `default` — For a 4xx status, ShipMonk will retry the webhook delivery up to 100 times, with a 5-minute delay between attempts.

---

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