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

# Get reward details

> Retrieve a single reward from the catalog including points cost, redemption limits, and availability.



## OpenAPI

````yaml /api-reference/openapi.json get /api/v2/rewards/{id}/
openapi: 3.0.3
info:
  title: Zupy API v2
  version: 2.0.0
  description: >-
    Zupy API v2 — versioned, gateway-aware API with envelope responses, RFC 7807
    errors, and multi-auth support (JWT, API Key, Device Key).
servers:
  - url: https://api.zupy.com
    description: Production
security: []
tags:
  - name: Authentication
    description: OTP request and verification endpoints
  - name: Customers
    description: Customer management, points, history, and data operations
  - name: Loyalty Programs
    description: Loyalty program configuration and details
  - name: Rewards
    description: Loyalty reward catalog (definitions redeemed with points)
  - name: Companies
    description: Company information and loyalty configuration
  - name: Coupons
    description: >-
      Issued coupons (RewardRedemption) — both loyalty-reward redemptions and
      marketing claims
  - name: Wallet
    description: Apple Wallet pass generation and notifications
  - name: Webhooks
    description: Partner integration webhook endpoints
  - name: Webhook Management
    description: Configure and test outbound webhook delivery
paths:
  /api/v2/rewards/{id}/:
    get:
      tags:
        - Rewards
      summary: Get reward details
      description: >-
        Retrieve a single reward from the catalog including points cost,
        redemption limits, and availability.
      operationId: rewards_retrieve
      parameters:
        - in: path
          name: id
          schema:
            type: string
          description: Unique identifier for this reward.
          required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RewardCatalog'
          description: ''
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
      security:
        - apiKeyAuth: []
components:
  schemas:
    RewardCatalog:
      type: object
      description: >-
        Available reward in the loyalty program catalog with points cost and
        validity details.
      properties:
        id:
          type: string
          readOnly: true
        name:
          type: string
          readOnly: true
          title: Nome
        description:
          type: string
          readOnly: true
        reward_type:
          allOf:
            - $ref: '#/components/schemas/RewardTypeEnum'
          readOnly: true
          description: >-
            Functional reward type. Use 'Generic' for rewards that don't fit
            other categories.
        points_required:
          type: integer
          readOnly: true
        monetary_value:
          type: string
          format: decimal
          pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
          readOnly: true
          nullable: true
          description: The approximate monetary value of this reward.
        validity_days:
          type: integer
          readOnly: true
          title: Validity Days After Redemption
          description: Number of days the reward is valid after redemption.
        is_available:
          type: string
          readOnly: true
        quantity_available:
          type: integer
          readOnly: true
          nullable: true
          description: Number of rewards available. Null means unlimited.
        quantity_redeemed:
          type: integer
          readOnly: true
          description: Number of rewards already redeemed.
        discount_type:
          allOf:
            - $ref: '#/components/schemas/DiscountTypeEnum'
          readOnly: true
          description: |-
            Type of discount applied when redeeming this reward

            * `none` - Nenhum
            * `percentage` - Percentage
            * `fixed_amount` - Fixed Amount
            * `free_shipping` - Free Shipping
            * `free_item` - Free Item
            * `conditional` - Conditional
        discount_percentage:
          type: string
          format: decimal
          pattern: ^-?\d{0,3}(?:\.\d{0,2})?$
          readOnly: true
          nullable: true
          description: Percentage discount (e.g., 15.50 for 15.5%)
        discount_fixed_amount:
          type: string
          format: decimal
          pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
          readOnly: true
          nullable: true
          description: Fixed amount discount in currency
        maximum_discount_value:
          type: string
          format: decimal
          pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
          readOnly: true
          nullable: true
          description: Maximum discount value (for percentage discounts)
        image_url:
          type: string
          readOnly: true
          nullable: true
        program_id:
          type: string
          title: Loyalty Program
          readOnly: true
        program_name:
          type: string
          readOnly: true
        is_active:
          type: boolean
          readOnly: true
        already_redeemed:
          type: boolean
          readOnly: true
          default: false
        start_date:
          type: string
          format: date-time
          readOnly: true
          nullable: true
        end_date:
          type: string
          format: date-time
          readOnly: true
          nullable: true
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
        settlement_budget:
          type: string
          format: decimal
          pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
          readOnly: true
          nullable: true
        customer_split_pct:
          type: string
          readOnly: true
          description: Customer's share of the settlement (hardcoded constant 50.00%).
        operator_split_pct:
          type: string
          format: decimal
          pattern: ^-?\d{0,3}(?:\.\d{0,2})?$
          readOnly: true
          nullable: true
          description: >-
            **Reserved — always `null` in 2026-05 production data.** This field
            is part of a 4-way settlement-split surface (customer / operator /
            publisher / sharer) intended for a future cross-merchant marketplace
            flow where Z\$ payouts route to multiple parties on redemption.
            Today only `customer_split_pct` is populated (constant 50%); the
            operator/publisher/sharer fields exist in the schema but are not yet
            wired into the redemption pipeline. **Do not write partner code that
            depends on a non-null value here yet.**
        publisher_split_pct:
          type: string
          format: decimal
          pattern: ^-?\d{0,3}(?:\.\d{0,2})?$
          readOnly: true
          nullable: true
          description: >-
            **Reserved — always `null` in 2026-05 production data.** Same caveat
            as `operator_split_pct`: part of the 4-way settlement surface, not
            yet wired. Documented here so the schema stays explicit about what's
            live and what's coming.
        sharer_split_pct:
          type: string
          format: decimal
          pattern: ^-?\d{0,3}(?:\.\d{0,2})?$
          readOnly: true
          nullable: true
          description: >-
            **Reserved — always `null` in 2026-05 production data.** Same caveat
            as `operator_split_pct` / `publisher_split_pct`.
        z_distributed_total:
          type: string
          readOnly: true
          description: >-
            Total Z$ already distributed via this reward (used_redemptions ×
            settlement_budget). null for non-marketing rewards.
        origin_type:
          type: string
          readOnly: true
        budget_mode:
          type: string
          readOnly: true
          description: >-
            How the campaign budget is enforced: 'unlimited' (no cap),
            'per_redemption' (each redeem consumes settlement_budget Z$), or
            'pooled' (shared across all redemptions).
        campaign_status:
          type: string
          readOnly: true
          nullable: true
          description: >-
            Lifecycle of the campaign that hosts this reward (draft, active,
            paused, ended). null for non-marketing rewards.
        campaign_operator_id:
          type: string
          readOnly: true
          nullable: true
          description: >-
            ID of the partner operator who created/operates this campaign (e.g.
            an aggregator running the marketing reward on behalf of a merchant).
            null for direct-merchant rewards.
        campaign_operator_name:
          type: string
          readOnly: true
          nullable: true
          description: >-
            Human-readable name of the campaign operator (paired with
            campaign_operator_id).
      required:
        - already_redeemed
        - created_at
        - description
        - discount_fixed_amount
        - discount_percentage
        - discount_type
        - end_date
        - id
        - image_url
        - is_active
        - is_available
        - maximum_discount_value
        - monetary_value
        - name
        - points_required
        - program_id
        - program_name
        - quantity_available
        - quantity_redeemed
        - reward_type
        - start_date
        - updated_at
        - validity_days
    Error:
      type: object
      description: RFC 7807 Problem Details error response.
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
      required:
        - detail
        - instance
        - status
        - title
        - type
    RewardTypeEnum:
      enum:
        - other
        - generic
        - welcome
        - return
        - birthday
        - surprise
        - recovery
        - gift
      type: string
      description: >-
        Reward type classification: other, generic, welcome, return, birthday,
        anniversary, referral, profile_completion, custom.
    DiscountTypeEnum:
      enum:
        - none
        - percentage
        - fixed_amount
        - free_shipping
        - free_item
        - conditional
      type: string
      description: |-
        * `none` - Nenhum
        * `percentage` - Percentage
        * `fixed_amount` - Fixed Amount
        * `free_shipping` - Free Shipping
        * `free_item` - Free Item
        * `conditional` - Conditional
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Per-company partner API key (zupy_pk_…). Validated by Zupy against the
        company integration key hash (Story 14.x); send it on every request as
        the X-API-Key header. Scoped read-write to the owning company's data.

````