A donation with every order

Build it

The calls behind the demo, in order. Each step shows the request your server sends.

1. 1

   Create the campaign

   Once, create a charities selection with the charities you want to offer, create the campaign with its charitiesSelectionId, then activate it, as in steps 3 to 5 of Your first donation. It works as a charity cashback for an online store: the customer picks the charity after paying, so your checkout stays as it is.

   cURLNode.jsPythonPrompt

   POST /v1/campaigns

   1curl -X POST https://api.sandbox.charitips.com/v1/campaigns \2  -H "Authorization: Bearer $CHARITIPS_TOKEN" \3  -H "Content-Type: application/json" \4  -d '{5    "name": "Order donations",6    "charitiesSelectionId": "<charitiesSelectionId>"7  }'

   Built from the spec and the API code

   Request bodies are written for this docs and checked against the API's validation; ids in angle brackets are placeholders. Response values are placeholders built from the schema.

2. 2

   Give on each paid order

   When an order is paid, create a donation with the order id as uniqueExternalId. amount is in cents. Create it from your payment webhook, not from the browser: if the customer closes the tab, the donation still exists.

   cURLNode.jsPythonPrompt

   POST /v1/donations

   1curl -X POST https://api.sandbox.charitips.com/v1/donations \2  -H "Authorization: Bearer $CHARITIPS_TOKEN" \3  -H "Content-Type: application/json" \4  -d '{5    "campaignId": "<campaignId>",6    "amount": 200,7    "uniqueExternalId": "<orderId>"8  }'

   Built from the spec and the API code

   Request bodies are written for this docs and checked against the API's validation; ids in angle brackets are placeholders. Response values are placeholders built from the schema.

3. 3

   Show the charities

   Read the selection with its charities from your server and render them on the confirmation page. Each charity comes with its charityId, name and logoUrl. The list changes only when you edit the selection: cache it rather than reading it for every order.

   ShellCopy

   1curl "https://api.sandbox.charitips.com/v1/charities-selections/<charitiesSelectionId>?includeCharities=true" \2  -H "Authorization: Bearer $CHARITIPS_TOKEN"

4. 4

   Claim it for the customer's charity

   Claim the donation for the charity the customer picks. If the customer never chooses, the donation is assigned automatically when it expires or when the campaign closes. No donation is lost.

   cURLNode.jsPythonPrompt

   POST /v1/donations/<donationId>/claim

   1curl -X POST https://api.sandbox.charitips.com/v1/donations/<donationId>/claim \2  -H "Authorization: Bearer $CHARITIPS_TOKEN" \3  -H "Content-Type: application/json" \4  -d '{5    "charityId": "<charityId>"6  }'

   Built from the spec and the API code

   Request bodies are written for this docs and checked against the API's validation; ids in angle brackets are placeholders. Response values are placeholders built from the schema.

5. 5

   Listen for the claim

   Create a webhook for donation_update once, with Create a webhook. Each delivery, shortened here, holds event, payload, the donation as it is now, and diff, the fields that changed. When diff holds a charityId, the donation is claimed, by the customer or automatically: find the order with payload.uniqueExternalId. Verify the signature first, as shown in Webhooks configuration, and key your handler on donationId and status, since a delivery can arrive more than once.

   JSONCopy

   1{2  "event": "donation_update",3  "payload": { "donationId": "<donationId>", "status": "DONE", "charityId": "<charityId>", "uniqueExternalId": "<orderId>" },4  "diff": { "status": "DONE", "charityId": "<charityId>" }5}