> ## Documentation Index
> Fetch the complete documentation index at: https://developers.momogood.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/events-auctions/overview#payload-customization-examples) for the full comparison).

Quick links:

* [`Event` (Custom Data Export variant)](#event-custom-data-export-variant)
* [`ItemsBundle`](#itemsbundle) — wrapper for items
  * [`BuyNowItem`](#buynowitem) · [`AuctionItem`](#auctionitem) · [`Pledge`](#pledge) · [`Raffle`](#raffle) · [`GliRaffle`](#gliraffle) · [`Ticket`](#ticket) · [`BidIncrement`](#bidincrement)
  * [Example `ItemsBundle` (Custom Data Export) response](#example-itemsbundle-custom-data-export-response)
* [`PurchasesBundle`](#purchasesbundle) — wrapper for purchases
  * [Common purchase fields](#common-purchase-fields) · [`BuyNowPurchase`](#buynowpurchase) · [`AuctionBid`](#auctionbid) · [`RafflePurchase`](#rafflepurchase) · [`GliRafflePurchase`](#glirafflepurchase) · [`TicketPurchase`](#ticketpurchase) · [`Donation`](#donation)
  * [Example `PurchasesBundle` (Custom Data Export) response](#example-purchasesbundle-custom-data-export-response)
* [`Guest` (Custom Data Export variant)](#guest-custom-data-export-variant) · [Connector guest variants](#guest-connector-variants-salesforce-and-blackbaud)
* [`AddressDetail`](#addressdetail)
* [Enums](#enums): [`Status`](#status-enum) · [`PaymentStatus`](#paymentstatus-enum) · [`ProcessorType`](#processortype-enum) · [`giftAidStatus`](#giftaidstatus-yesnoanswer)

***

## Event (Custom Data Export variant)

Returned by [`GET /<your-namespace>/v1/events`](/events-auctions/endpoints/events).

| Field         | Type           | Description                                                                   |
| ------------- | -------------- | ----------------------------------------------------------------------------- |
| `id`          | UUID           | Event id.                                                                     |
| `name`        | string         | Event display name.                                                           |
| `status`      | enum string    | One of [`Status`](#status-enum). 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

```json theme={null}
{
  "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](/events-auctions/overview#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`](#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`](#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`](#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`.                            |

<Warning>
  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.
</Warning>

### Example `ItemsBundle` (Custom Data Export) response

```json theme={null}
{
  "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

```json theme={null}
{
  "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`](#processortype-enum). *(Custom Data Export only)* |
| `paymentStatus`  | enum           | One of [`PaymentStatus`](#paymentstatus-enum). *(Custom Data Export only)* |

### Type-specific fields

| Type                                      | Wrapper key          | Extra fields                                                                                   |
| ----------------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------- |
| [`BuyNowPurchase`](#buynowpurchase)       | `buyNowPurchases`    | `buyNowItemId`, `buyNowItemTitle`, `supplyPrice`                                               |
| [`AuctionBid`](#auctionbid)               | `winningBids`        | `auctionItemId`, `auctionItemTitle`, `calculatedAmount`, `supplyPrice` (no `count` field)      |
| [`RafflePurchase`](#rafflepurchase)       | `rafflePurchases`    | `raffleId`, `raffleTitle`, `winningCount`                                                      |
| [`GliRafflePurchase`](#glirafflepurchase) | `gliRafflePurchases` | `raffleId`, `raffleTitle`, `winningCount`                                                      |
| [`TicketPurchase`](#ticketpurchase)       | `ticketPurchases`    | `ticketId`, `ticketTitle`, `ticketPurchaseRef`, `bookingFeeAmount`, `bookingFeePassedOnAmount` |
| [`Donation`](#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`](#giftaidstatus-yesnoanswer): `not_asked`, `yes`, `no`. |

### Example `PurchasesBundle` (Custom Data Export) response

```json theme={null}
{
  "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`](#addressdetail) \| null | Primary postal address.                                                                             |
| `giftAidAddress`       | [`AddressDetail`](#addressdetail) \| null | Gift Aid declaration address (UK).                                                                  |
| `taxReceiptAidAddress` | [`AddressDetail`](#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`](#status-enum); 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.                                                      |

<Warning>
  Note the snake\_case spelling: the field is `recipient_name`, not `recipientName`. This is the only snake\_case field across these schemas.
</Warning>

***

## Enums

All enum values are serialized in **lowercase** in JSON. See [Conventions → Enum casing](/events-auctions/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.                                 |

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

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