# API and webhook reference

> This reference is generated from the canonical version 2 OpenAPI, AsyncAPI, asset contract, and integration manifest. Examples contain no credentials or user data and reserved `.invalid` origins never execute. Interactive ‘try it’ is intentionally disabled: never paste an API key or webhook secret into a public documentation page.

## Environments and authentication

All API calls are server-to-server HTTPS. Both environments use separate runtime and finance credentials plus a receiver-only webhook secret. No credential is ever shipped to a browser or mobile app.

| Environment | JSON API | Credential shape |
|---|---|---|
| Intentionally non-resolving sandbox contract placeholder — synthetic data only. Use the exact HTTPS origin in the signed onboarding package. | `https://api.sandbox.invalid` | `chia_test_…` runtime + `chia_test_finance_…` finance |
| Intentionally non-resolving gated-production contract placeholder. Use the exact HTTPS origin and separate chia_live_ runtime and chia_live_finance_ finance credentials from signed onboarding. Credentials alone do not activate catalog or handoff. | `https://api.production.invalid` | `chia_live_…` runtime + `chia_live_finance_…` finance |

Every request sends `Authorization: Bearer ${CHIA_RUNTIME_KEY}` or `Authorization: Bearer ${CHIA_FINANCE_KEY}` and `Accept: application/json`. Never log the header, request/response body, asset URL, or handoff URL. Record only a validated `Chia-Request-Id`, status, and safe error code.

Exact immutable 2.1.0 downloads: [OpenAPI 3.1](https://partners.chia.health/contracts/v2.1.0/openapi.yaml), [AsyncAPI 3.0](https://partners.chia.health/contracts/v2.1.0/asyncapi.yaml), [asset contract](https://partners.chia.health/contracts/v2.1.0/assets.yaml), and [integration manifest](https://partners.chia.health/contracts/v2.1.0/integration-manifest.json). Revalidating compatibility aliases remain under `/contracts/v2/`; stable convenience aliases remain at the site root. Historical `/contracts/v2.0.0/` URLs remain immutable.

## JSON API operations

### `GET /v2/catalog/items` — List approved care-program catalog publications

Returns the authenticated partner's small, deterministically ordered, unpaginated catalog. No query parameters are accepted. Fetch from the partner's confidential backend on a schedule, mirror digest-verified assets, and never call once per signed-in user. Sandbox publications are synthetic; before written activation production fails closed, and after activation it returns only approved live care-program listings.

Credential: **runtime** · Required scope: `catalog:read` · Idempotency: `safe`

#### Request

| Location | Name | Required | Contract |
|---|---|---|---|
| header | `Authorization` | yes | `Bearer` runtime credential with `catalog:read` |
| header | `Accept` | yes | `application/json` |
| header | `If-None-Match` | no | Exact previously validated `ETag`; enables `304` without extending publication expiry |
| header | `If-None-Match` | no | `string`; pattern `^\"[a-f0-9]{64}\"$` — Exact strong ETag from the last complete authorized catalog response. A match returns 304; never construct, weaken, or reuse it across credentials or environments. |

```bash
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer ${CHIA_RUNTIME_KEY}" \
  -H 'Accept: application/json' \
  "${CHIA_API_ORIGIN}/v2/catalog/items"
```

#### Responses

| Status | Meaning | Body schema |
|---|---|---|
| `200` | Current approved catalog. | [CatalogList](#schema-cataloglist) |
| `304` | The exact authorized representation is unchanged. | none |
| `400` | Malformed JSON, unknown query/input field, invalid parameter, or unsupported media type. | [ErrorResponse](#schema-errorresponse) |
| `401` | Missing, invalid, expired, revoked, or wrong-environment credential. | [ErrorResponse](#schema-errorresponse) |
| `403` | The credential lacks the operation's exact environment or scope. | [ErrorResponse](#schema-errorresponse) |
| `405` | The resource accepts GET only. | [ErrorResponse](#schema-errorresponse) |
| `429` | Per-partner or per-credential limit exceeded. | [ErrorResponse](#schema-errorresponse) |
| `500` | Unexpected error with no internal details exposed. | [ErrorResponse](#schema-errorresponse) |
| `503` | A safe dependency failed before the operation could commit. | [ErrorResponse](#schema-errorresponse) |

Synthetic success response:

```json
{
  "object": "list",
  "data": [
    {
      "id": "cat_01K0M6A7H9Q2N4V8X3C5B7D9F1",
      "object": "catalog_item",
      "kind": "care_program",
      "presentation": {
        "advertising_label": "Paid advertisement · Chia",
        "title": "GLP-1 weight management care",
        "summary": "Online evaluation and ongoing support from the named medical group. Medication is not guaranteed and is prescribed only when an independent licensed clinician determines it is appropriate.",
        "cta_label": "Start an evaluation with Chia",
        "image": {
          "backend_download_url": "https://assets.sandbox.invalid/a/ast_01K0M6B1Q8D3R5T7V9X2Z4C6N8",
          "alt": "Chia GLP-1 weight management care",
          "delivery": "server_fetch_only",
          "sha256": "431ced6916a2a21a156e38701afe55bbd7f88969fbbfc56d7fe099d47f265460"
        }
      },
      "presentation_contract": {
        "layout_profile": "care_card_v1",
        "block_order": [
          "advertising_label",
          "title",
          "summary",
          "price",
          "material_terms",
          "disclosures",
          "cta"
        ],
        "visible_before_action": [
          "advertising_label",
          "title",
          "summary",
          "price.presentation",
          "price.billing_terms.minimum_total",
          "disclosures",
          "cta"
        ],
        "may_truncate": [],
        "viewport_profile": "partner_mobile_v1",
        "digest": "8ca07d44f27fd32f1e3f25bb5d09fb74ef1ca198809af8d33e10df450f6f5f84"
      },
      "price": {
        "scope": "care_program",
        "currency": "USD",
        "presentation": "$299/month for 3 months ($897 minimum)",
        "components": {
          "clinical_evaluation": "included",
          "ongoing_care_support": "included",
          "membership": "included",
          "medication": "excluded",
          "required_labs": "excluded",
          "shipping": "disclosed_before_any_applicable_charge",
          "taxes": "additional_if_applicable"
        },
        "billing_terms": {
          "first_charge_amount": 29900,
          "first_charge_rule": "Only after explicit authorization in Chia checkout",
          "recurring_unit_amount": 29900,
          "billing_interval": "month",
          "billing_interval_count": 1,
          "next_charge_rule": "Exact date and amount shown before checkout authorization",
          "minimum_term_cycles": 3,
          "minimum_total": 89700,
          "renews": true,
          "renewal_summary": "Continues monthly after the minimum term until canceled; exact renewal terms are shown before payment.",
          "cancellation_summary": "Cancellation method and effective date are shown before payment and remain available in Chia.",
          "refund_and_ineligibility_summary": "Clinical eligibility is not guaranteed; the applicable refund treatment is shown before payment."
        }
      },
      "availability": {
        "status": "available",
        "reason": null
      },
      "marketing_availability": {
        "policy": "partner_local_display_and_share_gate",
        "display": {
          "approved_state_codes": [
            "AZ",
            "CA",
            "CO",
            "FL",
            "IL",
            "NY",
            "TX",
            "WA"
          ],
          "accepted_evidence_bases": [
            "partner_account_service_state"
          ],
          "max_evidence_age_seconds": 2592000,
          "unknown_or_stale_behavior": "hide"
        },
        "context_sharing": {
          "approved_state_codes": [
            "AZ",
            "CO",
            "IL",
            "WA"
          ],
          "accepted_evidence_bases": [
            "partner_account_service_state"
          ],
          "max_evidence_age_seconds": 604800,
          "outside_approved_behavior": "neutral_url_only",
          "unknown_or_stale_behavior": "neutral_url_only"
        },
        "audience_profile_version": "aud_01K0M6C2R9E4T6V8X1Z3B5D7F9",
        "valid_until": "2026-08-16T00:00:00Z"
      },
      "parties": {
        "advertiser": "Chia Sandbox Services, Inc. (synthetic fixture)",
        "service_seller": "Chia Sandbox Services, Inc. (synthetic fixture)",
        "clinical_provider": "Chia Sandbox Medical Group, P.C. (synthetic fixture)",
        "billing_entity": {
          "name": "Chia Sandbox Services, Inc. (synthetic fixture)",
          "role": "merchant_of_record"
        },
        "pharmacy_role": "Exact seller/source/pharmacy named before any medication-specific charge and again before dispensing if prescribed",
        "partner_id": "example-partner",
        "partner_display_name": "Example Partner",
        "partner_role": "paid_publisher"
      },
      "regulatory": {
        "profile": "care_program_v1",
        "copy_version": "cpy_01K0M6D3S0F5U7W9Y2A4C6E8G0",
        "effective_at": "2026-07-22T00:00:00Z",
        "valid_until": "2026-08-16T00:00:00Z"
      },
      "handoff": {
        "version": "hnd_01K0M6E4T1G6V8X0Z3B5D7F9H1",
        "heading": "Share this care-program selection with Chia?",
        "body": "If you continue, Example Partner will tell Chia Sandbox Services, Inc. that you selected this care program and arrived from Example Partner so Chia can open the matching independent evaluation. Example Partner will not send your name, account ID, contact information, answers, or device identifier, and Chia will not tell Example Partner whether you became a patient, purchased care, received a prescription, or received a shipment.",
        "recipient": {
          "legal_name": "Chia Sandbox Services, Inc. (synthetic fixture)",
          "privacy_contact": "privacy-sandbox@chia.example"
        },
        "data_shared": [
          "selected care program",
          "Example Partner referral origin"
        ],
        "purpose": "Open the matching independent Chia evaluation",
        "compensation_disclosure": "Example Partner is paid a fixed marketplace service fee that does not depend on your click, purchase, prescription, or treatment.",
        "primary_action_label": "Share selection and continue",
        "session_creation_path": "/v2/handoff-sessions",
        "secondary_action_label": "Continue without sharing",
        "secondary_url": "https://care.sandbox.invalid/sandbox/start",
        "neutral_only_heading": "Continue to Chia without sharing this selection",
        "neutral_only_body": "Your Example Partner care-program selection will not be sent to Chia. You can choose a care program again after Chia opens.",
        "neutral_only_action_label": "Continue to Chia",
        "partner_consumer_health_policy_url": "https://partner.example/privacy/consumer-health",
        "partner_privacy_rights_url": "https://partner.example/privacy/rights",
        "chia_recipient_privacy_notice_url": "https://www.chia.example/legal/consumer-health-data",
        "chia_recipient_rights_url": "https://www.chia.example/privacy/rights",
        "effective_at": "2026-07-22T00:00:00Z",
        "valid_until": "2026-08-16T00:00:00Z"
      },
      "disclosures": [
        "Example Partner is a paid publisher and does not provide medical care, sell medication, collect patient payment, or receive information submitted to Chia or individual outcomes.",
        "A Chia clinician may recommend a different treatment or no treatment after an independent evaluation.",
        "If medication is considered, its exact seller/source/pharmacy and all medication-specific costs and disclosures appear inside Chia before any medication charge."
      ],
      "version": "pub_01K0M6G6W3J8X0Z2B5D7F9H1K3"
    }
  ],
  "catalog_version": "cav_01K0M6H7X4K9Y1A3C6E8G0J2L4",
  "livemode": false
}
```

Success headers: `Chia-Request-Id`, `Chia-Version`, `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, `Cache-Control`, `ETag`, `Vary`.

### `POST /v2/handoff-sessions` — Create a short-lived hosted Chia handoff after affirmative disclosure consent

Call from the authenticated partner's confidential backend immediately after the user affirmatively accepts the exact handoff disclosure returned on the selected catalog item. The closed request accepts no partner user, account, device, contact, patient, order, state, or arbitrary metadata identifier. The opaque URL expires 15 minutes after creation and has no read/status endpoint. Sandbox opens an isolated synthetic page. Before written production activation this operation fails closed; once activated, production opens the selected co-branded Chia journey, where Chia performs identity, intake, eligibility, checkout, payment, care, support, and fulfillment.

Credential: **runtime** · Required scope: `handoffs:create` · Idempotency: `required_random_uuid_v4`

#### Request

| Location | Name | Required | Contract |
|---|---|---|---|
| header | `Authorization` | yes | `Bearer` runtime credential with `handoffs:create` |
| header | `Accept` | yes | `application/json` |
| header | `Content-Type` | yes | Exact `application/json` |
| header | `Idempotency-Key` | yes | `string`; pattern `^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$`; maximum length `36` — Random UUIDv4 persisted before the first attempt and reused only for byte-identical retries. Never derive it from a user, account, device, contact, patient, or order. |

```bash
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer ${CHIA_RUNTIME_KEY}" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: ${UUID_V4}" \
  --data '{"catalog_item_id":"cat_01K0M6A7H9Q2N4V8X3C5B7D9F1","disclosure_version":"hnd_01K0M6E4T1G6V8X0Z3B5D7F9H1","consent_attestation":{"affirmed":true,"affirmed_at":"2026-07-22T15:00:00Z"}}' \
  "${CHIA_API_ORIGIN}/v2/handoff-sessions"
```

JSON body schema: [HandoffSessionRequest](#schema-handoffsessionrequest). The examples below are safe synthetic values.

`sandbox`:

```json
{
  "catalog_item_id": "cat_01K0M6A7H9Q2N4V8X3C5B7D9F1",
  "disclosure_version": "hnd_01K0M6E4T1G6V8X0Z3B5D7F9H1",
  "consent_attestation": {
    "affirmed": true,
    "affirmed_at": "2026-07-22T15:00:00Z"
  }
}
```

`production`:

```json
{
  "catalog_item_id": "cat_01K0M6A7H9Q2N4V8X3C5B7D9F1",
  "disclosure_version": "hnd_01K0M6E4T1G6V8X0Z3B5D7F9H2",
  "consent_attestation": {
    "affirmed": true,
    "affirmed_at": "2026-07-22T15:00:00Z"
  }
}
```

#### Responses

| Status | Meaning | Body schema |
|---|---|---|
| `201` | A new handoff was created, or the exact idempotent response was replayed. It expires exactly 15 minutes after creation. | [HandoffSessionResponse](#schema-handoffsessionresponse) |
| `400` | Malformed JSON, unknown query/input field, invalid parameter, or unsupported media type. | [ErrorResponse](#schema-errorresponse) |
| `401` | Missing, invalid, expired, revoked, or wrong-environment credential. | [ErrorResponse](#schema-errorresponse) |
| `403` | The credential lacks the operation's exact environment or scope. | [ErrorResponse](#schema-errorresponse) |
| `405` | The resource accepts POST only. | [ErrorResponse](#schema-errorresponse) |
| `409` | Idempotency key reuse with a different body or unavailable webhook endpoint. | [ErrorResponse](#schema-errorresponse) |
| `413` | Malformed JSON, unknown query/input field, invalid parameter, or unsupported media type. | [ErrorResponse](#schema-errorresponse) |
| `415` | Malformed JSON, unknown query/input field, invalid parameter, or unsupported media type. | [ErrorResponse](#schema-errorresponse) |
| `429` | Per-partner or per-credential limit exceeded. | [ErrorResponse](#schema-errorresponse) |
| `500` | Unexpected error with no internal details exposed. | [ErrorResponse](#schema-errorresponse) |
| `503` | A safe dependency failed before the operation could commit. | [ErrorResponse](#schema-errorresponse) |

Synthetic success response:

```json
{
  "object": "handoff_session",
  "id": "phs_01K0R7A2B3C4D5E6F7G8H9J0K1",
  "url": "https://a1b2c3d4.execute-api.us-east-1.amazonaws.com/sandbox/handoff/phs_01K0R7A2B3C4D5E6F7G8H9J0K1",
  "expires_at": "2026-07-22T15:15:00Z",
  "livemode": false
}
```

Success headers: `Chia-Request-Id`, `Chia-Version`, `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, `Cache-Control`.

### `GET /v2/settlement_summaries` — List environment-authorized settlement presentations

Requires the separate environment finance credential. Only opaque cursor pagination is supported; patient, order, payment-level, shipment, program, geography, event, date-row, status, time-range, expansion, and line-item filters do not exist. Sandbox returns documented synthetic fixtures. Production returns only closed, immutable statement revisions that Finance explicitly authored and released for this credential-bound partner and environment. Corrections append a new revision and point to the prior release with supersedes_id; a release is never mutated. Amounts, due/paid status, and timestamps come only from the Finance-authored release record. Aggregate activity is nullable and a count is exposed only after the internal threshold and composition approvals pass; those internal proofs are never projected. Production never reads live activity or synthesizes liability, due, paid, count, or statement state from configuration, runtime events, or the wall clock.

Credential: **finance** · Required scope: `settlements:read` · Idempotency: `safe`

#### Request

| Location | Name | Required | Contract |
|---|---|---|---|
| header | `Authorization` | yes | `Bearer` finance credential with `settlements:read` |
| header | `Accept` | yes | `application/json` |
| query | `limit` | no | `integer`; minimum `1`; maximum `25` — Number of summaries, newest fixed reporting window first. |
| query | `starting_after` | no | `string`; pattern `^cur_[A-Za-z0-9_-]{16,252}$` — Authenticated opaque cursor from next_cursor. It expires 24 hours after issue and carries no client-readable business fields. On cursor_expired, restart without starting_after and reconcile immutable revisions by id, revision, and supersedes_id. |

```bash
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer ${CHIA_FINANCE_KEY}" \
  -H 'Accept: application/json' \
  "${CHIA_API_ORIGIN}/v2/settlement_summaries?limit=10"
```

#### Responses

| Status | Meaning | Body schema |
|---|---|---|
| `200` | Sandbox synthetic fixtures or Finance-released immutable production statement revisions. | [SettlementList](#schema-settlementlist) |
| `400` | Malformed JSON, unknown query/input field, invalid parameter, or unsupported media type. | [ErrorResponse](#schema-errorresponse) |
| `401` | Missing, invalid, expired, revoked, or wrong-environment credential. | [ErrorResponse](#schema-errorresponse) |
| `403` | The credential lacks the operation's exact environment or scope. | [ErrorResponse](#schema-errorresponse) |
| `405` | The resource accepts GET only. | [ErrorResponse](#schema-errorresponse) |
| `429` | Per-partner or per-credential limit exceeded. | [ErrorResponse](#schema-errorresponse) |
| `500` | Unexpected error with no internal details exposed. | [ErrorResponse](#schema-errorresponse) |
| `503` | A safe dependency failed before the operation could commit. | [ErrorResponse](#schema-errorresponse) |

Synthetic success response:

```json
{
  "object": "list",
  "data": [
    {
      "id": "set_01K0M9A3D0R5F7H9K2N4Q6S8V0",
      "object": "settlement_summary",
      "service_fee": {
        "statement_id": "fee_01K0M9B4E1S6G8J0L3P5R7T9W1",
        "period": {
          "start": "2026-06-01",
          "end": "2026-07-01",
          "timezone": "UTC"
        },
        "status": "finalized",
        "payer": {
          "name": "Chia Sandbox Services, Inc. (synthetic fixture)"
        },
        "payee": {
          "name": "Example Partner"
        },
        "fixed_service_fee": {
          "amount": 250000,
          "currency": "USD"
        },
        "amount_paid": {
          "amount": 0,
          "currency": "USD"
        },
        "amount_due_to_partner": {
          "amount": 250000,
          "currency": "USD"
        },
        "payable_on": "2026-07-31",
        "paid_at": null,
        "terms_version": "terms_01K0M9C5F2T7H9K1N4Q6S8V0X2",
        "as_of": "2026-07-08T00:00:00Z"
      },
      "aggregate_activity": {
        "release_id": "act_01K0M9D6G3V8J0L2P5R7T9W1Y3",
        "period": {
          "start": "2026-05-01",
          "end": "2026-07-01",
          "timezone": "UTC"
        },
        "aggregate_initial_purchase_count": 42,
        "as_of": "2026-07-08T00:00:00Z"
      }
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "livemode": false
}
```

Success headers: `Chia-Request-Id`, `Chia-Version`, `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, `Cache-Control`, `Vary`.

### `POST /v2/webhook_tests` — Send a signed synthetic webhook

Creates or exactly replays one synthetic test event to the authenticated environment's already registered endpoint. The caller cannot choose a destination, payload, headers, identifiers, period, or metadata. Both sandbox and production support all three documented test shapes. Every test event has test=true and must cause no business side effect.

Credential: **runtime** · Required scope: `webhooks:test` · Idempotency: `required_random_uuid_v4`

#### Request

| Location | Name | Required | Contract |
|---|---|---|---|
| header | `Authorization` | yes | `Bearer` runtime credential with `webhooks:test` |
| header | `Accept` | yes | `application/json` |
| header | `Content-Type` | yes | Exact `application/json` |
| header | `Idempotency-Key` | yes | `string`; pattern `^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$`; maximum length `36` — Random UUIDv4 persisted by the caller before the first network attempt and reused for byte-identical retries. Never derive it from a partner user, account, device, email, phone, patient, or order. |

```bash
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer ${CHIA_RUNTIME_KEY}" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: ${UUID_V4}" \
  --data '{"event_type":"endpoint.test"}' \
  "${CHIA_API_ORIGIN}/v2/webhook_tests"
```

JSON body schema: [WebhookTestRequest](#schema-webhooktestrequest). The examples below are safe synthetic values.

`endpoint`:

```json
{
  "event_type": "endpoint.test"
}
```

`catalog`:

```json
{
  "event_type": "catalog.updated"
}
```

`settlement`:

```json
{
  "event_type": "settlement_summary.finalized"
}
```

#### Responses

| Status | Meaning | Body schema |
|---|---|---|
| `202` | Synthetic event durably accepted, or the exact idempotent response replayed. | [WebhookTestResponse](#schema-webhooktestresponse) |
| `400` | Malformed JSON, unknown query/input field, invalid parameter, or unsupported media type. | [ErrorResponse](#schema-errorresponse) |
| `401` | Missing, invalid, expired, revoked, or wrong-environment credential. | [ErrorResponse](#schema-errorresponse) |
| `403` | The credential lacks the operation's exact environment or scope. | [ErrorResponse](#schema-errorresponse) |
| `409` | Idempotency key reuse with a different body or unavailable webhook endpoint. | [ErrorResponse](#schema-errorresponse) |
| `405` | The resource accepts POST only. | [ErrorResponse](#schema-errorresponse) |
| `413` | Malformed JSON, unknown query/input field, invalid parameter, or unsupported media type. | [ErrorResponse](#schema-errorresponse) |
| `415` | Malformed JSON, unknown query/input field, invalid parameter, or unsupported media type. | [ErrorResponse](#schema-errorresponse) |
| `429` | Per-partner or per-credential limit exceeded. | [ErrorResponse](#schema-errorresponse) |
| `500` | Unexpected error with no internal details exposed. | [ErrorResponse](#schema-errorresponse) |
| `503` | A safe dependency failed before the operation could commit. | [ErrorResponse](#schema-errorresponse) |

Synthetic success response:

```json
{
  "id": "evt_test_01K0N1A2B3C4D5E6F7G8H9J0K1",
  "object": "webhook_test",
  "event_type": "endpoint.test",
  "destination_hint": "https://hooks.sandbox.partner.example/***",
  "created_at": "2026-07-22T15:00:00Z",
  "livemode": false,
  "test": true
}
```

Success headers: `Chia-Request-Id`, `Chia-Version`, `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, `Cache-Control`.

## Authenticated catalog assets

Authenticated backend-only delivery of immutable, digest-pinned catalog image bytes. This is not a JSON business API resource and must never be called from a mobile app or browser. Static origins below use the reserved .invalid suffix intentionally; the exact per-environment HTTPS origin comes only from the signed onboarding package and is used as a strict SSRF allowlist.

Operation: `GET /a/{opaque_asset_id}` · Credential: **runtime** · Scope: `catalog:read`.

| Environment | Origin |
|---|---|
| sandbox | `https://assets.sandbox.invalid` |
| production | `https://assets.production.invalid` |

A success is `200` with `image/avif`, `image/webp`, `image/png`, no more than `5242880` bytes. Verify `Content-Length`, `Content-Type`, `ETag`, and `Content-Digest` while streaming into a commit/abort sink before publishing a neutral partner-owned mirror.

Authorization and enumeration failures collapse to `404 catalog_asset_unavailable`. Assets are backend-only: never fetch from mobile/browser, follow redirects, send cookies/ranges/query strings, or expose the authenticated URL.

Full schema and integrity rules: [immutable 2.1.0 asset contract](https://partners.chia.health/contracts/v2.1.0/assets.yaml) and [asset contract JSON Schema](https://partners.chia.health/schemas/asset-contract.schema.json).

## Signed webhooks

Outbound, partner- and environment-isolated, at-least-once synthetic webhook tests for endpoint.test, catalog.updated, and settlement_summary.finalized receiver shapes. Version 2.1 emits no live business event; production settlement releases are read only through the finance API. There are no patient, launch, eligibility, payment, order, prescription, fulfillment, shipment, refund, support, or outcome events.

Chia sends `POST` to the exact pre-registered HTTPS endpoint. Preserve the raw bytes. Reject stale timestamps, compute HMAC-SHA256 over `<Chia-Webhook-Timestamp>.<exact_raw_body>`, constant-time match a `v1=` value against the current or one retiring environment secret, then validate header/envelope equality and deduplicate the event ID before routing.

`test: true` is the first branch and must have zero cache, finance, accounting, notification, care, or analytics side effects—even when `livemode: true` in production.

Required headers: `Chia-Webhook-Id`, `Chia-Webhook-Timestamp`, `Chia-Webhook-Signature`, `Chia-Webhook-Type`, and `Chia-Version`.

Signature tolerance: `300` seconds. Delivery is `at_least_once` for up to `24` hours in sandbox and `24` hours in production. Any `200-299` response acknowledges; response bodies are discarded and redirects are not followed.

Receiver responses: return `2xx` only after the durable no-op deduplication receipt commits; use `400` for invalid/stale/cross-environment payloads, `413` for the bounded body limit, `415` for media type, and `5xx` only for a transient pre-commit failure.

### `endpoint.test` — Endpoint test

Explicitly synthetic endpoint test with exact empty data.

Payload schema: [EndpointTestEvent](#schema-endpointtestevent). Delivery is at least once; V2 requires `test:true` and acknowledgement only after a durable no-side-effect deduplication receipt commits.

Synthetic signed headers:

```json
{
  "Chia-Webhook-Id": "evt_test_01K0N3A4B5C6D7E8F9G0H1J2K3",
  "Chia-Webhook-Timestamp": "1784732400",
  "Chia-Webhook-Signature": "v1=fdcc5eec535c9b22eec93eb7a064ef0606f96e70d2aafbb31e390c38bc321406",
  "Chia-Webhook-Type": "endpoint.test",
  "Chia-Version": "2026-07-22"
}
```

Synthetic payload:

```json
{
  "id": "evt_test_01K0N3A4B5C6D7E8F9G0H1J2K3",
  "object": "event",
  "type": "endpoint.test",
  "api_version": "2026-07-22",
  "created_at": "2026-07-22T15:00:00Z",
  "livemode": false,
  "test": true,
  "data": {}
}
```

### `catalog.updated` — Catalog updated

Synthetic catalog-update receiver test; it must never invalidate a live cache.

Payload schema: [CatalogUpdatedEvent](#schema-catalogupdatedevent). Delivery is at least once; V2 requires `test:true` and acknowledgement only after a durable no-side-effect deduplication receipt commits.

Synthetic signed headers:

```json
{
  "Chia-Webhook-Id": "evt_test_01K0N4A5B6C7D8E9F0G1H2J3K4",
  "Chia-Webhook-Timestamp": "1784732460",
  "Chia-Webhook-Signature": "v1=2942ddbb4a55568eb0c29f1dca87eb7bf71ebd3d7c00d690b629c7e926508c82",
  "Chia-Webhook-Type": "catalog.updated",
  "Chia-Version": "2026-07-22"
}
```

Synthetic payload:

```json
{
  "id": "evt_test_01K0N4A5B6C7D8E9F0G1H2J3K4",
  "object": "event",
  "type": "catalog.updated",
  "api_version": "2026-07-22",
  "created_at": "2026-07-22T15:01:00Z",
  "livemode": false,
  "test": true,
  "data": {
    "catalog_version": "cav_test_01K0N4B5C6D7E8F9G0H1J2K3M4",
    "required_action": "invalidate_and_refetch",
    "effective_at": "2026-07-22T15:01:00Z"
  }
}
```

### `settlement_summary.finalized` — Settlement presentation finalized

Synthetic settlement-finalization receiver test; it must never trigger a finance refresh.

Payload schema: [SettlementSummaryFinalizedEvent](#schema-settlementsummaryfinalizedevent). Delivery is at least once; V2 requires `test:true` and acknowledgement only after a durable no-side-effect deduplication receipt commits.

Synthetic signed headers:

```json
{
  "Chia-Webhook-Id": "evt_test_01K0S6A7B8C9D0E1F2G3H4J5K6",
  "Chia-Webhook-Timestamp": "1786148040",
  "Chia-Webhook-Signature": "v1=1ad208d999fa3212fd89e4d91bbc772a78bc8af1364696363cb1dd1a22474423",
  "Chia-Webhook-Type": "settlement_summary.finalized",
  "Chia-Version": "2026-07-22"
}
```

Synthetic payload:

```json
{
  "id": "evt_test_01K0S6A7B8C9D0E1F2G3H4J5K6",
  "object": "event",
  "type": "settlement_summary.finalized",
  "api_version": "2026-07-22",
  "created_at": "2026-08-08T00:14:00Z",
  "livemode": false,
  "test": true,
  "data": {
    "summary_id": "set_test_01K0S6B7C8D9E0F1G2H3J4K5M6",
    "period": {
      "start": "2026-07-01",
      "end": "2026-08-01",
      "timezone": "UTC"
    }
  }
}
```

## Schema index

Schema names link to compact property summaries generated from the exact machine contracts.

### OpenAPI schemas

[ErrorResponse](#schema-errorresponse) · [Error](#schema-error) · [CatalogList](#schema-cataloglist) · [CatalogItem](#schema-catalogitem) · [Presentation](#schema-presentation) · [CatalogImage](#schema-catalogimage) · [PresentationContract](#schema-presentationcontract) · [Price](#schema-price) · [FixedTermsPrice](#schema-fixedtermsprice) · [VariablePrice](#schema-variableprice) · [ObservedMonthlyRange](#schema-observedmonthlyrange) · [VariablePriceComponents](#schema-variablepricecomponents) · [PriceComponents](#schema-pricecomponents) · [BillingTerms](#schema-billingterms) · [Availability](#schema-availability) · [MarketingAvailability](#schema-marketingavailability) · [DisplayPolicy](#schema-displaypolicy) · [ContextSharingPolicy](#schema-contextsharingpolicy) · [StateCodes](#schema-statecodes) · [Parties](#schema-parties) · [BillingEntity](#schema-billingentity) · [Regulatory](#schema-regulatory) · [Handoff](#schema-handoff) · [HandoffRecipient](#schema-handoffrecipient) · [SettlementList](#schema-settlementlist) · [SettlementSummary](#schema-settlementsummary) · [ServiceFee](#schema-servicefee) · [NamedParty](#schema-namedparty) · [Money](#schema-money) · [Period](#schema-period) · [AggregateActivity](#schema-aggregateactivity) · [LegacyAggregateActivity](#schema-legacyaggregateactivity) · [PrivacyThresholdedAggregateActivity](#schema-privacythresholdedaggregateactivity) · [ConsentAttestation](#schema-consentattestation) · [HandoffSessionRequest](#schema-handoffsessionrequest) · [HandoffSessionResponse](#schema-handoffsessionresponse) · [WebhookTestRequest](#schema-webhooktestrequest) · [WebhookTestResponse](#schema-webhooktestresponse)

### Webhook schemas

[WebhookHeaders](#schema-webhookheaders) · [EmptyData](#schema-emptydata) · [CatalogUpdatedData](#schema-catalogupdateddata) · [SettlementSummaryFinalizedData](#schema-settlementsummaryfinalizeddata) · [Period](#schema-period) · [EndpointTestEvent](#schema-endpointtestevent) · [CatalogUpdatedEvent](#schema-catalogupdatedevent) · [SettlementSummaryFinalizedEvent](#schema-settlementsummaryfinalizedevent)


### Schema: ErrorResponse

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `error` | yes | [Error](#schema-error) |  |

### Schema: Error

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `type` | yes | one of `"invalid_request_error"`, `"authentication_error"`, `"permission_error"`, `"conflict_error"`, `"rate_limit_error"`, `"api_error"` |  |
| `code` | yes | `string`; pattern `^[a-z][a-z0-9_]{2,63}$` |  |
| `message` | yes | `string`; minimum length `1`; maximum length `240` |  |
| `param` | yes | `string` or `null`; maximum length `80` |  |
| `request_id` | yes | `string`; pattern `^req_[A-Za-z0-9]{8,64}$` |  |
| `retryable` | yes | `boolean` |  |

### Schema: CatalogList

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `object` | yes | literal `"list"` |  |
| `data` | yes | array of [CatalogItem](#schema-catalogitem); maximum items `50` |  |
| `catalog_version` | yes | `string`; pattern `^cav_[A-Za-z0-9]{8,64}$` |  |
| `livemode` | yes | `boolean` |  |

### Schema: CatalogItem

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `id` | yes | `string`; pattern `^cat_[A-Za-z0-9]{8,64}$` |  |
| `object` | yes | literal `"catalog_item"` |  |
| `kind` | yes | literal `"care_program"` |  |
| `presentation` | yes | [Presentation](#schema-presentation) |  |
| `presentation_contract` | yes | [PresentationContract](#schema-presentationcontract) |  |
| `price` | yes | [Price](#schema-price) |  |
| `availability` | yes | [Availability](#schema-availability) |  |
| `marketing_availability` | yes | [MarketingAvailability](#schema-marketingavailability) |  |
| `parties` | yes | [Parties](#schema-parties) |  |
| `regulatory` | yes | [Regulatory](#schema-regulatory) |  |
| `handoff` | yes | [Handoff](#schema-handoff) |  |
| `disclosures` | yes | array of `string`; minimum length `1`; maximum length `500`; minimum items `3`; maximum items `12` |  |
| `program_key` | no | `string`; pattern `^[a-z][a-z0-9-]*:[a-z][a-z0-9-]*$`; maximum length `120` | Chia-controlled public acquisition context. Present on live production publications; never a drug, offering, price, clinician, pharmacy, or fulfillment identifier. |
| `version` | yes | `string`; pattern `^pub_[A-Za-z0-9]{8,64}$` |  |

### Schema: Presentation

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `advertising_label` | yes | one of `"Paid advertisement · Chia"`, `"Paid marketplace listing · Chia"` |  |
| `title` | yes | `string`; minimum length `1`; maximum length `120` |  |
| `summary` | yes | `string`; minimum length `1`; maximum length `600` |  |
| `cta_label` | yes | `string`; minimum length `1`; maximum length `80` |  |
| `image` | yes | [CatalogImage](#schema-catalogimage) |  |

### Schema: CatalogImage

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `backend_download_url` | yes | `string`; pattern `^https://[A-Za-z0-9.-]+/a/ast_[A-Za-z0-9]{8,64}$` |  |
| `alt` | yes | `string`; minimum length `1`; maximum length `180` |  |
| `delivery` | yes | literal `"server_fetch_only"` |  |
| `sha256` | yes | `string`; pattern `^[a-f0-9]{64}$` |  |

### Schema: PresentationContract

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `layout_profile` | yes | literal `"care_card_v1"` |  |
| `block_order` | yes | tuple of literal `"advertising_label"`, literal `"title"`, literal `"summary"`, literal `"price"`, literal `"material_terms"`, literal `"disclosures"`, literal `"cta"`; minimum items `7`; maximum items `7` |  |
| `visible_before_action` | yes | tuple of literal `"advertising_label"`, literal `"title"`, literal `"summary"`, literal `"price.presentation"`, one of `"price.billing_terms.minimum_total"`, `"price.material_terms"`, literal `"disclosures"`, literal `"cta"`; minimum items `7`; maximum items `7` |  |
| `may_truncate` | yes | array of unspecified; maximum items `0` |  |
| `viewport_profile` | yes | literal `"partner_mobile_v1"` |  |
| `digest` | yes | `string`; pattern `^[a-f0-9]{64}$` |  |

### Schema: Price

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| — | — | [FixedTermsPrice](#schema-fixedtermsprice) or [VariablePrice](#schema-variableprice) | No direct properties; follow referenced alternatives. |

### Schema: FixedTermsPrice

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `scope` | yes | literal `"care_program"` |  |
| `currency` | yes | literal `"USD"` |  |
| `presentation` | yes | `string`; minimum length `1`; maximum length `160` |  |
| `components` | yes | [PriceComponents](#schema-pricecomponents) |  |
| `billing_terms` | yes | [BillingTerms](#schema-billingterms) |  |

### Schema: VariablePrice

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `scope` | yes | literal `"care_program"` |  |
| `currency` | yes | literal `"USD"` |  |
| `pricing_model` | yes | literal `"varies_by_treatment_and_term"` |  |
| `presentation` | yes | `string`; minimum length `1`; maximum length `500` |  |
| `observed_monthly_range` | yes | [ObservedMonthlyRange](#schema-observedmonthlyrange) |  |
| `components` | yes | [VariablePriceComponents](#schema-variablepricecomponents) |  |
| `material_terms` | yes | array of `string`; minimum length `1`; maximum length `500`; minimum items `1`; maximum items `12` |  |

### Schema: ObservedMonthlyRange

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `minimum` | yes | `integer`; minimum `0`; maximum `9007199254740991` |  |
| `maximum` | yes | `integer`; minimum `0`; maximum `9007199254740991` |  |
| `observed_at` | yes | `string` |  |
| `source` | yes | literal `"chia_live_offering_catalog"` |  |

### Schema: VariablePriceComponents

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `clinical_evaluation` | yes | literal `"included"` |  |
| `ongoing_care_support` | yes | literal `"included"` |  |
| `membership` | yes | literal `"included"` |  |
| `medication` | yes | literal `"included_if_prescribed"` |  |
| `required_labs` | yes | literal `"disclosed_before_charge_if_required"` |  |
| `shipping` | yes | literal `"disclosed_before_charge"` |  |
| `taxes` | yes | literal `"additional_if_applicable"` |  |

### Schema: PriceComponents

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `clinical_evaluation` | yes | one of `"included"`, `"excluded"` |  |
| `ongoing_care_support` | yes | one of `"included"`, `"excluded"` |  |
| `membership` | yes | one of `"included"`, `"excluded"` |  |
| `medication` | yes | literal `"excluded"` |  |
| `required_labs` | yes | one of `"included"`, `"excluded"` |  |
| `shipping` | yes | one of `"included"`, `"excluded"`, `"disclosed_before_any_applicable_charge"` |  |
| `taxes` | yes | one of `"included"`, `"additional_if_applicable"` |  |

### Schema: BillingTerms

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `first_charge_amount` | yes | `integer`; minimum `0`; maximum `9007199254740991` |  |
| `first_charge_rule` | yes | `string`; minimum length `1`; maximum length `240` |  |
| `recurring_unit_amount` | yes | `integer`; minimum `0`; maximum `9007199254740991` |  |
| `billing_interval` | yes | one of `"day"`, `"week"`, `"month"`, `"year"` |  |
| `billing_interval_count` | yes | `integer`; minimum `1`; maximum `36` |  |
| `next_charge_rule` | yes | `string`; minimum length `1`; maximum length `240` |  |
| `minimum_term_cycles` | yes | `integer`; minimum `1`; maximum `60` |  |
| `minimum_total` | yes | `integer`; minimum `0`; maximum `9007199254740991` |  |
| `renews` | yes | `boolean` |  |
| `renewal_summary` | yes | `string`; minimum length `1`; maximum length `400` |  |
| `cancellation_summary` | yes | `string`; minimum length `1`; maximum length `400` |  |
| `refund_and_ineligibility_summary` | yes | `string`; minimum length `1`; maximum length `400` |  |

### Schema: Availability

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `status` | yes | one of `"available"`, `"unavailable"` |  |
| `reason` | yes | one of `null`, `"temporarily_unavailable"` |  |

### Schema: MarketingAvailability

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `policy` | yes | literal `"partner_local_display_and_share_gate"` |  |
| `display` | yes | [DisplayPolicy](#schema-displaypolicy) |  |
| `context_sharing` | yes | [ContextSharingPolicy](#schema-contextsharingpolicy) |  |
| `audience_profile_version` | yes | `string`; pattern `^aud_[A-Za-z0-9]{8,64}$` |  |
| `valid_until` | yes | `string` |  |

### Schema: DisplayPolicy

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `approved_state_codes` | yes | [StateCodes](#schema-statecodes) |  |
| `accepted_evidence_bases` | yes | array of literal `"partner_account_service_state"`; minimum items `1`; unique items |  |
| `max_evidence_age_seconds` | yes | `integer`; minimum `60`; maximum `31536000` |  |
| `unknown_or_stale_behavior` | yes | one of `"hide"`, `"show_with_chia_eligibility_disclosure"` |  |

### Schema: ContextSharingPolicy

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `approved_state_codes` | yes | [StateCodes](#schema-statecodes) |  |
| `accepted_evidence_bases` | yes | array of literal `"partner_account_service_state"`; minimum items `1`; unique items |  |
| `max_evidence_age_seconds` | yes | `integer`; minimum `60`; maximum `31536000` |  |
| `outside_approved_behavior` | yes | literal `"neutral_url_only"` |  |
| `unknown_or_stale_behavior` | yes | literal `"neutral_url_only"` |  |

### Schema: StateCodes

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| — | — | array of `string`; pattern `^[A-Z]{2}$`; minimum items `1`; maximum items `60`; unique items | No direct properties; follow referenced alternatives. |

### Schema: Parties

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `advertiser` | yes | `string`; minimum length `1`; maximum length `180` |  |
| `service_seller` | yes | `string`; minimum length `1`; maximum length `180` |  |
| `clinical_provider` | yes | `string`; minimum length `1`; maximum length `180` |  |
| `billing_entity` | yes | [BillingEntity](#schema-billingentity) |  |
| `pharmacy_role` | yes | `string`; minimum length `1`; maximum length `320` |  |
| `partner_id` | yes | `string`; pattern `^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$`; minimum length `2`; maximum length `32` |  |
| `partner_display_name` | yes | `string`; pattern `^(?!\s)(?:[^\u0000-\u001F\u007F]*\S)?$`; minimum length `2`; maximum length `80` |  |
| `partner_role` | yes | one of `"paid_publisher"`, `"paid_marketplace_publisher"` |  |

### Schema: BillingEntity

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `name` | yes | `string`; minimum length `1`; maximum length `180` |  |
| `role` | yes | literal `"merchant_of_record"` |  |

### Schema: Regulatory

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `profile` | yes | literal `"care_program_v1"` |  |
| `copy_version` | yes | `string`; pattern `^cpy_[A-Za-z0-9]{8,64}$` |  |
| `effective_at` | yes | `string` |  |
| `valid_until` | yes | `string` |  |

### Schema: Handoff

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `version` | yes | `string`; pattern `^hnd_[A-Za-z0-9]{8,64}$` |  |
| `heading` | yes | `string`; minimum length `1`; maximum length `180` |  |
| `body` | yes | `string`; minimum length `1`; maximum length `1000` |  |
| `recipient` | yes | [HandoffRecipient](#schema-handoffrecipient) |  |
| `data_shared` | yes | tuple of literal `"selected care program"`, `string`; pattern `^[^\r\n]{2,80} referral origin$`; maximum length `96`; minimum items `2`; maximum items `2` |  |
| `purpose` | yes | `string`; minimum length `1`; maximum length `240` |  |
| `compensation_disclosure` | yes | `string`; minimum length `1`; maximum length `320` |  |
| `primary_action_label` | yes | literal `"Share selection and continue"` |  |
| `session_creation_path` | yes | literal `"/v2/handoff-sessions"` |  |
| `secondary_action_label` | yes | literal `"Continue without sharing"` |  |
| `secondary_url` | yes | `string`; pattern `^https://[A-Za-z0-9.-]+/(?:sandbox/start&#124;quiz)$` |  |
| `neutral_only_heading` | yes | `string`; minimum length `1`; maximum length `180` |  |
| `neutral_only_body` | yes | `string`; minimum length `1`; maximum length `500` |  |
| `neutral_only_action_label` | yes | literal `"Continue to Chia"` |  |
| `partner_consumer_health_policy_url` | yes | `string`; pattern `^https://` |  |
| `partner_privacy_rights_url` | yes | `string`; pattern `^https://` |  |
| `chia_recipient_privacy_notice_url` | yes | `string`; pattern `^https://` |  |
| `chia_recipient_rights_url` | yes | `string`; pattern `^https://` |  |
| `effective_at` | yes | `string` |  |
| `valid_until` | yes | `string` |  |

### Schema: HandoffRecipient

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `legal_name` | yes | `string`; minimum length `1`; maximum length `180` |  |
| `privacy_contact` | yes | `string`; minimum length `1`; maximum length `240` |  |

### Schema: SettlementList

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `object` | yes | literal `"list"` |  |
| `data` | yes | array of [SettlementSummary](#schema-settlementsummary); maximum items `25` |  |
| `has_more` | yes | `boolean` |  |
| `next_cursor` | yes | `string` or `null`; pattern `^cur_[A-Za-z0-9_-]{16,252}$` |  |
| `livemode` | yes | `boolean` |  |

### Schema: SettlementSummary

One closed settlement projection. Sandbox rows are synthetic 2.0-compatible fixtures. Every production row is a distinct immutable Finance release: id identifies that release, revision is the Finance-authored statement revision, supersedes_id links a correction to the immediately prior release, and released_at records the release decision. The public object contains no patient, order, payment-level, shipment, program, geography, event, or date-row data.

| Property | Required | Type | Description |
|---|---|---|---|
| `id` | yes | `string`; pattern `^set_[A-Za-z0-9]{8,64}$` |  |
| `object` | yes | literal `"settlement_summary"` |  |
| `revision` | no | `integer`; minimum `1`; maximum `9007199254740991` | Required in production. Finance-authored immutable revision number for this logical statement. |
| `supersedes_id` | no | `string` or `null`; pattern `^set_[A-Za-z0-9]{8,64}$` | Required in production. Null for revision 1; otherwise the prior immutable release id corrected by this revision. |
| `released_at` | no | `string` | Required in production. Finance-authored release timestamp; never inferred from request or processing time. |
| `service_fee` | yes | [ServiceFee](#schema-servicefee) |  |
| `aggregate_activity` | yes | [AggregateActivity](#schema-aggregateactivity) or `null` |  |

### Schema: ServiceFee

Finance-authored statement values only. The API validates and projects this released record; it never calculates fee, due, paid, payable, or paid-at state from live data, configuration, events, or time.

| Property | Required | Type | Description |
|---|---|---|---|
| `statement_id` | yes | `string`; pattern `^fee_[A-Za-z0-9]{8,64}$` |  |
| `period` | yes | [Period](#schema-period) |  |
| `status` | yes | one of `"finalized"`, `"paid"` |  |
| `payer` | yes | [NamedParty](#schema-namedparty) |  |
| `payee` | yes | [NamedParty](#schema-namedparty) |  |
| `fixed_service_fee` | yes | [Money](#schema-money) |  |
| `amount_paid` | yes | [Money](#schema-money) |  |
| `amount_due_to_partner` | yes | [Money](#schema-money) |  |
| `payable_on` | yes | `string` or `null` |  |
| `paid_at` | yes | `string` or `null` |  |
| `terms_version` | yes | `string`; pattern `^terms_[A-Za-z0-9]{8,64}$` |  |
| `as_of` | yes | `string` |  |

### Schema: NamedParty

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `name` | yes | `string`; minimum length `1`; maximum length `180` |  |

### Schema: Money

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `amount` | yes | `integer`; minimum `0`; maximum `9007199254740991` |  |
| `currency` | yes | literal `"USD"` |  |

### Schema: Period

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `start` | yes | `string` |  |
| `end` | yes | `string` |  |
| `timezone` | yes | literal `"UTC"` |  |

### Schema: AggregateActivity

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| — | — | [LegacyAggregateActivity](#schema-legacyaggregateactivity) or [PrivacyThresholdedAggregateActivity](#schema-privacythresholdedaggregateactivity) | No direct properties; follow referenced alternatives. |

### Schema: LegacyAggregateActivity

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `release_id` | yes | `string`; pattern `^act_[A-Za-z0-9]{8,64}$` |  |
| `period` | yes | [Period](#schema-period) |  |
| `aggregate_initial_purchase_count` | yes | `integer`; minimum `1`; maximum `9007199254740991` |  |
| `as_of` | yes | `string` |  |

### Schema: PrivacyThresholdedAggregateActivity

Optional released aggregate only. An internal immutable privacy release must prove both the hard minimum group size of 10 and composition approval before a non-null count is projected; those proof fields remain private. Otherwise the count is null with below_minimum_group_size, or aggregate_activity is null.

| Property | Required | Type | Description |
|---|---|---|---|
| `release_id` | yes | `string`; pattern `^act_[A-Za-z0-9]{8,64}$` |  |
| `period` | yes | [Period](#schema-period) |  |
| `aggregate_initial_purchase_count` | yes | `integer` or `null`; minimum `1`; maximum `9007199254740991` |  |
| `suppression_reason` | yes | one of `null`, `"below_minimum_group_size"` |  |
| `minimum_group_size` | yes | `integer`; minimum `10`; maximum `100` | Finance-released threshold for this aggregate. The Partner API hard floor is 10; a partner-specific approval may require a larger value. |
| `as_of` | yes | `string` |  |

### Schema: ConsentAttestation

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `affirmed` | yes | literal `true` |  |
| `affirmed_at` | yes | `string` |  |

### Schema: HandoffSessionRequest

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `catalog_item_id` | yes | `string`; pattern `^cat_[A-Za-z0-9]{8,64}$` |  |
| `disclosure_version` | yes | `string`; pattern `^hnd_[A-Za-z0-9]{8,64}$` |  |
| `consent_attestation` | yes | [ConsentAttestation](#schema-consentattestation) |  |

### Schema: HandoffSessionResponse

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `object` | yes | literal `"handoff_session"` |  |
| `id` | yes | `string`; pattern `^phs_[A-Za-z0-9]{8,64}$` |  |
| `url` | yes | `string`; pattern `^https://[A-Za-z0-9.-]+/(?:sandbox&#124;production)/handoff/phs_[A-Za-z0-9]{8,64}$` |  |
| `expires_at` | yes | `string` |  |
| `livemode` | yes | `boolean` |  |

### Schema: WebhookTestRequest

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `event_type` | yes | one of `"endpoint.test"`, `"catalog.updated"`, `"settlement_summary.finalized"` |  |

### Schema: WebhookTestResponse

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `id` | yes | `string`; pattern `^evt_test_[A-Za-z0-9]{8,64}$` |  |
| `object` | yes | literal `"webhook_test"` |  |
| `event_type` | yes | one of `"endpoint.test"`, `"catalog.updated"`, `"settlement_summary.finalized"` |  |
| `destination_hint` | yes | `string`; pattern `^https://[A-Za-z0-9.-]+/\*\*\*$`; maximum length `240` |  |
| `created_at` | yes | `string` |  |
| `livemode` | yes | `boolean` |  |
| `test` | yes | literal `true` |  |

### Schema: WebhookHeaders

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `Chia-Webhook-Id` | yes | `string`; pattern `^evt_test_[A-Za-z0-9]{8,64}$` |  |
| `Chia-Webhook-Timestamp` | yes | `string`; pattern `^[0-9]{10}$` |  |
| `Chia-Webhook-Signature` | yes | `string`; pattern `^v1=[a-f0-9]{64}$` |  |
| `Chia-Webhook-Type` | yes | one of `"endpoint.test"`, `"catalog.updated"`, `"settlement_summary.finalized"` |  |
| `Chia-Version` | yes | literal `"2026-07-22"` |  |

### Schema: EmptyData

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| — | — | `object` | No direct properties; follow referenced alternatives. |

### Schema: CatalogUpdatedData

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `catalog_version` | yes | `string`; pattern `^cav_test_[A-Za-z0-9]{8,64}$` |  |
| `required_action` | yes | literal `"invalidate_and_refetch"` |  |
| `effective_at` | yes | `string` |  |

### Schema: SettlementSummaryFinalizedData

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `summary_id` | yes | `string`; pattern `^set_test_[A-Za-z0-9]{8,64}$` |  |
| `period` | yes | [Period](#schema-period) |  |

### Schema: Period

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `start` | yes | `string` |  |
| `end` | yes | `string` |  |
| `timezone` | yes | literal `"UTC"` |  |

### Schema: EndpointTestEvent

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `id` | yes | `string`; pattern `^evt_test_[A-Za-z0-9]{8,64}$` |  |
| `object` | yes | literal `"event"` |  |
| `type` | yes | literal `"endpoint.test"` |  |
| `api_version` | yes | literal `"2026-07-22"` |  |
| `created_at` | yes | `string` |  |
| `livemode` | yes | `boolean` |  |
| `test` | yes | literal `true` |  |
| `data` | yes | [EmptyData](#schema-emptydata) |  |

### Schema: CatalogUpdatedEvent

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `id` | yes | `string`; pattern `^evt_test_[A-Za-z0-9]{8,64}$` |  |
| `object` | yes | literal `"event"` |  |
| `type` | yes | literal `"catalog.updated"` |  |
| `api_version` | yes | literal `"2026-07-22"` |  |
| `created_at` | yes | `string` |  |
| `livemode` | yes | `boolean` |  |
| `test` | yes | literal `true` |  |
| `data` | yes | [CatalogUpdatedData](#schema-catalogupdateddata) |  |

### Schema: SettlementSummaryFinalizedEvent

Contract-defined object.

| Property | Required | Type | Description |
|---|---|---|---|
| `id` | yes | `string`; pattern `^evt_test_[A-Za-z0-9]{8,64}$` |  |
| `object` | yes | literal `"event"` |  |
| `type` | yes | literal `"settlement_summary.finalized"` |  |
| `api_version` | yes | literal `"2026-07-22"` |  |
| `created_at` | yes | `string` |  |
| `livemode` | yes | `boolean` |  |
| `test` | yes | literal `true` |  |
| `data` | yes | [SettlementSummaryFinalizedData](#schema-settlementsummaryfinalizeddata) |  |

## Error envelope and support

All JSON errors use `ErrorResponse`. Retry only when `error.retryable` is true and the operation is safe/idempotent; obey a bounded `Retry-After`. Do not retry authentication, permission, validation, idempotency-conflict, or asset-integrity failures.

For support, send UTC time, environment, operation, HTTP status, safe error code, and a validated `Chia-Request-Id` when present. Never send a credential, raw webhook, body, asset URL, handoff URL, user state, or patient/consumer information.