curl --request PATCH \
  --url https://east.sandbox.spade.com/merchant-action-triggers \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "operation": "add",
  "merchantTriggers": [
    {
      "id": "trigger-1",
      "merchantName": "Starbucks",
      "website": "https://www.starbucks.com",
      "level": "corporation",
      "action": {
        "type": "REWARD",
        "rewardPercent": 5,
        "offerId": "summer-2024-promo"
      }
    }
  ]
}
'

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

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

{
  "invalidField": [
    "This field is required."
  ]
}

{
  "details": "Incorrect authentication credentials."
}

{
  "detail": "An action trigger registration is already in progress for this scope."
}

{
  "details": "Internal server error."
}

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

curl --request PATCH \
  --url https://east.sandbox.spade.com/merchant-action-triggers \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "operation": "add",
  "merchantTriggers": [
    {
      "id": "trigger-1",
      "merchantName": "Starbucks",
      "website": "https://www.starbucks.com",
      "level": "corporation",
      "action": {
        "type": "REWARD",
        "rewardPercent": 5,
        "offerId": "summer-2024-promo"
      }
    }
  ]
}
'

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

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

{
  "invalidField": [
    "This field is required."
  ]
}

{
  "details": "Incorrect authentication credentials."
}

{
  "detail": "An action trigger registration is already in progress for this scope."
}

{
  "details": "Internal server error."
}

Authorizations

X-Api-Key

string

header

required

Body

application/json

Request body for incremental merchant action trigger operations.

For add: merchantTriggers is required. triggerIds is optional and ignored if provided.
For remove: triggerIds is required and must be a non-empty list.

operation

enum<string>

required

The operation to perform:

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

Available options:

add,

remove

Example:

"add"

merchantTriggers

object[]

List of merchant triggers to add. Required for the add operation.

If a trigger ID already exists, the old registration is replaced (upsert behavior).

Field requirements:

id, merchantName, and action are always required
level defaults to location if omitted
For level: "location" (default): requires both address and postalCode, or both latitude and longitude
For level: "corporation": requires website on its own, or both address and postalCode, or both latitude and longitude
Triggers that don't meet these requirements are rejected with a 400 error

Required array length: 1 - 100000 elements

Show child attributes

triggerIds

string[] | null

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.

Maximum string length: 512

Example:

["merchant_123", "merchant_456"]

Response

Remove operation completed successfully

Response for the remove PATCH operation.

status

enum<string>

Available options:

succeeded

Example:

"succeeded"

version

integer

The version number of this operation.

Example:

5

Card Enrichment

Transfer Enrichment

Universal Enrichment

Feedback and Reporting

Merchant Search

Merchant Action Triggers

Category Action Triggers

Category Personalization

Incremental trigger operations at account scope

Authorizations

Body

Response