> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Gift card activity history
> Every event Fluz records on a gift card — purchase, archive and used status, balance edits, expense details, sharing, and approvals — and how each one appears in objectChangeHistory.
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](/features/activity-history) for the full query, response fields, and access rules.
```graphql theme={null}
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`](/purchase-gift-card) | 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](/features/request-gift-card-purchase-approval) | 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](/features/activity-history#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`](/features/add-expense-details), the `UPDATE_TRANSACTION_METADATA` [bulk operation](/submit-a-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.
***
## Sharing and access
A gift card's ownership, access, and invite events follow the shared rules in [Ownership and access](/features/activity-history#ownership-and-access).
## Approvals
| Request | `approval_type` | `approval_code` | Resulting event |
| - | - | - | - |
| [Purchase a gift card](/features/request-gift-card-purchase-approval) | `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](/features/activity-history#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.
## Next steps
The query, response fields, actors, approvals, and access levels.
List the gift cards on an account and get their IDs.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.