Credits and certificates

Annual credits, certificates, and free-night awards: what a card grants and what's already been used.

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
`status`	`string`
`program`	`string`

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
`card_name`	`string`
`only_unused`	`boolean`

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), estimated expiry, and estimated value.

Scope	Quota
`miles:read`	standard

Name	Type	Required
`status`	`string`
`program`	`string`

set_certificate_status

Record a companion certificate or lounge-pass bundle's status. Requires wallet-change access.

Scope	Quota
`miles:write`	standard

Name	Type	Required
`card_id`	`string`	required
`cert_id`	`string`	required
`status`	`string`	required
`count`	`integer`
`expected_used_count`	`integer`
`used_on`	`string`
`source`	`string`

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 wallet-change access.

Scope	Quota
`miles:write`	standard

Name	Type	Required
`entries`	`object[]`	required

set_free_night_status

Record a free-night certificate as used, or confirm a pending spend-threshold certificate was earned. Requires wallet-change access.

Scope	Quota
`miles:write`	standard

Name	Type	Required
`card_name`	`string`
`status`	`string`
`cert_id`	`string`
`used_on`	`string`
`card_id`	`string`
`source`	`string`