Transaction Tagging
Overview
Shaype Transaction Tagging enables clients to attach arbitrary metadata to transactions using a flexible category/value model. Tags can be added or removed at any time after a transaction has settled, and are automatically included in transaction retrieval and search responses.
| Capability | API's Involved |
|---|---|
| Add, retrieve, and remove tags on transactions | POST/v1/transactions/{transactionHayId}/tags GET/v1/transactions/{transactionHayId}/tags |
| Tags automatically returned in standard transaction queries | GET/v1/transactions/{transactionHayId} POST/v0/transactions/search |
Tag Data Model
Each tag is defined by a category and a value. Together they form a unique label that can be associated with a transaction.
| Field | Type | Description |
|---|---|---|
| id | UUID (string) | Shaype-assigned identifier for the tag association. Returned in API responses; not required when adding tags. |
| category | string | Grouping or namespace for the tag (e.g. "expense-type", "cost-centre", "project"). |
| value | string | The label within the given category (e.g. "travel", "FIN-001", "alpha-launch"). |
API Reference
All endpoint paths are relative to the base URL provided by Shaype for your environment.
Add Tags to a Transaction
POST/v1/transactions/{transactionHayId}/tags Associate one or more tags with the specified transaction.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| transactionId | UUID (string) | The unique identifier of the transaction to tag. This is the Shaype transaction ID returned when the transaction was created. |
Request Body (application/json)
API Reference: Modify Tags for a Transaction
Behaviour
• Tags are idempotent — submitting a category/value pair that already exists on the transaction has no effect. • Multiple tags can be added in a single request. • The tags array must contain at least one entry; an empty array will be rejected with 400 Bad Request.
Remove Tags from a Transaction
POST/v1/transactions/{transactionHayId}/tags Remove one or more tags from the specified transaction.
Request Body (application/json)
API Reference: Modify Tags for a Transaction
Behaviour • Only the specified tags are removed; all other tags on the transaction are unchanged. • Requesting removal of a tag that does not exist on the transaction is a no-op — no error is returned.
Retrieve Tags for a Transaction
GET/v1/transactions/{transactionHayId}/tags Return all tags currently associated with a transaction.
Request Body (application/json)
API Reference: Get Tags for Transaction
Behaviour • Tags are returned ordered by createdAt ascending. • If the transaction has no tags, the response contains an empty tags array.
Single Transaction Retrieval (with Tags)
GET/v1/transactions/{transactionHayId} Retrieve a single transaction. The response now includes a tags field.
The tags field is included automatically. No additional request parameters are required. If the transaction has no tags, the field is present as an empty array.
Request Body (application/json)
API Reference: Get Transaction by ID
Transaction Search (with Tags)
POST/v0/transactions/search Search transactions. Each result in the response now includes a tags array.
The search request body and all existing filter parameters are unchanged. Tags are automatically included on every transaction object within the results array.
Request Body (application/json)
API Reference: Search Transactions
Usage Guidelines
Designing Your Tag Taxonomy
Because categories and values are free-form strings, we recommend agreeing on a naming convention before going live: • Use lowercase kebab-case for category names (e.g. expense-type, cost-centre, project-code). • Keep category names descriptive but concise — they appear in all tag query responses. • Where consistency matters for downstream reporting, agree on a controlled vocabulary for values within each category. • Do not embed PII or other sensitive data in tag categories or values.
Timing of Tag Operations
Tags can only be applied to transactions that have been processed and written to our the ledger. Tag operations are retrospective — real-time tagging during payment authorisation is not currently supported.
Mutability
Tags are fully mutable after assignment. You may add or remove tags at any point after a transaction has settled. There is no limit to the number of times tags on a transaction can be modified.
Performance
When using the transaction search endpoint, tags are fetched in a single batch query alongside transaction data. There is no per-transaction query overhead, and tag enrichment is designed to add less than 10 ms of latency for typical page sizes (up to 50 transactions per page).