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 application/json. 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: {}