mobile_fetch_user_balance

Fetch User Balance

​

Displays user information regarding active redemptions, notifications, badges, balance, etc.

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

  • Content-Type
    Type: string
    required

    Set this header to application/json.

  • Accept
    Type: string
    required

    Advertises which content types the client is able to understand

  • Accept-Language
    Type: string

    Preferred language

  • 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: object
    • account_balance
      Type: Account Balance Details (Object)
    • active_redemptions
      Type: Redemption Details (Object)

      Returns the details of a redemption done by a user

    • challenge_badges
      Type: array object[]
    • converted_category_balances
      Type: array Converted Category Balances (Array Object)[]
    • coupons
      Type: array Coupons (Array Object)[]
    • messages
      Type: Messages (Array Object)

      Returned in response to the Fetch User Balance API

    • notifications
      Type: array Notifications (Array Object)[]

      Returns the details of the notifications received by a user. A maximum of 10 notifications will be fetched.

    • preferred_charities
      Type: array object[]
    • punch_cards
      Type: array object[]
    • rewards
      Type: array Rewards (Array Object)[]

      Contains information about the available rewards of the user

  • 422
get/api2/mobile/users/balance
{
  "active_redemptions": {
    "redemption_status": "string",
    "created_at": "string",
    "redeemable_id": 1,
    "redeemable_name": "string",
    "redeemed_value": "string",
    "redemption_image_url": "string",
    "redemption_message": "string",
    "redeemable_description": "string",
    "updated_at": "string",
    "redemption_id": 1,
    "redemption_tracking_code": "string",
    "expiring_at": "string",
    "location_id": 1
  },
  "challenge_badges": [
    {
      "badge_id": 1,
      "challenge_campaign_id": 1,
      "published": true,
      "public_url": "string",
      "challenge_campaign_status": "string"
    }
  ],
  "coupons": [
    {
      "code": "string",
      "image_url": "string",
      "name": "string",
      "description": "string",
      "start_date": "YYYY-MM-DD",
      "end_date": "YYYY-MM-DD"
    }
  ],
  "messages": {
    "messages": [
      {
        "background_content": {
          "type": "string",
          "url": "string",
          "alt_text": "string",
          "initial_frame": "string"
        },
        "body": "string",
        "cta": [
          {
            "type": "string",
            "link": "string",
            "label": "string",
            "cta_type": "string"
          }
        ],
        "dismissable": true,
        "hero_content": {
          "type": "string",
          "url": "string",
          "alt_text": "string",
          "initial_frame": "string"
        },
        "launch_time": "string",
        "message_type": "string",
        "rank": 1,
        "style_url": "string",
        "subtitle": "string",
        "tags": [
          "string"
        ],
        "take_down_time": "string",
        "title": "string",
        "message_id": 1
      }
    ],
    "read_at": "YYYY-MM-DDThh:mm:ssZ",
    "created_at": "YYYY-MM-DDThh:mm:ssZ",
    "deleted_at": "YYYY-MM-DDThh:mm:ssZ"
  },
  "notifications": [
    {
      "id": 1,
      "kind": "string",
      "message": "string",
      "read_at": "YYYY-MM-DDThh:mm:ssZ",
      "created_at": "YYYY-MM-DDThh:mm:ssZ"
    }
  ],
  "rewards": [
    {
      "becomes_available_at": "2025-12-19T16:30:02.130Z",
      "campaign_type": "string",
      "created_at": "2025-12-19T16:30:02.130Z",
      "description": "string",
      "discount_channel": "string",
      "discount_amount": 1,
      "reward_image_url": "string",
      "name": "string",
      "read_at": "2025-12-19T16:30:02.130Z",
      "reward_properties": "string",
      "store_numbers": [
        "string"
      ],
      "franchisee_id": 1,
      "meta_data": "string",
      "redeemable_created_at": "2025-12-19T16:30:02.130Z",
      "reward_id": 1,
      "expiring_at": "2025-12-19T16:30:02.130Z",
      "redemption_details": {
        "redemption_status": "string",
        "created_at": "string",
        "redeemable_id": 1,
        "redeemable_name": "string",
        "redeemed_value": "string",
        "redemption_image_url": "string",
        "redemption_message": "string",
        "redeemable_description": "string",
        "updated_at": "string",
        "redemption_id": 1,
        "redemption_tracking_code": "string",
        "expiring_at": "string",
        "location_id": 1
      },
      "auto_select": true
    }
  ],
  "punch_cards": [
    {
      "progress": [
        {
          "completed_steps": 1,
          "total_steps": 1
        }
      ],
      "name": "string",
      "description": null,
      "image_url": "string",
      "challenge_id": 1,
      "icon_url": "string",
      "icon_completed_url": "string",
      "start_date": "YYYY-MM-DD",
      "end_date": "YYYY-MM-DD",
      "gift_reason": "string",
      "miscellaneous": "string",
      "challenge_reach": "string",
      "challenge_status": "string",
      "challenge_type": "string",
      "occurrence": "string",
      "past_completions": 1,
      "challenge_expiring_at_tz": "YYYY-MM-DDThh:mm:ssZ"
    }
  ],
  "preferred_charities": [
    {
      "user_donations": {
        "reward": {
          "user_donations": 1,
          "last_donated_item": null,
          "last_donation_time": null
        }
      },
      "name": "string",
      "description": "string",
      "social_cause_id": 1,
      "image_url": "string",
      "miscellaneous": "string",
      "city": "string",
      "state": "string",
      "street": "string",
      "zip": "string",
      "phone_number": null,
      "email": "string",
      "address": "string"
    }
  ],
  "converted_category_balances": [
    {
      "category_id": 1,
      "name": "string",
      "source_type": "string",
      "source_value": 1,
      "converted_type": "string",
      "converted_value": 1,
      "balance": 1
    }
  ],
  "account_balance": {
    "banked_currency": 1,
    "checkins_on_current_card": 1,
    "current_membership_level_id": 1,
    "current_membership_level_expiring_on": "YYYY-MM-DD",
    "expiring_banked_currency": 1,
    "banked_currency_expiring_on": "YYYY-MM-DD",
    "pending_points": 1,
    "redeemed_cards": 1,
    "total_loyalty_visits": 1,
    "unredeemed_cards": 1,
    "current_membership_level_name": "string",
    "lifetime_points": 1,
    "redeemable_points": 1,
    "unbanked_points": 1,
    "membership_qualification_points": 1
  }
}