---
title: "Incremental trigger operations at account scope"
method: PATCH
path: "/merchant-action-triggers"
tags: ["Merchant Action Triggers"]
---

# Incremental trigger operations at account scope

`PATCH /merchant-action-triggers`

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](/reference/merchant-action-triggers-guide#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](https://docs.spade.com/reference/merchant-action-triggers-guide).

## Request body

- MerchantActionTriggerPatchRequest — 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` '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)
  - `merchantTriggers` MerchantTriggerItem[] — 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 - If location fields (address, city) are NOT provided, `website` is required
    - `id` string, required — Your identifier for this trigger, unique within the scope you are registering against. This ID will be returned in the `actions` field of enrichment responses when this trigger matches a transaction.
    - `merchantName` string, required — The name of the merchant.
    - `action` object, required — A custom JSON object that will be returned in the enrichment response when this trigger matches. Use this to store any data relevant to your use case (e.g., reward amounts, offer IDs, campaign metadata). The optional `type` field has reserved values with special behavior: - `BLOCK`: Adds `authRecommendation: "BLOCK"` to the action in the enrichment response. Use this to flag transactions that should be declined. - `ALLOW_ONLY`: Adds `authRecommendation: "ALLOW"` when the transaction matches a registered merchant. If the transaction does **not** match any `ALLOW_ONLY` trigger, the action is returned with `authRecommendation: "BLOCK"` (inverse semantics). Use this to create allowlists where only registered merchants are permitted. - `REWARD`: No special behavior. Passed through as-is. - Any other value: Treated as a custom type and passed through as-is.
      - `type` string — Optional action type. Reserved values `BLOCK` and `ALLOW_ONLY` have special authorization semantics (see above). All other values are passed through without modification.
    - `website` string — The merchant's website URL. Required if location fields (address, city) are not provided.
    - `address` string — The street address of the merchant location.
    - `city` string — The city of the merchant location.
    - `region` string — The state or region of the merchant location.
    - `country` string — The country of the merchant location.
    - `postalCode` string — The postal code of the merchant location.
    - `latitude` number, double — The latitude of the merchant location.
    - `longitude` number, double — The longitude of the merchant location.
    - `level` 'corporation' | 'location' — Controls whether matching is performed at the corporation level or location level. Use "corporation" for brand-level matching (e.g. apply trigger to Costco in general). Use "location" for a specific physical location (e.g. apply trigger to one specific Costco location). Defaults to "location" if not specified.
    - `customAttributes` object — Optional custom attributes to associate with this trigger registration.
  - `triggerIds` string[], 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.

## Response `200`

Remove operation completed successfully

- ActionTriggerPatchResponse — Response for the remove PATCH operation.
  - `status` 'succeeded'
  - `version` integer — The version number of this operation.

## Other responses

- `201` — Add operation completed (or submitted for batch processing)
- `400` — Invalid input
- `403` — Unauthorized
- `409` — A registration is already in progress for this scope
- `500` — Unexpected Error

---

[API](https://skmtc.net/spade/apis/spade-api.md) · [All operations](https://skmtc.net/spade/apis/spade-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/spade/spade-api/versions/a37c626f84de/schema)