openapi: 3.2.0
info:
  version: 1.0.0
  title: Accrue Merchant Rewards API
  x-links:
  - name: View Alternative Version
    url: /api-fs/
    description: View API documentation with alternative enum-based WebhookIncluded schema
  description: Partner-issued rewards let trusted integrations credit customer wallets or create pre-issued rewards for recipients identified by phone number. When a recipient has an active wallet, rewards are deposited immediately. When no active wallet exists, a pre-issued reward is created for the user to claim when they sign up. All issue requests require an idempotency key.
servers:
- description: Production API
  url: https://merchant-api.accruesavings.com
- description: Sandbox API
  url: https://merchant-api-sandbox.accruesavings.com
tags:
- name: Rewards
  description: Partner-issued rewards let trusted integrations credit customer wallets or create pre-issued rewards for recipients identified by phone number. When a recipient has an active wallet, rewards are deposited immediately. When no active wallet exists, a pre-issued reward is created for the user to claim when they sign up. All issue requests require an idempotency key.
paths:
  /api/v1/rewards:
    post:
      operationId: issueReward
      tags:
      - Rewards
      summary: Issue Reward
      description: 'Issue a reward to a recipient identified by phone number. If the recipient has exactly one active wallet, the reward is credited immediately (`kind: immediate`, `status: Credited`). Otherwise, if no blocking wallet exists, a pre-issued reward is created (`kind: preIssued`, `status: Created`). All responses use the unified `Reward` resource type. Requires an `idempotencyKey`. Retries are safe when the full request body is unchanged — the API fingerprints the body server-side and replays the prior result for matching key + fingerprint pairs.'
      parameters:
      - schema:
          type: string
          format: uuid
          description: The unique identifier of the client making the request. This header is required to retrieve the client-specific configuration and ensure that the response is tailored to the client's settings and permissions.
          example: 123e4567-e89b-12d3-a456-426614174000
        required: true
        name: Client-ID
        in: header
      - schema:
          type: string
          format: uuid
          description: Secure secret to access privileged endpoints.
          example: Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef
        required: true
        name: Authorization
        in: header
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/IssueRewardRequest'
              required:
              - data
      responses:
        '200':
          description: 'Reward issued successfully. Response is always `type: Reward`; use `kind`, `status`, and capability flags to interpret the outcome.'
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/IssueRewardResponse'
        '400':
          description: Validation error or unresolvable recipient
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/IssueRewardErrorResponse'
        '409':
          description: Conflict — wallet not issuable, pre-issued exists, or idempotency mismatch
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/IssueRewardConflictResponse'
        '500':
          description: Internal Server Error
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/IssueRewardUnexpectedErrorResponse'
      x-codeSamples:
      - lang: Shell
        source: "curl --request POST \\\n  --url https://merchant-api.accruesavings.com/api/v1/rewards \\\n  --header 'Authorization: Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef' \\\n  --header 'Client-ID: 123e4567-e89b-12d3-a456-426614174000'"
      - lang: Node
        source: "const request = require('request');\n\nconst options = {\n  method: 'POST',\n  url: 'https://merchant-api.accruesavings.com/api/v1/rewards',\n  headers: {\n    'Client-ID': '123e4567-e89b-12d3-a456-426614174000',\n    Authorization: 'Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef'\n  }\n};\n\nrequest(options, function (error, response, body) {\n  if (error) throw new Error(error);\n\n  console.log(body);\n});\n"
      - lang: Python
        source: "import http.client\n\nconn = http.client.HTTPSConnection(\"merchant-api.accruesavings.com\")\n\nheaders = {\n    'Client-ID': \"123e4567-e89b-12d3-a456-426614174000\",\n    'Authorization': \"Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef\"\n    }\n\nconn.request(\"POST\", \"/api/v1/rewards\", headers=headers)\n\nres = conn.getresponse()\ndata = res.read()\n\nprint(data.decode(\"utf-8\"))"
      - lang: Ruby
        source: 'require ''uri''

          require ''net/http''

          require ''openssl''


          url = URI("https://merchant-api.accruesavings.com/api/v1/rewards")


          http = Net::HTTP.new(url.host, url.port)

          http.use_ssl = true

          http.verify_mode = OpenSSL::SSL::VERIFY_NONE


          request = Net::HTTP::Post.new(url)

          request["Client-ID"] = ''123e4567-e89b-12d3-a456-426614174000''

          request["Authorization"] = ''Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef''


          response = http.request(request)

          puts response.read_body'
      - lang: Java
        source: "OkHttpClient client = new OkHttpClient();\n\nRequest request = new Request.Builder()\n  .url(\"https://merchant-api.accruesavings.com/api/v1/rewards\")\n  .post(null)\n  .addHeader(\"Client-ID\", \"123e4567-e89b-12d3-a456-426614174000\")\n  .addHeader(\"Authorization\", \"Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef\")\n  .build();\n\nResponse response = client.newCall(request).execute();"
      - lang: Go
        source: "package main\n\nimport (\n\t\"fmt\"\n\t\"net/http\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\n\turl := \"https://merchant-api.accruesavings.com/api/v1/rewards\"\n\n\treq, _ := http.NewRequest(\"POST\", url, nil)\n\n\treq.Header.Add(\"Client-ID\", \"123e4567-e89b-12d3-a456-426614174000\")\n\treq.Header.Add(\"Authorization\", \"Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef\")\n\n\tres, _ := http.DefaultClient.Do(req)\n\n\tdefer res.Body.Close()\n\tbody, _ := ioutil.ReadAll(res.Body)\n\n\tfmt.Println(res)\n\tfmt.Println(string(body))\n\n}"
      - lang: Csharp
        source: 'var client = new RestClient("https://merchant-api.accruesavings.com/api/v1/rewards");

          var request = new RestRequest(Method.POST);

          request.AddHeader("Client-ID", "123e4567-e89b-12d3-a456-426614174000");

          request.AddHeader("Authorization", "Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef");

          IRestResponse response = client.Execute(request);'
      - lang: Php
        source: "<?php\n\n$request = new HttpRequest();\n$request->setUrl('https://merchant-api.accruesavings.com/api/v1/rewards');\n$request->setMethod(HTTP_METH_POST);\n\n$request->setHeaders([\n  'Client-ID' => '123e4567-e89b-12d3-a456-426614174000',\n  'Authorization' => 'Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef'\n]);\n\ntry {\n  $response = $request->send();\n\n  echo $response->getBody();\n} catch (HttpException $ex) {\n  echo $ex;\n}"
    get:
      operationId: listIssuedRewards
      tags:
      - Rewards
      summary: List Issued Rewards
      description: List rewards issued to a recipient. Returns a paginated list of unified `Reward` resources that may include both immediate credits and pre-issued rewards. `filter[phoneNumber]` is required. When `filter[status]` is provided, only pre-issued rewards matching that status are returned.
      parameters:
      - schema:
          type: string
          description: Recipient phone number to look up (required).
          example: '+15551234567'
        required: false
        name: filter[phoneNumber]
        in: query
      - schema:
          type: string
          description: When set, filters to pre-issued rewards with this status only (`Created`, `Claimed`, `Expired`, or `Cancelled`).
          example: Created
        required: false
        name: filter[status]
        in: query
      - schema:
          type: number
          minimum: 1
          maximum: 50
          default: 10
          description: Maximum number of objects that will be returned. Can not be greater than 50.
        required: false
        name: page[limit]
        in: query
      - schema:
          type: number
          minimum: 0
          default: 0
          description: Offset from the beginning of the list of objects. Can not be negative.
        required: false
        name: page[offset]
        in: query
      - schema:
          type: string
          format: uuid
          description: The unique identifier of the client making the request. This header is required to retrieve the client-specific configuration and ensure that the response is tailored to the client's settings and permissions.
          example: 123e4567-e89b-12d3-a456-426614174000
        required: true
        name: Client-ID
        in: header
      - schema:
          type: string
          format: uuid
          description: Secure secret to access privileged endpoints.
          example: Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef
        required: true
        name: Authorization
        in: header
      responses:
        '200':
          description: OK
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ListIssuedRewardsResponse'
        '400':
          description: Validation error
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/InvalidRewardRequestResponse'
        '500':
          description: Internal Server Error
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/RewardLookupUnexpectedErrorResponse'
      x-codeSamples:
      - lang: Shell
        source: "curl --request GET \\\n  --url 'https://merchant-api.accruesavings.com/api/v1/rewards?filter%5BphoneNumber%5D=%2B15551234567&filter%5Bstatus%5D=Created&page%5Blimit%5D=SOME_NUMBER_VALUE&page%5Boffset%5D=SOME_NUMBER_VALUE' \\\n  --header 'Authorization: Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef' \\\n  --header 'Client-ID: 123e4567-e89b-12d3-a456-426614174000'"
      - lang: Node
        source: "const request = require('request');\n\nconst options = {\n  method: 'GET',\n  url: 'https://merchant-api.accruesavings.com/api/v1/rewards',\n  qs: {\n    'filter[phoneNumber]': '+15551234567',\n    'filter[status]': 'Created',\n    'page[limit]': 'SOME_NUMBER_VALUE',\n    'page[offset]': 'SOME_NUMBER_VALUE'\n  },\n  headers: {\n    'Client-ID': '123e4567-e89b-12d3-a456-426614174000',\n    Authorization: 'Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef'\n  }\n};\n\nrequest(options, function (error, response, body) {\n  if (error) throw new Error(error);\n\n  console.log(body);\n});\n"
      - lang: Python
        source: "import http.client\n\nconn = http.client.HTTPSConnection(\"merchant-api.accruesavings.com\")\n\nheaders = {\n    'Client-ID': \"123e4567-e89b-12d3-a456-426614174000\",\n    'Authorization': \"Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef\"\n    }\n\nconn.request(\"GET\", \"/api/v1/rewards?filter%5BphoneNumber%5D=%2B15551234567&filter%5Bstatus%5D=Created&page%5Blimit%5D=SOME_NUMBER_VALUE&page%5Boffset%5D=SOME_NUMBER_VALUE\", headers=headers)\n\nres = conn.getresponse()\ndata = res.read()\n\nprint(data.decode(\"utf-8\"))"
      - lang: Ruby
        source: 'require ''uri''

          require ''net/http''

          require ''openssl''


          url = URI("https://merchant-api.accruesavings.com/api/v1/rewards?filter%5BphoneNumber%5D=%2B15551234567&filter%5Bstatus%5D=Created&page%5Blimit%5D=SOME_NUMBER_VALUE&page%5Boffset%5D=SOME_NUMBER_VALUE")


          http = Net::HTTP.new(url.host, url.port)

          http.use_ssl = true

          http.verify_mode = OpenSSL::SSL::VERIFY_NONE


          request = Net::HTTP::Get.new(url)

          request["Client-ID"] = ''123e4567-e89b-12d3-a456-426614174000''

          request["Authorization"] = ''Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef''


          response = http.request(request)

          puts response.read_body'
      - lang: Java
        source: "OkHttpClient client = new OkHttpClient();\n\nRequest request = new Request.Builder()\n  .url(\"https://merchant-api.accruesavings.com/api/v1/rewards?filter%5BphoneNumber%5D=%2B15551234567&filter%5Bstatus%5D=Created&page%5Blimit%5D=SOME_NUMBER_VALUE&page%5Boffset%5D=SOME_NUMBER_VALUE\")\n  .get()\n  .addHeader(\"Client-ID\", \"123e4567-e89b-12d3-a456-426614174000\")\n  .addHeader(\"Authorization\", \"Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef\")\n  .build();\n\nResponse response = client.newCall(request).execute();"
      - lang: Go
        source: "package main\n\nimport (\n\t\"fmt\"\n\t\"net/http\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\n\turl := \"https://merchant-api.accruesavings.com/api/v1/rewards?filter%5BphoneNumber%5D=%2B15551234567&filter%5Bstatus%5D=Created&page%5Blimit%5D=SOME_NUMBER_VALUE&page%5Boffset%5D=SOME_NUMBER_VALUE\"\n\n\treq, _ := http.NewRequest(\"GET\", url, nil)\n\n\treq.Header.Add(\"Client-ID\", \"123e4567-e89b-12d3-a456-426614174000\")\n\treq.Header.Add(\"Authorization\", \"Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef\")\n\n\tres, _ := http.DefaultClient.Do(req)\n\n\tdefer res.Body.Close()\n\tbody, _ := ioutil.ReadAll(res.Body)\n\n\tfmt.Println(res)\n\tfmt.Println(string(body))\n\n}"
      - lang: Csharp
        source: 'var client = new RestClient("https://merchant-api.accruesavings.com/api/v1/rewards?filter%5BphoneNumber%5D=%2B15551234567&filter%5Bstatus%5D=Created&page%5Blimit%5D=SOME_NUMBER_VALUE&page%5Boffset%5D=SOME_NUMBER_VALUE");

          var request = new RestRequest(Method.GET);

          request.AddHeader("Client-ID", "123e4567-e89b-12d3-a456-426614174000");

          request.AddHeader("Authorization", "Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef");

          IRestResponse response = client.Execute(request);'
      - lang: Php
        source: "<?php\n\n$request = new HttpRequest();\n$request->setUrl('https://merchant-api.accruesavings.com/api/v1/rewards');\n$request->setMethod(HTTP_METH_GET);\n\n$request->setQueryData([\n  'filter[phoneNumber]' => '+15551234567',\n  'filter[status]' => 'Created',\n  'page[limit]' => 'SOME_NUMBER_VALUE',\n  'page[offset]' => 'SOME_NUMBER_VALUE'\n]);\n\n$request->setHeaders([\n  'Client-ID' => '123e4567-e89b-12d3-a456-426614174000',\n  'Authorization' => 'Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef'\n]);\n\ntry {\n  $response = $request->send();\n\n  echo $response->getBody();\n} catch (HttpException $ex) {\n  echo $ex;\n}"
  /api/v1/rewards/{id}:
    get:
      operationId: getIssuedRewardById
      tags:
      - Rewards
      summary: Get Issued Reward by ID
      description: 'Look up a single issued reward by ID. Returns a unified `Reward` resource when found, or `{ data: null }` when not found.'
      parameters:
      - schema:
          type: string
          format: uuid
          description: Reward ID (immediate credit or pre-issued reward).
          example: 123e4567-e89b-12d3-a456-426614174000
        required: true
        name: id
        in: path
      - schema:
          type: string
          format: uuid
          description: The unique identifier of the client making the request. This header is required to retrieve the client-specific configuration and ensure that the response is tailored to the client's settings and permissions.
          example: 123e4567-e89b-12d3-a456-426614174000
        required: true
        name: Client-ID
        in: header
      - schema:
          type: string
          format: uuid
          description: Secure secret to access privileged endpoints.
          example: Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef
        required: true
        name: Authorization
        in: header
      responses:
        '200':
          description: OK — reward found or `data` is null
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/GetIssuedRewardByIdResponse'
        '400':
          description: Validation error
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/InvalidRewardRequestResponse'
        '500':
          description: Internal Server Error
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/RewardLookupUnexpectedErrorResponse'
      x-codeSamples:
      - lang: Shell
        source: "curl --request GET \\\n  --url https://merchant-api.accruesavings.com/api/v1/rewards/123e4567-e89b-12d3-a456-426614174000 \\\n  --header 'Authorization: Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef' \\\n  --header 'Client-ID: 123e4567-e89b-12d3-a456-426614174000'"
      - lang: Node
        source: "const request = require('request');\n\nconst options = {\n  method: 'GET',\n  url: 'https://merchant-api.accruesavings.com/api/v1/rewards/123e4567-e89b-12d3-a456-426614174000',\n  headers: {\n    'Client-ID': '123e4567-e89b-12d3-a456-426614174000',\n    Authorization: 'Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef'\n  }\n};\n\nrequest(options, function (error, response, body) {\n  if (error) throw new Error(error);\n\n  console.log(body);\n});\n"
      - lang: Python
        source: "import http.client\n\nconn = http.client.HTTPSConnection(\"merchant-api.accruesavings.com\")\n\nheaders = {\n    'Client-ID': \"123e4567-e89b-12d3-a456-426614174000\",\n    'Authorization': \"Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef\"\n    }\n\nconn.request(\"GET\", \"/api/v1/rewards/123e4567-e89b-12d3-a456-426614174000\", headers=headers)\n\nres = conn.getresponse()\ndata = res.read()\n\nprint(data.decode(\"utf-8\"))"
      - lang: Ruby
        source: 'require ''uri''

          require ''net/http''

          require ''openssl''


          url = URI("https://merchant-api.accruesavings.com/api/v1/rewards/123e4567-e89b-12d3-a456-426614174000")


          http = Net::HTTP.new(url.host, url.port)

          http.use_ssl = true

          http.verify_mode = OpenSSL::SSL::VERIFY_NONE


          request = Net::HTTP::Get.new(url)

          request["Client-ID"] = ''123e4567-e89b-12d3-a456-426614174000''

          request["Authorization"] = ''Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef''


          response = http.request(request)

          puts response.read_body'
      - lang: Java
        source: "OkHttpClient client = new OkHttpClient();\n\nRequest request = new Request.Builder()\n  .url(\"https://merchant-api.accruesavings.com/api/v1/rewards/123e4567-e89b-12d3-a456-426614174000\")\n  .get()\n  .addHeader(\"Client-ID\", \"123e4567-e89b-12d3-a456-426614174000\")\n  .addHeader(\"Authorization\", \"Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef\")\n  .build();\n\nResponse response = client.newCall(request).execute();"
      - lang: Go
        source: "package main\n\nimport (\n\t\"fmt\"\n\t\"net/http\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\n\turl := \"https://merchant-api.accruesavings.com/api/v1/rewards/123e4567-e89b-12d3-a456-426614174000\"\n\n\treq, _ := http.NewRequest(\"GET\", url, nil)\n\n\treq.Header.Add(\"Client-ID\", \"123e4567-e89b-12d3-a456-426614174000\")\n\treq.Header.Add(\"Authorization\", \"Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef\")\n\n\tres, _ := http.DefaultClient.Do(req)\n\n\tdefer res.Body.Close()\n\tbody, _ := ioutil.ReadAll(res.Body)\n\n\tfmt.Println(res)\n\tfmt.Println(string(body))\n\n}"
      - lang: Csharp
        source: 'var client = new RestClient("https://merchant-api.accruesavings.com/api/v1/rewards/123e4567-e89b-12d3-a456-426614174000");

          var request = new RestRequest(Method.GET);

          request.AddHeader("Client-ID", "123e4567-e89b-12d3-a456-426614174000");

          request.AddHeader("Authorization", "Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef");

          IRestResponse response = client.Execute(request);'
      - lang: Php
        source: "<?php\n\n$request = new HttpRequest();\n$request->setUrl('https://merchant-api.accruesavings.com/api/v1/rewards/123e4567-e89b-12d3-a456-426614174000');\n$request->setMethod(HTTP_METH_GET);\n\n$request->setHeaders([\n  'Client-ID' => '123e4567-e89b-12d3-a456-426614174000',\n  'Authorization' => 'Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef'\n]);\n\ntry {\n  $response = $request->send();\n\n  echo $response->getBody();\n} catch (HttpException $ex) {\n  echo $ex;\n}"
    patch:
      operationId: updateReward
      tags:
      - Rewards
      summary: Update Reward
      description: Update a reward when `canUpdate` is `true` (pre-issued rewards in `Created` status). At least one attribute must be provided. Returns the updated unified `Reward` resource.
      parameters:
      - schema:
          type: string
          format: uuid
          description: Reward ID.
          example: 123e4567-e89b-12d3-a456-426614174000
        required: true
        name: id
        in: path
      - schema:
          type: string
          format: uuid
          description: The unique identifier of the client making the request. This header is required to retrieve the client-specific configuration and ensure that the response is tailored to the client's settings and permissions.
          example: 123e4567-e89b-12d3-a456-426614174000
        required: true
        name: Client-ID
        in: header
      - schema:
          type: string
          format: uuid
          description: Secure secret to access privileged endpoints.
          example: Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef
        required: true
        name: Authorization
        in: header
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/UpdateRewardRequest'
              required:
              - data
      responses:
        '200':
          description: Reward updated successfully
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/UpdateRewardResponse'
        '400':
          description: Validation error
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/InvalidRewardRequestResponse'
        '404':
          description: Reward not found
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/RewardNotFoundResponse'
        '409':
          description: Reward cannot be modified in its current state
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/InvalidRewardStateResponse'
        '500':
          description: Internal Server Error
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/RewardManagementUnexpectedErrorResponse'
      x-codeSamples:
      - lang: Shell
        source: "curl --request PATCH \\\n  --url https://merchant-api.accruesavings.com/api/v1/rewards/123e4567-e89b-12d3-a456-426614174000 \\\n  --header 'Authorization: Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef' \\\n  --header 'Client-ID: 123e4567-e89b-12d3-a456-426614174000'"
      - lang: Node
        source: "const request = require('request');\n\nconst options = {\n  method: 'PATCH',\n  url: 'https://merchant-api.accruesavings.com/api/v1/rewards/123e4567-e89b-12d3-a456-426614174000',\n  headers: {\n    'Client-ID': '123e4567-e89b-12d3-a456-426614174000',\n    Authorization: 'Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef'\n  }\n};\n\nrequest(options, function (error, response, body) {\n  if (error) throw new Error(error);\n\n  console.log(body);\n});\n"
      - lang: Python
        source: "import http.client\n\nconn = http.client.HTTPSConnection(\"merchant-api.accruesavings.com\")\n\nheaders = {\n    'Client-ID': \"123e4567-e89b-12d3-a456-426614174000\",\n    'Authorization': \"Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef\"\n    }\n\nconn.request(\"PATCH\", \"/api/v1/rewards/123e4567-e89b-12d3-a456-426614174000\", headers=headers)\n\nres = conn.getresponse()\ndata = res.read()\n\nprint(data.decode(\"utf-8\"))"
      - lang: Ruby
        source: 'require ''uri''

          require ''net/http''

          require ''openssl''


          url = URI("https://merchant-api.accruesavings.com/api/v1/rewards/123e4567-e89b-12d3-a456-426614174000")


          http = Net::HTTP.new(url.host, url.port)

          http.use_ssl = true

          http.verify_mode = OpenSSL::SSL::VERIFY_NONE


          request = Net::HTTP::Patch.new(url)

          request["Client-ID"] = ''123e4567-e89b-12d3-a456-426614174000''

          request["Authorization"] = ''Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef''


          response = http.request(request)

          puts response.read_body'
      - lang: Java
        source: "OkHttpClient client = new OkHttpClient();\n\nRequest request = new Request.Builder()\n  .url(\"https://merchant-api.accruesavings.com/api/v1/rewards/123e4567-e89b-12d3-a456-426614174000\")\n  .patch(null)\n  .addHeader(\"Client-ID\", \"123e4567-e89b-12d3-a456-426614174000\")\n  .addHeader(\"Authorization\", \"Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef\")\n  .build();\n\nResponse response = client.newCall(request).execute();"
      - lang: Go
        source: "package main\n\nimport (\n\t\"fmt\"\n\t\"net/http\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\n\turl := \"https://merchant-api.accruesavings.com/api/v1/rewards/123e4567-e89b-12d3-a456-426614174000\"\n\n\treq, _ := http.NewRequest(\"PATCH\", url, nil)\n\n\treq.Header.Add(\"Client-ID\", \"123e4567-e89b-12d3-a456-426614174000\")\n\treq.Header.Add(\"Authorization\", \"Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef\")\n\n\tres, _ := http.DefaultClient.Do(req)\n\n\tdefer res.Body.Close()\n\tbody, _ := ioutil.ReadAll(res.Body)\n\n\tfmt.Println(res)\n\tfmt.Println(string(body))\n\n}"
      - lang: Csharp
        source: 'var client = new RestClient("https://merchant-api.accruesavings.com/api/v1/rewards/123e4567-e89b-12d3-a456-426614174000");

          var request = new RestRequest(Method.PATCH);

          request.AddHeader("Client-ID", "123e4567-e89b-12d3-a456-426614174000");

          request.AddHeader("Authorization", "Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef");

          IRestResponse response = client.Execute(request);'
      - lang: Php
        source: "<?php\n\nHttpRequest::methodRegister('PATCH');\n$request = new HttpRequest();\n$request->setUrl('https://merchant-api.accruesavings.com/api/v1/rewards/123e4567-e89b-12d3-a456-426614174000');\n$request->setMethod(HttpRequest::HTTP_METH_PATCH);\n\n$request->setHeaders([\n  'Client-ID' => '123e4567-e89b-12d3-a456-426614174000',\n  'Authorization' => 'Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef'\n]);\n\ntry {\n  $response = $request->send();\n\n  echo $response->getBody();\n} catch (HttpException $ex) {\n  echo $ex;\n}"
    delete:
      operationId: cancelReward
      tags:
      - Rewards
      summary: Cancel Reward
      description: Cancel a reward when `canCancel` is `true` (pre-issued rewards in `Created` status). Returns `204 No Content` on success.
      parameters:
      - schema:
          type: string
          format: uuid
          description: Reward ID.
          example: 123e4567-e89b-12d3-a456-426614174000
        required: true
        name: id
        in: path
      - schema:
          type: string
          format: uuid
          description: The unique identifier of the client making the request. This header is required to retrieve the client-specific configuration and ensure that the response is tailored to the client's settings and permissions.
          example: 123e4567-e89b-12d3-a456-426614174000
        required: true
        name: Client-ID
        in: header
      - schema:
          type: string
          format: uuid
          description: Secure secret to access privileged endpoints.
          example: Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef
        required: true
        name: Authorization
        in: header
      responses:
        '204':
          description: Reward cancelled successfully
        '404':
          description: Reward not found
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/RewardNotFoundResponse'
        '409':
          description: Reward cannot be modified in its current state
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/InvalidRewardStateResponse'
        '500':
          description: Internal Server Error
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/RewardManagementUnexpectedErrorResponse'
      x-codeSamples:
      - lang: Shell
        source: "curl --request DELETE \\\n  --url https://merchant-api.accruesavings.com/api/v1/rewards/123e4567-e89b-12d3-a456-426614174000 \\\n  --header 'Authorization: Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef' \\\n  --header 'Client-ID: 123e4567-e89b-12d3-a456-426614174000'"
      - lang: Node
        source: "const request = require('request');\n\nconst options = {\n  method: 'DELETE',\n  url: 'https://merchant-api.accruesavings.com/api/v1/rewards/123e4567-e89b-12d3-a456-426614174000',\n  headers: {\n    'Client-ID': '123e4567-e89b-12d3-a456-426614174000',\n    Authorization: 'Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef'\n  }\n};\n\nrequest(options, function (error, response, body) {\n  if (error) throw new Error(error);\n\n  console.log(body);\n});\n"
      - lang: Python
        source: "import http.client\n\nconn = http.client.HTTPSConnection(\"merchant-api.accruesavings.com\")\n\nheaders = {\n    'Client-ID': \"123e4567-e89b-12d3-a456-426614174000\",\n    'Authorization': \"Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef\"\n    }\n\nconn.request(\"DELETE\", \"/api/v1/rewards/123e4567-e89b-12d3-a456-426614174000\", headers=headers)\n\nres = conn.getresponse()\ndata = res.read()\n\nprint(data.decode(\"utf-8\"))"
      - lang: Ruby
        source: 'require ''uri''

          require ''net/http''

          require ''openssl''


          url = URI("https://merchant-api.accruesavings.com/api/v1/rewards/123e4567-e89b-12d3-a456-426614174000")


          http = Net::HTTP.new(url.host, url.port)

          http.use_ssl = true

          http.verify_mode = OpenSSL::SSL::VERIFY_NONE


          request = Net::HTTP::Delete.new(url)

          request["Client-ID"] = ''123e4567-e89b-12d3-a456-426614174000''

          request["Authorization"] = ''Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef''


          response = http.request(request)

          puts response.read_body'
      - lang: Java
        source: "OkHttpClient client = new OkHttpClient();\n\nRequest request = new Request.Builder()\n  .url(\"https://merchant-api.accruesavings.com/api/v1/rewards/123e4567-e89b-12d3-a456-426614174000\")\n  .delete(null)\n  .addHeader(\"Client-ID\", \"123e4567-e89b-12d3-a456-426614174000\")\n  .addHeader(\"Authorization\", \"Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef\")\n  .build();\n\nResponse response = client.newCall(request).execute();"
      - lang: Go
        source: "package main\n\nimport (\n\t\"fmt\"\n\t\"net/http\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\n\turl := \"https://merchant-api.accruesavings.com/api/v1/rewards/123e4567-e89b-12d3-a456-426614174000\"\n\n\treq, _ := http.NewRequest(\"DELETE\", url, nil)\n\n\treq.Header.Add(\"Client-ID\", \"123e4567-e89b-12d3-a456-426614174000\")\n\treq.Header.Add(\"Authorization\", \"Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef\")\n\n\tres, _ := http.DefaultClient.Do(req)\n\n\tdefer res.Body.Close()\n\tbody, _ := ioutil.ReadAll(res.Body)\n\n\tfmt.Println(res)\n\tfmt.Println(string(body))\n\n}"
      - lang: Csharp
        source: 'var client = new RestClient("https://merchant-api.accruesavings.com/api/v1/rewards/123e4567-e89b-12d3-a456-426614174000");

          var request = new RestRequest(Method.DELETE);

          request.AddHeader("Client-ID", "123e4567-e89b-12d3-a456-426614174000");

          request.AddHeader("Authorization", "Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef");

          IRestResponse response = client.Execute(request);'
      - lang: Php
        source: "<?php\n\n$request = new HttpRequest();\n$request->setUrl('https://merchant-api.accruesavings.com/api/v1/rewards/123e4567-e89b-12d3-a456-426614174000');\n$request->setMethod(HTTP_METH_DELETE);\n\n$request->setHeaders([\n  'Client-ID' => '123e4567-e89b-12d3-a456-426614174000',\n  'Authorization' => 'Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef'\n]);\n\ntry {\n  $response = $request->send();\n\n  echo $response->getBody();\n} catch (HttpException $ex) {\n  echo $ex;\n}"
components:
  schemas:
    IssueRewardResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/RewardResponse'
      required:
      - data
    IssueRewardConflictResponse:
      anyOf:
      - $ref: '#/components/schemas/WalletNotIssuableResponse'
      - $ref: '#/components/schemas/PreIssuedConflictResponse'
      - $ref: '#/components/schemas/IdempotencyConflictResponse'
    IssueRewardUnexpectedErrorResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: A unique UUID for this particular occurrence of the problem.
          example: 123e4567-e89b-12d3-a456-426614174000
        status:
          type: integer
          description: The HTTP status code applicable to this error.
          example: 500
        code:
          type: string
          enum:
          - UnexpectedError
          description: A unique, camel-cased Accrue-specific code detailing the error.
          example: UnexpectedError
        title:
          type: string
          description: Generic title for the error.
          example: RewardIssuanceError
        detail:
          type: string
          description: A human-readable explanation providing more insights about the error.
          examples:
          - Failed to issue reward.
        meta:
          type: object
          properties:
            environment:
              type: string
              enum:
              - production
              - sandbox
              example: sandbox
            timestamp:
              type: string
              format: date-time
              example: '2025-06-23T12:00:00.000Z'
            path:
              type: string
              example: /api/v1/rewards
          required:
          - environment
          - timestamp
          - path
          example:
            environment: sandbox
            timestamp: '2025-06-23T12:00:00.000Z'
            path: /api/v1/rewards
      required:
      - id
      - status
      - code
      - title
      - detail
      - meta
    IssueRewardWalletNotFoundResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: A unique UUID for this particular occurrence of the problem.
          example: 123e4567-e89b-12d3-a456-426614174000
        status:
          type: integer
          description: The HTTP status code applicable to this error.
          example: 400
        code:
          type: string
          enum:
          - WalletNotFound
          description: A unique, camel-cased Accrue-specific code detailing the error.
          example: WalletNotFound
        title:
          type: string
          description: Generic title for the error.
          example: RewardException
        detail:
          type: string
          description: A human-readable explanation providing more insights about the error.
          examples:
          - Wallet not found for recipient.
        meta:
          type: object
          properties:
            environment:
              type: string
              enum:
              - production
              - sandbox
              example: sandbox
            timestamp:
              type: string
              format: date-time
              example: '2025-06-23T12:00:00.000Z'
            path:
              type: string
              example: /api/v1/rewards
          required:
          - environment
          - timestamp
          - path
          example:
            environment: sandbox
            timestamp: '2025-06-23T12:00:00.000Z'
            path: /api/v1/rewards
      required:
      - id
      - status
      - code
      - title
      - detail
      - meta
    RewardNotFoundResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: A unique UUID for this particular occurrence of the problem.
          example: 123e4567-e89b-12d3-a456-426614174000
        status:
          type: integer
          description: The HTTP status code applicable to this error.
          example: 404
        code:
          type: string
          enum:
          - NotFound
          description: A unique, camel-cased Accrue-specific code detailing the error.
          example: NotFound
        title:
          type: string
          description: Generic title for the error.
          example: RewardNotFoundException
        detail:
          type: string
          description: A human-readable explanation providing more insights about the error.
          examples:
          - Reward not found.
        meta:
          type: object
          properties:
            environment:
              type: string
              enum:
              - production
              - sandbox
              example: sandbox
            timestamp:
              type: string
              format: date-time
              example: '2025-06-23T12:00:00.000Z'
            path:
              type: string
              example: /api/v1/rewards/123e4567-e89b-12d3-a456-426614174000
          required:
          - environment
          - timestamp
          - path
          example:
            environment: sandbox
            timestamp: '2025-06-23T12:00:00.000Z'
            path: /api/v1/rewards/123e4567-e89b-12d3-a456-426614174000
      required:
      - id
      - status
      - code
      - title
      - detail
      - meta
    MultipleActiveWalletsResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: A unique UUID for this particular occurrence of the problem.
          example: 123e4567-e89b-12d3-a456-426614174000
        status:
          type: integer
          description: The HTTP status code applicable to this error.
          example: 400
        code:
          type: string
          enum:
          - MultipleActiveWallets
          description: A unique, camel-cased Accrue-specific code detailing the error.
          example: MultipleActiveWallets
        title:
          type: string
          description: Generic title for the error.
          example: RewardException
        detail:
          type: string
          description: A human-readable explanation providing more insights about the error.
          examples:
          - Multiple active wallets match this phone number.
        meta:
          type: object
          properties:
            environment:
              type: string
              enum:
              - production
              - sandbox
              example: sandbox
            timestamp:
              type: string
              format: date-time
              example: '2025-06-23T12:00:00.000Z'
            path:
              type: string
              example: /api/v1/rewards
          required:
          - environment
          - timestamp
          - path
          example:
            environment: sandbox
            timestamp: '2025-06-23T12:00:00.000Z'
            path: /api/v1/rewards
      required:
      - id
      - status
      - code
      - title
      - detail
      - meta
    IssueRewardRequest:
      type: object
      properties:
        type:
          type: string
          enum:
          - IssueReward
        attributes:
          type: object
          properties:
            phoneNumber:
              type: string
              minLength: 1
              description: Recipient phone number in E.164 or supported national format.
              example: '+15551234567'
            amount:
              type: integer
              exclusiveMinimum: 0
              maximum: 2147483647
              description: Reward amount in cents. Must be a positive integer.
              format: int32
              example: 500
            idempotencyKey:
              type: string
              minLength: 1
              maxLength: 255
              description: Required idempotency key (1–255 characters). Idempotency is scoped to this key plus a server-computed SHA-256 fingerprint of the normalized phone number, amount, and optional metadata fields (`message`, `reasonCode`, `costCenter`, `notificationEmail`). Reusing the same key with an identical request body returns the original result. Reusing the key with any change to those fields returns `409 IdempotencyConflict`.
              example: reward-2025-06-11-001
            message:
              type: string
              description: Optional message shown to the recipient.
              example: Thanks for being a valued customer!
            reasonCode:
              type: string
              description: Partner-defined reason code.
              example: CX-COMPENSATION-001
            costCenter:
              type: string
              description: Partner-defined cost center.
              example: CX-SUPPORT
            notificationEmail:
              type: string
              format: email
              description: Email to notify when a pre-issued reward is claimed.
              example: agent@partner.example
          required:
          - phoneNumber
          - amount
          - idempotencyKey
      required:
      - type
      - attributes
      description: Request to issue a reward to a phone number.
      x-tags:
      - Model
    InvalidRewardRequestResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: A unique UUID for this particular occurrence of the problem.
          example: 123e4567-e89b-12d3-a456-426614174000
        status:
          type: integer
          description: The HTTP status code applicable to this error.
          example: 400
        code:
          type: string
          enum:
          - InvalidRequest
          description: A unique, camel-cased Accrue-specific code detailing the error.
          example: InvalidRequest
        title:
          type: string
          description: Generic title for the error.
          example: RewardException
        detail:
          type: string
          description: A human-readable explanation providing more insights about the error.
          examples:
          - Invalid phone number format
          - Amount must be greater than 0
          - Invalid notification email format
        meta:
          type: object
          properties:
            environment:
              type: string
              enum:
              - production
              - sandbox
              example: sandbox
            timestamp:
              type: string
              format: date-time
              example: '2025-06-23T12:00:00.000Z'
            path:
              type: string
              example: /api/v1/rewards
          required:
          - environment
          - timestamp
          - path
          example:
            environment: sandbox
            timestamp: '2025-06-23T12:00:00.000Z'
            path: /api/v1/rewards
      required:
      - id
      - status
      - code
      - title
      - detail
      - meta
    GetIssuedRewardByIdResponse:
      type: object
      properties:
        data:
          allOf:
          - $ref: '#/components/schemas/RewardResponse'
          - type:
            - object
            - 'null'
      required:
      - data
    RewardResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the object.
          readOnly: true
        type:
          type: string
          enum:
          - Reward
        attributes:
          type: object
          properties:
            kind:
              type: string
              enum:
              - immediate
              - preIssued
              description: Informational discriminator only. Use `canUpdate` and `canCancel` to decide which operations are allowed — do not branch behavior on `kind` alone.
              example: immediate
            amount:
              type: integer
              exclusiveMinimum: 0
              description: Reward amount in cents.
              format: int32
              example: 500
            walletId:
              type:
              - string
              - 'null'
              format: uuid
              description: Wallet that received the reward. Set for immediate credits; `null` for pre-issued rewards awaiting claim.
              example: 497f6eca-6276-4993-bfeb-53cbbbba6f08
            status:
              type: string
              enum:
              - Credited
              - Created
              - Claimed
              - Expired
              - Cancelled
              description: Unified lifecycle status. Immediate wallet credits are `Credited`; pre-issued rewards use `Created`, `Claimed`, `Expired`, or `Cancelled`.
              example: Credited
            canUpdate:
              type: boolean
              description: Whether `PATCH /api/v1/rewards/{id}` is allowed for this reward.
              example: false
            canCancel:
              type: boolean
              description: Whether `DELETE /api/v1/rewards/{id}` is allowed for this reward.
              example: false
            claimExpiresAt:
              type:
              - string
              - 'null'
              format: date-time
              description: When a pre-issued reward must be claimed before it expires. `null` for immediate wallet credits.
              example: '2026-09-15T12:00:00.000Z'
            message:
              type:
              - string
              - 'null'
              description: Optional message attached to the reward.
              example: Thank you for your loyalty!
            reasonCode:
              type:
              - string
              - 'null'
              description: Partner-defined reason code for reporting and reconciliation.
              example: CX-COMPENSATION-001
            costCenter:
              type:
              - string
              - 'null'
              description: Partner-defined cost center for reporting.
              example: CX-SUPPORT
            notificationEmail:
              type:
              - string
              - 'null'
              format: email
              description: Email address to notify when a pre-issued reward is claimed.
              example: agent@partner.example
          required:
          - kind
          - amount
          - walletId
          - status
          - canUpdate
          - canCancel
          - claimExpiresAt
          - message
          - reasonCode
          - costCenter
          - notificationEmail
      required:
      - id
      - type
      - attributes
      description: Unified reward resource for both immediate wallet credits and pre-issued rewards awaiting claim.
      x-tags:
      - Model
    IssueRewardErrorResponse:
      anyOf:
      - $ref: '#/components/schemas/InvalidRewardRequestResponse'
      - $ref: '#/components/schemas/IssueRewardWalletNotFoundResponse'
      - $ref: '#/components/schemas/MultipleActiveWalletsResponse'
    UpdateRewardResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/RewardResponse'
      required:
      - data
    RewardLookupUnexpectedErrorResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: A unique UUID for this particular occurrence of the problem.
          example: 123e4567-e89b-12d3-a456-426614174000
        status:
          type: integer
          description: The HTTP status code applicable to this error.
          example: 500
        code:
          type: string
          enum:
          - UnexpectedError
          description: A unique, camel-cased Accrue-specific code detailing the error.
          example: UnexpectedError
        title:
          type: string
          description: Generic title for the error.
          example: RewardLookupError
        detail:
          type: string
          description: A human-readable explanation providing more insights about the error.
          examples:
          - Failed to look up reward.
        meta:
          type: object
          properties:
            environment:
              type: string
              enum:
              - production
              - sandbox
              example: sandbox
            timestamp:
              type: string
              format: date-time
              example: '2025-06-23T12:00:00.000Z'
            path:
              type: string
              example: /api/v1/rewards
          required:
          - environment
          - timestamp
          - path
          example:
            environment: sandbox
            timestamp: '2025-06-23T12:00:00.000Z'
            path: /api/v1/rewards
      required:
      - id
      - status
      - code
      - title
      - detail
      - meta
    IdempotencyConflictResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: A unique UUID for this particular occurrence of the problem.
          example: 123e4567-e89b-12d3-a456-426614174000
        status:
          type: integer
          description: The HTTP status code applicable to this error.
          example: 409
        code:
          type: string
          enum:
          - IdempotencyConflict
          description: A unique, camel-cased Accrue-specific code detailing the error.
          example: IdempotencyConflict
        title:
          type: string
          description: Generic title for the error.
          example: RewardConflictException
        detail:
          type: string
          description: A human-readable explanation providing more insights about the error.
          examples:
          - Idempotency key reused with a different payload.
        meta:
          type: object
          properties:
            environment:
              type: string
              enum:
              - production
              - sandbox
              example: sandbox
            timestamp:
              type: string
              format: date-time
              example: '2025-06-23T12:00:00.000Z'
            path:
              type: string
              example: /api/v1/rewards
          required:
          - environment
          - timestamp
          - path
          example:
            environment: sandbox
            timestamp: '2025-06-23T12:00:00.000Z'
            path: /api/v1/rewards
      required:
      - id
      - status
      - code
      - title
      - detail
      - meta
    WalletNotIssuableResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: A unique UUID for this particular occurrence of the problem.
          example: 123e4567-e89b-12d3-a456-426614174000
        status:
          type: integer
          description: The HTTP status code applicable to this error.
          example: 409
        code:
          type: string
          enum:
          - WalletNotIssuable
          description: A unique, camel-cased Accrue-specific code detailing the error.
          example: WalletNotIssuable
        title:
          type: string
          description: Generic title for the error.
          example: RewardConflictException
        detail:
          type: string
          description: A human-readable explanation providing more insights about the error.
          examples:
          - The recipient wallet cannot receive issued rewards in its current state.
        meta:
          type: object
          properties:
            environment:
              type: string
              enum:
              - production
              - sandbox
              example: sandbox
            timestamp:
              type: string
              format: date-time
              example: '2025-06-23T12:00:00.000Z'
            path:
              type: string
              example: /api/v1/rewards
          required:
          - environment
          - timestamp
          - path
          example:
            environment: sandbox
            timestamp: '2025-06-23T12:00:00.000Z'
            path: /api/v1/rewards
      required:
      - id
      - status
      - code
      - title
      - detail
      - meta
    RewardManagementUnexpectedErrorResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: A unique UUID for this particular occurrence of the problem.
          example: 123e4567-e89b-12d3-a456-426614174000
        status:
          type: integer
          description: The HTTP status code applicable to this error.
          example: 500
        code:
          type: string
          enum:
          - UnexpectedError
          description: A unique, camel-cased Accrue-specific code detailing the error.
          example: UnexpectedError
        title:
          type: string
          description: Generic title for the error.
          example: RewardManagementError
        detail:
          type: string
          description: A human-readable explanation providing more insights about the error.
          examples:
          - Failed to update or cancel reward.
        meta:
          type: object
          properties:
            environment:
              type: string
              enum:
              - production
              - sandbox
              example: sandbox
            timestamp:
              type: string
              format: date-time
              example: '2025-06-23T12:00:00.000Z'
            path:
              type: string
              example: /api/v1/rewards/123e4567-e89b-12d3-a456-426614174000
          required:
          - environment
          - timestamp
          - path
          example:
            environment: sandbox
            timestamp: '2025-06-23T12:00:00.000Z'
            path: /api/v1/rewards/123e4567-e89b-12d3-a456-426614174000
      required:
      - id
      - status
      - code
      - title
      - detail
      - meta
    ListIssuedRewardsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/RewardResponse'
        meta:
          type: object
          properties:
            total:
              type: number
              example: 1
            limit:
              type: number
              example: 10
            offset:
              type: number
              example: 0
          required:
          - total
          - limit
          - offset
      required:
      - data
      - meta
    UpdateRewardRequest:
      type: object
      properties:
        type:
          type: string
          enum:
          - UpdateReward
        attributes:
          type: object
          properties:
            amount:
              type: integer
              exclusiveMinimum: 0
              maximum: 2147483647
              description: Updated reward amount in cents.
              format: int32
              example: 750
            message:
              type: string
              description: Updated message shown to the recipient.
              example: Updated thank-you note
            reasonCode:
              type: string
              description: Updated reason code.
              example: CX-COMPENSATION-002
            costCenter:
              type: string
              description: Updated cost center.
              example: CX-ESCALATIONS
            notificationEmail:
              type: string
              format: email
              description: Updated notification email.
              example: supervisor@partner.example
      required:
      - type
      - attributes
      description: Request to update a reward when `canUpdate` is `true` (pre-issued rewards in `Created` status). At least one attribute must be provided.
      x-tags:
      - Model
    PreIssuedConflictResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: A unique UUID for this particular occurrence of the problem.
          example: 123e4567-e89b-12d3-a456-426614174000
        status:
          type: integer
          description: The HTTP status code applicable to this error.
          example: 409
        code:
          type: string
          enum:
          - PreIssuedConflict
          description: A unique, camel-cased Accrue-specific code detailing the error.
          example: PreIssuedConflict
        title:
          type: string
          description: Generic title for the error.
          example: RewardConflictException
        detail:
          type: string
          description: A human-readable explanation providing more insights about the error.
          examples:
          - A pre-issued reward already exists for this recipient.
        meta:
          type: object
          properties:
            environment:
              type: string
              enum:
              - production
              - sandbox
              example: sandbox
            timestamp:
              type: string
              format: date-time
              example: '2025-06-23T12:00:00.000Z'
            path:
              type: string
              example: /api/v1/rewards
          required:
          - environment
          - timestamp
          - path
          example:
            environment: sandbox
            timestamp: '2025-06-23T12:00:00.000Z'
            path: /api/v1/rewards
      required:
      - id
      - status
      - code
      - title
      - detail
      - meta
    InvalidRewardStateResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: A unique UUID for this particular occurrence of the problem.
          example: 123e4567-e89b-12d3-a456-426614174000
        status:
          type: integer
          description: The HTTP status code applicable to this error.
          example: 409
        code:
          type: string
          enum:
          - InvalidState
          description: A unique, camel-cased Accrue-specific code detailing the error.
          example: InvalidState
        title:
          type: string
          description: Generic title for the error.
          example: RewardConflictException
        detail:
          type: string
          description: A human-readable explanation providing more insights about the error.
          examples:
          - Reward cannot be modified in its current state.
        meta:
          type: object
          properties:
            environment:
              type: string
              enum:
              - production
              - sandbox
              example: sandbox
            timestamp:
              type: string
              format: date-time
              example: '2025-06-23T12:00:00.000Z'
            path:
              type: string
              example: /api/v1/rewards/123e4567-e89b-12d3-a456-426614174000
          required:
          - environment
          - timestamp
          - path
          example:
            environment: sandbox
            timestamp: '2025-06-23T12:00:00.000Z'
            path: /api/v1/rewards/123e4567-e89b-12d3-a456-426614174000
      required:
      - id
      - status
      - code
      - title
      - detail
      - meta
x-tagGroups:
- name: Overview
  tags:
  - Introduction
  - API Design
- name: Users
  tags:
  - Users
  - LinkedAccounts
  - Identity Verification
- name: Wallets
  tags:
  - Wallets
- name: Gifts
  tags:
  - Gifts
- name: Payments
  tags:
  - PaymentIntents
  - Payments
  - ExternalTransactions
  - Simulations
- name: Banking & KYC
  tags:
  - Banking
  - Counterparties
  - CounterpartyTransfers
- name: Sweepstakes
  tags:
  - Sweepstakes
- name: Rewards
  tags:
  - Rewards
- name: Widgets
  tags:
  - Widgets
- name: Webhooks
  tags:
  - Webhooks
  - WebhookEvents
  - Webhook Topics