Update Return | Ply | API Documentation

curl -X PUT https://api.getply.com/api/v1/returns/d6e7f8a9-b0c1-2345-defa-678901234567 \
     -H "API_KEY: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "trackingNumber": "1Z999AA10123456784"
}'

{
  "id": "d6e7f8a9-b0c1-2345-defa-678901234567",
  "status": "DRAFT",
  "itemCount": 1,
  "assignedUserIds": [],
  "returnNumber": "RET-1001",
  "purchaseOrder": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "PO-2045"
  },
  "location": {
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "name": "Main Warehouse"
  },
  "trackingNumber": "1Z999AA10123456784",
  "note": "3 pipes arrived damaged.",
  "totalMaterialsCost": 75,
  "totalFees": 0,
  "finalPrice": 75,
  "returnDate": "2026-03-25",
  "createdAt": "2026-03-20T10:00:00Z",
  "updatedAt": "2026-03-20T15:00:00Z"
}

Updates mutable fields on an existing return. Only fields included in the request body are modified.

Requires scope: returns:write

Authentication

API_KEYstring

API Key authentication via header

Path parameters

idUUIDRequired

Return ID.

Request

This endpoint expects an object.

returnNumberstringOptional

Updated reference number.

trackingNumberstringOptional

Updated tracking number. Pass null to clear.

notestringOptional

Updated notes. Pass null to clear.

returnDatedateOptional

Updated return date. Pass null to clear.

locationIdUUIDOptional

Updated location ID.

Response

This endpoint returns an object.

idUUID

Unique identifier for the return.

statusenum

Current lifecycle status of the return.

itemCountinteger

Number of line items in this return.

assignedUserIdslist of UUIDs

IDs of users assigned to this return.

returnNumberstring

Human-readable reference number for the return.

purchaseOrderobject

Reference to the originating purchase order (ID and order number as name).

locationobject

Reference to the location associated with this return.

trackingNumberstring

Shipping carrier tracking number for the return shipment.

notestring

Free-text notes about this return.

totalMaterialsCostdouble

Sum of all line item costs.

totalFeesdouble

Additional fees associated with the return (e.g. restocking fees).

finalPricedouble

Final total after materials cost and fees.

returnDatedate

ISO 8601 date the return was or will be shipped (e.g. 2026-03-25).

createdAtdatetime

ISO 8601 timestamp when the record was created.

updatedAtdatetime

ISO 8601 timestamp when the record was last updated.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error