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:00",
  "updatedAt": "2026-03-20T15:00:00"
}

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. Omitted or null leaves the current value unchanged.

notestringOptional

Updated notes. Omitted or null leaves the current value unchanged.

returnDatedateOptional

Updated return date. Omitted or null leaves the current value unchanged.

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.

returnNumberstringOptional

Human-readable reference number for the return.

purchaseOrderobjectOptional

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

locationobjectOptional

Reference to the location associated with this return.

trackingNumberstringOptional

Shipping carrier tracking number for the return shipment.

notestringOptional

Free-text notes about this return.

totalMaterialsCostdoubleOptional

Sum of all line item costs.

totalFeesdoubleOptional

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

finalPricedoubleOptional

Final total after materials cost and fees.

returnDatedateOptional

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

createdAtdatetimeOptional

ISO 8601 timestamp when the record was created.

updatedAtdatetimeOptional

ISO 8601 timestamp when the record was last updated.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

429

Rate Limit Error