Skip to main content
POST
Approve or reject

Authorizations

Authorization
string
header
required

API key authentication

Path Parameters

id
string
required

The subscription proposal ID

Body

application/json

A decision on a pending proposal, and the hash of the proposal the person decided on. To reject, send reason, and text when the reason is other. An approval sends neither.

decision
enum<string>
required

approve creates the subscription and makes the proposal approved. reject rejects the proposal. Either is final: the proposal never becomes pending again.

Available options:
approve,
reject
basedOnHash
string
required

The proposal's hash as the person read it. When the proposal has changed since, the decision is refused with 409 SUBSCRIPTION_PROPOSAL_CHANGED: read the proposal again and decide on what it holds now.

Pattern: ^[0-9a-f]{64}$
reason
enum<string>

Why a person rejected the proposal. price_mismatch: a price or discount is not the one agreed. wrong_plan: the proposal names the wrong plan. wrong_start_date: the start date is wrong. wrong_customer: the proposal names the wrong customer. duplicate: the customer already has this subscription, or another proposal holds it. other: another reason, explained in text.

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

Notes on the rejection, at most 2000 characters. Required when reason is other. Whitespace around it is trimmed, and a blank value is stored as null. An approval refuses it.

Maximum string length: 2000

Response

The decided 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.