Skip to content
Aller au contenu
Charitips

Concepts

Account hierarchy

Give each business customer its own Charitips account under yours, and see what that changes for billing, dashboards, keys, receipts and webhooks.

When you sell to businesses and each of them should run its own giving, each business customer gets a Charitips account of its own, linked under yours. Your account is the parent account; each customer's account is a child account.

In short

  • Each child account has its own campaigns, charities, donations, dashboard users and fiscal information. It only sees its own data; your account sees all of its child accounts.
  • Your API credentials act on every child account: you pass the child's accountId when you set something up for it or read its data.
  • Who pays is set per child: your account, on one invoice for all your customers, or the customer itself (billing delegation).
  • Fiscal receipts for the donations a company funds are made out to the account that owns the campaign: the child, when the campaign is the child's.
  • It needs the account hierarchy feature on your plan (accountHierarchy in Get entitlements). Without it, creating a child account answers 402 Plan upgrade required.

How the accounts fit together

Everything hangs off an account. Donations always belong to the account of their campaign, so a customer's donations land in that customer's account.

  • Your account (parent): your API credentials, your webhooks, and your own campaigns if you run any.
    • Customer A (child account, its own accountId)
      • Campaign "A donation with every order"
      • Campaign "Year-end vote"
    • Customer B (child account, its own accountId)
      • Campaign "Round-up"
      • Campaign "Loyalty points"

A child account is one level below yours. A user of Customer A's dashboard sees Customer A and nothing else: not your account, not Customer B.

When to turn it on

Turn it on when the giving belongs to your customers rather than to you. Typical signs:

  • You sell software or services to companies, and you want to offer them a giving feature inside your product.
  • Each customer needs its own campaigns and charities, its own reports, and receipts in its own name.
  • Each customer may pay for its own donations, or you want to bill them yourself, customer by customer.

You do not need it when the donations are yours: you fund them for your own customers or employees. One account is enough, and several campaigns segment the flows. See Campaigns.

What you need first

  • The account hierarchy feature. There is no API call to switch it on: ask the Charitips team. Until then, Create a child account answers 402 Plan upgrade required.
  • Your own account validated. Creating campaigns, activating them and creating donations check the status of the account behind your credentials, yours, and answer 403 Account not validated until it is. Child accounts are created already validated.
  • For each customer: the company name (3 to 100 characters), a contact's first name, last name and email, a legal registration number (a SIREN for a French company, a VAT number otherwise) and the postal address. They become the customer's billing and fiscal information, so they are needed for invoices and receipts. Most products collect them at the end of the customer's onboarding.
POST /v1/accounts/<accountId>/child-accounts
curl -X POST https://api.sandbox.charitips.com/v1/accounts/<accountId>/child-accounts \  -H "Authorization: Bearer $CHARITIPS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "name": "Customer A",    "firstName": "Jane",    "lastName": "Doe",    "email": "jane.doe@example.com",    "legalRegistrationNumber": "<SIREN or VAT number>",    "street": "8 rue de la Paix",    "city": "Paris",    "zip": "75002",    "country": "FR"  }'
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.

The response holds the child's accountId. Keep it with your customer record: every later call for this customer uses it.

What changes with child accounts

Billing

Two ways to bill, set per child account from your contract:

  • Billed to you. The donations of all your customers are added to your monthly invoice. You invoice your customers yourself. The checks before a campaign starts or a donation is created look at your account: your subscription, your payment method.
  • Billed to each customer (billing delegation). Each child account gets its own monthly subscription when it is created, and its own invoices. It starts with bank transfer as its payment method. To let the customer add a card or a direct debit, send its billing contact the link from Create a shareable billing link (valid one month, so create a new one each time you share it), or embed the billing form in your product.

A share of the revenue for you can be agreed in either mode. How to set up each one, step by step: Bill your business customers.

Technical detail: the mode is the child's billedTo (PARENT_ACCOUNT or ACCOUNT), copied from your account's default when the child is created. With your API credentials, the shareable billing link needs the account hierarchy feature (402 Plan upgrade required otherwise), answers 403 Billing delegation is not enabled for this account when the child is billed to you or your plan does not include billing delegation, and 400 No domain found for your account when your own account has no site.

Dashboards and users

  • Creating a child account also creates a dashboard user for the contact you sent. Nothing else to do for that person.
  • In the dashboard, your administrators manage each customer under Settings, Sub-accounts (or Subsidiaries): open the customer, then its admin team, to invite people or remove them.
  • To add people, call Create an invitation with the child's accountId: Charitips emails the invitation, and the user is created once it is accepted. During your tests, invite an address you own. The role is ADMIN, or MEMBER (limited to the campaigns you list in campaignIds). Seat limits come from your plan; past them, the call answers 402 Plan upgrade required.
  • Manage them with List users, Update a user and Delete a user, and the pending invitations with List user invitations and Delete a user invitation. Both lists take the child's accountId.
  • To open the dashboard from your product without a second login, call Create a user magic link with the user's userId. It answers 403 API_AUTH_NOT_ALLOWED if the child's authSchemes leave out API. By default a child accepts EMAIL, GOOGLE and API; set authSchemes to ["API"] on creation to let its users in through your magic links only.

Invite with your own accountId and the person gets your account, with every child account in it. For a customer's staff, always use the child's accountId.

Campaigns and charities

  • Pass the child's accountId to Create a charities selection and Create a campaign. Without it, they are created on your account.
  • A child's campaign can use a selection of that child, a selection of your account, or a generic one. A selection of another child answers 400 Invalid charitiesSelectionId.
  • Donations, votes and recurring donations take the account of their campaign: you never pass accountId on them.
  • Optionally, give the child's pages a subdomain under yours (subdomain must end with your own subdomain) or a custom domain (customDomain, which needs that feature on your plan).
POST /v1/campaigns
curl -X POST https://api.sandbox.charitips.com/v1/campaigns \  -H "Authorization: Bearer $CHARITIPS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "name": "Order donations",    "accountId": "<child accountId>",    "charitiesSelectionId": "<charitiesSelectionId>"  }'
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.

Reading data

List calls return your own account's data unless you pass an accountId. Pass the child's to read its campaigns, donations, invoices or fiscal receipts. An accountId that is neither yours nor one of your children's is refused with 400. For totals across all your customers, Get all campaigns metrics takes includeChildAccountsCampaigns (not combined with accountId). List child accounts pages through your customers.

API credentials

  • Credentials are created in the dashboard, for the account you are signed in to, and need the API access feature. Keep a single set on your parent account: it reaches every child account.
  • They are secret: call Charitips from your server, never from a browser or a mobile app.
  • Plan checks read your account: a donation paid by a user (hasBeenCharged) on a child's campaign needs the B2C use case on your account, and seat limits are yours.
  • uniqueExternalId is unique within one account. The same order id can exist in two child accounts without a 409.

Fiscal receipts

  • Donations a company funds (your customer, through its campaign): the receipt is made out to the account that owns the campaign, with that account's fiscal information (filled from the details sent when it was created). A campaign of Customer A gives receipts in Customer A's name, even when the invoice goes to you.
  • Donations a user pays with their own money (hasBeenCharged: true): the receipt is in the donor's name, never the company's.
  • When the receipt comes depends on the campaign: grouped once a year, or at the end of the campaign. See Billing and fiscal receipts.
  • Read them with List fiscal receipts and the child's accountId.

Webhooks

  • A webhook is created on the account behind your credentials, so on your parent account. To create one on a child account instead, pass the child's accountId to Create a webhook; List webhooks takes it too.
  • An event on a child account's object (a donation, a vote, a campaign, a payment method…) is sent to the webhooks of that child account and to those of its parent. One webhook on your account therefore receives the events of all your customers.
  • Each event carries the object, with its accountId: use it to route the event to the right customer on your side.
  • With billing delegation, the paymentmethod_create event, with the child's accountId, tells you a customer has a new payment method; its type says which (card, SEPA direct debit or bank transfer).

See Webhooks configuration.

Widgets

Which donation types work for your customers

Every flow that runs on a campaign runs on a child's campaign, the same way:

What to store on your side

  • Your own accountId, in your configuration.
  • Each child's accountId, on your customer record.
  • Each campaign's campaignId and publicKey (widgets use the publicKey): on the customer record if each customer has one campaign, on your own campaign record otherwise. Both are in the create response and in the campaign's information tab of the dashboard.
  • Your own id in uniqueExternalId on every donation, vote and donor (an order id, a gift id, a customer id). It lets you find them again, and a retried call answers 409 instead of creating a duplicate. Use externalId when the value is not unique.
  • The person who chose the charity in donor, when you know them.

Related

Donations for your business customers, Bill your business customers, Plans and prerequisites, Campaigns, Billing and fiscal receipts.