Add Item to Return

POST

/api/v1/returns/:id/items

POST

/api/v1/returns/:id/items

$ curl -X POST https://api.getply.com/api/v1/returns/d6e7f8a9-b0c1-2345-defa-678901234567/items \
>      -H "API_KEY: <apiKey>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "materialId": "e5f6a7b8-c9d0-1234-efab-345678901234",
>   "price": 25,
>   "deliveredQuantity": 3,
>   "materialVariationId": "b8c9d0e1-f2a3-4567-bcde-678901234567",
>   "note": "All three damaged on arrival"
> }'

1 {
2   "id": "e7f8a9b0-c1d2-3456-efab-789012345678",
3   "material": {
4     "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
5     "name": "3/4 inch PVC Pipe (10ft)"
6   },
7   "variation": {
8     "id": "b8c9d0e1-f2a3-4567-bcde-678901234567",
9     "name": null
10   },
11   "price": 25,
12   "deliveredQuantity": 3,
13   "note": "All three damaged on arrival",
14   "createdAt": "2026-03-20T14:30:00Z",
15   "updatedAt": "2026-03-20T14:30:00Z"
16 }

Adds a material line item to a return. Returns 201 Created.

Requires scope: returns:write

Authentication

API_KEYstring

API Key authentication via header

Path parameters

idUUIDRequired

Return ID.

Request

This endpoint expects an object.

materialIdUUIDRequired

ID of the material to return. Required.

pricedoubleRequired

Unit price of the material. Required. Must be zero or greater.

deliveredQuantitydoubleRequired

Quantity to return. Required. Must be greater than zero.

materialVariationIdUUIDOptional

ID of the material variation to return. Optional.

notestringOptional

Optional note for this line item.

Response

This endpoint returns an object.

idUUID

Unique identifier for this return item record.

materialobject

Reference to the parent material.

variationobject

Reference to the material variation, if applicable.

pricedouble

Unit price of the material at time of return.

deliveredQuantitydouble

Quantity being returned. Must be greater than zero.

notestring

Optional note for this line item.

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