Transfers

Move loyalty points and perks from one membership to another. Every transfer follows a two-step preview → execute pattern: you first call the preview endpoint to see the outcome of a proposed transfer without changing any balances, then call the execute endpoint to commit it. After a transfer runs you can list the source membership's transfer history or fetch a single transfer by its ID.

All transfer endpoints are scoped to a source membership ({membership_id} in the path) and require white-label authentication:

• Authorization: Bearer <JWT> — the end-user token issued by your OAuth2 flow
• X-App-Id: <uuid> (or X-App-Slug: <slug>) — identifies your white-label app
• X-Environment: Sandbox | Production — selects the environment

Preview a Transfer

POST /v1/memberships/{membership_id}/transfers/preview

Previews the result of a proposed point transfer without any side effects — no balances are debited or credited, and no transfer record is created. Use this to show the user what a transfer would cost and produce before they confirm. The preview reflects the same validation the execute step applies, so a preview that succeeds indicates the transfer is expected to go through.

The request body is sent as JSON and is required. The transfer request schema is not yet published in the OpenAPI specification, so the exact body fields are defined by the transfers service rather than this document. Send the same body you intend to pass to the execute endpoint.

curl -X POST 'https://cloud.vanitypass.com/v1/memberships/{membership_id}/transfers/preview' \
  -H 'Content-Type: application/json' \
  -H 'X-Environment: Sandbox' \
  -d '{}'

Execute a Transfer

POST /v1/memberships/{membership_id}/transfers

Executes a point transfer between memberships. Unlike preview, this commits the transfer: it debits the source membership, credits the destination, and creates a transfer record you can later retrieve. Call Preview a Transfer first with the same body to confirm the outcome before committing.

The request body is sent as JSON and is required. The transfer request schema is not yet published in the OpenAPI specification, so the exact body fields are defined by the transfers service rather than this document.

curl -X POST 'https://cloud.vanitypass.com/v1/memberships/{membership_id}/transfers' \
  -H 'Content-Type: application/json' \
  -H 'X-Environment: Sandbox' \
  -d '{}'

List Transfer History

GET /v1/memberships/{membership_id}/transfers

Lists the transfer history for a membership. Returns the transfers associated with the given membership so you can display a ledger of past point movements.

curl -X GET 'https://cloud.vanitypass.com/v1/memberships/{membership_id}/transfers' \
  -H 'Content-Type: application/json' \
  -H 'X-Environment: Sandbox' \

Get a Transfer

GET /v1/memberships/{membership_id}/transfers/{transfer_id}

Fetches a single transfer by its ID, scoped to the membership. Use this to look up the details of a specific transfer, for example after executing one or from an entry in the transfer history.

curl -X GET 'https://cloud.vanitypass.com/v1/memberships/{membership_id}/transfers/{transfer_id}' \
  -H 'Content-Type: application/json' \
  -H 'X-Environment: Sandbox' \