Skip to main content
POST
Change a policy's offering
This endpoint is in beta: its request and response contract can still change while it’s being developed.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

idempotency-key
string
required

Unique per change you mean to make; send the same key on a retry to get the first answer back.

Required string length: 1 - 100

Path Parameters

policyId
string
required
Pattern: ^[a-fA-F0-9]{24}$

Body

application/json
toOfferingId
string
required

The offering in the policy's scheme to move onto.

timing
enum<string>
required

NOW applies straight away once anything due is paid; AT_RENEWAL at the renewal on or after notBefore.

Available options:
NOW,
AT_RENEWAL
notBefore
string<date-time>

For AT_RENEWAL only: the first renewal on or after this. The next renewal when absent.

releaseSeatIds
string[]

Secondary seats to end when the change takes effect, so the rest fit the target plan. Never the primary seat.

returnUrl
string

Member tokens only: where our payment page sends the member once they have paid, failed to or run out of time, with policyChangeId and outcome (paid, failed or expired) added to its query. It must be on the origin of one of your app's redirect URIs, or use the same custom scheme and host.

Response

Default Response

policyChangeId
string
required
state
enum<string>
required

ACCEPTED: it takes effect at effectiveAt, paid for when anything was due. AWAITING_PAYMENT: only once payment is made.

Available options:
ACCEPTED,
AWAITING_PAYMENT
effectiveAt
string<date-time>
required
payment
MembershipOfferingChangePayment · object | null
required

Null when nothing is due: always for an organizer key.