v1

latestOpenAPI 3.1.02026-07-227350156.5 KB

Merchant Action Triggers

Incremental trigger operations at program scope

Perform incremental operations on merchant action triggers at the program scope.

See the account-scope PATCH endpoint for full documentation on supported operations (add, remove).

Limits: Up to 100,000 triggers per add request, with a total cap of 300,000 active triggers per scope. To register more than 100,000 triggers, split them into ≤100,000 batches and submit them with sequential add operations, waiting for each to reach succeeded before the next — see Registering large trigger sets.

patch/programs/{programId}/merchant-action-triggers

Request body

operation'add' | 'remove' required

The operation to perform:

add: Register new merchants or update existing ones via merchant matching
remove: Remove merchants (excluded from enrichment lookups)

triggerIdsstring[] nullable

List of trigger IDs to remove. Required and must be non-empty for the remove operation.

Trigger IDs that are not currently active are silently ignored (idempotent).

For add operations, this field is optional and ignored if provided — you may pass null, [], or omit it entirely.

Example request

{
  "operation": "add",
  "merchantTriggers": [
    {
      "id": "trigger-12345",
      "merchantName": "Starbucks",
      "action": {
        "type": "REWARD",
        "rewardPercent": 5,
        "offerId": "offer-abc123"
      },
      "website": "https://www.starbucks.com",
      "address": "123 Main St",
      "city": "Seattle",
      "region": "WA",
      "country": "USA",
      "postalCode": "98101",
      "latitude": 47.6062,
      "longitude": -122.3321,
      "level": "corporation",
      "customAttributes": {
        "storeId": "store-789"
      }
    }
  ],
  "triggerIds": [
    "merchant_123",
    "merchant_456"
  ]
}

Response

Remove operation completed successfully

status'succeeded'

versioninteger

The version number of this operation.

Example response

{
  "status": "succeeded",
  "version": 5
}