Donations for your business customers

Build it

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

1. 1

   Request account hierarchy access

   Account hierarchy lets you create and manage Charitips accounts on behalf of your business customers. Ask for it at contact@charitips.com: our team validates it on your account. Your own account is the parent account, and each customer gets a child account linked to it: see Account hierarchy.

2. 2

   Create a child account

   For each customer, create a child account with Create a child account, during their onboarding once you have their company details. It needs the company name, a contact's first name, last name and email, a legal registration number (SIREN for French businesses, a valid VAT number for others) and the postal address. They become the customer's billing and fiscal information: invoices use the first, fiscal receipts the second. Save the accountId from the response with your customer: the next steps use it.

   cURLNode.jsPythonPrompt

   POST /v1/accounts/<accountId>/child-accounts

   1curl -X POST https://api.sandbox.charitips.com/v1/accounts/<accountId>/child-accounts \2  -H "Authorization: Bearer $CHARITIPS_TOKEN" \3  -H "Content-Type: application/json" \4  -d '{5    "name": "Hero Corp",6    "firstName": "John",7    "lastName": "Doe",8    "email": "john.doe@herocorp.com",9    "legalRegistrationNumber": "883060550",10    "street": "8 rue de la Paix",11    "city": "Paris",12    "zip": "75002",13    "country": "FR"14  }'

   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

   Create a charities selection

   On the child account, create the charities your customer offers with Create a charities selection and the child's accountId. Get the charity ids from List charities.

   cURLNode.jsPythonPrompt

   POST /v1/charities-selections

   1curl -X POST https://api.sandbox.charitips.com/v1/charities-selections \2  -H "Authorization: Bearer $CHARITIPS_TOKEN" \3  -H "Content-Type: application/json" \4  -d '{5    "name": "Hero Corp selection",6    "charityIds": [7      "ca68f22c-2fdf-48b1-b8f6-43c3073e83bb",8      "1cccaa7c-cc5e-4dc8-9978-fc2de5f5d7b3",9      "0d65b4e6-f663-4ec7-b69d-0da5e7e8b2ee"10    ],11    "accountId": "<child accountId>"12  }'

   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.

4. 4

   Create and activate the campaign

   Create the campaign with Create a campaign, the child's accountId and the charitiesSelectionId. Without a type, it runs until you end it and its total depends on usage, which suits long-lived and usage-based experiences. Campaigns are created PENDING: activate it with Activate a campaign once it is configured. Write to contact@charitips.com for help with the first one.

   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    "accountId": "<child accountId>",6    "charitiesSelectionId": "<charitiesSelectionId>",7    "name": "Hero corp campaign"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.

5. 5

   Let the user pick a charity

   To record a donation, the user first chooses the charity to support. Show the charities with the charity selection widgets, and call your backend when the user picks one.

6. 6

   Create the donation

   In that backend endpoint, create the donation with Create a donation on the child's campaign. externalId is an optional id of your system, such as a customer, transaction or order id; uniqueExternalId is the same but unique across all donations, so a retried call answers 409 instead of creating a duplicate. amount is in cents: 2000 is 20 €.

   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    "externalId": "<externalId>",7    "uniqueExternalId": "<uniqueExternalId>",8    "amount": 20009  }'

   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.

7. 7

   Claim it for the chosen charity

   Right after, link the donation to the user's charity with Claim a donation.

   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.

8. 8

   Store the ids on your side

   Keep your parent accountId in an environment variable, and each child accountId on the record of your customer. Store the campaignId and publicKey of each campaign there too, or on your own campaign record when a customer has several; both are also in the Informations tab of the campaign in the dashboard. On donations, votes and donors, pass your own id in uniqueExternalId, or in externalId when it is not unique, and the person choosing the charity in donor to track usage.

9. 9

   Billing and receipts

   Donations without a set budget are billed monthly. A campaign's fiscal receipts are in the child account's name: yearly by default, at the end of the campaign for a time-limited one. To bill each customer directly instead of your account, see Bill your business customers; to open each customer's dashboard, see Dashboards and users.