Conventions

Money fields, timestamps, pagination, enum casing, and other conventions shared across all 9 endpoints.

The same conventions apply across every endpoint regardless of family (Custom Data Export, Salesforce, or Blackbaud).

Money fields

All amounts are integers in the event’s minor currency unit:

• Pence for GBP (£1.50 → 150)
• Cents for USD, CAD, AUD, HKD ($1.50 → 150)

The event’s currency is reported on the Event record’s currency field as an ISO 4217 code.

Timestamps

created and updated fields are Unix epoch seconds in UTC — not milliseconds.

{
  "created": 1709123456,
  "updated": 1714003200
}

For human-readable times, format these as UTC and convert to the event’s timezone (Event.timezone, an IANA timezone id) if displaying to end users.

IDs

UUIDs unless otherwise specified.

The since parameter

Parameter	Type	Default	Notes
since	long (epoch seconds)	1606062358 (2020-11-12)	The server filters records by updated >= since. Use -1 (or any past epoch) to backfill everything.

The default is a past epoch — leaving it off returns all records updated since that date, which for most accounts is effectively “everything.” Pass an explicit since value to scope the response to recently-updated records.

See the polling pattern for the recommended way to use since for incremental sync.

The q parameter

A simple full-text search. Empty string disables search.

For bundle endpoints (/items, /purchases), the same q filters each category (buy-nows, auction items, etc.) independently.

Pagination

Parameter	Type	Default	Notes
offset	int	0	Records to skip.
limit	int	1000	Page size. Maximum 1000.

For bundle endpoints (/items, /purchases), offset and limit apply per category in the response, not across the whole bundle. The bundle’s wrapper structure (its keys) is constant; only the array contents grow or shrink.

Status filter

All list endpoints implicitly filter to records with ACTIVE status. Archived, inactive, pending, and obfuscated records are not returned.

Enum casing

Enum values returned by the API are serialized in lowercase:

{
  "status": "active",
  "processorType": "stripe",
  "paymentStatus": "paid",
  "giftAidStatus": "yes"
}

Older Givergy reference material may show uppercase enum values (e.g. ACTIVE, STRIPE). Those are incorrect — the wire format is lowercase. Code-generated clients that assume uppercase will not deserialize correctly.

Content type and compression

Header	Value
Response Content-Type	application/json
Response compression	gzip when Accept-Encoding: gzip is sent on the request
Response ETag / Cache-Control	Not emitted

None of these endpoints emit ETag or Cache-Control: max-age. For incremental sync, use the polling pattern with since, not HTTP caching.