Refunds.md

Refunds

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

Refund API reference · All methods