---
title: "Register merchant triggers at program scope"
method: PUT
path: "/programs/{programId}/merchant-action-triggers"
tags: ["Merchant Action Triggers"]
---

# Register merchant triggers at program scope

`PUT /programs/{programId}/merchant-action-triggers`

Register merchant action triggers at the program scope.

Program-level triggers apply to all enrichment requests where the `programId` field matches this program.

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

## Request body

- MerchantActionTriggerRegistrationRequest — Request body for registering merchant action triggers.
  - `merchantTriggers` MerchantTriggerItem[], required — List of merchant triggers to register for action matching. Each trigger must have a unique `id`. **Field requirements:** - `id`, `merchantName`, and `action` are always required - If location fields (address, city) are NOT provided, `website` is required **Limits:** User-scope and card-scope registrations are limited to 100 triggers. Account-scope and program-scope registrations with more than 100 triggers will be processed asynchronously as a batch job.
    - `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.

## Response `201`

Registration created successfully

- ActionTriggerStatusResponse — Response containing the status of an action trigger registration.
  - `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
  - `version` integer — The version number of this registration. Increments with each PUT, PATCH, or DELETE request to this scope.
  - `merchantTriggers` object[] — The list of active merchant triggers registered for this scope. Present on GET responses; omitted on PUT and PATCH responses.
    - `id` string — The trigger ID as provided during registration.
    - `action` object — The action data associated with this trigger, as provided during registration.
  - `totalCount` integer — The total number of active merchant triggers registered for this scope. Present on GET responses; omitted on PUT and PATCH responses.

## Other responses

- `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)