Custom Label Now Available in Merchant Identifiers

What's new?

Submerchants can now carry a custom label, an optional name/value pair assigned during boarding that lets you identify merchants according to criteria you define such as a Subscription Tier, Internal Account ID, or Sales Region. The label is returned as a CustomLabel entry within merchantIdentifiers on both submerchant and transaction responses.

In Backoffice, the label appears on the Submerchant Profile and in the Transaction export. See Tag Your Merchants with a Custom Label for details on managing the label directly within the web interface.

See Update a Merchant's Custom Label for setting, changing, or clearing the label on merchants you have already boarded, including backfills and bulk updates. Setting the label through the API updates the merchant record only. It does not change the value on the merchant application.

The CustomLabel identifier

CustomLabel is a single merchant identifier whose value is a small JSON document containing both halves of the pair, name and value, stored as a string:

{"name":"Subscription Tier","value":"Gold"}

Not every merchant carries a label. A label configuration applies to merchants boarded after it is set up, so merchants boarded before then will not have one until a label is added. Expect the CustomLabel key to be missing on merchants that never had one, and present with an empty value on merchants whose label was cleared.

The shape differs between the two responses. A submerchant response returns merchantIdentifiers as an object, with CustomLabel as a keyed property:

"merchantIdentifiers": {
    "MID": "70944180506",
    "CoBrand": "examplepayfac",
    "CustomLabel": "{\"name\":\"Subscription Tier\",\"value\":\"Gold\"}"
}

A transaction response returns it as an array of key/value entries:

"merchantIdentifiers": [
    { "key": "MID", "value": "70944180506" },
    { "key": "CoBrand", "value": "examplepayfac" },
    { "key": "CustomLabel", "value": "{\"name\":\"Subscription Tier\",\"value\":\"Gold\"}" }
]