Refunds

A refund returns funds to the original payment method after settlement. Refunds are distinct from voids which cancel pre-settlement payments.

Create a refund

POST /pos/v1/orders/{order_id}/payments/{payment_id}/refunds

Required scopes: tilt/payments:refund

Request body

{
  "amount_cents": 2500,
  "reason": "customer_request"
}

Field	Type	Required	Description
amount_cents	integer	Yes	Amount to refund in cents. Must be ≤ the payment amount minus already-refunded amount.
reason	string	No	Reason code. One of: customer_request, duplicate, fraudulent, other.

Response

{
  "refund_id": "uuid",
  "payment_id": "uuid",
  "order_id": "uuid",
  "status": "pending",
  "amount_cents": 2500,
  "reason": "customer_request",
  "created_at": "2024-01-16T09:00:00Z"
}

Refunds are processed asynchronously. Subscribe to the payment.refunded webhook event for completion notification.

Get a refund

GET /pos/v1/orders/{order_id}/payments/{payment_id}/refunds/{refund_id}

Required scopes: tilt/payments:read

Refund statuses

Status	Description
pending	Submitted to processor
approved	Processor confirmed the refund
failed	Processor rejected the refund (see processor_message)

Note

Partial refunds are supported. You can issue multiple partial refunds against a single payment as long as the total does not exceed the original payment amount. Each partial refund fires a separate payment.refunded webhook event.

Caution

Refund availability depends on the processor’s settlement window. Some processors reject refunds on payments older than 90–180 days. The API returns 409 Conflict with error: refund_window_expired in that case.