> ## 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. # Register category triggers at program scope > Register category action triggers at the program scope. Program-level triggers apply to all enrichment requests where the `programId` field matches this program. **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). ## OpenAPI ````yaml /api-reference/spec.yml put /programs/{programId}/category-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: /programs/{programId}/category-action-triggers: parameters: - in: path name: programId schema: type: string maxLength: 512 description: Your unique identifier for the program required: true put: tags: - Category Action Triggers summary: Register category triggers at program scope description: >- Register category action triggers at the program scope. Program-level triggers apply to all enrichment requests where the `programId` field matches this program. **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). operationId: programCategoryActionTriggersPut requestBody: content: application/json: schema: $ref: '#/components/schemas/CategoryActionTriggerRegistrationRequest' required: true responses: '201': description: Registration created successfully content: application/json: schema: $ref: '#/components/schemas/CategoryActionTriggerStatusResponse' '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: CategoryActionTriggerRegistrationRequest: type: object description: Request body for registering category action triggers. required: - categoryTriggers properties: categoryTriggers: type: array description: > 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. minItems: 1 maxItems: 300 items: $ref: '#/components/schemas/CategoryTriggerItem' CategoryActionTriggerStatusResponse: type: object description: >- Response containing the status of a category action trigger registration. properties: status: type: string description: > 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 enum: - 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 categoryTriggers: type: array description: >- The list of active category 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: - travel-reward-1 categoryId: type: string description: >- The category ID associated with this trigger, as provided during registration. examples: - 020-001-000-000 action: type: object description: >- The action data associated with this trigger, as provided during registration. additionalProperties: true examples: - type: REWARD rewardPercent: 3 totalCount: type: integer description: >- The total number of active category triggers registered for this scope. Present on GET responses; omitted on PUT and PATCH responses. examples: - 10 CategoryTriggerItem: type: object description: A category trigger to register for action matching. required: - id - categoryId - 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: - travel-reward-1 categoryId: type: string description: >- 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. maxLength: 15 pattern: ^\d{3}-\d{3}-\d{3}-\d{3}$ examples: - 020-001-000-000 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 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. 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: 3 offerId: travel-3x-promo - type: BLOCK reason: Gambling not permitted - type: ALLOW_ONLY 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 ````