--- updatedAt: 2026-04-22T08:07:44.000Z agentTools: projectIndex: https://apidocs.shipmonk.com/llms.txt --- # Return status change ## 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. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Shipmonk API", "version": "v1.033" }, "components": { "schemas": { "Fulfillment_CommonBundle_ApiResource_IntegrationDataOutput": { "type": "object", "properties": { "name": { "description": "Key of the custom data entry.", "type": "string" }, "value": { "description": "Value of the custom data entry; may be any JSON-serializable structure.", "type": "object" } }, "required": [ "name", "value" ], "title": "Integration Data Output" }, "Fulfillment_IntegrationsBundle_Crate_ReturnOrReceivingItemLotPublicApiOutput": { "type": "object", "properties": { "lot_number": { "description": "Lot/batch number assigned by the supplier, or null if not provided.", "type": [ "string", "null" ] }, "expiration_date": { "description": "Lot expiration date in ISO 8601 format (YYYY-MM-DD), or null if not applicable.", "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "lot_number", "expiration_date" ], "title": "Return Or Receiving Item Lot Output" }, "Fulfillment_IntegrationsBundle_Crate_ReturnOrReceivingItemProductPublicApiOutput": { "type": "object", "properties": { "id": { "description": "Server-assigned numeric identifier of the product.", "type": "integer" }, "sku": { "description": "Stock Keeping Unit (SKU), the client's unique product code.", "type": "string" }, "name": { "description": "Human-readable name of the product.", "type": "string" } }, "required": [ "id", "sku", "name" ], "title": "Return Or Receiving Item Product Output" }, "ShipMonk_Warehouse_Returns_Api_Output_PublicApi_PublicApiReturnItemOutput": { "type": "object", "properties": { "receiving_details": { "description": "Per-unit receiving records for this return item, capturing lot, quantities, timestamps, and final disposition.", "type": "array", "items": { "$ref": "#/components/schemas/ShipMonk_Warehouse_Returns_Api_Output_PublicApi_ReturnItemDetailsPublicApiOutput" } }, "desired_action": { "description": "Requested handling for the returned item: received_back_into_inventory or damaged_not_resellable.", "$ref": "#/components/schemas/ShipMonk_Warehouse_Returns_Enum_ReturnItemStatus" }, "product": { "description": "The product identified by this receiving item.", "$ref": "#/components/schemas/Fulfillment_IntegrationsBundle_Crate_ReturnOrReceivingItemProductPublicApiOutput" }, "expected_quantity": { "description": "Total number of units of this product expected to be received.", "type": "integer" }, "received_quantity": { "description": "Total number of units of this product received so far across all batches.", "type": "integer" } }, "required": [ "receiving_details", "desired_action", "product", "expected_quantity", "received_quantity" ], "title": "Return Item Output" }, "ShipMonk_Warehouse_Returns_Api_Output_PublicApi_ReturnEmptyPackageReportPublicApiOutput": { "type": "object", "properties": { "unit_uuid": { "description": "UUID of the return unit that records the empty package.", "type": "string" }, "reported_at": { "description": "Timestamp when the warehouse reported the package as empty and disposed of it, in ISO 8601 format.", "type": "string", "format": "date-time" } }, "required": [ "unit_uuid", "reported_at" ], "title": "Return Empty Package Report Output" }, "ShipMonk_Warehouse_Returns_Api_Output_PublicApi_ReturnFraudulentUnitPublicApiOutput": { "type": "object", "properties": { "unit_uuid": { "description": "UUID of the return unit the warehouse reported.", "type": "string" }, "classification": { "description": "What the warehouse found instead of the returned product: fraudulent (an item that is not the merchant's, such as a counterfeit or a substitute) or unknown_merchant_item (an item that may be the merchant's but was not part of this return).", "$ref": "#/components/schemas/ShipMonk_Warehouse_Returns_Enum_FlaggedUnitReportClassification" }, "final_disposition": { "description": "Final disposition of the reported unit; reported units are disposed of.", "$ref": "#/components/schemas/ShipMonk_Warehouse_Returns_Enum_ReturnItemFinalDisposition" }, "received_at": { "description": "Timestamp when the warehouse finished reporting the unit at the grading station, in ISO 8601 format.", "type": "string", "format": "date-time" } }, "required": [ "unit_uuid", "classification", "final_disposition", "received_at" ], "title": "Return Fraudulent Unit Output" }, "ShipMonk_Warehouse_Returns_Api_Output_PublicApi_ReturnItemDetailsPublicApiOutput": { "type": "object", "properties": { "lot": { "description": "Lot/batch tracking data for the units in this receipt entry, or null if no lot is tracked.", "anyOf": [ { "$ref": "#/components/schemas/Fulfillment_IntegrationsBundle_Crate_ReturnOrReceivingItemLotPublicApiOutput" }, { "type": "null" } ] }, "expected_quantity": { "description": "Number of units expected in this lot/batch entry.", "type": "integer" }, "received_quantity": { "description": "Number of units actually received in this lot/batch entry.", "type": "integer" }, "received_at": { "description": "Timestamp when this batch was received at the warehouse, in ISO 8601 format. Null if not yet received.", "type": [ "string", "null" ], "format": "date-time" }, "type_scoped_id": { "description": "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": [ "integer", "null" ] }, "type": { "description": "Type of the receiving detail record: receive (standard warehouse receipt) or return_unit (unit processed by the returns flow, including historical units sourced from the legacy Optoro flow).", "$ref": "#/components/schemas/ShipMonk_Warehouse_Returns_Api_Output_PublicApi_ReturnItemDetailsType" }, "unit_uuid": { "description": "UUID of the return unit this record originates from; only present for unit-sourced records.", "type": [ "string", "null" ] }, "final_disposition": { "description": "Final disposition decided for the unit after inspection (e.g. restocked, damaged); null while disposition is pending.", "anyOf": [ { "$ref": "#/components/schemas/ShipMonk_Warehouse_Returns_Enum_ReturnItemFinalDisposition" }, { "type": "null" } ] } }, "required": [ "lot", "expected_quantity", "received_quantity", "received_at", "type_scoped_id", "type", "unit_uuid", "final_disposition" ], "title": "Return Item Details Output" }, "ShipMonk_Warehouse_Returns_Api_Output_PublicApi_ReturnItemDetailsType": { "type": [ "string" ], "enum": [ "receive", "return_unit" ], "title": "Return Item Details Type" }, "ShipMonk_Warehouse_Returns_Api_Output_PublicApi_ReturnOutput": { "type": "object", "properties": { "id": { "description": "Unique numeric identifier of the return.", "type": "integer" }, "warehouse": { "description": "Code of the warehouse handling this return.", "type": "string" }, "order_key": { "description": "External order key of the original order this return relates to; null when no linked order exists.", "type": [ "string", "null" ] }, "store_id": { "description": "Identifier of the store the return belongs to; null if the return is not linked to a store.", "type": [ "integer", "null" ] }, "rma": { "description": "Return Merchandise Authorization (RMA) number identifying this return.", "type": "string" }, "tracking_number": { "description": "Primary carrier tracking number of the return shipment; null if not yet known. Set to the most recently added of tracking_numbers.", "type": [ "string", "null" ] }, "tracking_numbers": { "description": "All carrier tracking numbers associated with the return shipment; empty when none are known.", "type": "array", "items": { "type": "string" } }, "status": { "description": "Current processing status of the return: status_created, in_progress, en_route, returned, arrived, not_arrived, or grading_completed.", "$ref": "#/components/schemas/ShipMonk_Warehouse_Returns_Enum_ReturnStatus" }, "return_reason": { "description": "Reason the return was initiated: exchange, changed_mind, undeliverable, unknown, or incorrect_product.", "$ref": "#/components/schemas/ShipMonk_Warehouse_Returns_Enum_ReturnReason" }, "note": { "description": "Optional free-text note attached to the return; null when no note was provided.", "type": [ "string", "null" ] }, "created_at": { "description": "ISO 8601 timestamp when the return record was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "ISO 8601 timestamp when the return record was last updated.", "type": "string", "format": "date-time" }, "received_at": { "description": "ISO 8601 timestamp when the return was physically received at the warehouse; null until received.", "type": [ "string", "null" ], "format": "date-time" }, "items": { "description": "Line items included in the return, each with expected and received quantities.", "type": "array", "items": { "$ref": "#/components/schemas/ShipMonk_Warehouse_Returns_Api_Output_PublicApi_PublicApiReturnItemOutput" } }, "fraudulent_units": { "description": "Units the warehouse found in the return that the merchant never sent, such as a counterfeit or a substitute item, in the order they were reported; empty when nothing was reported. They are not part of items, because no return item describes them.", "type": "array", "items": { "$ref": "#/components/schemas/ShipMonk_Warehouse_Returns_Api_Output_PublicApi_ReturnFraudulentUnitPublicApiOutput" } }, "empty_package_report": { "description": "Present when the warehouse reported that the return package arrived empty; null otherwise.", "anyOf": [ { "$ref": "#/components/schemas/ShipMonk_Warehouse_Returns_Api_Output_PublicApi_ReturnEmptyPackageReportPublicApiOutput" }, { "type": "null" } ] }, "custom_data": { "description": "List of custom name/value pairs attached to the return by the source integration.", "type": "array", "items": { "$ref": "#/components/schemas/Fulfillment_CommonBundle_ApiResource_IntegrationDataOutput" } }, "source": { "description": "System that originated this return record: shipmonk, loop, returnly, deposco, happy_returns_loop, or happy_returns.", "$ref": "#/components/schemas/ShipMonk_Warehouse_Returns_Enum_ReturnEntitySource" } }, "required": [ "id", "warehouse", "order_key", "store_id", "rma", "tracking_number", "tracking_numbers", "status", "return_reason", "note", "created_at", "updated_at", "received_at", "items", "fraudulent_units", "empty_package_report", "custom_data", "source" ], "title": "Return Output" }, "ShipMonk_Warehouse_Returns_Enum_FlaggedUnitReportClassification": { "type": [ "string" ], "enum": [ "fraudulent", "unknown_merchant_item" ], "title": "Flagged Unit Report Classification" }, "ShipMonk_Warehouse_Returns_Enum_ReturnEntitySource": { "type": [ "string" ], "enum": [ "shipmonk", "loop", "returnly", "deposco", "happy_returns_loop", "happy_returns" ], "title": "Return Entity Source" }, "ShipMonk_Warehouse_Returns_Enum_ReturnItemFinalDisposition": { "type": [ "string" ], "enum": [ "reworked", "returned_to_inventory", "return_to_merchant", "dispose", "donate", "other" ], "title": "Return Item Final Disposition" }, "ShipMonk_Warehouse_Returns_Enum_ReturnItemStatus": { "type": [ "string" ], "enum": [ "received_back_into_inventory", "damaged_not_resellable" ], "title": "Return Item Status" }, "ShipMonk_Warehouse_Returns_Enum_ReturnReason": { "type": [ "string" ], "enum": [ "reason_exchange", "reason_changed_mind", "reason_undeliverable", "reason_unknown", "reason_incorrect_product" ], "title": "Return Reason" }, "ShipMonk_Warehouse_Returns_Enum_ReturnStatus": { "type": [ "string" ], "enum": [ "status_created", "in_progress", "en_route", "returned", "arrived", "not_arrived", "grading_completed" ], "title": "Return Status" } } }, "tags": [ { "name": "Webhooks", "description": "ShipMonk supports webhooks to help you stay updated in real time as key events happen in our system. Currently, we provide webhooks for the following areas:\n- Orders\n- Returns\n- Receivings\n\n## Webhooks Setup\nYou have full flexibility in configuring which webhooks to subscribe to. You can:\n- Use a single URL to receive all events, or\n- Define separate endpoints for individual webhook types.\n\nWebhook setup can be done by your ShipMonk support team.\n\n## Store filter\nBy default, a webhook subscription delivers events for all stores in your account. If you operate multiple stores, a subscription can be restricted to one or more specific stores (store filter), so you only receive events for those stores.\n\n## Security\nAll webhooks support HTTP Basic Authentication. If you provide a username and password, ShipMonk will include these credentials in the webhook request. This allows you to restrict access and ensure only ShipMonk can call your endpoints.\n\n## Data Integrity\nEach webhook request sent by ShipMonk includes an `X-Sm-Signature` header. This header allows you to verify that the request genuinely originated from ShipMonk and was not tampered with.\n\nTo enable this verification, you must provide ShipMonk with a secret key (a random string of your choice). For every webhook, ShipMonk uses this secret key to generate a HMAC using the SHA-512 algorithm (HMAC-SHA512), applied to the raw payload. The resulting signature is included in the `X-Sm-Signature` header.\n\nTo validate the authenticity of a webhook:\n- Retrieve the raw payload from the HTTP POST request.\n- Using the same secret key and the HMAC-SHA512 algorithm, generate a signature from the payload.\n- Compare your generated signature to the value in the X-Sm-Signature header.\n- If they match, you can safely trust the request.\n\nThis mechanism ensures both the integrity and authenticity of the webhook payload.\n\n## Accepting the webhook\n\nWebhook requests are sent as HTTP POST requests. To acknowledge successful processing, your endpoint must respond with an HTTP status code in the 2xx range.\n- If a 2xx response is returned, the webhook is considered successfully delivered.\n- For any other response, ShipMonk will retry the webhook delivery up to 8 times using an exponential backoff schedule. The delay starts at 30 seconds and doubles after each attempt — 30s, 1m, 2m, 4m, 8m, 16m, 32m, 60m (capped at 60 minutes) — spanning roughly 2 hours before delivery is abandoned." } ], "servers": [ { "url": "https://api.shipmonk.com", "description": "Once you finish testing on Sandbox, our support team generates you Production API keys and store_id for production. Just write us at api@shipmonk.com and we will handle it." }, { "url": "https://sandbox.shipmonk.dev", "description": "Sandbox environment is used for preproduction testing. It allows you to play around without worries of corrupting the data. We highly recommend using the Sandbox environment and run tests before going to Production. To get access to the Sandbox, please contact the ShipMonk support team. Note: Sandbox access can only be requested by customers with signed contracts." } ], "webhooks": { "returnStatusChange": { "post": { "operationId": "webhook-return-status-change", "summary": "Return status change", "tags": [ "Webhooks" ], "description": "## Supported Return Webhooks\nAll 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.\n\n- Return created (`status`: `status_created`)\n- Return in progress (`status`: `in_progress`)\n- Return en route (`status`: `en_route`)\n- Return returned (`status`: `returned`)\n\n## Payload Structure (JSON Schema)\nThe 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.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipMonk_Warehouse_Returns_Api_Output_PublicApi_ReturnOutput" } } } }, "responses": { "200": { "description": "Return a 2xx status to indicate that the data was received successfully" }, "default": { "description": "For a 4xx status, ShipMonk will retry the webhook delivery up to 100 times, with a 5-minute delay between attempts." } } } } } } ```