Annual credits, certificates, and free-night awards: what a card grants and what's already been used.
clear_credit_usage
Remove credit usage an agent recorded -- the retraction half of set_credit_usage. Requires reconciliation write access, like it.
Scope
Quota
miles:write:reconcile
standard
Name
Type
Required
Description
entries
object[]
required
A list of rows to remove, one per credit and period, even for a single row. Each row is {credit_id, period, card_id?, card_name?}; period is required, in the label the credit's own frequency produces (2026-08 monthly, 2026-Q3 quarterly).
get_certificates
Companion certificates and lounge-pass bundles across the wallet -- what's pending, available, used, or expired, plus an estimated total value. The quantity-aware sibling of get_free_nights (a lounge-pass bundle grants more than one use; a companion fare does not).
Scope
Quota
miles:read
standard
Name
Type
Required
Description
status
string
Filter to one status: pending, available, used, expired, may_have_expired, unconfirmed, or dismissed. Omit for every certificate on file; to answer whether one has been used, omit it and read each row's own status.
program
string
Filter by loyalty program name, matched as a substring, e.g. Hilton. Omit for every program.
get_credit_usage
Which of the wallet's recurring card credits are still unused this period -- the read half of the reconciliation loop get_reconciliation_needs opens.
Scope
Quota
miles:read
standard
Name
Type
Required
Description
card_name
string
Limit the result to one wallet card, matched fuzzily by name. Omit for every card's credits.
only_unused
boolean
When true, drops rows whose status is used or unknown -- both already-resolved questions -- leaving only the credits still open this period.
include_record
boolean
When true, adds value_record: each card's last 12 months of recorded credit use, with every closed period's source and, for an agent's write, the client_id of the app that wrote it. Without Membership it is value_record_locked: true instead. Off, the payload is unchanged.
category
string
Limit to credits of this kind, e.g. 'dining'. 'travel' includes airline, hotel, car-rental and Global Entry/TSA credits. 'any' or omit for every credit.
get_free_nights
Free-night hotel certificates across the wallet (Marriott/Hilton/ Hyatt/IHG-style annual and spend-triggered certs): status (available/pending/used/expired/may_have_expired/unconfirmed/unknown), estimated expiry, and estimated value.
Scope
Quota
miles:read
standard
Name
Type
Required
Description
status
string
Filter to one status: available, pending, used, expired, may_have_expired, unconfirmed, or unknown. Omit for every certificate on file; to answer whether one has been used, omit it and read each row's own status.
program
string
Filter by hotel loyalty program name, e.g. Marriott Bonvoy. Omit for every program.
set_certificate_status
Record a companion certificate or lounge-pass bundle's status. Requires reconciliation write access (the narrower of the two write grants -- see get_reconciliation_needs's own docstring).
Scope
Quota
miles:write:reconcile
standard
Name
Type
Required
Description
card_id
string
required
The exact card_id from the certificate's get_certificates row, e.g. cc_4. There is no fuzzy card-name lookup here.
cert_id
string
required
The exact cert_id from the certificate's get_certificates row, e.g. companion-fare.
status
string
The new status: pending, available, used, or dismissed. Required UNLESS you are sending note, earned_on or expires_on; omit it then and the saved status is left exactly as it was.
count
integer
For status=used only: how many units of a bundle to mark used on this call; omit for 1. Silently clamped to what is actually left, so read the returned used_count rather than assuming the value landed exactly.
expected_used_count
integer
For status=used only: the used_count you last read from get_certificates. If it no longer matches what is stored, the write is rejected, so a retried or double-sent call is a safe no-op. Pass it on every used call; omit only with no prior read.
used_on
string
For status=used only: the date of use, written YYYY-MM-DD, no later than today and no earlier than the certificate's own earned_on if one is on file.
note
string
The member's own note about this certificate -- what it is for, or where it is already booked ("Maui, March -- booked"). Their words, not a summary; 500 characters max; "" clears it; omit it to leave it alone. A note is never a status.
earned_on
string
The date (YYYY-MM-DD) or month (YYYY-MM) the certificate was earned. Makes the expiry exact. "" clears it.
expires_on
string
The date the certificate really expires, written YYYY-MM-DD, as the member read it off the issuer. May be in the past. "" clears the override and falls back to the estimate.
source
string
Who is attesting the status: agent_reconciled (you found an actual transaction showing the certificate was earned or used) or user_reported (the member told you directly). Defaults to user_reported when omitted.
set_credit_usage
Record which recurring card credits were used, for a batch of periods -- the write half of the reconciliation loop get_reconciliation_needs opens. Requires reconciliation write access (the narrower of the two write grants -- see get_reconciliation_needs's own docstring).
Scope
Quota
miles:write:reconcile
standard
Name
Type
Required
Description
entries
object[]
required
A list of rows, one per credit and period, even for a single row. Each row is {credit_id, status, card_id?, card_name?, period?, amount_used?}; status is used, partial (needs amount_used, in dollars), unused, or unknown. period is the label the credit's own frequency produces: 2026-08 for a monthly or cardmember-year credit, 2026 for calendar-year, 2026-Q3 quarterly, 2026-H1 semi-annual. Any source field is discarded; every row is stamped agent_reconciled. Replaying the same batch overwrites in place.
only_if_absent
boolean
When true, a period that already has an answer is left alone and comes back skipped with reason: "already_recorded" and the existing entry.
overwrite
boolean
When true, a row replaces an answer the member recorded themselves. Send it only when the member told you, in this conversation, to replace their answer; otherwise such a row comes back skipped with reason: "member_recorded".
set_free_night_status
Record a free-night certificate as used, or confirm a pending spend-threshold certificate was earned. Requires reconciliation write access (the narrower of the two write grants -- see get_reconciliation_needs's own docstring).
Scope
Quota
miles:write:reconcile
standard
Name
Type
Required
Description
status
string
The new status: pending, available (a pending spend-threshold certificate was confirmed earned), used, dismissed, or unknown (you searched for matching spend and could not determine whether it was earned). Required UNLESS you are sending note, earned_on or expires_on; omit it then and the saved status is left exactly as it was.
card_name
string
Identify the card by name, matched fuzzily -- the everyday form. Required unless card_id is given; cannot be combined with source.
cert_id
string
The certificate's id from its get_free_nights row, e.g. anniversary or spend_30k. Required when the card carries more than one free-night certificate, and always required alongside card_id; never guess between certificates.
used_on
string
The date the certificate was used, written YYYY-MM-DD, no later than today.
card_id
string
Identify the card exactly by the card_id a get_free_nights or get_reconciliation_needs row carries, e.g. cc_5. Requires cert_id; the only form that accepts source.
note
string
The member's own note about this certificate -- what it is for, or where it is already booked ("Maui, March -- booked"). Their words, not a summary; 500 characters max; "" clears it; omit it to leave it alone. A note is never a status.
earned_on
string
The date (YYYY-MM-DD) the certificate was earned. Makes the expiry exact. "" clears it.
expires_on
string
The date the certificate really expires, written YYYY-MM-DD, as the member read it off the issuer. May be in the past. "" clears the override and falls back to the estimate.
source
string
Who is attesting the status: agent_reconciled (you found an actual transaction showing the certificate was earned or used) or user_reported (the member told you directly). Requires card_id, not card_name. Omit for a member's own plain statement.
set_status_entitlement
Record a status-earned certificate or award -- what a member's elite tier grants (milestone nights, upgrade certificates, suite night awards, choice benefits). Requires reconciliation write access.
Scope
Quota
miles:write:reconcile
standard
Name
Type
Required
Description
program_id
string
required
From a get_certificates offer or row.
item_id
string
required
The offer's item_id. For used, a confirmed row's cert_id also works with no option_id.
status
string
required
confirmed or used. There is no decline.
option_id
string
The pick from a choice menu (the offer's option_id). Required for a choice, refused otherwise.
program_year
integer
e.g. 2026. Only when the offer says program_year_required.
period
string
Required for used: the row's period, e.g. 2026.
count
integer
For used: units used; omit for 1. Clamped.
expected_used_count
integer
For used: the used_count you last read; a mismatch rejects the write, so a retry is safe.
used_on
string
For used: YYYY-MM-DD; defaults to today.
undo_status_entitlement
Take back the last status-entitlement write -- the retraction half of set_status_entitlement. Requires reconciliation write access.
Scope
Quota
miles:write:reconcile
standard
Name
Type
Required
Description
program_id
string
required
As on the write.
item_id
string
required
The row's cert_id, or the offer's item_id with option_id.