Sign in

v1

latestOpenAPI 3.1.02026-07-227350156.5 KB
Merchant Action Triggers

Register merchant triggers at account scope

Register merchant action triggers at the account scope.

Account-level triggers apply to all transactions for all users in your account.

Field requirements:

  • id, merchantName, and action are always required for each trigger
  • If location fields (address, city) are NOT provided, website is required

Batch processing: Registrations with more than 100 triggers are processed asynchronously as a batch job. Poll the GET endpoint to monitor completion.

Limits: Up to 100,000 triggers per 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 sent sequentially via PATCH add — see Registering large trigger sets.

Important: Triggers are only applied to enrichment responses when the status is succeeded.

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

put/merchant-action-triggers

Request body

Example request

{
  "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"
      }
    }
  ]
}

Response

Registration created successfully

status'pending' | 'running' | 'succeeded' | 'failed'

The current status of the action trigger registration.

  • pending: Registration received, processing not yet started
  • running: Registration is being processed (for batch registrations with >100 triggers)
  • succeeded: Registration complete, triggers are now active
  • failed: Registration failed, check your request and retry
versioninteger

The version number of this registration. Increments with each PUT, PATCH, or DELETE request to this scope.

totalCountinteger

The total number of active merchant triggers registered for this scope. Present on GET responses; omitted on PUT and PATCH responses.

Example response

{
  "status": "succeeded",
  "version": 1,
  "merchantTriggers": [
    {
      "id": "merchant_123",
      "action": {
        "type": "REWARD",
        "points": 200
      }
    }
  ],
  "totalCount": 50000
}