Spade Merchant Action Triggers API

openapi: 3.1.0
info:
  title: Spade Card Enrichment Merchant Action Triggers 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 <hello@spade.com>.
  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: Merchant Action Triggers
  description: Register merchant action triggers and receive triggered actions in enrichment responses
paths:
  /merchant-action-triggers:
    delete:
      tags:
      - Merchant Action Triggers
      summary: Clear account-level triggers
      description: 'Clear all merchant action triggers at the account scope.


        This creates a new version with an empty trigger list.


        To learn more about action triggers, please read the [Merchant Action Triggers Guide](https://docs.spade.com/reference/merchant-action-triggers-guide).'
      operationId: merchantActionTriggersDelete
      responses:
        '204':
          description: Triggers cleared successfully
        '403':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      tags:
      - Merchant Action Triggers
      summary: Get account-level trigger status
      description: 'Get the status and version of the latest merchant action trigger registration at the account scope.


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


        **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).'
      operationId: merchantActionTriggersGet
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionTriggerStatusResponse'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: No action triggers exist for this scope
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    examples:
                    - No action triggers exist for this scope
        '500':
          $ref: '#/components/responses/InternalServerError'
    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'
    put:
      tags:
      - Merchant Action Triggers
      summary: Register merchant triggers at account scope
      description: 'Register merchant action triggers at the account scope.


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


        **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).'
      operationId: merchantActionTriggersPut
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MerchantActionTriggerRegistrationRequest'
        required: true
      responses:
        '201':
          description: Registration created successfully
          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'
  /users/{userId}/cards/{cardId}/merchant-action-triggers:
    parameters:
    - in: path
      name: userId
      schema:
        type: string
        maxLength: 512
      description: Your unique identifier for the user
      required: true
    - in: path
      name: cardId
      schema:
        type: string
        maxLength: 512
      description: Your unique identifier for the card
      required: true
    delete:
      tags:
      - Merchant Action Triggers
      summary: Clear card-level triggers
      description: 'Clear all merchant action triggers at the card scope.


        This creates a new version with an empty trigger list.


        To learn more about action triggers, please read the [Merchant Action Triggers Guide](https://docs.spade.com/reference/merchant-action-triggers-guide).'
      operationId: cardMerchantActionTriggersDelete
      responses:
        '204':
          description: Triggers cleared successfully
        '403':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      tags:
      - Merchant Action Triggers
      summary: Get card-level trigger status
      description: 'Get the status and version of the latest merchant action trigger registration at the card scope.


        Card-level triggers apply only to transactions for the specified card.


        **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).'
      operationId: cardMerchantActionTriggersGet
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionTriggerStatusResponse'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: No action triggers exist for this scope
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    examples:
                    - No action triggers exist for this scope
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      tags:
      - Merchant Action Triggers
      summary: Incremental trigger operations at card scope
      description: 'Perform incremental operations on merchant action triggers at the card scope.


        See the account-scope PATCH endpoint for full documentation on supported operations (add, remove).'
      operationId: cardMerchantActionTriggersPatch
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MerchantActionTriggerPatchRequest'
        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
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
      - Merchant Action Triggers
      summary: Register merchant triggers at card scope
      description: 'Register merchant action triggers at the card scope.


        Card-level triggers apply only to transactions for the specified card.


        **Field requirements:**

        - `id`, `merchantName`, and `action` are always required for each trigger

        - If location fields (address, city) are NOT provided, `website` is required


        **Limit:** A maximum of 100 `merchantTriggers` can be submitted per request at the card scope. Requests exceeding this limit will receive a `400` error.


        **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).'
      operationId: cardMerchantActionTriggersPut
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MerchantActionTriggerRegistrationRequest'
        required: true
      responses:
        '201':
          description: Registration created successfully
          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'
  /programs/{programId}/merchant-action-triggers:
    parameters:
    - in: path
      name: programId
      schema:
        type: string
        maxLength: 512
      description: Your unique identifier for the program
      required: true
    delete:
      tags:
      - Merchant Action Triggers
      summary: Clear program-level triggers
      description: 'Clear all merchant action triggers at the program scope.


        This creates a new version with an empty trigger list.


        To learn more about action triggers, please read the [Merchant Action Triggers Guide](https://docs.spade.com/reference/merchant-action-triggers-guide).'
      operationId: programMerchantActionTriggersDelete
      responses:
        '204':
          description: Triggers cleared successfully
        '403':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      tags:
      - Merchant Action Triggers
      summary: Get program-level trigger status
      description: 'Get the status and version of the latest merchant action trigger registration at the program scope.


        Program-level triggers apply to all enrichment requests where the `programId` field matches this program. See [What is a program?](/reference/merchant-action-triggers-guide#what-is-a-program) for more details.


        **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).'
      operationId: programMerchantActionTriggersGet
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionTriggerStatusResponse'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: No action triggers exist for this scope
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    examples:
                    - No action triggers exist for this scope
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      tags:
      - Merchant Action Triggers
      summary: Incremental trigger operations at program scope
      description: 'Perform incremental operations on merchant action triggers at the program scope.


        See the account-scope PATCH endpoint for full documentation on supported operations (add, remove).


        **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/realtime-action-triggers-guide#registering-large-trigger-sets).'
      operationId: programMerchantActionTriggersPatch
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MerchantActionTriggerPatchRequest'
        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
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
      - Merchant Action Triggers
      summary: Register merchant triggers at program scope
      description: '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).'
      operationId: programMerchantActionTriggersPut
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MerchantActionTriggerRegistrationRequest'
        required: true
      responses:
        '201':
          description: Registration created successfully
          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'
  /users/{userId}/merchant-action-triggers:
    parameters:
    - in: path
      name: userId
      schema:
        type: string
        maxLength: 512
      description: Your unique identifier for the user
      required: true
    delete:
      tags:
      - Merchant Action Triggers
      summary: Clear user-level triggers
      description: 'Clear all merchant action triggers at the user scope.


        This creates a new version with an empty trigger list.


        To learn more about action triggers, please read the [Merchant Action Triggers Guide](https://docs.spade.com/reference/merchant-action-triggers-guide).'
      operationId: userMerchantActionTriggersDelete
      responses:
        '204':
          description: Triggers cleared successfully
        '403':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      tags:
      - Merchant Action Triggers
      summary: Get user-level trigger status
      description: 'Get the status and version of the latest merchant action trigger registration at the user scope.


        User-level triggers apply to all transactions for all cards belonging to the specified user.


        **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).'
      operationId: userMerchantActionTriggersGet
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionTriggerStatusResponse'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: No action triggers exist for this scope
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    examples:
                    - No action triggers exist for this scope
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      tags:
      - Merchant Action Triggers
      summary: Incremental trigger operations at user scope
      description: 'Perform incremental operations on merchant action triggers at the user scope.


        See the account-scope PATCH endpoint for full documentation on supported operations (add, remove).'
      operationId: userMerchantActionTriggersPatch
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MerchantActionTriggerPatchRequest'
        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
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
      - Merchant Action Triggers
      summary: Register merchant triggers at user scope
      description: 'Register merchant action triggers at the user scope.


        User-level triggers apply to all transactions for all cards belonging to the specified user.


        **Field requirements:**

        - `id`, `merchantName`, and `action` are always required for each trigger

        - If location fields (address, city) are NOT provided, `website` is required


        **Limit:** A maximum of 100 `merchantTriggers` can be submitted per request at the user scope. Requests exceeding this limit will receive a `400` error.


        **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).'
      operationId: userMerchantActionTriggersPut
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MerchantActionTriggerRegistrationRequest'
        required: true
      responses:
        '201':
          description: Registration created successfully
          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:
    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
    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
    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
    MerchantActionTriggerRegistrationRequest:
      type: object
      description: Request body for registering merchant action triggers.
      required:
      - merchantTriggers
      properties:
        merchantTriggers:
          type: array
          description: '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.

            '
          minItems: 1
          maxItems: 100000
          items:
            $ref: '#/components/schemas/MerchantTriggerItem'
    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 agains

# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/spade/refs/heads/main/openapi/spade-merchant-action-triggers-api-openapi.yml