Overview

The custom label is an optional name/value pair assigned to a merchant during boarding, allowing you to identify merchants according to criteria you define: a Subscription Tier, an Internal Account ID, a Sales Region, and similar classifications. Both the custom label name and value are determined by you. Labels are not checked for uniqueness, so any number of merchants can carry the same label, which is what makes them useful for grouping.

The label is originally assigned to merchants during boarding. Our team helps configure your preferred mapping option within your boarding service configuration. This guide documents the subsequent operation: modifying or clearing a label on a merchant that has already been boarded.

📌 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.

How it works

The four characteristics below govern how the label is stored and written. Review these before submitting a request.

The label is one identifier holding a JSON document

The Custom Label is not two fields. It is a single merchant identifier under the key CustomLabel, whose value is a small JSON document containing both halves of the pair:

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

That document is stored as a string. This endpoint writes identifier values directly, which means you supply that JSON yourself, escaped, as the value of the CustomLabel key.

Writes replace the whole identifier

The name and the value cannot be updated independently. Every write replaces the entire CustomLabel identifier, so both halves must be included in each request. The same request works whether or not the merchant already has a label. An existing CustomLabel is overwritten, and a merchant without one has it created.

Other identifiers you do not include in your request are untouched. Only the keys you include in the request are written, so you will not disturb a merchant's MID, terminals, or other identifiers by leaving them out.

The command status confirms the write

The endpoint queues your request and processes it asynchronously, so a 200 on the write means the request was accepted. Checking the status of the returned command is how you know a label was saved. Every write returns a command fingerprint, and a GET on that fingerprint reports the outcome: a Completed status confirms the label was written, and a Failed status carries the error.

Labels are meant to be short

We recommend a maximum of 50 characters each for the name and the value. See Label length guidelines in step 2.

Recommended update sequence

1. Read the merchant's current label, so you have both halves of the pair.
2. Send the complete name/value document to the identifiers endpoint.
3. Confirm the command completed.

Before you begin

Make sure you have the following:

• Active Backoffice API credentials (x-AuthenticationKeyId and x-AuthenticationKeyValue). See Manage Backoffice API Keys.
• Your tenantId.
• The numeric submerchantId of the merchant you are updating. This is the Backoffice merchant ID.

Step 1: Read the current label

Retrieve the merchant so you have both halves of the pair as they stand today. See Review Submerchant Information for request details.

Example request

GET https://api.infinicept.com/api/examplepayfac/merchant/48213

Example response

{
    "id": 48213,
    "legalEntityName": "Contact Company",
    "merchantIdentifiers": {
        "MID": "70944180506",
        "InfiniceptMerchantId": "754d2bdd-50d5-471e-a6ec-9c0571479363",
        "CoBrand": "examplepayfac",
        "CustomLabel": "{\"name\":\"Subscription Tier\",\"value\":\"Gold\"}"
    }
}

Parse the CustomLabel string and keep the half you are not changing. The label appears inside merchantIdentifiers as a raw JSON string rather than as separate fields. Because every write replaces the whole identifier, carrying the existing half into step 2 is what keeps it from being discarded.

A merchant with no label yet has either no CustomLabel key at all, or a key with an empty value. Treat both as no label. If you are setting a label for the first time, or replacing both halves at once, you can go straight to step 2.

Step 2: Send the label

Send the complete name/value document to the identifiers endpoint. See Add Submerchant Boarding Ids for request details.

The example below updates a merchant's custom label to Subscription Tier: Platinum.

Example request

PUT https://api.infinicept.com/api/examplepayfac/merchant/48213/identifiers
Content-Type: application/json

{
    "additionalIdentifiers": {
        "CustomLabel": "{\"name\":\"Subscription Tier\",\"value\":\"Platinum\"}"
    }
}

Send the value as a JSON name/value pair. The CustomLabel value is a JSON document with exactly two lowercase properties, name and value, sent as a JSON-escaped string. Backoffice reads the value as a name/value document, so this is what makes the label display. A plain string such as "Gold" is accepted and stored, but the label will not appear in Backoffice and no error is returned. Both halves are stored as text. Numbers, dates, and internal codes are accepted as is, with no type conversion.

Match the key exactly: CustomLabel. The key is case-sensitive. Customlabel or customLabel creates a separate identifier that Backoffice does not recognize, and leaves the existing label untouched. The request still returns a successful response.

Omit the other body fields. The endpoint also accepts mid and tiDs, which set the processor MID and add terminal IDs. Leave both out when you are editing a label. A body that carries only additionalIdentifiers cannot return a 409 Conflict.

A successful call returns 200 with a command fingerprint:

Example response

{
    "commandFingerprint": "8f14e45f-ea0d-4b6c-9b1a-2d3c4e5f6a7b",
    "status": "Processing"
}

Label length guidelines

The custom label name and value are designed to display short, easy-to-recognize labels. We recommend a maximum of 50 characters each, which comfortably fits values like the examples below.

Step 3: Confirm the command completed

Check the command status to confirm the write. A 200 on the original request means the write was queued. Poll the command until it leaves Processing. See Request Status of Queued Request for request details. A nonexistent merchant ID and an over-length value both return 200 and fail afterward.

Example request

GET https://api.infinicept.com/api/examplepayfac/commands/8f14e45f-ea0d-4b6c-9b1a-2d3c4e5f6a7b

Example response

{
    "commandFingerprint": "8f14e45f-ea0d-4b6c-9b1a-2d3c4e5f6a7b",
    "status": "Completed",
    "endTime": "2026-09-01T18:04:11.7Z"
}

Status values

Clearing a label

To remove a merchant's label, send an empty string for the CustomLabel key. Clearing empties the value rather than deleting the identifier, so the CustomLabel key continues to appear in API responses.

Example request

PUT https://api.infinicept.com/api/examplepayfac/merchant/48213/identifiers
Content-Type: application/json

{
    "additionalIdentifiers": {
        "CustomLabel": ""
    }
}

Confirm the command as in step 3. Once it completes, the label stops appearing on the Backoffice Submerchant Profile, and the CustomLabel column of the Transaction export is blank for that merchant.

API responses continue to return the key with an empty value: "CustomLabel": "" on the merchant response, and an entry with an empty value on transaction responses. Your integration should treat an empty value as "no label" rather than expecting the key to disappear.

Backfilling and retagging in bulk

Two situations call for updating many merchants at once: you configured a label after merchants were already boarded, or you want to change a label name across an existing list of merchants.

The endpoint updates one merchant per call. To update many merchants, write a script that calls the endpoint once per merchant. A safe script does three things:

• Reads each merchant immediately before writing it. Because every write replaces the whole identifier, a label edited in Backoffice partway through a long run would be reverted by a value read at the start.
• Checks command status for every write. A 200 means queued, so counting them measures how many requests were accepted. Collect the fingerprints, poll each one, and treat Completed as your success count. A nonexistent merchant ID also returns 200 and surfaces as a Failed command.
• Keeps both halves together. Sending only the new value drops the name on every merchant it touches.

Where the label appears

Support

Have a question? Contact us on the Customer Support Portal.

Learn about updates in our Changelog.