Versions, compatibility, and changelog

Use the exact release named in the signed onboarding and activation receipt, not a mutable “latest” assumption.

Current public line#

The exact 2.1.0 contracts live below /contracts/v2.1.0/. /contracts/v2/ and the root contract URLs are convenience aliases and must not replace the exact URLs and digests in the signed onboarding receipt. Immutable legacy /contracts/v1.0.0/ and /contracts/v2.0.0/ URLs remain permanent for previously issued receipts, but new partner integrations use 2.1.0.

Four version signals#

1. The path major (/v2) identifies the resource family. A new major is required when an integration cannot preserve the existing resource, authorization, privacy, or processing model.
2. Chia-Version identifies credential-pinned behavior. The API response, webhook header, and signed webhook envelope must agree with the version supported by the installed SDK. Stop and escalate on a mismatch.
3. The contract release is semantic-versioned and immutable. A published exact-release URL never changes bytes. A newer release is a new artifact even when its wire behavior is unchanged.
4. The SDK has its own semantic version, but each SDK release declares the exact API behavior and contract digests it supports. Upgrading the package does not migrate a credential or activate a new behavior version.

Do not infer compatibility from dates or version numbers alone. Verify the signed release manifest, exact contract digests, SDK metadata, and this changelog.

Compatibility rules#

Schemas and event envelopes are closed. An unknown response field, enum member, webhook type, status, or required header can fail a conforming strict client, so it is not treated as harmless merely because it is additive.

The following may ship without a new behavior version only when canonical contract bytes and observable protocol semantics remain unchanged:

• clearer prose, navigation, or synthetic examples that do not change a requirement;
• corrections that make generated reference material match the already canonical contract;
• SDK or documentation fixes that accept and produce exactly the same wire values; and
• reliability or infrastructure work that does not change status codes, headers, schemas, timing semantics, pagination, authentication, or webhook verification.

The following require a new credential-pinned behavior version, immutable contracts, SDK compatibility declaration, migration notes, and opt-in sandbox certification before production use:

• any field, requiredness, type, bound, pattern, enum, status code, error code, header, cache rule, or pagination change;
• any signature input, freshness window, delivery, retry, deduplication, or ordering change;
• any semantic change to an existing field, event, operation, asset, or handoff rule; or
• any changed environment, credential, scope, origin, or security requirement.

Removing or renaming a resource, changing the authorization or merchant/provider boundary, or exposing individual patient, order, payment, prescription, shipment, or outcome data requires a separately reviewed major version. It cannot be introduced as a compatible /v2 update.

Existing credentials are never silently moved to a new behavior version. Chia must provision or explicitly migrate the credential through the approved onboarding process; the partner must verify the release in sandbox before any production migration.

Lifecycle and sunset policy#

Before a release can become supported, its signed onboarding receipt must name the behavior version and either a support end date or “no sunset scheduled.” If that evidence is absent, treat the release as unsupported rather than indefinitely supported.

For a supported, non-emergency behavior, Chia will publish the replacement and migration guide, notify the partner's registered integration contact, and provide at least 12 months between deprecation notice and sunset. A signed commercial or partner agreement may require a longer period and controls when it does. Deprecated versions receive critical security, privacy, legal, patient-safety, and severe reliability fixes, but no new features.

An urgent security, privacy, legal, or patient-safety issue may require a shorter window. Chia must give direct notice as soon as practicable, state the reason without exposing sensitive details, provide the safest available migration or containment path, and preserve patient continuity. No policy requires Chia to keep an unsafe behavior active.

Notices are published in this changelog and delivered through the registered integration channel. Do not depend on an HTTP Deprecation or Sunset header unless that header appears in the exact versioned contract used by the credential.

Upgrade procedure#

1. Obtain the new signed onboarding release through the approved channel and verify its issuer, identity, archive checksum, contract digests, and SDK digest.
2. Read the release's changelog and migration notes. Do not generate a diff from mutable aliases.
3. Upgrade in an isolated branch and run contract, SDK, reference-backend, and receiver tests.
4. Certify catalog, assets, pagination, all three signed webhook shapes, duplicate handling, and role isolation against sandbox.
5. Repeat the complete production catalog, handoff, finance, and all-three-webhook-test certification with isolated production credentials.
6. Move traffic only after the signed Chia activation identifies the exact behavior, SDK, contracts, credentials, endpoint, signing-secret configuration, catalog, and rollback owner.

Rollback means restoring the last still-supported, credential-compatible release and its exact configuration. Do not point an old SDK at a newly migrated credential or reuse credentials across environments.

Public changelog#

2026-07-23 — Partner API contract release 2.1.0#

• Activated the previously reserved production finance surface for append-only immutable statement revisions. Each production row now carries a Finance-authored revision, supersedes_id, and released_at; corrections append and point directly to the immediately prior release.
• Kept the API isolated from live purchase activity. Amount due, paid state, timestamps, and optional aggregate values come only from a separately approved Finance release record and are never inferred from configuration, events, or time.
• Added strict privacy-thresholded production aggregates. Counts remain nullable, have a hard minimum group-size floor of 10, and are exposed only after internal immutable threshold and composition release proofs pass; those proof fields are not public.
• Published immutable OpenAPI, AsyncAPI, asset-contract, integration-manifest, and TypeScript SDK 2.1.0 artifacts. The credential-pinned behavior remains 2026-07-22.
• Preserved every 1.0.0 and 2.0.0 release byte and permanent legacy URL unchanged. This documentation entry does not activate or migrate any credential.

2026-07-22 — Partner API contract release 2.0.0#

• Generalized the contract from a single launch partner into the reusable Chia Partner API. Partner identity and presentation now use the closed, tenant-bound partner_id, partner_display_name, and partner_role fields plus partner-specific consumer-health and privacy-rights policy URLs. The opaque partner_id is 2–32 characters matching ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$ and is never used to derive infrastructure.
• Moved all JSON operations to /v2 and published new immutable OpenAPI, AsyncAPI, asset-contract, integration-manifest, and TypeScript SDK 2.0.0 artifacts. The credential-pinned behavior is 2026-07-22.
• Preserved the merchant/provider/privacy boundary: Chia remains merchant of record; partners receive catalog, consent-gated co-branded handoff, synthetic webhook tests, and isolated aggregate finance connectivity only—never patient, order, payment, prescription, shipment, fulfillment, or outcome data.
• Existing 1.0.0 release bytes and permanent URLs remain unchanged. Credentials are not silently migrated; every partner receives distinct sandbox and production credentials and certifies 2.0.0 before activation.

2026-07-21 — Documentation lifecycle policy#

• Published explicit version axes, closed-schema compatibility rules, lifecycle states, notice mechanics, and upgrade/rollback procedure.
• Promoted 1.0.0 to the live production contract for production catalog, identity-free co-branded handoff, all-three-event webhook tests, and an isolated finance endpoint that remains empty until an approved append-only Finance release exists.
• Runtime readiness is evidenced by the signed activation receipt, exact issued credentials/origins, and acceptance-test record—not by documentation publication alone.
• This documentation entry does not activate or migrate any credential. Exact wire behavior remains the behavior and immutable artifact digests named by the signed onboarding release.

2026-07-16 — Contract release 1.0.0#

• Created the initial /v1 contract release and server-only TypeScript SDK for catalog publication, authenticated assets, consent-gated 15-minute browser handoff, signed synthetic webhook tests, sandbox finance fixtures, and the production finance connectivity page.
• Pinned behavior to 2026-07-16; the launch revision adds the live production catalog/handoff contract and distinct production runtime and finance roles. Production finance is empty until a separately approved append-only statement release exists.

See Onboarding for release verification and Go-live for the activation evidence required in each environment.