---
title: "Account hierarchy"
description: "Give each business customer its own Charitips account under yours, and see what that changes for billing, dashboards, keys, receipts and webhooks."
canonical: https://www.charitips.com/docs/concepts/account-hierarchy
---

# 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](https://www.charitips.com/docs/api-reference/get-entitlements.md)). 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](https://www.charitips.com/docs/concepts/campaigns.md).

### 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](https://www.charitips.com/docs/api-reference/create-child-account.md) 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.

```bash
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"
  }'
```

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](https://www.charitips.com/docs/api-reference/create-shareable-billing-link.md) (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](https://www.charitips.com/docs/guides/account-hierarchy-billing.md).

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](https://www.charitips.com/docs/api-reference/create-invitation.md) 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](https://www.charitips.com/docs/api-reference/list-users.md), [Update a user](https://www.charitips.com/docs/api-reference/update-user.md) and [Delete a user](https://www.charitips.com/docs/api-reference/delete-user.md), and the pending invitations with [List user invitations](https://www.charitips.com/docs/api-reference/list-user-invitations.md) and [Delete a user invitation](https://www.charitips.com/docs/api-reference/delete-user-invitation.md). Both lists take the child's `accountId`.
- To open the dashboard from your product without a second login, call [Create a user magic link](https://www.charitips.com/docs/api-reference/create-user-magic-link.md) 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.

> **Warning**
>
> 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](https://www.charitips.com/docs/api-reference/create-charities-selection.md) and [Create a campaign](https://www.charitips.com/docs/api-reference/create-campaign.md). 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).

```bash
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>"
  }'
```

### 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](https://www.charitips.com/docs/api-reference/get-all-campaigns-metrics.md) takes `includeChildAccountsCampaigns` (not combined with `accountId`). [List child accounts](https://www.charitips.com/docs/api-reference/list-child-accounts.md) 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](https://www.charitips.com/docs/concepts/billing-and-receipts.md).
- Read them with [List fiscal receipts](https://www.charitips.com/docs/api-reference/list-fiscal-receipts.md) 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](https://www.charitips.com/docs/api-reference/create-webhook.md); [List webhooks](https://www.charitips.com/docs/api-reference/list-webhooks.md) 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](https://www.charitips.com/docs/webhooks/configuration.md).

### Widgets

- Admin widgets (metrics, receipts, selection): [Create an admin widget token](https://www.charitips.com/docs/api-reference/create-admin-widget-token.md) takes an `accountId`. Pass the child's, and the widgets show that customer's data. See [Admin widgets](https://www.charitips.com/docs/widgets/admin.md).
- Billing delegation: the billing form can be embedded instead of sharing the link. See [Bill your business customers](https://www.charitips.com/docs/guides/account-hierarchy-billing.md#or-embed-the-billing-form).

## Which donation types work for your customers

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

- **Donations the customer funds:** [a donation with every order](https://www.charitips.com/docs/use-cases/donation-per-order.md), [loyalty points](https://www.charitips.com/docs/use-cases/loyalty-points.md), [gift card balance](https://www.charitips.com/docs/use-cases/gift-card-balance.md), [referral](https://www.charitips.com/docs/use-cases/referral.md), [card cashback](https://www.charitips.com/docs/use-cases/card-cashback.md), [a share of each subscription](https://www.charitips.com/docs/use-cases/subscription-share.md), [round-up](https://www.charitips.com/docs/use-cases/round-up.md), [a campaign for a date](https://www.charitips.com/docs/use-cases/campaign-for-a-date.md). All are [Create a donation](https://www.charitips.com/docs/api-reference/create-donation.md) on the child's campaign.
- **A budget shared by votes:** [customers vote on a budget](https://www.charitips.com/docs/use-cases/vote-on-a-budget.md), with [Create a vote](https://www.charitips.com/docs/api-reference/create-vote.md).
- **Matching:** [donation matching](https://www.charitips.com/docs/use-cases/donation-matching.md), set on the child's campaign.
- **Users giving their own money:** [your users give their own money](https://www.charitips.com/docs/use-cases/b2c.md), with the B2C use case on your account.
- **Monthly giving:** [monthly giving by your users](https://www.charitips.com/docs/use-cases/recurring-donations.md), with [Create a recurring donation](https://www.charitips.com/docs/api-reference/create-recurring-donation.md).
- **Employee giving:** [payroll giving and days off given](https://www.charitips.com/docs/use-cases/employee-giving.md), in Charitips widgets embedded in your HR or payroll software, after a call with our team.

## 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](https://www.charitips.com/docs/use-cases/account-hierarchy.md), [Bill your business customers](https://www.charitips.com/docs/guides/account-hierarchy-billing.md), [Plans and prerequisites](https://www.charitips.com/docs/overview/plans.md), [Campaigns](https://www.charitips.com/docs/concepts/campaigns.md), [Billing and fiscal receipts](https://www.charitips.com/docs/concepts/billing-and-receipts.md).