Skip to main content
GET
Get

Authorizations

Authorization
string
header
required

API key authentication

Path Parameters

id
string
required

Query Parameters

expand
enum<string>

revisions adds the proposal's revisions.

Available options:
revisions

Response

Subscription proposal

A subscription a client proposed, held until a person approves or rejects it. No subscription exists until it is approved.

id
string
required
object
enum<string>
required
Available options:
subscriptionProposal
merchantId
string
required

Unique identifier for an organization

Pattern: ^org_[a-zA-Z0-9]+$
status
enum<string>
required

pending until a person approves or rejects the proposal.

Available options:
pending,
approved,
rejected
customerId
string
required

Unique identifier for a customer

Pattern: ^cus_[a-zA-Z0-9]+$
planId
string
required

Unique identifier for a plan

Pattern: ^plan_[a-zA-Z0-9]+$
planVersionId
string | null
required

The plan version a pinned proposal is pinned to. Null for a floating proposal, which follows the plan's default version.

resolvedPlanVersionId
string | null
required

The plan version approve would use now: planVersionId when pinned, else the plan's default version. Null when the plan has no published version.

hash
string
required

Changes whenever current or resolvedPlanVersionId changes. A decision sends it as basedOnHash, so a person only decides on the proposal they read.

testClockId
string | null
required
requested
object
required

The values as the client last sent them, without externalReference.

current
object
required

The values as they are now, amendments included, with planVersionId when the proposal is pinned. Approve creates the subscription from them.

amendedFields
string[]
required

The top-level fields a person amended. A re-send of the external reference keeps the person's value for each; a field stays amended when the client sends the person's value.

refusedResync
object | null
required

The CRM's latest refused re-sync, or null. It changes hash, so a decision made before it arrived answers 409 SUBSCRIPTION_PROPOSAL_CHANGED.

lockVersion
integer
required

Starts at 1, and every change to the proposal adds one.

source
string
required

The provider of the proposal's external reference, or api when it has none.

externalReference
object | null
required

The record the proposal comes from. Null when it was created without one.

subscriptionId
string | null
required

The subscription approve created.

rejectionReason
enum<string> | null
required

Why the proposal was rejected. Null unless it is rejected.

Available options:
price_mismatch,
wrong_plan,
wrong_start_date,
wrong_customer,
duplicate,
other
rejectionText
string | null
required

The notes the reviewer gave with the rejection.

decidedAt
string<date-time> | null
required
decidedByPrincipalId
string | null
required
decidedBy
object | null
required

Who approved or rejected the proposal, by name. Null until it is decided, and when the decider cannot be named: a decision made with the platform key, or by a principal that no longer exists.

strandedAt
string<date-time> | null
required

Set when an approve ended with its subscription waiting for its first invoice; a repeated approve resumes it.

createdByPrincipalId
string | null
required
createdByCredentialId
string | null
required

The API key or OAuth client that created the proposal; null for a dashboard session.

createdAt
string<date-time>
required
updatedAt
string<date-time>
required
revisions
object[]

Each set of values the client sent, earliest first. Present only with expand=revisions. The last one is requested.