---
title: "API conventions"
description: "Amounts in cents, dates in UTC, language and country codes, your own ids, and how every list call pages, sorts and filters."
canonical: https://www.charitips.com/docs/api-reference/conventions
---

# 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](https://www.charitips.com/docs/api-reference/list-donations.md), [List votes](https://www.charitips.com/docs/api-reference/list-votes.md) and [List donors](https://www.charitips.com/docs/api-reference/list-donors.md) 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](https://www.charitips.com/docs/api-reference/list-charities.md) answers 100 by default).
- `cursor`: the id of the last item of the previous page. Leave it out for the first page.

```bash
curl "https://api.sandbox.charitips.com/v1/charities?limit=10" -H "Authorization: Bearer $CHARITIPS_TOKEN"

# Next page: the charityId of the last charity received
curl "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](https://www.charitips.com/docs/api-reference/errors.md) and [Troubleshooting](https://www.charitips.com/docs/api-reference/troubleshooting.md).

## Related

[Authentication](https://www.charitips.com/docs/get-started/authentication.md), [All endpoints](https://www.charitips.com/docs/api-reference/llms.txt), [Errors](https://www.charitips.com/docs/api-reference/errors.md).