Response schemas

Event, ItemsBundle, PurchasesBundle, Guest, AddressDetail, and the enums returned across every endpoint.

Reference for every record type returned by the Events & Auctions API. Where the Custom Data Export and connector variants differ, the Custom Data Export variant is the superset — connector variants omit some fields (see Payload customization examples for the full comparison).

Quick links:

• Event (Custom Data Export variant)
• ItemsBundle — wrapper for items
  • BuyNowItem · AuctionItem · Pledge · Raffle · GliRaffle · Ticket · BidIncrement
  • Example ItemsBundle (Custom Data Export) response
• PurchasesBundle — wrapper for purchases
  • Common purchase fields · BuyNowPurchase · AuctionBid · RafflePurchase · GliRafflePurchase · TicketPurchase · Donation
  • Example PurchasesBundle (Custom Data Export) response
• Guest (Custom Data Export variant) · Connector guest variants
• AddressDetail
• Enums: Status · PaymentStatus · ProcessorType · giftAidStatus

---

Event (Custom Data Export variant)

Returned by GET /<your-namespace>/v1/events.

Field	Type	Description
id	UUID	Event id.
name	string	Event display name.
status	enum string	One of Status. All listed events are "active".
inAidOf	string | null	Beneficiary description.
startTime	long (epoch s)	Event start.
endTime	long (epoch s)	Event end.
eventDate	long (epoch s)	Headline event date used for sorting/display.
timezone	string	IANA timezone id (e.g. Europe/London, America/New_York).
currency	string	ISO 4217 currency code (GBP, USD, CAD, AUD, HKD).
created	long (epoch s)	When the event was created.
updated	long (epoch s)	When the event was last updated.
projectType	string	EMS project type code (e.g. auction, mixed). Custom Data Export only.
externalId	string | null	Client-supplied external reference. Custom Data Export only.

The Salesforce/Blackbaud Event variant (not returned by any documented endpoint today, but useful background) would omit projectType and externalId.

---

ItemsBundle

{
  "buyNows":      [ BuyNowItem, ... ],
  "auctionItems": [ AuctionItem, ... ],
  "pledges":      [ Pledge, ... ],
  "prizeDraws":   [ Raffle, ... ],
  "gliRaffles":   [ GliRaffle, ... ],
  "tickets":      [ Ticket, ... ]
}

prizeDraws holds standard Raffle records; gliRaffles is a separate list because GLI-regulated raffles have distinct compliance handling.

The wrapper shape is identical across all three families; the difference is in the per-record fields (see Payload customization examples).

BuyNowItem

Field	Type	Description
id	UUID	Item id.
eventId	UUID	Parent event.
number	string	Display / catalogue number.
title	string	Item name.
price	long	Unit price (minor units).
available	int	Inventory remaining.
bought	int	Quantity sold to date.
requirePayment	boolean	Whether checkout enforces payment.
created	long (epoch s)	Creation timestamp.
updated	long (epoch s)	Last-update timestamp.
revenueStreamType	string	EMS revenue stream code. (Custom Data Export only)
externalId	string | null	Client reference. (Custom Data Export only)
categories	string[]	Category tags. (Custom Data Export only)
irsSubcategory	string[]	IRS reporting subcategories. (Custom Data Export only)
startPrice	long	Suggested / starting price (minor units). (Custom Data Export only)
increments	BidIncrement[]	Pricing tiers, where applicable. (Custom Data Export only)
description	string | null	Long description. (Custom Data Export only)
termsDescription	string | null	T&Cs text. (Custom Data Export only)
taxRate	double | null	Tax rate as decimal (0.2 = 20%). (Custom Data Export only)
estimate	long | null	Estimated value (minor units). (Custom Data Export only)

The Salesforce/Blackbaud BuyNowItem variants include only the first 10 fields (down to updated).

AuctionItem

Field	Type	Description
id	UUID	Lot id.
eventId	UUID	Parent event.
number	string	Lot number.
title	string	Lot title.
currentAmount	long	Current top bid (minor units).
topBidder	string | null	Top bidder name. Null when anonymous.
topBidAnonymous	boolean	Whether the top bid is anonymous.
created	long (epoch s)	Creation timestamp.
updated	long (epoch s)	Last-update timestamp.
revenueStreamType	string	EMS revenue stream code. (Custom Data Export only)
externalId	string | null	Client reference. (Custom Data Export only)
categories	string[]	Category tags. (Custom Data Export only)
irsSubcategory	string[]	IRS reporting subcategories. (Custom Data Export only)
startPrice	long	Opening bid (minor units). (Custom Data Export only)
increments	BidIncrement[]	Bid increment tiers. (Custom Data Export only)
type	string	Auction type code (e.g. STANDARD). (Custom Data Export only)
description	string | null	Description text. (Custom Data Export only)
termsDescription	string | null	T&Cs text. (Custom Data Export only)
estimate	long | null	Estimated value (minor units). (Custom Data Export only)

Pledge

Identical across all three families.

Field	Type	Description
id	UUID	Pledge id.
eventId	UUID	Parent event.
number	string	Display number.
title	string	Pledge title.
minimum	long	Minimum donation (minor units).
fixed	boolean	true = fixed donation amount; false = open amount.
created	long (epoch s)	Creation timestamp.
updated	long (epoch s)	Last-update timestamp.

Raffle

Field	Type	Description
id	string (UUID format)	Raffle id.
eventId	UUID	Parent event.
number	string	Display number.
title	string	Raffle title.
price	long	Ticket price (minor units).
available	int	Tickets remaining.
bought	int	Tickets sold.
requirePayment	boolean	Whether checkout enforces payment.
created	long (epoch s)	Creation timestamp.
updated	long (epoch s)	Last-update timestamp.
revenueStreamType	string	EMS revenue stream code. (Custom Data Export only)

Connector variants omit revenueStreamType only.

GliRaffle

All fields from Raffle, plus externalId (string | null, Custom Data Export only). GLI-regulated raffles (Gaming Laboratories International) are reported separately for compliance.

Connector variants omit revenueStreamType and externalId.

Ticket

Field	Type	Description
id	UUID	Ticket type id.
eventId	UUID	Parent event.
title	string	Ticket name.
price	long	Ticket price (minor units).
maxPerPurchase	int	Per-order cap.
available	int	Tickets remaining.
bought	int	Tickets sold.
created	long (epoch s)	Creation timestamp.
updated	long (epoch s)	Last-update timestamp.
revenueStreamType	string	EMS revenue stream code. (Custom Data Export only)
externalId	string | null	Client reference. (Custom Data Export only)

BidIncrement

A single tier of a bid-increment ladder.

Field	Type	Description
threshold	long (≥0)	Lower bound (minor units) at which this increment applies. 0 means the increment applies from the opening bid.
amount	long (≥1)	The minimum bid step (minor units) when the current price is at or above threshold.

Some earlier Givergy reference material used from / increment for these field names. The actual JSON field names are threshold and amount. Trust this document over older examples.

Example ItemsBundle (Custom Data Export) response

{
  "buyNows": [
    {
      "id": "b1a2c3d4-0001-4000-8000-000000000001",
      "eventId": "8f3c2a1d-9b4e-4c7a-a1d2-6e5f4c3b2a10",
      "number": "BN-001",
      "title": "Signed Football",
      "price": 5000,
      "available": 8,
      "bought": 2,
      "requirePayment": true,
      "created": 1709200000,
      "updated": 1714100000,
      "revenueStreamType": "merchandise",
      "externalId": "EXT-BN-001",
      "categories": ["sports", "memorabilia"],
      "irsSubcategory": ["sports_collectibles"],
      "startPrice": 5000,
      "increments": [],
      "description": "Football signed by the 2025 squad.",
      "termsDescription": "No refunds.",
      "taxRate": 0.2,
      "estimate": 7500
    }
  ],
  "auctionItems": [
    {
      "id": "a1a2c3d4-0001-4000-8000-000000000001",
      "eventId": "8f3c2a1d-9b4e-4c7a-a1d2-6e5f4c3b2a10",
      "number": "L-001",
      "title": "Weekend Stay in Paris",
      "currentAmount": 120000,
      "topBidder": "Jane Doe",
      "topBidAnonymous": false,
      "created": 1709200000,
      "updated": 1714200000,
      "revenueStreamType": "auction",
      "externalId": "EXT-L-001",
      "categories": ["travel"],
      "irsSubcategory": ["travel_packages"],
      "startPrice": 50000,
      "increments": [
        { "threshold": 0,      "amount": 5000 },
        { "threshold": 100000, "amount": 10000 }
      ],
      "type": "STANDARD",
      "description": "Two nights at a 4-star hotel in central Paris.",
      "termsDescription": "Subject to availability.",
      "estimate": 150000
    }
  ],
  "pledges": [
    {
      "id": "p1a2c3d4-0001-4000-8000-000000000001",
      "eventId": "8f3c2a1d-9b4e-4c7a-a1d2-6e5f4c3b2a10",
      "number": "PL-001",
      "title": "Sponsor a Meal",
      "minimum": 1000,
      "fixed": false,
      "created": 1709200000,
      "updated": 1709200000
    }
  ],
  "prizeDraws": [
    {
      "id": "r1a2c3d4-0001-4000-8000-000000000001",
      "eventId": "8f3c2a1d-9b4e-4c7a-a1d2-6e5f4c3b2a10",
      "number": "PD-001",
      "title": "Win a Tesla",
      "price": 2500,
      "available": 500,
      "bought": 124,
      "requirePayment": true,
      "created": 1709200000,
      "updated": 1714050000,
      "revenueStreamType": "raffle"
    }
  ],
  "gliRaffles": [
    {
      "id": "g1a2c3d4-0001-4000-8000-000000000001",
      "eventId": "8f3c2a1d-9b4e-4c7a-a1d2-6e5f4c3b2a10",
      "number": "GLI-001",
      "title": "50/50 Draw",
      "price": 2000,
      "available": 1000,
      "bought": 312,
      "requirePayment": true,
      "created": 1709200000,
      "updated": 1714100000,
      "revenueStreamType": "gli_raffle",
      "externalId": "EXT-GLI-001"
    }
  ],
  "tickets": [
    {
      "id": "t1a2c3d4-0001-4000-8000-000000000001",
      "eventId": "8f3c2a1d-9b4e-4c7a-a1d2-6e5f4c3b2a10",
      "title": "Standard Entry",
      "price": 7500,
      "maxPerPurchase": 10,
      "available": 200,
      "bought": 47,
      "created": 1709200000,
      "updated": 1714000000,
      "revenueStreamType": "ticket",
      "externalId": "EXT-T-STD"
    }
  ]
}

---

PurchasesBundle

{
  "buyNowPurchases":    [ BuyNowPurchase, ... ],
  "winningBids":        [ AuctionBid, ... ],
  "donations":          [ Donation, ... ],
  "rafflePurchases":    [ RafflePurchase, ... ],
  "gliRafflePurchases": [ GliRafflePurchase, ... ],
  "ticketPurchases":    [ TicketPurchase, ... ]
}

All purchase records share a common set of fields. Each subtype adds a small number of type-specific fields.

Common purchase fields

Field	Type	Description
id	UUID	Purchase id.
eventId	UUID	Parent event.
guestId	UUID	Guest who made the purchase.
guestName	string	Guest display name. Empty string when anonymous.
anonymous	boolean	Whether the guest chose to remain anonymous.
amount	long	Gross amount (minor units).
count	int	Quantity. Not present on AuctionBid (a winning bid is always 1).
totalFeesAmount	long	Total fees retained from amount.
totalFeesPassedOnAmount	long	Fees added on top, paid by the guest.
paymentProcessorId	string | null	Processor’s transaction reference (e.g. Stripe payment intent id).
created	long (epoch s)	Creation timestamp.
updated	long (epoch s)	Last-update timestamp.

The following three fields are present only on the Custom Data Export variants. They are absent from every purchase record returned by the Salesforce and Blackbaud connector endpoints.

Field	Type	Description
projectSegment	string | null	Reporting segment (free-form). (Custom Data Export only)
processorType	enum	One of ProcessorType. (Custom Data Export only)
paymentStatus	enum	One of PaymentStatus. (Custom Data Export only)

Type-specific fields

Type	Wrapper key	Extra fields
BuyNowPurchase	buyNowPurchases	buyNowItemId, buyNowItemTitle, supplyPrice
AuctionBid	winningBids	auctionItemId, auctionItemTitle, calculatedAmount, supplyPrice (no count field)
RafflePurchase	rafflePurchases	raffleId, raffleTitle, winningCount
GliRafflePurchase	gliRafflePurchases	raffleId, raffleTitle, winningCount
TicketPurchase	ticketPurchases	ticketId, ticketTitle, ticketPurchaseRef, bookingFeeAmount, bookingFeePassedOnAmount
Donation	donations	pledgeId, pledgeTitle, giftAidStatus

BuyNowPurchase

Common purchase fields plus:

Field	Type	Description
buyNowItemId	UUID	Reference to the BuyNowItem.
buyNowItemTitle	string	Item title.
supplyPrice	long	Cost of supply (minor units).

AuctionBid

Common purchase fields plus:

Field	Type	Description
auctionItemId	UUID	Reference to the AuctionItem.
auctionItemTitle	string	Lot title.
calculatedAmount	long	Calculated final amount (minor units).
supplyPrice	long	Cost of supply (minor units).

No count field — a winning bid is always 1.

RafflePurchase

Common purchase fields plus:

Field	Type	Description
raffleId	UUID	Reference to the Raffle.
raffleTitle	string	Raffle title.
winningCount	int	Number of winning tickets in this purchase.

GliRafflePurchase

Same fields as RafflePurchase, returned under the gliRafflePurchases key. GLI raffles are reported separately for compliance.

TicketPurchase

Common purchase fields plus:

Field	Type	Description
ticketId	UUID	Reference to the Ticket.
ticketTitle	string	Ticket name.
ticketPurchaseRef	string	Human-readable booking reference (e.g. TKT-2026-00047).
bookingFeeAmount	long	Booking fee retained (minor units).
bookingFeePassedOnAmount	long	Booking fee added on top, paid by the guest (minor units).

Donation

Common purchase fields plus:

Field	Type	Description
pledgeId	UUID	Reference to the Pledge.
pledgeTitle	string	Pledge title.
giftAidStatus	enum string	One of giftAidStatus: not_asked, yes, no.

Example PurchasesBundle (Custom Data Export) response

{
  "buyNowPurchases": [
    {
      "id": "c0000001-0000-4000-8000-000000000001",
      "buyNowItemId": "b1a2c3d4-0001-4000-8000-000000000001",
      "buyNowItemTitle": "Signed Football",
      "anonymous": false,
      "guestId": "f0000001-0000-4000-8000-000000000001",
      "guestName": "Alice Smith",
      "eventId": "8f3c2a1d-9b4e-4c7a-a1d2-6e5f4c3b2a10",
      "amount": 5000,
      "count": 1,
      "totalFeesAmount": 150,
      "totalFeesPassedOnAmount": 0,
      "paymentProcessorId": "pi_3OabcDEFghi",
      "supplyPrice": 2000,
      "created": 1713900000,
      "updated": 1713900000,
      "projectSegment": "main",
      "processorType": "stripe",
      "paymentStatus": "paid"
    }
  ],
  "winningBids": [
    {
      "id": "c0000002-0000-4000-8000-000000000002",
      "auctionItemId": "a1a2c3d4-0001-4000-8000-000000000001",
      "auctionItemTitle": "Weekend Stay in Paris",
      "anonymous": false,
      "guestId": "f0000002-0000-4000-8000-000000000002",
      "guestName": "Bob Jones",
      "eventId": "8f3c2a1d-9b4e-4c7a-a1d2-6e5f4c3b2a10",
      "amount": 120000,
      "calculatedAmount": 120000,
      "totalFeesAmount": 3600,
      "totalFeesPassedOnAmount": 0,
      "paymentProcessorId": "pi_3OxyzABCdef",
      "supplyPrice": 60000,
      "created": 1714200000,
      "updated": 1714200000,
      "projectSegment": "main",
      "processorType": "stripe",
      "paymentStatus": "paid"
    }
  ],
  "donations": [
    {
      "id": "c0000004-0000-4000-8000-000000000004",
      "pledgeId": "p1a2c3d4-0001-4000-8000-000000000001",
      "pledgeTitle": "Sponsor a Meal",
      "anonymous": false,
      "guestId": "f0000004-0000-4000-8000-000000000004",
      "guestName": "Carol White",
      "eventId": "8f3c2a1d-9b4e-4c7a-a1d2-6e5f4c3b2a10",
      "amount": 2500,
      "count": 1,
      "totalFeesAmount": 75,
      "totalFeesPassedOnAmount": 0,
      "paymentProcessorId": "pi_3OdonLMNopq",
      "giftAidStatus": "yes",
      "created": 1714100000,
      "updated": 1714100000,
      "projectSegment": "main",
      "processorType": "stripe",
      "paymentStatus": "paid"
    }
  ],
  "rafflePurchases": [
    {
      "id": "c0000003-0000-4000-8000-000000000003",
      "raffleId": "r1a2c3d4-0001-4000-8000-000000000001",
      "raffleTitle": "Win a Tesla",
      "winningCount": 0,
      "anonymous": true,
      "guestId": "f0000003-0000-4000-8000-000000000003",
      "guestName": "",
      "eventId": "8f3c2a1d-9b4e-4c7a-a1d2-6e5f4c3b2a10",
      "amount": 5000,
      "count": 2,
      "totalFeesAmount": 0,
      "totalFeesPassedOnAmount": 150,
      "paymentProcessorId": "pi_3OrafFGHijk",
      "created": 1714050000,
      "updated": 1714050000,
      "projectSegment": "main",
      "processorType": "stripe",
      "paymentStatus": "paid"
    }
  ],
  "gliRafflePurchases": [
    {
      "id": "c0000006-0000-4000-8000-000000000006",
      "raffleId": "g1a2c3d4-0001-4000-8000-000000000001",
      "raffleTitle": "50/50 Draw",
      "winningCount": 0,
      "anonymous": false,
      "guestId": "f0000006-0000-4000-8000-000000000006",
      "guestName": "Eve Green",
      "eventId": "8f3c2a1d-9b4e-4c7a-a1d2-6e5f4c3b2a10",
      "amount": 4000,
      "count": 2,
      "totalFeesAmount": 0,
      "totalFeesPassedOnAmount": 120,
      "paymentProcessorId": "pi_3OgliWXYzab",
      "created": 1714100000,
      "updated": 1714100000,
      "projectSegment": "main",
      "processorType": "stripe",
      "paymentStatus": "paid"
    }
  ],
  "ticketPurchases": [
    {
      "id": "c0000005-0000-4000-8000-000000000005",
      "ticketId": "t1a2c3d4-0001-4000-8000-000000000001",
      "ticketTitle": "Standard Entry",
      "ticketPurchaseRef": "TKT-2026-00047",
      "guestId": "f0000005-0000-4000-8000-000000000005",
      "guestName": "David Black",
      "eventId": "8f3c2a1d-9b4e-4c7a-a1d2-6e5f4c3b2a10",
      "amount": 15000,
      "count": 2,
      "bookingFeeAmount": 0,
      "bookingFeePassedOnAmount": 450,
      "totalFeesAmount": 450,
      "totalFeesPassedOnAmount": 450,
      "paymentProcessorId": "pi_3OtktRSTuvw",
      "created": 1713800000,
      "updated": 1713800000,
      "projectSegment": "main",
      "processorType": "stripe",
      "paymentStatus": "paid"
    }
  ]
}

A Salesforce or Blackbaud /purchases response would be the same shape, but every record would have projectSegment, processorType, and paymentStatus removed.

---

Guest (Custom Data Export variant)

Returned by the Custom Data Export /guests endpoint.

Field	Type	Description
id	UUID	Guest (contact) id.
eventId	UUID	Parent event.
firstName	string | null	First name.
lastName	string | null	Last name.
email	string | null	Email address.
mobile	string | null	Mobile phone. May be E.164 or local format depending on how it was captured.
mainAddress	AddressDetail | null	Primary postal address.
giftAidAddress	AddressDetail | null	Gift Aid declaration address (UK).
taxReceiptAidAddress	AddressDetail | null	Tax-receipt address (US).
created	long (epoch s)	Creation timestamp.
updated	long (epoch s)	Last-update timestamp.
consentAsked	boolean	Whether the guest has been prompted for consent.
consentStatus	enum string	One of Status; typically "active" or "inactive" for consent records.
consentChannels	string	Comma-separated channels the guest has opted in to (e.g. email,sms,post). Empty string when none.
externalId	string | null	Client reference. (Custom Data Export only)
smsOptIn	boolean	SMS opt-in flag. (Custom Data Export only)
companyName	string | null	Company / organisation name. (Custom Data Export only)

Guest connector variants (Salesforce and Blackbaud)

SalesforceGuest (returned by /salesforce/v1/.../guests) and BlackbaudGuest (returned by /blackbaud/v1/.../guests) are identical to each other and contain every field from the Custom Data Export Guest except externalId, smsOptIn, and companyName.

If you need any of those three fields, you must use the Custom Data Export /guests endpoint.

---

AddressDetail

Field	Type	Description
name	string | null	Label (e.g. Home, Billing).
line1	string | null	First address line.
line2	string | null	Second address line.
line3	string | null	Third address line.
line4	string | null	Fourth address line.
town	string | null	Town / city.
postcode	string | null	Postal / ZIP code.
state	string | null	State / province / region.
country	string | null	ISO 3166-1 alpha-2 country code (e.g. GB, US, CA, AU, HK).
recipient_name	string | null	Recipient name.

Note the snake_case spelling: the field is recipient_name, not recipientName. This is the only snake_case field across these schemas.

---

Enums

All enum values are serialized in lowercase in JSON. See Conventions → Enum casing.

Status enum

Returned for Event.status and Guest.consentStatus. Values:

error, archived, active, inactive, not_archived, obfuscated, pending

In practice list endpoints only ever return records with status: "active" because of the implicit active-only filter.

PaymentStatus enum

Returned on Custom Data Export purchase records only.

Value	Meaning
unknown	Status not yet determined.
paid	Payment captured in full.
unpaid	Awaiting payment.
part_paid	Partial payment received.
retracted	Payment retracted.
overpaid	Payment exceeds the amount due.
processor_pending	Processor is still processing the payment.
processor_declined	Processor declined the payment.
user_canceled	Guest cancelled before payment.
split	Amount split across multiple records / processors.
pay_later	Payment deferred (will settle later).

For most reporting use cases, treat paid, part_paid, overpaid, and split as “money received.”

ProcessorType enum

Returned on Custom Data Export purchase records only.

none, paypal, paypal_here, cheque_client, cheque_ibid, cash_client, cash_ibid, bank_transfer_client, bank_transfer_ibid, braintree, braintree_amex, braintree_vt, braintree_vt_amex, stripe, daf_pay, stripe_amex, stripe_vt, stripe_vt_amex, pdq, pdq_amex, eftpos, amex, zero_amount_charge, free

Conventions:

• The _vt suffix indicates a virtual terminal (typed-in card).
• _client variants indicate funds collected directly by the client.
• _ibid variants indicate funds collected by Givergy on the client’s behalf.

giftAidStatus (YesNoAnswer)

Donation.giftAidStatus is a tri-state string answering “has the guest agreed to Gift Aid this donation?”

Value	Meaning
not_asked	The guest has not been asked, or Gift Aid is not applicable.
yes	Guest has agreed and a Gift Aid declaration is on file.
no	Guest has declined Gift Aid.

Earlier Givergy reference material listed values like CLAIMED, PENDING, NOT_REQUESTED. Those are incorrect — the wire values are the three above.

Gift Aid is a UK-only HMRC mechanism, so this field is most meaningful for UK events.