> ## Documentation Index > Fetch the complete documentation index at: https://docs.spade.com/llms.txt > Use this file to discover all available pages before exploring further. # 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](/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). ## OpenAPI ````yaml /api-reference/spec.yml patch /merchant-action-triggers openapi: 3.1.0 info: title: Spade API description: >- Documentation for Spade's card transaction enrichment API and related endpoints. We offer sandbox and production environments on both the east coast and west coast to enable ultra low latency enrichment for realtime applications. Each environment requires different API keys. To inquire about API keys, please contact your Spade representative or reach out to . version: 2.7.3 servers: - url: https://east.sandbox.spade.com description: East coast sandbox environment - url: https://east.api.spade.com description: East coast production environment - url: https://west.sandbox.spade.com description: West coast sandbox environment - url: https://west.api.spade.com description: West coast production environment - url: https://sandbox.v2.spadeapi.com description: East coast sandbox environment (deprecated) - url: https://v2.spadeapi.com description: East coast production environment (deprecated) - url: https://sandbox.west.v2.spadeapi.com description: West coast sandbox environment (deprecated) - url: https://west.v2.spadeapi.com description: West coast production environment (deprecated) security: - ApiKeyAuth: [] tags: - name: Card Enrichment description: Enrich card transactions - name: Transfer Enrichment description: Enrich transfers - name: Category Personalization description: Create custom categories and personalize enrichments - name: Feedback and Reporting description: Provide feedback on card events or report enrichment errors - name: Merchant Matching description: Match your merchants to Spade counterparties and locations - name: Merchant Search description: Search for Spade merchants - name: Merchant Action Triggers description: >- Register merchant action triggers and receive triggered actions in enrichment responses - name: Category Action Triggers description: >- Register category action triggers and receive triggered actions in enrichment responses paths: /merchant-action-triggers: patch: tags: - Merchant Action Triggers summary: Incremental trigger operations at account scope description: >- 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). operationId: merchantActionTriggersPatch requestBody: content: application/json: schema: $ref: '#/components/schemas/MerchantActionTriggerPatchRequest' examples: add: summary: Add merchant triggers value: operation: add merchantTriggers: - id: trigger-1 merchantName: Starbucks website: https://www.starbucks.com level: corporation action: type: REWARD rewardPercent: 5 offerId: summer-2024-promo remove: summary: Remove merchant triggers value: operation: remove triggerIds: - trigger-1 - trigger-2 required: true responses: '200': description: Remove operation completed successfully content: application/json: schema: $ref: '#/components/schemas/ActionTriggerPatchResponse' '201': description: Add operation completed (or submitted for batch processing) content: application/json: schema: $ref: '#/components/schemas/ActionTriggerStatusResponse' '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Unauthorized' '409': description: A registration is already in progress for this scope content: application/json: schema: type: object properties: detail: type: string examples: - >- An action trigger registration is already in progress for this scope. '500': $ref: '#/components/responses/InternalServerError' components: schemas: MerchantActionTriggerPatchRequest: type: object description: >- 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. required: - operation properties: operation: type: string enum: - add - remove description: >- The operation to perform: - `add`: Register new merchants or update existing ones via merchant matching - `remove`: Remove merchants (excluded from enrichment lookups) examples: - add merchantTriggers: type: array description: >- 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 minItems: 1 maxItems: 100000 items: $ref: '#/components/schemas/MerchantTriggerItem' triggerIds: type: - array - 'null' description: >- 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. items: type: string maxLength: 512 examples: - - merchant_123 - merchant_456 ActionTriggerPatchResponse: type: object description: Response for the remove PATCH operation. properties: status: type: string enum: - succeeded examples: - succeeded version: type: integer description: The version number of this operation. examples: - 5 ActionTriggerStatusResponse: type: object description: Response containing the status of an action trigger registration. properties: status: type: string description: > 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 enum: - pending - running - succeeded - failed examples: - succeeded version: type: integer description: >- The version number of this registration. Increments with each PUT, PATCH, or DELETE request to this scope. examples: - 1 merchantTriggers: type: array description: >- The list of active merchant triggers registered for this scope. Present on GET responses; omitted on PUT and PATCH responses. items: type: object properties: id: type: string description: The trigger ID as provided during registration. examples: - merchant_123 action: type: object description: >- The action data associated with this trigger, as provided during registration. additionalProperties: true examples: - type: REWARD points: 200 totalCount: type: integer description: >- The total number of active merchant triggers registered for this scope. Present on GET responses; omitted on PUT and PATCH responses. examples: - 50000 MerchantTriggerItem: type: object description: A merchant trigger to register for action matching. required: - id - merchantName - action properties: id: type: string description: >- 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. maxLength: 512 examples: - trigger-12345 merchantName: type: string description: The name of the merchant. maxLength: 150 examples: - Starbucks action: type: object description: > 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. properties: type: type: string description: > Optional action type. Reserved values `BLOCK` and `ALLOW_ONLY` have special authorization semantics (see above). All other values are passed through without modification. examples: - REWARD - BLOCK - ALLOW_ONLY additionalProperties: true examples: - type: REWARD rewardPercent: 5 offerId: offer-abc123 - type: BLOCK reason: Gambling merchant - type: ALLOW_ONLY category: approved-vendors website: type: string description: >- The merchant's website URL. Required if location fields (address, city) are not provided. maxLength: 256 examples: - https://www.starbucks.com address: type: string description: The street address of the merchant location. maxLength: 150 examples: - 123 Main St city: type: string description: The city of the merchant location. maxLength: 100 examples: - Seattle region: type: string description: The state or region of the merchant location. maxLength: 100 examples: - WA country: type: string description: The country of the merchant location. maxLength: 100 examples: - USA postalCode: type: string description: The postal code of the merchant location. maxLength: 20 examples: - '98101' latitude: type: number format: double description: The latitude of the merchant location. examples: - 47.6062 longitude: type: number format: double description: The longitude of the merchant location. examples: - -122.3321 level: type: string enum: - corporation - location description: > 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. examples: - corporation - location customAttributes: type: object description: >- Optional custom attributes to associate with this trigger registration. additionalProperties: type: string examples: - storeId: store-789 responses: BadRequest: description: Invalid input content: application/json: schema: type: object properties: invalidField: type: array items: type: string examples: - This field is required. Unauthorized: description: Unauthorized content: application/json: schema: type: object properties: details: type: string examples: - Incorrect authentication credentials. InternalServerError: description: Unexpected Error content: application/json: schema: type: object properties: details: type: string examples: - Internal server error. securitySchemes: ApiKeyAuth: type: apiKey name: X-Api-Key in: header ````