JavaScript SDK
Refunds
A refund returns funds to a customer for an order.
A refund returns funds to a customer for an order. Refunds are created against an order (see Orders); the top-level refunds resource lets you list and retrieve them across all orders.
For all fields and options, see the Refunds API reference and creating order refunds. The OpenAPI spec is also available for tooling.
The Refund resource
| Name | Type | Description |
|---|---|---|
id | string | Unique identifier (refund_…). |
customerId | string | The customer being refunded. |
originalOrderId | string | The order this refund is against. |
status | string | pending, queued, processing, refunded, failed, or canceled. The success event is refund.completed, but the status is refunded. |
total | Money | Gross amount refunded (incl. tax). |
subtotal | Money | Net amount refunded (excl. tax). |
taxSummary | array | Per-rate VAT breakdown of the refund. |
testmode | boolean | Whether this is a test refund. |
Retrieve a refund
GET /v1/refunds/{refundId}
const refund = await vatly.refunds.get("refund_abc123");
List refunds
GET /v1/refunds
const page = await vatly.refunds.list({ limit: 25 });
for await (const refund of vatly.refunds.listAll()) {
// ...
}
Creating refunds
Create refunds against an order with orders.createRefund / orders.createFullRefund:
await vatly.orders.createRefund("order_abc123", {
items: [{ itemId: "order_item_abc123", amount: { value: "15.00", currency: "EUR" } }],
});
await vatly.orders.createFullRefund("order_abc123");
Listen for the refund.completed / refund.failed / refund.canceled webhooks
to reconcile your local records — the webhook payload carries the full tax
breakdown, so no follow-up call is needed.