openapi: 3.1.0 info: title: ShipMonk Returns API version: v1.024 description: The Returns surface of the ShipMonk public fulfillment API. 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.' tags: - name: Returns paths: /v1/integrations/returns: get: operationId: get-v1-integrations-returns parameters: - in: query name: rma schema: type: string maxLength: 255 pattern: \S required: true description: Return Merchandise Authorization (RMA) number used to look up the return; optional query filter. responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_ReturnOutput' tags: - Returns security: - api_key_header_Api-Key: [] description: DEPRECATED – please use Retrieve List of Returns instead with filter for RMA. deprecated: true summary: Get Return post: operationId: post-v1-integrations-returns parameters: [] responses: '200': description: Success content: application/json: schema: type: object properties: status: type: integer data: type: object properties: message: type: string id: type: integer required: - message - id required: - status - data tags: - Returns security: - api_key_header_Api-Key: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_ReturnInput' summary: Create or Update Return /v1/integrations/returns-list: get: operationId: get-v1-integrations-returns-list parameters: - in: query name: rma schema: type: - string - 'null' maxLength: 255 pattern: \S default: null required: false description: Return only returns whose Return Merchandise Authorization (RMA) number matches this value. - in: query name: return_status schema: anyOf: - $ref: '#/components/schemas/ShipMonk_Warehouse_Returns_Enum_ReturnStatus' - type: 'null' default: null required: false description: Return only returns currently in this status (e.g., in_progress, returned, arrived). - in: query name: warehouse_id schema: type: - integer - 'null' minimum: 1 default: null required: false description: Numeric identifier of the warehouse processing the return; use the value returned by the warehouses endpoint. - in: query name: return_reason schema: anyOf: - $ref: '#/components/schemas/ShipMonk_Warehouse_Returns_Enum_ReturnReason' - type: 'null' default: null required: false description: Return only returns flagged with this reason code (e.g., damaged, wrong_item, no_longer_needed). - in: query name: created_at schema: type: string format: date-time default: null required: false description: Return only returns created at or after this ISO 8601 timestamp. example: '2025-07-24 14:53:00' - in: query name: updated_at schema: type: string format: date-time default: null required: false description: Return only returns updated at or after this ISO 8601 timestamp. example: '2025-07-24 14:53:00' - in: query name: desired_action schema: anyOf: - $ref: '#/components/schemas/ShipMonk_Warehouse_Returns_Enum_ReturnItemStatus' - type: 'null' default: null required: false description: Return only returns whose items have this intended processing action (e.g., damaged_not_resellable, received_back_into_inventory). - in: query name: page schema: type: integer minimum: 1 default: 1 required: false description: 1-based page number to return. Defaults to 1. example: 1 - in: query name: page_size schema: type: integer minimum: 1 maximum: 100 default: 100 required: false description: Number of results per page (default and maximum values are documented at the endpoint level). example: 10 responses: '200': description: Success content: application/json: schema: type: object properties: paginator: $ref: '#/components/schemas/ShipMonk_Api_Output_PaginatorOutput' status: type: integer data: $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_Crate_ReturnsListPublicApiOutput' required: - paginator - status - data tags: - Returns security: - api_key_header_Api-Key: [] summary: Retrieve List of Returns /v1/integrations/sandbox/complete-return: post: operationId: post-v1-integrations-sandbox-complete-return parameters: [] responses: '200': description: Success content: application/json: schema: type: object properties: status: type: integer required: - status tags: - Returns security: - api_key_header_Api-Key: [] description: 'This endpoint simulates the full return lifecycle on Sandbox environment. It can''t be used in production! The return goes through arrival, check-in, receiving, grading, and completion based on the specified completion mode and disposition. ## Completion Modes Completion mode changes how many units are received of the FIRST item in the return. Other items are always fully received. | Mode | Description | Constraint | |------|-------------|------------| | `fully_received` | Receives the complete expected quantity | None | | `short_received` | Receives one less unit than expected | Expected quantity must be greater than 1 | | `excess_received` | Receives one more unit than expected | None | | `partially_received` | Receives only 1 unit regardless of expected quantity | Expected quantity must be greater than 1 | ## Dispositions | Disposition | Constraint | |-------------|------------| | `returned_to_inventory`| None | | `reworked` | Account must have rework feature enabled | | `dispose` | None | | `donate` | None | | `return_to_merchant` | None |' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_Input_CompleteSandboxReturnInput' summary: Complete Return components: schemas: Fulfillment_AccountApiBundle_Input_Return_ReferencesToRelatedOrderInput: type: object properties: order_number: description: Order number to look up among existing orders' references; null disables the lookup. type: - string - 'null' minLength: 1 example: Order-123 search_in_all_stores: description: When true, searches for the related order across all stores. When false, searches only within the store associated with the return. type: boolean required: - order_number - search_in_all_stores title: References To Related Order Input Fulfillment_AccountApiBundle_Input_Return_ReturnIntegrationDataRecordInput: type: object properties: name: type: string minLength: 3 maxLength: 255 value: anyOf: - type: object - type: 'null' required: - name - value title: Return Integration Data Record Input 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_ApiResource_ReturnInput: type: object properties: warehouse: description: Code of the warehouse that will process this return. type: string minLength: 1 example: PA1 rma: description: Return Merchandise Authorization (RMA) number; must be unique per return and is used as the upsert key. type: string minLength: 1 order_key: description: Order key of the original outbound order this return relates to. Optional; supply to link the return to a known order. type: - string - 'null' minLength: 1 example: 327b5abd-017a-4504-a50d-54f1cea80269 store_id: description: Identifier of the store this return belongs to. type: integer example: 123456 return_reason: description: 'Reason code for the return, used for reporting: 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 for internal reference. type: - string - 'null' tracking_number: description: Carrier tracking number of the parcel returning to the warehouse; optional, supply when known to enable inbound matching. Mutually exclusive with tracking_numbers. type: - string - 'null' minLength: 1 tracking_numbers: description: Carrier tracking numbers of the parcels returning to the warehouse; optional, supply when known to enable inbound matching. Mutually exclusive with tracking_number. type: array items: type: string minLength: 1 items: type: array items: $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_ReturnItemInput' custom_data: description: Free-form key/value metadata stored on the return; not interpreted by fulfillment logic and returned as-is in return reads. type: array items: $ref: '#/components/schemas/Fulfillment_AccountApiBundle_Input_Return_ReturnIntegrationDataRecordInput' references_to_related_order: description: Optional lookup criteria used to associate this return with an existing order when order_key is unknown. $ref: '#/components/schemas/Fulfillment_AccountApiBundle_Input_Return_ReferencesToRelatedOrderInput' required: - warehouse - rma - store_id - return_reason - items title: Return Input Fulfillment_IntegrationsBundle_ApiResource_ReturnItemInput: type: object properties: sku: description: Stock Keeping Unit (SKU) of the returned product; must match an existing product. type: string expected_quantity: description: Quantity of this SKU the customer is expected to return; must be a positive integer. type: integer minimum: 1 desired_action: description: 'Requested handling for the item once received: received_back_into_inventory (restock as sellable) or damaged_not_resellable (write off).' $ref: '#/components/schemas/ShipMonk_Warehouse_Returns_Enum_ReturnItemStatus' required: - sku - expected_quantity - desired_action title: Return Item Input Fulfillment_IntegrationsBundle_ApiResource_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/Fulfillment_IntegrationsBundle_Crate_PublicApiReturnItemOutput' 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 - custom_data - source title: Return Output Fulfillment_IntegrationsBundle_Crate_PublicApiReturnItemOutput: type: object properties: 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 receiving_details: description: Per-unit receiving records for this return item, capturing lot, quantities, timestamps, and final disposition. type: array items: $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_Crate_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' required: - product - expected_quantity - received_quantity - receiving_details - desired_action title: Return Item Output Fulfillment_IntegrationsBundle_Crate_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. type: integer type: description: 'Type of the receiving detail record: receive (standard warehouse receipt) or optoro_inventory (record sourced from Optoro inventory).' $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_Crate_ReturnItemDetailsType' 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 - final_disposition title: Return Item Details Output Fulfillment_IntegrationsBundle_Crate_ReturnItemDetailsType: type: - string enum: - receive - optoro_inventory title: Return Item Details Type 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 Fulfillment_IntegrationsBundle_Crate_ReturnsListPublicApiOutput: type: object properties: returns_list: description: Returns matching the query criteria. type: array items: $ref: '#/components/schemas/Fulfillment_IntegrationsBundle_ApiResource_ReturnOutput' required: - returns_list title: Returns List Output Fulfillment_IntegrationsBundle_Input_CompleteSandboxReturnInput: type: object properties: rma: description: Return Merchandise Authorization (RMA) number; must be unique per return and is used as the upsert key. type: string minLength: 1 maxLength: 255 completion_mode: description: 'How the sandbox should simulate return completion: ''fully_received'' (all expected units), ''short_received'' (fewer than expected), ''excess_received'' (more than expected), or ''partially_received'' (partial completion).' $ref: '#/components/schemas/ShipMonk_Warehouse_Returns_Sandbox_Enum_SandboxReturnsCompletionMode' final_disposition: description: 'Simulated final disposition of returned items: ''reworked'', ''returned_to_inventory'', ''return_to_merchant'', ''dispose'', or ''donate''.' $ref: '#/components/schemas/ShipMonk_Warehouse_Returns_Sandbox_Enum_SandboxReturnDisposition' required: - rma - completion_mode - final_disposition title: Complete Sandbox Return Input ShipMonk_Api_Output_PaginatorOutput: type: object properties: total: type: integer pages: type: integer page: type: integer required: - total - pages - page title: Paginator Output 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 ShipMonk_Warehouse_Returns_Sandbox_Enum_SandboxReturnDisposition: type: - string enum: - reworked - returned_to_inventory - return_to_merchant - dispose - donate title: Sandbox Return Disposition ShipMonk_Warehouse_Returns_Sandbox_Enum_SandboxReturnsCompletionMode: type: - string enum: - fully_received - short_received - excess_received - partially_received title: Sandbox Returns Completion Mode securitySchemes: api_key_header_Api-Key: type: apiKey in: header name: Api-Key security: - api_key_header_Api-Key: []