Skip to main content
PATCH
Amend

Authorizations

Authorization
string
header
required

API key authentication

Path Parameters

id
string
required

Body

application/json
autoCharge
boolean | null

Enable automatic charging of invoices using stored payment methods. When true, invoices will be automatically paid using off-session payment. Defaults to false.

taxExempt
boolean | null

When true, forces tax rate to 0%. Use for customers with verified tax-exempt status.

customerId
string

Unique identifier for a customer

Pattern: ^cus_[a-zA-Z0-9]+$
endingAt
string<date-time> | null

Subscription expiration timestamp in ISO 8601 format. Sample values: '2024-12-31T23:59:59Z', '2025-01-15T10:30:00Z'. Omit for indefinite subscriptions. Must be after startedAt: a value at or before it is rejected with 400.

name
string

Subscription identifier combining customer and service details. Sample values: 'TechCorp - LLM API Access', 'Analytics Co - Data Platform Enterprise', 'StartupXYZ - Image Generation Service', 'Enterprise Inc - ML Training Platform'

planId
string

Unique identifier for a plan

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

Deprecated. This field is ignored and has no effect.

minimumAccountBalance
string | null
deprecated

Deprecated. This field is ignored and has no effect.

redirectUrls
UpdateSubscriptionProposalRedirectUrls · object | null

Optional redirect URLs after payment completion or failure. If not provided, uses default platform behavior.

startedAt
string<date-time>

Subscription activation timestamp in ISO 8601 format. Sample values: '2024-01-15T10:30:00Z', '2024-02-01T00:00:00Z'

elapsedPeriodBilling
enum<string>

Whether a backdated start bills its elapsed periods. A start is backdated when startedAt is more than 24 hours before the subscription is created. none bills only charges that fall due from the moment of creation, for a customer whose earlier periods another system already billed. per_period bills every charge that fell due from startedAt, on one first invoice; it refuses a startedAt more than 12 months back, with the code PER_PERIOD_LOOKBACK_EXCEEDED. Has no effect on a start that is not backdated. Defaults to none.

Available options:
none,
per_period
billingAnchor
string<date-time> | null

A billing anchor for this subscription, in place of the plan's. Any instant, past or future. The subscription's billing anchor is its first recurrence on or after startedAt, stepping back or forward by whole billing cadences. Example: on a monthly plan, an anchor of '2027-01-31T00:00:00Z' with a start of '2026-10-10T00:00:00Z' gives '2026-10-31T00:00:00Z'. A create is refused with 400 when the resolved anchor does not line up with the usage period anchor of a feature that credits unused balance. Omit it to use the plan's billing anchor. A repeated create that names an anchor resolving to a different instant than the existing subscription's gets 409.

testClockId
string | null

Test clock identifier for simulating time-based billing scenarios. Sample values: 'tc_abc123xyz', 'tc_789def456'. Restricted to non-production environments (local, dev, sandbox). Must belong to the same merchant organization.

renewalReminderEnabled
boolean | null

Override plan setting for renewal reminder emails. When set, this subscription's setting takes precedence over the plan default. Set to true to enable reminders, false to disable, or null/omit to use plan default.

renewalReminderDays
integer | null

Override plan setting for number of days before renewal to send the reminder. Only used if renewalReminderEnabled is true (or inherited from plan). Set to null to use plan default.

Required range: 1 <= x <= 30
paymentTermDays
integer | null

Payment term in days ("Net X") applied to every invoice the subscription generates: invoice dueAt = invoice issue date + paymentTermDays. Defaults to 0 ("due on issue"). A non-zero value needs metadata.bankTransferOnly: true; without it the request answers 400 PAYMENT_TERM_DAYS_REQUIRES_BANK_TRANSFER_ONLY.

Required range: 0 <= x <= 365
sessionExpiryMinutes
number | null

Number of minutes until the payment session expires. Defaults to 240 minutes (4 hours) if not provided.

Required range: x >= 1
versionPolicy
enum<string>

How the subscription follows new versions of its plan. floating follows the plan's default version: when the default changes, the subscription bills from the new default from its next billing period. pinned keeps the plan version that the subscription holds. A subscription created without a value is floating. A change to this value does not change a billing period that has already started.

Available options:
floating,
pinned
metadata
object

Free-form merchant metadata to attach to the subscription. Values must be strings, numbers, or booleans.

changeReason
enum<string>

Why a change was made. correction repairs data that was entered wrong; migration moves a contract from another system; commercial is a real change to the deal; contractual applies a step the original contract scheduled, such as an annual uplift. Defaults to unspecified.

Available options:
commercial,
correction,
migration,
unspecified,
contractual
changeDescription
string | null

A free-text note on why these intervals are changing.

Maximum string length: 1000
changeMetadata
object

Your own key-value data about the change, such as a CRM deal ID.

addPrices
object[] | null

Catalog prices to bill on this subscription that its plan version does not carry. Each must be owned by the same merchant and use the standard price model.

Maximum array length: 25
overridePrices
object[] | null

Rate or quantity overrides for prices the plan version does carry.

Maximum array length: 25
removePrices
object[] | null

Plan prices this subscription does not bill.

Maximum array length: 25
planVersionId
string | null

A published version of planId to pin the proposal to. Only a pinned proposal (versionPolicy: "pinned") names a version. One that names none, or null, pins the plan's default version, as a change of planId without a version does. A floating proposal follows the plan's default version, and one that names a version is refused with 400.

adjustments
object[] | null

Adjustments the subscription gets when the proposal is approved. Each is checked as subscription adjustment create checks it, against the prices the proposal bills and the other adjustments in this list.

Maximum array length: 25

One adjustment to attach to the subscription. The type decides which number the body carries: a rate for percentageDiscount, a unit count and one target price for usageDiscount, and a contracted quantity and one target price for minimumQuantity and maximumQuantity.

basedOnHash
string

The proposal's hash as the person read it. When sent and the proposal has changed since, the amend is refused with 409 SUBSCRIPTION_PROPOSAL_CHANGED and nothing is written: read the proposal again and amend what it holds now. Leave it out to amend whatever the proposal holds.

Pattern: ^[0-9a-f]{64}$

Response

Subscription proposal amended

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.