Read what disputes cost the hotel in a year, and who paid
const url = 'https://api.aerandil.com/v1/merchant-accounts/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/dispute-costs?year=example';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://api.aerandil.com/v1/merchant-accounts/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/dispute-costs?year=example' \ --header 'Authorization: Bearer <token>'The account’s dispute cases opened in a year, per currency: how many, how many the house fought, won and lost, what was disputed and what was lost, and the network’s dispute fees by who carried them — the platform (platform_dispute_cost: the received fee the processor never returns, plus every fee not passed through) and the hotel (dispute_fee_recovered, less a late win’s refund). Under the published dispute line — Stripe’s £20 received and £20 countered, the second back on a win, and neither on a lost case the kernel built — this is the hotel’s own evidence of it. The general manager’s read (analytics:read, from a desk shift at the house — another house’s account is a 403 property_out_of_scope) or the operator’s (tenant_admin:write).
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The property’s merchant account.
Query Parameters
Section titled “Query Parameters”The year the cases were opened in, YYYY.
Responses
Section titled “Responses”The year’s dispute cases and costs on the account.
object
object
Cases opened in the year.
ISO 4217 code of the cases’ disputed amounts.
The sum of the disputed amounts.
The dispute fees recovered from the hotel, less what a late win handed back.
The network’s dispute fees the platform carried: the received fee the processor never returns, and every fee not passed through to the hotel (a written-off fee, a waived one).
Cases lost under the dispute-fee waiver: certified when their evidence was submitted, so neither of the network’s fees was passed to the hotel (dispute_fee_recovery = waived).
Cases whose fee the hotel’s balance could not cover after the card rail’s last retry, or a person settled as not there (dispute_fee_recovery = written_off): the platform carries it.
Cases whose evidence reached the processor.
The disputed amounts of the cases lost.
Cases not yet decided.
Cases won, or prevented before they were filed.
Examplegenerated
{ "dispute_costs": [ { "cases": 1, "currency": "example", "disputed": "example", "fees_carried_by_hotel": "example", "fees_carried_by_platform": "example", "fees_waived": 1, "fees_written_off": 1, "fought": 1, "lost": 1, "lost_amount": "example", "open": 1, "won": 1 } ], "merchant_account_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "property_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "year": 1}Headers
Section titled “Headers”Always no-store. Object and link state is live data and is never cacheable.
The bearer authenticated but does not hold the scope this operation requires.
Structured error wrapper. Every non-2xx response from any Aerandil endpoint serialises to this shape; the HTTP status carries the failure class (4xx/5xx), the body adds a stable code for programmatic dispatch plus a human-readable message.
object
object
Stable, programmatic error code (e.g. unauthorized, forbidden, not_found, invalid_body, invalid_url, precondition_failed, no_secondary_key). Clients dispatch on code, not on the message (which may be localised or contextualised in future versions).
Request-id correlation handle echoed on the request-id response header — support teams correlate without scraping logs.
Human-readable explanation of the failure.
Per-error structured detail. The shape varies by code (e.g. forbidden_action carries {"action": "..."}; precondition_failed carries {"current_version": N}).
Examplegenerated
{ "error": { "code": "example", "instance_id": "example", "message": "example", "parameters": "example" }}No such object in the caller’s tenant — which is also the answer when it exists in another tenant, by design.
Structured error wrapper. Every non-2xx response from any Aerandil endpoint serialises to this shape; the HTTP status carries the failure class (4xx/5xx), the body adds a stable code for programmatic dispatch plus a human-readable message.
object
object
Stable, programmatic error code (e.g. unauthorized, forbidden, not_found, invalid_body, invalid_url, precondition_failed, no_secondary_key). Clients dispatch on code, not on the message (which may be localised or contextualised in future versions).
Request-id correlation handle echoed on the request-id response header — support teams correlate without scraping logs.
Human-readable explanation of the failure.
Per-error structured detail. The shape varies by code (e.g. forbidden_action carries {"action": "..."}; precondition_failed carries {"current_version": N}).
Examplegenerated
{ "error": { "code": "example", "instance_id": "example", "message": "example", "parameters": "example" }}year is missing or not YYYY.
Structured error wrapper. Every non-2xx response from any Aerandil endpoint serialises to this shape; the HTTP status carries the failure class (4xx/5xx), the body adds a stable code for programmatic dispatch plus a human-readable message.
object
object
Stable, programmatic error code (e.g. unauthorized, forbidden, not_found, invalid_body, invalid_url, precondition_failed, no_secondary_key). Clients dispatch on code, not on the message (which may be localised or contextualised in future versions).
Request-id correlation handle echoed on the request-id response header — support teams correlate without scraping logs.
Human-readable explanation of the failure.
Per-error structured detail. The shape varies by code (e.g. forbidden_action carries {"action": "..."}; precondition_failed carries {"current_version": N}).
Examplegenerated
{ "error": { "code": "example", "instance_id": "example", "message": "example", "parameters": "example" }}