openapi: 3.2.0
info:
  version: 1.0.0
  title: Accrue Merchant Gifts API
  x-links:
  - name: View Alternative Version
    url: /api-fs/
    description: View API documentation with alternative enum-based WebhookIncluded schema
  description: Gifts expose remaining spendable balance for a scanned lookUpId. Point-of-sale remaining lookup is GET /api/v1/gifts/{lookUpId}. Spend still uses payment intents with the same scanned string as lookUpId — never send Gift.id as walletId. Amounts are integer cents.
servers:
- description: Production API
  url: https://merchant-api.accruesavings.com
- description: Sandbox API
  url: https://merchant-api-sandbox.accruesavings.com
tags:
- name: Gifts
  description: Gifts expose remaining spendable balance for a scanned lookUpId. Point-of-sale remaining lookup is GET /api/v1/gifts/{lookUpId}. Spend still uses payment intents with the same scanned string as lookUpId — never send Gift.id as walletId. Amounts are integer cents.
paths:
  /api/v1/gifts/{lookUpId}:
    get:
      operationId: getGiftByLookUpId
      tags:
      - Gifts
      summary: Get Gift by lookUpId
      description: 'Fetch remaining gift balance by scanned `lookUpId`.


        The identifier is scoped to the merchant derived from the request. Amounts are integer cents.


        `data.id` is the gift public reference. Point-of-sale spend must POST `/api/v1/payment-intents` with the **path** `lookUpId` — never send `data.id` as `walletId`.'
      parameters:
      - schema:
          type: string
          description: Scanned lookup identifier for the gift. Use this same string as payment-intent lookUpId to spend.
          example: SCAN-LOOKUP-ID
        required: true
        name: lookUpId
        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
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/GetGiftByLookUpIdResponse'
        '400':
          description: LookUpId expired or invalid
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/GiftLookUpIdExpiredOrInvalidResponse'
        '404':
          description: Gift for lookUpId not found
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/GiftNotFoundResponse'
      x-codeSamples:
      - lang: Shell
        source: "curl --request GET \\\n  --url https://merchant-api.accruesavings.com/api/v1/gifts/SCAN-LOOKUP-ID \\\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/gifts/SCAN-LOOKUP-ID',\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/gifts/SCAN-LOOKUP-ID\", 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/gifts/SCAN-LOOKUP-ID")


          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/gifts/SCAN-LOOKUP-ID\")\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/gifts/SCAN-LOOKUP-ID\"\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/gifts/SCAN-LOOKUP-ID");

          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/gifts/SCAN-LOOKUP-ID');\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}"
components:
  schemas:
    Gift:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the object.
          readOnly: true
        type:
          type: string
          enum:
          - Gift
        attributes:
          type: object
          properties:
            available:
              type: integer
              minimum: 0
              description: Remaining amount available to spend, in integer cents.
              format: int32
              example: 3000
            originalAmount:
              type: integer
              minimum: 0
              description: Original gift amount, in integer cents.
              format: int32
              example: 5000
          required:
          - available
          - originalAmount
      required:
      - id
      - type
      - attributes
      description: A gift remaining-balance lookup.
      x-tags:
      - Model
    GiftNotFoundResponse:
      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:
          - GiftNotFound
          description: A unique, camel-cased Accrue-specific code detailing the error.
          example: GiftNotFound
        title:
          type: string
          description: Generic title for the error.
          example: GiftNotFoundException
        detail:
          type: string
          description: A human-readable explanation providing more insights about the error.
          examples:
          - Gift for lookUpId 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/gifts/SCAN-LOOKUP-ID
          required:
          - environment
          - timestamp
          - path
          example:
            environment: sandbox
            timestamp: '2025-06-23T12:00:00.000Z'
            path: /api/v1/gifts/SCAN-LOOKUP-ID
      required:
      - id
      - status
      - code
      - title
      - detail
      - meta
    GiftLookUpIdExpiredOrInvalidResponse:
      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:
          - GiftIdentifierExpired
          - GiftIdentifierMaxUsesExceeded
          description: A unique, camel-cased Accrue-specific code detailing the error.
          example: GiftIdentifierExpired
        title:
          type: string
          description: Generic title for the error.
          example: GiftValidationException
        detail:
          type: string
          description: A human-readable explanation providing more insights about the error.
          examples:
          - LookUpId has expired.
          - LookUpId has exceeded maximum uses.
        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/gifts/SCAN-LOOKUP-ID
          required:
          - environment
          - timestamp
          - path
          example:
            environment: sandbox
            timestamp: '2025-06-23T12:00:00.000Z'
            path: /api/v1/gifts/SCAN-LOOKUP-ID
      required:
      - id
      - status
      - code
      - title
      - detail
      - meta
    GetGiftByLookUpIdResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Gift'
      required:
      - data
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