Skip to content

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 tags field. Keys and values are strings.
  • When the merchant creates an order, Ginger copies the merchant's current tags to the order as merchant_tags. Every transaction of the order gets the same 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_tags on orders and transactions is read-only. You manage tags on the merchant only.
WhereFieldWritable
MerchanttagsYes, by you
Ordermerchant_tagsNo, copied when the order is created
Transactionmerchant_tagsNo, copied from the order

Set tags

  1. Open the merchant and go to Details.
  2. Click Edit.
  3. In the TAGS section, click Add tag and enter a key and a value. Add a row per tag.
  4. Click Save changes.

The tags show in the TAGS section of the merchant details.

Tags on orders and transactions

Orders of a tagged merchant carry the tags in merchant_tags, 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_tags 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.