> ## 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`.

> [!NOTE]
>
> **Prerequisites:** the `VIEW_OBJECT_CHANGE_HISTORY` scope on your application, with either a user access token or your API key, and the `giftCardId` of a gift card on the account. See [Activity history overview](https://docs.fluz.app/features/activity-history.md) 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 }
  }
}
```

## At a glance

```mermaid theme={null}
flowchart LR
  GC["Gift card<br/>GIFT_CARDS"]
  GC --> A["Purchased<br/>API, schedule, approval, Fluz app"]
  GC --> B["Status<br/>archived, reactivated"]
  GC --> C["Balance<br/>edited by a user"]
  GC --> D["Expense details<br/>memo, receipt, category"]
  GC --> E["Ownership and sharing<br/>owner, access, invites"]
  GC --> F["Approvals<br/>purchase and access requests"]
```

Each box is a group of events below. For one table of every gift card event, see the [Event catalog](https://docs.fluz.app/features/activity-history-events.md#gift-card-events).

***

## Purchase

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

| How the card was purchased | `actor` | `subjectUserId` |
| - | - | - |
| [`purchaseGiftCard`](https://docs.fluz.app/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](https://docs.fluz.app/features/request-gift-card-purchase-approval.md) | 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](https://docs.fluz.app/features/activity-history.md#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`](https://docs.fluz.app/features/add-expense-details), the `UPDATE_TRANSACTION_METADATA` [bulk operation](https://docs.fluz.app/submit-a-bulk-operation.md) (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](https://docs.fluz.app/features/activity-history.md#ownership-and-access).

## Approvals

| Request | `approval_type` | `approval_code` | Resulting event |
| - | - | - | - |
| [Purchase a gift card](https://docs.fluz.app/features/request-gift-card-purchase-approval.md) | `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](https://docs.fluz.app/features/activity-history.md#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

> **[Activity history overview](https://docs.fluz.app/features/activity-history.md)**
>
> The query, response fields, actors, approvals, and access levels.

> **[Event catalog](https://docs.fluz.app/features/activity-history-events.md)**
>
> Every event on every object, in one place.

> **[View gift cards](https://docs.fluz.app/view-gift-card.md)**
>
> 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.