Extole Rewards API

openapi: 3.0.1
info:
  description: 'Consumer-to-Extole integration endpoints: consumer event submission, zone rendering, profile management, and SDK-backing operations for browser and native app environments.'
  title: Integration API - Consumer to Extole Audiences Rewards API
  version: '1.0'
servers:
- description: Production
  url: https://{brand}.extole.io
  variables:
    brand:
      default: yourcompany
      description: Your Extole client subdomain (e.g. 'mycompany' for mycompany.extole.io)
security:
- HEADER: []
- QUERY: []
- COOKIE: []
tags:
- name: Rewards
paths:
  /v2/rewards:
    get:
      description: Returns reward records for the client matching the specified query parameters.
      operationId: listRewards
      parameters:
      - description: Filter by reward state(s). Repeat for multiple values (e.g. `EARNED`, `FULFILLED`).
        in: query
        name: state
        schema:
          type: string
      - description: Filter by Extole reward supplier id(s). Repeat for multiple values.
        in: query
        name: reward_supplier_id
        schema:
          type: string
      - description: Filter by partner-assigned reward supplier id(s). Repeat for multiple values.
        in: query
        name: partner_reward_supplier_id
        schema:
          type: string
      - description: Filter by Extole person id(s). Repeat for multiple values.
        in: query
        name: person_id
        schema:
          type: string
      - description: Filter by Extole action id(s). Repeat for multiple values.
        in: query
        name: action_id
        schema:
          type: string
      - description: Filter by root event id(s). Repeat for multiple values.
        in: query
        name: root_event_id
        schema:
          type: string
      - description: Filter by partner-assigned reward id(s). Repeat for multiple values.
        in: query
        name: partner_reward_id
        schema:
          type: string
      - description: Filter by reward type(s). Repeat for multiple values.
        in: query
        name: reward_type
        schema:
          type: string
      - description: When true (default), include only rewards that were successfully fulfilled.
        in: query
        name: success_only
        schema:
          type: boolean
      - description: ISO 8601 time interval to restrict results to a date range (e.g. `P30D` for last 30 days).
        in: query
        name: time_interval
        schema:
          type: string
      - description: Maximum number of rewards to return. Defaults to 100.
        in: query
        name: limit
        schema:
          format: int32
          type: integer
      - description: Number of rewards to skip for pagination. Defaults to 0.
        in: query
        name: offset
        schema:
          format: int32
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/RewardResponse'
                type: array
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_limit:
                  $ref: '#/components/examples/invalid_limit'
                invalid_offset:
                  $ref: '#/components/examples/invalid_offset'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                max_fetch_size_1000:
                  $ref: '#/components/examples/max_fetch_size_1000'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
                period_count_invalid:
                  $ref: '#/components/examples/period_count_invalid'
                period_not_supported:
                  $ref: '#/components/examples/period_not_supported'
                reward_state_invalid:
                  $ref: '#/components/examples/reward_state_invalid'
                reward_type_not_supported:
                  $ref: '#/components/examples/reward_type_not_supported'
                time_interval_invalid:
                  $ref: '#/components/examples/time_interval_invalid'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: List rewards
      tags:
      - Rewards
      x-extole-bundle: integration-server-to-extole
      x-extole-visibility: visible
  /v2/rewards/state_summary:
    get:
      description: Returns aggregate state counts for rewards on this client (e.g. earned, fulfilled, cancelled).
      operationId: getRewardStateSummary
      parameters:
      - description: Time period for grouping (e.g. `DAY`, `WEEK`, `MONTH`).
        in: query
        name: period
        schema:
          enum:
          - DAY
          - MONTH
          - WEEK
          type: string
      - description: Number of periods to include in the summary.
        in: query
        name: period_count
        schema:
          type: string
      - description: End of the date range for the summary.
        in: query
        name: end_date
        schema:
          $ref: '#/components/schemas/ZonedDateTime'
      - description: When true, include only rewards that were successfully fulfilled.
        in: query
        name: success_only
        schema:
          type: boolean
      - description: Filter by one or more reward supplier ids (repeat the parameter for multiple values).
        in: query
        name: reward_supplier_id
        schema:
          type: string
      - description: Filter by one or more reward types (repeat the parameter for multiple values).
        in: query
        name: reward_type
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/RewardStateSummaryResponse'
                type: array
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
                period_count_invalid:
                  $ref: '#/components/examples/period_count_invalid'
                period_not_supported:
                  $ref: '#/components/examples/period_not_supported'
                reward_state_invalid:
                  $ref: '#/components/examples/reward_state_invalid'
                reward_type_not_supported:
                  $ref: '#/components/examples/reward_type_not_supported'
                time_interval_invalid:
                  $ref: '#/components/examples/time_interval_invalid'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Get reward state summary
      tags:
      - Rewards
      x-extole-bundle: integration-server-to-extole
      x-extole-visibility: visible
  /v2/rewards/{reward_id}:
    get:
      description: Returns the reward record for the specified reward id, including its current state and history.
      operationId: getReward
      parameters:
      - description: Extole-assigned unique identifier for the reward.
        in: path
        name: reward_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RewardResponse'
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
                period_count_invalid:
                  $ref: '#/components/examples/period_count_invalid'
                period_not_supported:
                  $ref: '#/components/examples/period_not_supported'
                retry_claimed_reward_not_allowed:
                  $ref: '#/components/examples/retry_claimed_reward_not_allowed'
                reward_illegal_state_transition:
                  $ref: '#/components/examples/reward_illegal_state_transition'
                reward_in_not_retryable_state:
                  $ref: '#/components/examples/reward_in_not_retryable_state'
                reward_not_found:
                  $ref: '#/components/examples/reward_not_found'
                reward_retry_not_supported:
                  $ref: '#/components/examples/reward_retry_not_supported'
                reward_state_invalid:
                  $ref: '#/components/examples/reward_state_invalid'
                reward_supplier_not_found:
                  $ref: '#/components/examples/reward_supplier_not_found'
                reward_type_not_supported:
                  $ref: '#/components/examples/reward_type_not_supported'
                sandbox_not_found:
                  $ref: '#/components/examples/sandbox_not_found'
                time_interval_invalid:
                  $ref: '#/components/examples/time_interval_invalid'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Get a reward
      tags:
      - Rewards
      x-extole-bundle: integration-server-to-extole
      x-extole-visibility: visible
    put:
      description: Updates attributes on the specified reward record. Returns the updated reward.
      operationId: updateReward
      parameters:
      - description: Extole-assigned unique identifier for the reward.
        in: path
        name: reward_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              sandbox: sandbox
            schema:
              $ref: '#/components/schemas/RewardUpdateRequest'
        description: Reward update request.
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RewardResponse'
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
                retry_claimed_reward_not_allowed:
                  $ref: '#/components/examples/retry_claimed_reward_not_allowed'
                reward_illegal_state_transition:
                  $ref: '#/components/examples/reward_illegal_state_transition'
                reward_in_not_retryable_state:
                  $ref: '#/components/examples/reward_in_not_retryable_state'
                reward_not_found:
                  $ref: '#/components/examples/reward_not_found'
                reward_retry_not_supported:
                  $ref: '#/components/examples/reward_retry_not_supported'
                reward_supplier_not_found:
                  $ref: '#/components/examples/reward_supplier_not_found'
                sandbox_not_found:
                  $ref: '#/components/examples/sandbox_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
                person_not_found:
                  $ref: '#/components/examples/person_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Update a reward
      tags:
      - Rewards
      x-extole-bundle: integration-server-to-extole
      x-extole-visibility: visible
  /v2/rewards/{reward_id}/cancels:
    get:
      description: Returns the cancellation history for the specified reward.
      operationId: getRewardCancels
      parameters:
      - description: Extole-assigned unique identifier for the reward.
        in: path
        name: reward_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/CanceledRewardStateResponse'
                type: array
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
                period_count_invalid:
                  $ref: '#/components/examples/period_count_invalid'
                period_not_supported:
                  $ref: '#/components/examples/period_not_supported'
                retry_claimed_reward_not_allowed:
                  $ref: '#/components/examples/retry_claimed_reward_not_allowed'
                reward_illegal_state_transition:
                  $ref: '#/components/examples/reward_illegal_state_transition'
                reward_in_not_retryable_state:
                  $ref: '#/components/examples/reward_in_not_retryable_state'
                reward_not_found:
                  $ref: '#/components/examples/reward_not_found'
                reward_retry_not_supported:
                  $ref: '#/components/examples/reward_retry_not_supported'
                reward_state_invalid:
                  $ref: '#/components/examples/reward_state_invalid'
                reward_supplier_not_found:
                  $ref: '#/components/examples/reward_supplier_not_found'
                reward_type_not_supported:
                  $ref: '#/components/examples/reward_type_not_supported'
                sandbox_not_found:
                  $ref: '#/components/examples/sandbox_not_found'
                time_interval_invalid:
                  $ref: '#/components/examples/time_interval_invalid'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Get reward cancels
      tags:
      - Rewards
      x-extole-bundle: integration-server-to-extole
      x-extole-visibility: visible
  /v2/rewards/{reward_id}/fails:
    get:
      description: Returns the fulfilment failure history for the specified reward.
      operationId: getRewardFails
      parameters:
      - description: Extole-assigned unique identifier for the reward.
        in: path
        name: reward_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/FailedRewardStateResponse'
                type: array
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
                period_count_invalid:
                  $ref: '#/components/examples/period_count_invalid'
                period_not_supported:
                  $ref: '#/components/examples/period_not_supported'
                retry_claimed_reward_not_allowed:
                  $ref: '#/components/examples/retry_claimed_reward_not_allowed'
                reward_illegal_state_transition:
                  $ref: '#/components/examples/reward_illegal_state_transition'
                reward_in_not_retryable_state:
                  $ref: '#/components/examples/reward_in_not_retryable_state'
                reward_not_found:
                  $ref: '#/components/examples/reward_not_found'
                reward_retry_not_supported:
                  $ref: '#/components/examples/reward_retry_not_supported'
                reward_state_invalid:
                  $ref: '#/components/examples/reward_state_invalid'
                reward_supplier_not_found:
                  $ref: '#/components/examples/reward_supplier_not_found'
                reward_type_not_supported:
                  $ref: '#/components/examples/reward_type_not_supported'
                sandbox_not_found:
                  $ref: '#/components/examples/sandbox_not_found'
                time_interval_invalid:
                  $ref: '#/components/examples/time_interval_invalid'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Get reward fails
      tags:
      - Rewards
      x-extole-bundle: integration-server-to-extole
      x-extole-visibility: visible
  /v2/rewards/{reward_id}/fulfillments:
    get:
      description: Returns the fulfilment records for the specified reward.
      operationId: getRewardFulfillments
      parameters:
      - description: Extole-assigned unique identifier for the reward.
        in: path
        name: reward_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/FulfilledRewardStateResponse'
                type: array
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
                period_count_invalid:
                  $ref: '#/components/examples/period_count_invalid'
                period_not_supported:
                  $ref: '#/components/examples/period_not_supported'
                retry_claimed_reward_not_allowed:
                  $ref: '#/components/examples/retry_claimed_reward_not_allowed'
                reward_illegal_state_transition:
                  $ref: '#/components/examples/reward_illegal_state_transition'
                reward_in_not_retryable_state:
                  $ref: '#/components/examples/reward_in_not_retryable_state'
                reward_not_found:
                  $ref: '#/components/examples/reward_not_found'
                reward_retry_not_supported:
                  $ref: '#/components/examples/reward_retry_not_supported'
                reward_state_invalid:
                  $ref: '#/components/examples/reward_state_invalid'
                reward_supplier_not_found:
                  $ref: '#/components/examples/reward_supplier_not_found'
                reward_type_not_supported:
                  $ref: '#/components/examples/reward_type_not_supported'
                sandbox_not_found:
                  $ref: '#/components/examples/sandbox_not_found'
                time_interval_invalid:
                  $ref: '#/components/examples/time_interval_invalid'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptio

# --- truncated at 32 KB (86 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/extole/refs/heads/main/openapi/extole-rewards-api-openapi.yml