Create Return | Ply | API Documentation

curl -X POST https://api.getply.com/api/v1/returns \
     -H "API_KEY: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "returnNumber": "RET-1001",
  "purchaseOrderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "locationId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "note": "3 pipes arrived damaged.",
  "returnDate": "2026-03-25",
  "items": [
    {
      "materialId": "e5f6a7b8-c9d0-1234-efab-345678901234",
      "price": 25,
      "deliveredQuantity": 3,
      "materialVariationId": "b8c9d0e1-f2a3-4567-bcde-678901234567"
    }
  ]
}'

{
  "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": null,
  "note": "3 pipes arrived damaged.",
  "totalMaterialsCost": 75,
  "totalFees": 0,
  "finalPrice": 75,
  "returnDate": "2026-03-25",
  "createdAt": "2026-03-20T14:30:00Z",
  "updatedAt": "2026-03-20T14:30:00Z"
}

Creates a new return in DRAFT status.

Requires scope: returns:write

Authentication

API_KEYstring

API Key authentication via header

Request

This endpoint expects an object.

returnNumberstringRequired

Human-readable reference number for the return. Required.

purchaseOrderIdUUIDRequired

ID of the originating purchase order. Required.

locationIdUUIDRequired

ID of the location associated with this return. Required.

trackingNumberstringOptional

Shipping carrier tracking number.

notestringOptional

Notes about this return.

returnDatedateOptional

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

itemslist of objectsOptional

Initial line items. Items can also be added after creation.

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