Refunds API

List and create refunds for an order. Refunds are recorded against the order
and reflected in its refund_status.

Endpoints

• List Refunds - GET /api/v1/orders/{id}/refunds/
• Create Refund - POST /api/v1/orders/{id}/refunds/

List Refunds

Retrieve the refunds for an order. This endpoint is not paginated.

Endpoint: GET /api/v1/orders/{id}/refunds/

Permission Required: Read

Request

curl -X GET "https://studio.easel.engineering/api/v1/orders/ord_d0b6fmv28q6vn14peun0/refunds/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 200 OK

{
  "data": [
    {
      "id": "ref_d0b6fmv28q6vn14peun0",
      "number": 1,
      "amount": 500,
      "reason": "Damaged item",
      "created_at": "2023-01-03T10:00:00Z"
    }
  ]
}

Create Refund

Refund an amount against an order. The amount must be greater than zero and is
denominated in the store's smallest currency unit.

Endpoint: POST /api/v1/orders/{id}/refunds/

Permission Required: Write

Request Body

{
  "amount": 500,
  "reason": "Damaged item"
}

Request

curl -X POST "https://studio.easel.engineering/api/v1/orders/ord_d0b6fmv28q6vn14peun0/refunds/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-12345" \
  -d '{
    "amount": 500,
    "reason": "Damaged item"
  }'

Response

Status: 201 Created

The response body is empty.

Error Responses

Invalid amount

Status: 400 Bad Request

{
  "error": "Amount must be greater than zero",
  "code": "INVALID_FIELD"
}

Order not found

Status: 404 Not Found

{
  "error": "Resource not found",
  "code": "NOT_FOUND"
}

Refund Object

Fields