API reference

API conventions

Amounts in cents, dates in UTC, language and country codes, your own ids, and how every list call pages, sorts and filters.

The same rules hold on every endpoint: how amounts, dates and codes are written, how your own ids keep a retry safe, and how a list is paged, sorted and filtered.

In short

Amounts are integers in cents: 2000 is 20 €.
Dates are ISO 8601 strings in UTC, like 2026-11-01T09:00:00.000Z.
Languages are fr or en; countries are two capital letters (ISO 3166-1 alpha-2), like FR.
uniqueExternalId carries your own id: sending a create twice answers 409 instead of creating a duplicate.
Lists return up to limit items (20 by default, 100 at most) after the cursor, the id of the last item you already have.

Values

Amounts: integers in the currency's minor unit, cents for the euro. 100 is 1 €, 10000 is 100 €. Never send a decimal.
Dates: ISO 8601 strings. The API answers in UTC (Z). Date filters take the same format: 2026-07-01T00:00:00Z.
Languages: ISO 639-1 codes in lower case, fr or en, in language and locale fields.
Countries: ISO 3166-1 alpha-2 codes in upper case: FR for France, LU for Luxembourg.
Ids: UUIDs, returned on creation under the object's name: campaignId, donationId, charityId.

Your own ids

Donations, votes, donors and recurring donations take two ids of yours:

uniqueExternalId: unique within your account. A second create with the same value answers 409 and creates nothing, so a retried call after a timeout is safe. Use your order, gift or customer id.
externalId: any value, unique or not, such as a customer id shared by several donations.

List donations, List votes and List donors filter on both, to find an object from your own records.

Pagination

Every list call is paged with a cursor:

limit: the number of items, from 1 to 100, 20 by default (List charities answers 100 by default).
cursor: the id of the last item of the previous page. Leave it out for the first page.

Shell

1curl "https://api.sandbox.charitips.com/v1/charities?limit=10" -H "Authorization: Bearer $CHARITIPS_TOKEN"2 3# Next page: the charityId of the last charity received4curl "https://api.sandbox.charitips.com/v1/charities?limit=10&cursor=4c1f51c8-9f23-491e-9034-e502bf374b8a" -H "Authorization: Bearer $CHARITIPS_TOKEN"

Most lists answer an array: take the id of its last item as the next cursor (charityId for charities, donationId for donations), and stop when a page holds fewer items than limit. The few lists that answer an object give the next cursor in page.cursor, with pageSize, pageCount and recordsCount.

Sorting

Where a list call accepts sort, pass a field and an order, asc or desc, and separate several fields with commas:

/v1/campaigns?sort=name:asc sorts the campaigns by name.
/v1/campaigns?sort=status:asc,createdAt:desc sorts them by status, then the newest first.

Each endpoint's page lists the fields it sorts on. A field that is not listed answers 400.

Filtering

Pass a field as a query parameter for an exact match, or add an operator to it:

Operator	Meaning
`_gt`	after, or greater than
`_gte`	from, or greater than or equal to
`_lt`	before, or less than
`_lte`	until, or less than or equal to
`_in`	one of a list of values
`_notIn`	none of a list of values
`_not`	anything but this value

For example:

/v1/donations?campaignId=<campaignId> returns the donations of one campaign.
/v1/donations?campaignId=<campaignId>&createdAt_gte=2026-07-01T00:00:00Z&createdAt_lt=2026-08-01T00:00:00Z returns those created in July 2026.

Each endpoint's page lists its filters and their operators. A field and the same field with an operator cannot be combined: 400.

Errors

An error answers with its HTTP status and a body holding a message, and for some a code your code can test. See Errors and Troubleshooting.