---
title: "Register category triggers at account scope"
method: PUT
path: "/category-action-triggers"
tags: ["Category Action Triggers"]
---

# Register category triggers at account scope

`PUT /category-action-triggers`

Register category action triggers at the account scope.

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

**Field requirements:**
- `id`, `categoryId`, and `action` are required for each trigger
- `categoryId` must be a valid Spade category ID (use [`GET /categories`](https://docs.spade.com/api-reference/category-personalization/get-all-default-and-custom-integration-level-categories) to discover valid IDs)

**Limit:** A maximum of 300 `categoryTriggers` can be submitted per request. All registrations are processed synchronously.

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

To learn more about action triggers, please read the [Category Action Triggers Guide](https://docs.spade.com/reference/category-action-triggers-guide).

## Request body

- CategoryActionTriggerRegistrationRequest — Request body for registering category action triggers.
  - `categoryTriggers` CategoryTriggerItem[], required — List of category triggers to register for action matching. Each trigger must have a unique `id`. **Field requirements:** - `id`, `categoryId`, and `action` are always required **Limit:** A maximum of 300 triggers across all scopes. All registrations are processed synchronously.
    - `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.
    - `categoryId` string, required — The Spade category ID to match against. Category IDs use the format `xxx-xxx-xxx-xxx` where each `x` is a digit — use [`GET /categories`](https://docs.spade.com/api-reference/category-personalization/get-all-default-and-custom-integration-level-categories) to discover valid IDs.
    - `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 category. 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 categories 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.

## Response `201`

Registration created successfully

- CategoryActionTriggerStatusResponse — Response containing the status of a category action trigger registration.
  - `status` 'succeeded' | 'failed' — The current status of the action trigger registration. Category trigger registrations are processed synchronously, so the status is always one of: - `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.
  - `categoryTriggers` object[] — The list of active category triggers registered for this scope. Present on GET responses; omitted on PUT and PATCH responses.
    - `id` string — The trigger ID as provided during registration.
    - `categoryId` string — The category ID associated with this trigger, as provided during registration.
    - `action` object — The action data associated with this trigger, as provided during registration.
  - `totalCount` integer — The total number of active category 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/revisions/a37c626f84de/schema)