Sign in

v1

latestOpenAPI 3.1.02026-07-227350156.5 KB
Merchant Action Triggers

Incremental trigger operations at account scope

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

Supports two operations:

  • add: Register new merchants or update existing ones. Only the submitted merchants are affected—existing registrations are preserved. If a trigger ID already exists, its registration is replaced (upsert). Registrations with more than 100 triggers are processed asynchronously as a batch job.
  • remove: Remove merchants by trigger ID. Removed merchants are excluded from enrichment lookups. Trigger IDs that are not currently active are silently ignored (idempotent).

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.

Successful add operations return 201; successful remove operations return 200.

Important: Only one operation can be in progress per scope at a time. Concurrent requests return 409.

To learn more about action triggers, please read the Merchant Action Triggers Guide.

patch/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
}