Punchh

Punchh Social Cause Campaign API

The Social Cause Campaign API from Punchh — 2 operation(s) for social cause campaign.

Documentation GitHub OpenAPI

Operations 3

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /api2/mobile/social_causes Search active charity campaigns · Get Social Cause Campaigns #

Ask an LLM

“Which charities can guests donate to through the loyalty app?”

“Can I search social cause campaigns by city or zip code?”

Tell an agent

Search charity campaigns for {query}, page {page}, {per_page} per page.

Find social causes matching {query} on page {page} with {per_page} results.

POST /api2/mobile/social_causes Donate to a social cause campaign · Create Donation #

Ask an LLM

“How does a guest donate points or money to a charity campaign?”

“What kinds of items can a guest donate to a social cause?”

Tell an agent

Donate {item_to_donate} as {donation_type} to social cause {social_cause_id}.

Give {item_to_donate} of type {donation_type} to charity campaign {social_cause_id}.

GET /api2/mobile/social_causes/{social_cause_id} View a guest's donations to a cause · Social Cause Campaign Details #

Ask an LLM

“How much has this guest donated to a particular charity campaign?”

“Can I see campaign details for one social cause?”

Tell an agent

Show donation details for social cause {social_cause_id}.

What have I given to cause {social_cause_id}? Show me.

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/punchh:punchh-social-cause-campaign-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Mobile Social Cause Campaign API
  version: '1.0'
  contact:
    name: Punchh Dev Support
    url: https://developers.punchh.com
  description: Punchh provides a robust platform for offering loyalty programs to customers.
servers:
- url: https://SERVER_NAME_GOES_HERE.punchh.com
tags:
- name: Social Cause Campaign
paths:
  /api2/mobile/social_causes:
    get:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    social_cause_id:
                      type: integer
                      description: Unique ID assigned to a social cause campaign. This ID is generated by Punchh when the social cause campaign is created in the Punchh platform.
                    name:
                      type: string
                      description: Name of a social cause campaign as defined by the business admin while creating the social cause campaign in the Punchh platform
                    description:
                      type: string
                      description: Description of a social cause campaign as defined by the business admin
                    image_url:
                      type: string
                      description: URL of the image that is attached to the social cause campaign by the business admin
                    tags:
                      type: array
                      description: Tags configured in the Punchh platform
                      items:
                        type: object
                    miscellaneous:
                      type: string
                      description: Returns miscellaneous response string as configured in the Punchh platform
                    city:
                      type: string
                      description: City
                    state:
                      type: string
                      description: State
                    street:
                      type: string
                      description: Street name
                    zip:
                      type: string
                      description: Zip code
                    phone:
                      type: string
                      description: Phone number
                    email:
                      type: string
                      description: Email address
                    address:
                      type: string
                      description: Address
              examples:
                default:
                  value:
                  - social_cause_id: 1
                    name: Test Campaign
                    description: Test
                    image_url: IMAGE_URL_GOES_HERE
                    tags: []
                    miscellaneous: ''
                    city: San Mateo
                    state: CA
                    street: ADDRESS_GOES_HERE
                    zip: '94402'
                    phone: ''
                    email: ''
                    address: ADDRESS_GOES_HERE
      summary: Get Social Cause Campaigns
      operationId: mobile_get_social_cause_campaigns
      tags:
      - Social Cause Campaign
      description: Returns the list of active social cause campaigns created in a business
      parameters:
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/signature'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/User-Agent'
      x-stoplight:
        id: 8b1c5da01c00d
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                client:
                  type: string
                  x-stoplight:
                    id: wgjca419ij8rv
                  description: OAuth client ID provided by the business
                query:
                  type: string
                  x-stoplight:
                    id: 77453k6m62txz
                  description: Any field that can be used to search any charity with name, city, state, zip code, address, etc.
                page:
                  type: string
                  x-stoplight:
                    id: z5bkmsqor2szi
                  description: Returns data based on page number filtering
                per_page:
                  type: string
                  x-stoplight:
                    id: xbj6o6ndggory
                  description: Returns data based on per-page filtering
              required:
              - client
              - query
              - page
              - per_page
            examples:
              default:
                value:
                  client: CLIENT_GOES_HERE
                  query: name
                  page: ''
                  per_page: ''
    post:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    '0':
                      type: string
              examples:
                Donate currency:
                  value:
                  - '0': $2.00 donated to Social Cause Campaign One.
                Donate reward:
                  value: "[\n  \"Sandwich donated to Social Cause Campaign One.\"\n]"
                Donate card:
                  value: "[\n  \"Redeemable Card donated to Social Cause Campaign One.\"\n]"
                Donate redeemable:
                  value: "[\n  \"Dessert! donated to Social Cause Campaign One.\"\n]"
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    properties:
                      client:
                        type: string
              examples:
                default:
                  value:
                    errors:
                      client: Required parameter missing or the value is empty.
        '401':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    properties:
                      unknown_client:
                        type: array
                        items:
                          type: string
              examples:
                default:
                  value:
                    errors:
                      unknown_client:
                      - Client ID is incorrect. Please check client param or contact us
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: string
              examples:
                default:
                  value:
                    errors:
                    - Social Cause Campaign not found.
        '422':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: string
              examples:
                Invalid loyalty points:
                  value:
                    errors:
                    - Not enough points to redeem
                Invalid redeemable ID:
                  value: "{\n  \"errors\": [\n    \"Redeemable doesn't exist or not configured for loyalty points based redemption.\"\n  ]\n}"
                Invalid donation type:
                  value: "{\n  \"errors\": [\n    \"Invalid donation_type! Supported donation types are card, redeemable, reward, currency.\"\n  ]\n}"
                invalid reward ID:
                  value: "{\n  \"errors\": [\n    \"Reward doesn't exist or has already been redeemed.\"\n  ]\n}"
      summary: Create Donation
      description: Creates a donation for a user based on the selected social cause campaign
      operationId: Mobile_Create_donation
      tags:
      - Social Cause Campaign
      parameters:
      - $ref: '#/components/parameters/signature'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/User-Agent'
      x-stoplight:
        id: 69e89aca862e9
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                client:
                  type: string
                  description: OAuth client ID provided by the business
                social_cause_id:
                  type: integer
                  description: Unique ID assigned to a social cause campaign. This ID is generated by Punchh when the social cause campaign is created in the Punchh platform.
                donation_type:
                  type: string
                  description: "Type of donation that a user wants to make. Currently, Punchh supports donation of the following objects: \n- currency: For businesses that supports banked currency \n- reward: Available rewards of a user\n- redeemable: Loyalty redeemables for a business that supports points unlock redeemables\n- card: Redeemable cards for visit-based businesses                   "
                item_to_donate:
                  type: string
                  description: "Provide the value that corresponds to the donation type: \n1. currency: Dollar amount that will be donated\n2. reward: ID of the reward that will be donated                  \n3. redeemable: ID of the redeemable that will be donated \n4. card: Pass the string `card`                  "
              required:
              - client
              - social_cause_id
              - donation_type
              - item_to_donate
            examples:
              default:
                value:
                  client: CLIENT_GOES_HERE
                  social_cause_id: '1901'
                  donation_type: currency
                  item_to_donate: 2
  /api2/mobile/social_causes/{social_cause_id}:
    parameters:
    - schema:
        type: string
      name: social_cause_id
      in: path
      required: true
    get:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  social_cause_id:
                    type: integer
                    description: Unique ID assigned to a social cause campaign. This ID is generated by Punchh when the social cause campaign is created in the Punchh platform.
                  donations:
                    type: object
                    properties:
                      reward:
                        type: object
                        properties:
                          user_donations:
                            type: integer
                            description: Denotes all user donations of the social cause campaign
                          charity_donations:
                            type: integer
                            description: Denotes all charity donations of the social cause campaign
                          all_donations:
                            type: integer
                            description: Denotes all social cause donations for the business
                      currency:
                        type: object
                        properties:
                          user_donations:
                            type: integer
                            description: Denotes all user donations of the social cause campaign
                          charity_donations:
                            type: integer
                            description: Denotes all charity donations of the social cause campaign
                          all_donations:
                            type: integer
                            description: Denotes all social cause donations for the business
                  name:
                    type: string
                    description: Name of the social cause campaign
                  description:
                    type: string
                    description: Description of the social cause campaign
                  image_url:
                    type: string
                    description: URL of the icon image
                  miscellaneous:
                    type: string
                    description: Returns miscellaneous response string as configured in the Punchh platform
                  disclaimer:
                    type: string
                    description: Disclaimer of the social cause campaign
                  city:
                    type: string
                    description: City
                  state:
                    type: string
                    description: State
                  street:
                    type: string
                    description: Street name
                  zip:
                    type: string
                    description: Zip code
                  phone_number:
                    type: string
                    description: Phone number
                  email:
                    type: string
                    description: Email address
                  address:
                    type: string
                    description: Address
              examples:
                Currency based:
                  value:
                    social_cause_id: 1
                    donations:
                      reward:
                        user_donations: 0
                        charity_donations: 0
                        all_donations: 0
                      currency:
                        user_donations: 2
                        charity_donations: 2
                        all_donations: 2
                    name: Test Campaign
                    description: Test
                    image_url: IMAGE_URL_GOES_HERE
                    miscellaneous: ''
                    disclaimer: Updated value of charity donations & all donations will be reflected after 24 hours.
                    city: San Mateo
                    state: CA
                    street: ADDRESS_GOES_HERE
                    zip: '94402'
                    phone_number: ''
                    email: ''
                    address: ADDRESS_GOES_HERE
                Redeemable based:
                  value: "{\n    \"donations\": {\n        \"reward\": {\n            \"user_donations\": 0,\n            \"charity_donations\": 0,\n            \"all_donations\": 0\n        },\n        \"redeemable\": {\n            \"user_donations\": 2,\n            \"charity_donations\": 2,\n            \"all_donations\": 2\n        } \n    },\n    \"name\": \"test social for visit based\",\n    \"description\": \"test\",\n    \"social_cause_id\": 26882,\n    \"image_url\": \"IMAGE_URL_GOES_HERE\"\n}{}"
                Card based:
                  value: "{\n    \"donations\": {\n        \"reward\": {\n            \"user_donations\": 0,\n            \"charity_donations\": 0,\n            \"all_donations\": 0\n        },\n        \"card\": {\n            \"user_donations\": 2,\n            \"charity_donations\": 2,\n            \"all_donations\": 2\n        }\n    },\n    \"name\": \"test social for visit based\",\n    \"description\": \"test\",\n    \"social_cause_id\": 26882,\n    \"image_url\": \"IMAGE_URL_GOES_HERE\"\n}"
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    properties:
                      client:
                        type: string
              examples:
                default:
                  value:
                    errors:
                      client: Required parameter missing or the value is empty.
        '401':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    properties:
                      unknown_client:
                        type: array
                        items:
                          type: string
              examples:
                default:
                  value:
                    errors:
                      unknown_client:
                      - Client ID is incorrect. Please check client param or contact us
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: string
              examples:
                default:
                  value:
                    errors:
                    - Social Cause Campaign not found.
      summary: Social Cause Campaign Details
      description: Fetches donation details for a user based on the selected social cause campaign
      operationId: mobile_social_cause_campaign_details
      tags:
      - Social Cause Campaign
      parameters:
      - $ref: '#/components/parameters/signature'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/punchh-app-device-id'
      - schema:
          type: integer
        in: path
        name: social_cause_id
        required: true
        description: Unique ID assigned to a social cause campaign. This ID is generated by Punchh when the social cause campaign is created in the Punchh platform.
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/Accept-Language'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/User-Agent'
      x-stoplight:
        id: f7d4ac46778ae
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                client:
                  type: string
                  x-stoplight:
                    id: i90qggqzh3qbq
                  description: OAuth client ID provided by the business
              required:
              - client
            examples:
              default:
                value:
                  client: CLIENT_GOES_HERE
components:
  parameters:
    Authorization:
      schema:
        type: string
        default: Bearer ACCESS_TOKEN_GOES_HERE
      name: Authorization
      in: header
      description: Used to authorize the request with access_token. It should be supplied as `Bearer ACCESS_TOKEN_GOES_HERE`.
      required: true
    punchh-app-device-id:
      schema:
        type: string
        default: APP_DEVICE_ID_GOES_HERE
      name: punchh-app-device-id
      in: header
      required: true
      description: The app device ID helps Punchh identify each device so that certain rewards can be awarded individually to each device instead of per user. For example, the sign-up reward is given to each device ID to prevent fraudulent sign-ups so that a user cannot do repeated sign-ups from a single device to get rewards. It should not change even if the user resets a device. See the [sample code](/docs/dev-portal-mobile/56657769b1422-headers-and-caching#generating-the-punchh-app-device-id-header) to generate the punchh-app-device-id header.
    Accept:
      schema:
        type: string
        default: application/json
      name: Accept
      in: header
      description: Advertises which content types the client is able to understand
      required: true
    User-Agent:
      schema:
        type: string
        default: AppName/AppVersion/BuildNumber (OS; Model; MANUFACTURER; MODEL; OS Version)
      in: header
      name: User-Agent
      description: Used to identify the software, device, and application initiating the request, providing information about the client to the server. For details, see [User Agent](/docs/dev-portal-mobile/additional-topics/user-agent).
      required: true
    Content-Type:
      schema:
        type: string
        default: application/json
      name: Content-Type
      in: header
      description: Set this header to <b>application/json</b>.
      required: true
    Accept-Language:
      schema:
        type: string
        default: en
      name: Accept-Language
      in: header
      description: Preferred language
    signature:
      schema:
        type: string
        default: '{{$$.env.signature}}'
      name: x-pch-digest
      in: header
      description: The [signature](/docs/dev-portal-mobile/additional-topics/signature-sha256) for the API call
      required: true
x-stoplight:
  id: bf6eddb435209
x-ext-urls: {}

Punchh Social Cause Campaign API

Operations 3

Documentation

Specifications

Schemas & Data

Other Resources

Work with this as data

MCP server

Tools for apis

Call it yourself

Get an API key

OpenAPI Specification