Tags API
Create, rename, search, and assign organization-scoped tags to invoices and clients.
Tags organize receivables and client accounts. They do not change the lifecycle state.
/v1/receivables/tagsEndpoints and Schemas
| Method | Path | Request schema | Success response |
|---|---|---|---|
GET | / | query: limit, offset | TagsListResponse |
POST | / | CreateTagRequest | TagCreateResponse |
GET | /search | query: tag, limit, offset | TagSearchResult |
PATCH | /{id} | UpdateTagRequest | TagUpdateResponse |
DELETE | /{id} | none | TagDeleteResponse |
GET | /invoice/{invoiceId} | none | TagsByInvoiceResponse |
POST | /invoice/{invoiceId} | TagEntityRequest | TagEntityResponse |
DELETE | /invoice/{invoiceId}/{tagId} | none | TagEntityResponse |
GET | /client/{clientId} | none | TagsByClientResponse |
POST | /client/{clientId} | TagEntityRequest | TagEntityResponse |
DELETE | /client/{clientId}/{tagId} | none | TagEntityResponse |
POST | /bulk | BulkTagRequest | BulkTagResponse |
Tag Names
Tag names are 1–50 characters and can contain letters, numbers, hyphens, and underscores. They are case-sensitive and unique within the organization.
{
"name": "high-priority"
}A rename uses newTag. To add a tag to an invoice or client, use tag. The API creates the tag when it does not already exist.
Response Details
List results include invoiceCount, clientCount, and totalUsage. Search returns the invoice and client records that match, plus separate totals. Rename and delete responses report how many invoices and clients the API updated. Use these counts to invalidate every affected list.
A bulk tag operation returns taggedInvoices and taggedClients. Compare these counts with the identifiers you sent. Show partial results, because not every selected record is always accessible.