Skip to main content
POST
Create resend by SKU
This is an Enterprise-only feature, enabled only for Return Helper Enterprise customers with the SKU inventory module. Requests from accounts that are not enabled are denied. To learn more, contact enterprise-solution@returnhelper.com.
Creates a resend by supplying warehouse-scoped SKU quantities instead of explicit return inventory IDs. The request is processed atomically — either every requested unit is allocated and a single resend is created, or nothing is created and the call fails. There is no partial resend.

​
When to use this vs. Create resend order

  • Use Create resend by SKU when you track stock by SKU and quantity and don’t want to manage individual returnInventoryId values.
  • Use Create resend order when you already hold the specific returnInventoryId values (e.g. cached from the newInventoryCreated webhook) that you want to resend.

​
Prerequisites

  • Your account is enabled for the SKU inventory module (Enterprise).
  • Enough resend-eligible inventory exists for each requested SKU in that warehouse. Check the summary first with Search SKU inventory (availableQuantity), but note that passing the summary check is not a guarantee — see below.
  • shipmentServiceType is a shipment service type (not a return service type). Fetch valid codes from Get available shipment service types for warehouse.

​
How selection works

Allocation happens in three stages, and only the last one is authoritative:
  1. Validation. Your request lines are normalized (trim + uppercase SKU) and duplicate SKUs are combined. Validation checks availableQuantity per warehouseId + normalized SKU. Passing this only confirms the summary looks sufficient — it does not reserve or allocate anything.
  2. Selection. The service queries real return inventory records that match your warehouseId, and normalized SKU and are resend-eligible, then selects exactly the requested quantity using the pick-up strategy. If fewer eligible records exist than requested, the whole request is rejected.
  3. Allocation. Inside a transaction the selected rows are locked and re-checked; if any is no longer eligible the transaction rolls back and the call fails. Otherwise all selected records are advanced to resend / in-progress and the resend is created in the same transaction.
SkuInventory.availableQuantity is an early check, not a reservation. Multiple concurrent requests can all pass the same summary check; only the one that successfully locks and claims the underlying records commits. The others fail with a validation error and can be retried. The locked allocation is always the final authority.

​
Eligibility rules

A return inventory record is eligible for selection only when it:
  • matches the requested warehouseId, and the normalized SKU;
  • has handlingStatusCode = pending;
  • can transition to resend / in-progress; and
  • has no pending VAS, including any unfinished VAS Split.
Because eligibility is status-based, the MySQL-eligible count can be lower than availableQuantity from the summary (which may still count records with pending VAS). When it is, the request fails closed rather than resending an ineligible item.

​
Pick-up strategy

Selection uses LIFO by default: newest createOn first, with the highest return inventory ID as the tie-breaker. The strategy sits behind a factory so it can be switched to FIFO in future without changing allocation logic.

​
Errors and retries

  • Validation failures come back as HTTP 200 with meta.status: 400 (the standard soft-error envelope — see Error handling).
  • When a SKU has insufficient available quantity, the request is rejected as a whole. For security, the error does not disclose remaining available quantities.
  • When concurrent requests contend for the same stock, the request that fails to lock the records is rejected and can be retried.
  • Search SKU inventory — check availableQuantity before requesting.
  • Create resend order — resend by explicit return inventory IDs; also covers label generation (auto vs manual service types) and cancellation cut-off, which apply to the resend created here too.
  • Cancel resend order — abort before the warehouse dispatches.
  • Webhooks — the resend-status-update event delivers lifecycle changes to your endpoint.

Authorizations

​
x-rr-apikey
string
header
required

Your API key

​
x-rr-apitoken
string
header
required

Your API token — keep this private

Body

application/json

Create a resend by warehouse-scoped SKU quantities. companyName is not part of this request.

​
warehouseId
integer<int32>
required

Warehouse to fulfil the resend from. Must be greater than 0 and owned by the authenticated account. All selected inventory comes from this single warehouse.

​
shipmentServiceType
string
required

Shipment service type code (not a return service type). Non-others values are validated against the available shipment service and service zone for the warehouse and destination.

​
itemList
object[]
required

Non-empty list of SKU + quantity lines. The number of raw lines is limited to 100; the combined quantity across all lines is limited to 100.

​
toAddress
object
required

Destination address for the resend shipment.

​
sellerReferenceNumber
string

Optional seller reference number. When provided, 1-50 characters with no invisible characters. Stored on the created resend shipment and echoed back in the response.

Maximum string length: 50
​
description
string

Optional free-text description for the resend order.

​
remarks
string

Optional free-text merchant remarks for the resend order.

​
warehouseRemarks
string

Optional free-text remarks addressed to the warehouse.

Response

Success

Wraps CreateResendBySkuReply under data, alongside the standard correlationId and meta envelope.

​
data
object

Create resend by SKU result.