Credits & Billing

The Partners API is metered by Partner API credits, split into six independent buckets — one per product area:

Each endpoint charges only its own bucket. The buckets are strictly isolated: running out of searches credits returns 402 Payment Required on search even if your donors bucket still has a large balance, and vice versa. There is no shared/fungible pool — credits never move between buckets.

How charging works

• Single-item endpoints (e.g. GET /donors/{id}, GET /search) cost 1 credit per request, charged to that endpoint’s bucket.
• Bulk endpoints (POST /enhancements, POST /exports, POST /donors/batch, POST /lists/{id}/donors, POST /networks/{id}/members/batch) cost 1 credit per item in the request, charged to that endpoint’s bucket. If you don’t have enough credits in that bucket for the full batch, we process as many items as your bucket balance allows (partial processing).
• Credits are charged upfront, before the request runs.
• If the request fails with a 5xx server error, the credit is automatically refunded.
• If the request fails with a 4xx client error, the credit is also refunded.
• When your team has no credits left, the API returns 402 Payment Required (see below).

Free endpoints

The following endpoints never consume a credit:

Utility

• All health checks (e.g. GET /donors/health, GET /search/health)
• GET /docs, GET /redoc, and GET /openapi.json — the API docs and spec
• GET /test
• GET /credits — the balance endpoint

Donors

• GET /donors/{id}/metadata — single donor metadata
• POST /donors/metadata/batch — batch donor metadata

Enhancements

• POST /enhancements/results/batch — get enhancement results
• GET /enhancements/{id}/progress — single enhancement progress
• POST /enhancements/progress/batch — batch enhancement progress

Exports

• GET /exports — list past exports

Lists

• GET /lists — list all lists
• GET /lists/{id} — get single list metadata
• PATCH /lists/{id} — rename a list
• POST /lists/{id}/donors/remove — remove donors from a list

Networks

• GET /networks — list all networks
• PUT /networks/{id} — rename a network
• GET /networks/jobs/{job_id} — check bulk add progress
• POST /networks/{id}/members/remove — remove members

Checking your balance

Call the free GET /credits endpoint. It returns the available balance for each of the six buckets:

$
curl https://api.donoratlas.com/v1/partners/credits \
>
  -H "x-api-key: $DONORATLAS_API_KEY"

1
{
2
  "donors": 4200,
3
  "enhancements": 1000,
4
  "exports": 500,
5
  "lists": 300,
6
  "networks": 250,
7
  "searches": 800
8
}

• Each field is the credits remaining in that bucket right now.

Need more credits?

When a bucket is empty, the endpoints that charge that bucket return 402 Payment Required — even if your other buckets still have a balance:

1
{
2
  "error": "insufficient_partner_api_credits",
3
  "message": "Your team has run out of Partner API credits. Purchase more credits or wait until your next renewal. See https://developer.donoratlas.com/credits for details.",
4
  "bucket": "searches",
5
  "available_credits": 0
6
}

The bucket field names the exhausted bucket so you know which product area to top up.

To obtain more credits, email team@donoratlas.com.