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

GET /api2/mobile/social_causes Get Social Cause Campaigns #

POST /api2/mobile/social_causes Create Donation #

GET /api2/mobile/social_causes/{social_cause_id} Social Cause Campaign Details #

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-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. When a business integrates its back-end with the Punchh server, the Punchh APIs become instrumental in executing loyalty programs for enrolled customers, primarily via business-branded mobile apps and websites tailored by Punchh.


    To establish integration with the Punchh APIs, you need to understand how they are invoked and what responses are returned by the Punchh server. You can call APIs using any suitable API test client, such as Postman. Thus, the response to every API call made in Postman under a chosen environment (in app and/or platform) is reflected in the app and/or platform.'
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:
    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
    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:
      schema:
        type: string
        default: application/json
      name: Accept
      in: header
      description: Advertises which content types the client is able to understand
      required: true
    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.
x-stoplight:
  id: bf6eddb435209
x-ext-urls: {}

Punchh Social Cause Campaign API

Operations 3

Documentation

Specifications

Schemas & Data

Other Resources