Tags

Tags are key-value pairs that you attach to a resource to store your own metadata, such as an internal ID, a cohort, or a risk tier. Lithic does not interpret tags.

Format

Tags are a JSON object with string keys and string values. Keys are case-sensitive and matched exactly.

Limit	Value
Tags per resource	50
Key length	40 characters
Value length	500 characters

Setting tags on create

Pass tags on the create request. A null value is rejected on create.

{
  "tags": {
    "risk-level": "high"
  }
}

Updating tags

Updates use JSON merge patch semantics. Send only the keys you want to change.

To do this	Send
Leave tags unchanged	Omit `tags`, or send `"tags": {}`
Add or overwrite a tag	The key with a string value
Remove a tag	The key with a `null` value
Set a tag to an empty value	The key with `""`. An empty string is a value, not a removal

To rename a key atomically, add the new key and remove the old one in the same request:

{
  "tags": {
    "new-key": "v",
    "old-key": null
  }
}

There is no operation to remove all tags. Remove keys individually.

🚧
Reading a resource, editing its tags, and sending the result back does not delete tags. Keys missing from the request are left in place. To remove a tag, send the key with a null value.

Reading tags

Tags are returned on the resource in retrieve and list responses.

🚧
Do not store personal data, card data, or other sensitive information in tags. Tag values can appear in webhook payloads, authorization payloads, and logs.

Supported resources

Resource	How tags are set
Cards	Set on Create card and changed with Update card. A replacement card does not inherit tags from the card it replaces.
Card transactions	Applied by tagging rules in Transaction Monitoring Rules. Returned on the transaction object.

Lithic is adding tag support to more resources. If you want tags on a resource that is not listed here, contact your Customer Success manager.