Python SDK
Refunds
Refunds reverse some or all of an order.
Refunds reverse some or all of an order. Create them through client.orders, not
client.refunds. The top-level refunds resource is for reads.
Examples accept the client from setup.
Issue a full refund
from vatly import RequestOptions, VatlyClient
def example(client: VatlyClient):
refund = client.orders.create_full_refund(
"order_example",
{},
options=RequestOptions(idempotency_key="refund:request-42"),
)
return refund.id, refund.status
Keep the same key for retries of this refund. A timeout does not prove it failed; read the existing refund/order before deciding to issue another.
| Operation | Inputs | Return |
|---|---|---|
orders.create_full_refund | order ID, {} or optional metadata | Refund |
orders.create_refund | order ID, {"items": [...]}; optional metadata | Refund |
orders.cancel_refund | order ID, refund ID | None |
refunds.get | refund ID | Refund |
Refund part of a line
from vatly import RequestOptions, VatlyClient
def example(client: VatlyClient):
return client.orders.create_refund(
"order_example",
{
"items": [
{"itemId": "order_item_example", "amount": {"value": "5.00", "currency": "EUR"}}
],
},
options=RequestOptions(idempotency_key="partial-refund:42"),
)
itemId must be an original order line ID. amount is before tax and must not
exceed that line's remaining refundable amount. Preserve the order currency and
use decimal strings, never rounded floats. Vatly calculates the tax reversal.
Read and cancel a pending refund
from vatly import VatlyClient
def example(client: VatlyClient):
refunds = list(client.refunds.list_all({"limit": 25}))
scoped = list(client.orders.list_all_refunds("order_example"))
refund = client.orders.get_refund("order_example", "refund_example")
client.orders.cancel_refund("order_example", refund.id)
return refunds, scoped
Cancellation is only allowed while Vatly permits it; it is not a reversal of a completed refund. Signed refund events confirm completion, failure or cancellation.
| Response field | Meaning |
|---|---|
id, status | Refund identifier and state |
original_order_id | Order being reversed |
lines | Refunded lines and financial details |
testmode, metadata | Mode and custom data |