mobile_fetch_gift_card_balance

Fetch Gift Card Balance

​

Returns the details of a specified gift card

Path Parameters
  • uuid
    Type: string
    required

    Unique ID of the gift card issued by and maintained in the Punchh system

Headers
  • x-pch-digest
    Type: string
    required

    The signature for the API call

  • Authorization
    Type: string
    required

    Used to authorize the request with access_token. It should be supplied as Bearer ACCESS_TOKEN_GOES_HERE. Note: When authentication is performed using Advanced Authentication, you must include the id_token in the id-token header and the access_token in the Authorization header. See Access Punchh APIs Using Access and ID tokens

  • Accept
    Type: string
    required

    Advertises which content types the client is able to understand

  • Accept-Language
    Type: string

    Preferred language

  • Content-Type
    Type: string
    required

    Set this header to application/json.

  • User-Agent
    Type: string
    required

    Used to identify the software, device, and application initiating the request, providing information about the client to the server. For details, see User Agent.

  • id-token
    Type: string

    A token that contains identity information about the authenticated user. It is used to verify the user’s identity and is required only when authentication is performed using Advanced Authentication. This token alone does not grant access to Punchh APIs. To access the APIs, you must include the id_token in the id-token header and the access_token in the Authorization header. See Access Punchh APIs Using Access and ID tokens

Body
application/json
  • client
    Type: string
    required

    OAuth client ID provided by the business

Responses
  • 200
    Type: Gift Card (Object)
    • auto_reload_enabled
      Type: boolean

      Whether auto-reload is enabled for a gift card or not

    • card_background_image
      Type: string

      URL of the image that is displayed as the gift card background in the app of a business

    • card_number
      Type: string

      Unique gift card number as issued by the gift card processor (e.g., Aloha, Vantiv, Valutec, etc.) used by the business

    • created_at
      Format: date-timeenum
      const:  
      YYYY-MM-DDThh:mm:ssZ

      Date/time when the gift card was created in the system, in ISO 8601 format

      • YYYY-MM-DDThh:mm:ssZ
    • design_id
      Type: integer

      Identification of a particular gift card design selected by the user while purchasing a gift card

    • epin
      Type: string

      Security PIN associated with a gift card. A "null" value indicates that no epin is associated with the gift card.

    • gc_user_auto_reload_default_amount
      Type: numberFormat: float

      Default amount with which a gift card would be auto-reloaded

    • gc_user_auto_reload_preferred_payment
      Type: string

      UUID of the preferred payment card, which is used for making payments when auto-reloading the gift card

    • gc_user_auto_reload_threshold_amount
      Type: numberFormat: float

      Threshold amount below which a gift card becomes eligible for auto-reload

    • gift_card_id
      Type: integer

      Unique ID assigned to each gift card by the Punchh system. This ID will be passed in the push notification payload to app clients in the key gc. By mapping this, the app client can fetch the updated balance of a particular gift card.

    • last_fetched_amount
      Type: numberFormat: float

      The balance amount of a gift card last fetched from the gift card processor

    • last_fetched_at
      Format: date-timeenum
      const:  
      YYYY-MM-DDThh:mm:ssZ

      The last time the balance amount of a gift card was fetched from the gift card processor. This indicates when it was cached.

      • YYYY-MM-DDThh:mm:ssZ
    • name

      Name of the card that has been assigned by the user. In case of purchase of a gift card from an app, users cannot add a name to the card. A "null" value indicates that a name has not been added to the card. A name can be added later using the Update Gift Cards API.

    • preferred
      Type: boolean

      A "true" value for a gift card indicates that a user has selected it to be the preferred gift card for payment.

    • status
      Type: string

      The status of a gift card. The only value exposed to a gift card in the app is "active". Other statuses are maintained for internal tracking.

    • updated_at
      Format: date-timeenum
      const:  
      YYYY-MM-DDThh:mm:ssZ

      Date/time when the gift card was updated in the system, in ISO 8601 format

      • YYYY-MM-DDThh:mm:ssZ
    • usb_scannable_card_number
      Type: string

      Easily scannable form of a gift card's number by adding ~ and ^ as prefix and suffix, respectively, to the gift card number. This is done to avoid issues at certain POS systems while scanning the QR code.

    • users
      Type: User (Object)

      Includes details about the users who are registered on a particular business

    • uuid
      Type: string

      Unique ID of the gift card issued by and maintained in the Punchh system

get/api2/mobile/gift_cards/{uuid}/balance
{
  "card_background_image": "string",
  "card_number": "string",
  "epin": "string",
  "usb_scannable_card_number": "string",
  "created_at": "YYYY-MM-DDThh:mm:ssZ",
  "design_id": 1,
  "preferred": true,
  "name": null,
  "last_fetched_amount": 1,
  "last_fetched_at": "YYYY-MM-DDThh:mm:ssZ",
  "status": "string",
  "updated_at": "YYYY-MM-DDThh:mm:ssZ",
  "users": {
    "address": "string",
    "avatar_remote_url": "string",
    "birthday": "YYYY-MM-DD",
    "communicable_email": "string",
    "city": "string",
    "created_at": "YYYY-MM-DDThh:mm:ssZ",
    "email": "string",
    "email_verified": true,
    "facebook_signup": true,
    "favourite_locations": "string",
    "favourite_store_numbers": "string",
    "fb_uid": "string",
    "first_name": "string",
    "gender": "string",
    "last_name": "string",
    "marketing_email_subscription": true,
    "marketing_pn_subscription": true,
    "migrate_status": true,
    "passcode_configured_for_giftcards": true,
    "phone": "string",
    "profile_field_answers": {
      "upf0": "string",
      "upf1": "string",
      "upf2": "string"
    },
    "referral_code": "string",
    "referral_path": "string",
    "secondary_email": "string",
    "state": "string",
    "superuser": true,
    "terms_and_conditions": true,
    "title": "string",
    "updated_at": "YYYY-MM-DDThh:mm:ssZ",
    "user_as_barcode": "string",
    "user_as_qrcode": "string",
    "user_code": "string",
    "user_id": 1,
    "user_relations": [
      "kid"
    ],
    "zip_code": "string",
    "anniversary": "string",
    "verification_mode": null,
    "apple_signup": true,
    "apple_uid": "string",
    "has_generated_fb_email": true,
    "sms_subscription": true,
    "apple_pass_url": "string",
    "age_verified_status": true,
    "account_created_at": "2025-12-19T16:30:02.130Z",
    "user_joined_at": "2025-12-19T16:30:02.130Z"
  },
  "uuid": "string",
  "gift_card_id": 1,
  "auto_reload_enabled": true,
  "gc_user_auto_reload_threshold_amount": 1,
  "gc_user_auto_reload_default_amount": 1,
  "gc_user_auto_reload_preferred_payment": "string"
}