> ## Documentation Index
> Fetch the complete documentation index at: https://tapcoupon.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Public card rewards

> Retrieve configured points rewards and cooldown availability for each card instance.

## GET `/card/{cardId}/rewards`

Retrieve configured points rewards and cooldown availability for each card instance.

This endpoint is public. You do not need an API key or employee token.

The response is an array, including archived card instances. Match its `id` with the card instance from [public lookup](https://tapcoupon.mintlify.site/api-reference/cards/public-get.md). Points cards include rewards referenced by `program.rewardIds`; other card types have an empty `rewards` array.

`availableAt` is omitted when the card has never redeemed that reward or no cooldown applies. If present, compare it with the current time; a past value means the cooldown has ended. Sufficient points are still required. This endpoint allows 10 requests per minute per IP.

### Example request

```bash theme={null}
curl "https://tapcoupon.at/api/v1/card/9866191586296/rewards"
```

### Example response

```json theme={null}
[
  {
    "id": "693869428d49e641ba110e17",
    "cardId": "9866191586296",
    "rewards": [
      {
        "id": "693869428d49e641ba110e18",
        "name": "Free coffee",
        "description": "One coffee",
        "pointsNeeded": 100,
        "cooldownHours": 24,
        "availableAt": "2026-10-03T12:00:00Z"
      }
    ]
  }
]
```


## OpenAPI

````yaml api-reference/openapi.json GET /card/{cardId}/rewards
openapi: 3.1.0
info:
  title: TapCoupon POS and partner API
  version: 1.0.0
  description: >-
    API-key POS operations, customer card views, and partner payment sessions.
    Verified against the tap_coupon backend on 2026-10-02. Dashboard /clients
    and administrative routes use separate authentication and are outside this
    reference.
servers:
  - url: https://tapcoupon.at/api/v1
security: []
paths:
  /card/{cardId}/rewards:
    get:
      tags:
        - Cards
      summary: Public card rewards
      description: >-
        Retrieve configured points rewards and cooldown availability for each
        card instance.
      operationId: cards_public_rewards
      parameters:
        - name: cardId
          in: path
          required: true
          description: Printed or digital identifier.
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PublicCardRewards'
              example:
                - id: 693869428d49e641ba110e17
                  cardId: '9866191586296'
                  rewards:
                    - id: 693869428d49e641ba110e18
                      name: Free coffee
                      description: One coffee
                      pointsNeeded: 100
                      cooldownHours: 24
                      availableAt: '2026-10-03T12:00:00Z'
        '400':
          description: Invalid request, card type, balance, points, or location.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: >-
            Rate limit exceeded. The response body is determined by the
            rate-limit middleware.
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security: []
components:
  schemas:
    PublicCardRewards:
      type: object
      properties:
        id:
          type: string
          description: MongoDB object id.
          pattern: ^[a-fA-F0-9]{24}$
        cardId:
          type: string
        rewards:
          type: array
          items:
            $ref: '#/components/schemas/PublicReward'
      required:
        - id
        - cardId
        - rewards
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error.
        errorCode:
          type: string
          description: >-
            Handler errors include a machine-readable code; middleware errors
            may omit it.
      required:
        - error
    PublicReward:
      type: object
      properties:
        id:
          type: string
          description: MongoDB object id.
          pattern: ^[a-fA-F0-9]{24}$
        name:
          type: string
        description:
          type: string
        pointsNeeded:
          type: integer
          minimum: 1
        cooldownHours:
          type: integer
          description: Cooldown per card and reward; 0 disables it.
          minimum: 0
          maximum: 8760
        availableAt:
          type: string
          format: date-time
          description: Omitted when no previous redemption or no cooldown applies.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.