Skip to content

API Versions

The B2B Receivables API uses a header-based, namespaced version identifier. Partner integrations pin to a specific contract; breaking changes ship as a new major version that partners opt into explicitly.

Pinning a Version

Every B2B Receivables API request must include the Pyng-Api-Version header. The header value is a Pyng-controlled URN that names a major contract version.

Pyng-Api-Version: urn:pyng:api:billing:version:v1

Requests that omit the header receive 400 Bad Request with the error code urn:pyng:platform:billing:error:version:missing. Pyng does not maintain an unversioned default contract.

Supported Versions

Version Status Released Sunset
urn:pyng:api:billing:version:v1 Current 2026-05-04 —

Change Policy

A new major version (v2, v3, …) is minted when a breaking change is required. Breaking changes include:

  • Removed or renamed request or response fields
  • Changed semantics of an existing field
  • Changed required-ness of a field
  • Renamed enum values
  • Changed HTTP status codes for an existing scenario
  • Changed authentication or authorisation rules

Non-breaking additions do not bump the version. Partners on the current version receive these transparently:

  • New optional response fields
  • New optional request fields
  • New endpoints
  • New enum values that fall back to existing handling on older clients

Deprecation

When a version is deprecated:

  1. The version's row in the Supported Versions table is updated to Deprecated status with a sunset date.
  2. Responses to requests pinned to the deprecated version include the Deprecation and Sunset response headers, per RFC 8594 and RFC 9745.
Deprecation: true
Sunset: Sat, 04 May 2027 00:00:00 GMT
  1. The minimum window from announcement to sunset is 12 months.

After the sunset date, requests pinned to a sunset version receive 410 Gone with error code urn:pyng:platform:billing:error:version:gone. Partners must migrate to a current version before the sunset date.