Gift card activity history

A gift card’s activity history shows who bought the card, every change to its status and balance, who it was shared with, and the approval behind the purchase. Read it with objectChangeHistory and objectType: GIFT_CARDS.

Prerequisites: a user access token with the VIEW_OBJECT_CHANGE_HISTORY scope, and the giftCardId of a gift card on the account. See Activity history overview for the full query, response fields, and access rules.

query {
  objectChangeHistory(
    objectType: GIFT_CARDS
    objectId: "3f2a1b0c-9d8e-4f7a-8b6c-5d4e3f2a1b0c"
  ) {
    changeType
    change
    createdAt
    subjectUserId
    approvalId
    actor { userId system applicationId applicationName }
  }
}

Purchase

The gift card records OBJECT_CREATED, with change: {}, when it’s purchased.

How the card was purchased	`actor`	`subjectUserId`
`purchaseGiftCard`	The calling user and the connected application	—
A scheduled purchase	`system: "scheduled-task-handler"`	The user the card was bought for
An approved gift card purchase request	The requester, with `approvalId` set	—
The Fluz web or mobile app	The signed-in user	—

A card bought through an approval also gets the request’s APPROVAL_REQUESTED and APPROVAL_APPROVED events, dated when they happened. A declined request doesn’t buy a card, so there’s no history to read. New gift cards also record OWNER_ASSIGNED for their first owner, and an ACCESS_GRANTED event with "reason": "owner-floor" for the owner’s SPENDER access. See Ownership and access.

Status changes

Archiving or reactivating a gift card records FIELD_CHANGED with field: "status".

Event	`old` → `new`	Made in
Archived	`ACTIVE` → `ARCHIVED`	The Fluz web or mobile app. Marking a card as spent in the web app archives it.
Reactivated	`ARCHIVED` → `ACTIVE`	The Fluz web or mobile app

The actor is the user who made the change. A card with the older used status can show old as USED when the change is made in the web app, or NOT ACTIVE when it’s made in the mobile app.

Balance changes

Editing a gift card’s remaining balance records FIELD_CHANGED with field: "balance". old and new are numbers in the card’s currency, for example 25 → 12.5. Balance edits are made in the Fluz web and mobile apps. The balance event records an edit by a user. Spending the card at the merchant isn’t recorded.

Expense details

Memos, receipts, and categories belong to a transaction, not to the card. When one changes on a gift card purchase, Fluz records a FIELD_CHANGED event on the gift card.

`field`	`old` / `new`	Set with
`memo`	`old` is `null`. `new` is `ADDED`, `CHANGED`, or `REMOVED`. The memo text is never recorded.	`memo`
`receipt`	`old` is `null`. `new` is `ADDED`, `CHANGED`, or `REMOVED`. The file is never recorded.	`attachmentId`
`expense_category`	The previous and new category names, or `null`	`transactionCategory`
`erp_category`	The previous and new QuickBooks category names, or `null`	`erpTransactionMetadata.categoryReferenceItemId` or `categoryName`

Each event also carries transaction_log_id, transaction_record_id (the transaction’s recordId, when it’s known), and, on category events, old_id and new_id for the side that has a category. These events are recorded for updateTransactionMetadata, the UPDATE_TRANSACTION_METADATA bulk operation (memo and category), bulkUpdateErpTransactionMetadata (QuickBooks category), edits in the Fluz web app, and receipt uploads, receipt removals, and QuickBooks category changes in the Fluz mobile app. A category counts as changed only when its ID changes. A memo, category, or receipt passed to purchaseGiftCard is part of the purchase. It doesn’t record a separate expense details event.

A gift card’s ownership, access, and invite events follow the shared rules in Ownership and access.

Approvals

Request	`approval_type`	`approval_code`	Resulting event
Purchase a gift card	`GIFT_CARD`	`400007`	`OBJECT_CREATED` on the new gift card
Access to the gift card	`ACCOUNT_ACCESS`	`100004`, `100005`	`ACCESS_GRANTED`, or `ACCESS_LEVEL_CHANGED` if the requester already had lower access

An access request that nobody decides in time records APPROVAL_EXPIRED on the gift card. See Approvals for how the trail is linked.

Systems you can see

`actor.system`	What it does
`scheduled-task-handler`	Buys scheduled gift cards.
`approvals-service`	Records expired requests and decisions made through an approval link that names no approver.
`erp-service`	Applies a QuickBooks category automatically.
`transactional-graph-service`	Records an expense details change made through the API when the caller can’t be resolved to a user.

What isn’t recorded

Revealing the gift card code, with revealGiftCardByGiftCardId or in the Fluz app.
Redeeming or spending the card at the merchant.
A memo or category set at purchase time.
Archiving or reactivating a gift card in Fluz Enterprise.

Features

Gift card activity history

Purchase

Status changes

Balance changes

Expense details

Approvals

Systems you can see

What isn’t recorded

Next steps

Activity history overview

View gift cards

​Purchase

​Status changes

​Balance changes

​Expense details

​Sharing and access

​Approvals

​Systems you can see

​What isn’t recorded

​Next steps

Activity history overview

View gift cards

Purchase

Status changes

Balance changes

Expense details

Sharing and access

Approvals

Systems you can see

What isn’t recorded

Next steps