Merchant tags
Tag merchants with your own key-value labels. Ginger copies the tags to every new order and transaction of the merchant.
Merchant tags are key-value labels you put on a merchant, such as the ISO the merchant belongs to or its risk class. Ginger copies them to every order and transaction the merchant creates afterwards, so you can group and filter payments by your own categories.
How tags work
- You set tags on the merchant, in the
tagsfield. Keys and values are strings. - When the merchant creates an order, Ginger copies the merchant's current tags to the order as
merchant_. Every transaction of the order gets the sametags merchant_.tags - The tags on an order are a snapshot. When you change the tags of a merchant, existing orders and transactions keep their tags; only new orders get the new ones.
merchant_on orders and transactions is read-only. You manage tags on the merchant only.tags
| Where | Field | Writable |
|---|---|---|
| Merchant | tags | Yes, by you |
| Order | merchant_ | No, copied when the order is created |
| Transaction | merchant_ | No, copied from the order |
Set tags
- Open the merchant and go to Details.
- Click Edit.
- In the TAGS section, click Add tag and enter a key and a value. Add a row per tag.
- Click Save changes.
The tags show in the TAGS section of the merchant details.
Send the tags in an update of the merchant:
curl https://api.example.com/v1/admin/merchants/$MERCHANT_ID/ \
--user "$API_KEY:" \
--header "Content-Type: application/json" \
--request PUT \
--data '{
"company_name": "Acme Coffee",
"tags": {
"iso": "Acme Payments",
"risk": "low"
}
}'See Update a merchant in the API reference.
The update merges the tags you send into the existing tags: a key you send gets the new value, keys you leave out stay as they are.
Tags on orders and transactions
Orders of a tagged merchant carry the tags in merchant_, on the order and on each transaction. The response is
shortened:
{
"id": "a5c7d8e0-1234-5678-9abc-def012345678",
"amount": 500,
"currency": "EUR",
"merchant_order_id": "my-order-1",
"status": "new",
"merchant_tags": {
"iso": "Acme Payments",
"risk": "low"
},
"transactions": [
{
"id": "b6d8e9f0-2345-6789-abcd-ef0123456789",
"payment_method": "credit-card",
"status": "new",
"merchant_tags": {
"iso": "Acme Payments",
"risk": "low"
}
}
]
}The search index holds merchant_ on orders and transactions, so you can use them in your own reporting.
Use cases
- Grouping: tag every merchant that belongs to a PayFac, ISO or other part of your hierarchy.
- Reporting: group and filter orders and transactions by tag in your own analytics.