Skip to main content
PATCH
Update a subscription

Authorizations

x-api-key
string
header
required

API key for authentication (required)

x-merchant-id
string
header
required

Merchant ID for identifying the merchant (required)

Path Parameters

id
string<uuid>
required

Subscription unique identifier

Body

application/json

At least one field must be provided for update

paymentMethodId
string<uuid>

New payment method ID for billing

Example:

"123e4567-e89b-12d3-a456-426614174003"

cancelAtPeriodEnd
boolean

Whether to cancel at the end of the current billing period

Example:

true

metadata
object | null

Additional metadata for the subscription

Response

Subscription updated successfully

id
string<uuid>
required

Unique subscription identifier

Example:

"123e4567-e89b-12d3-a456-426614174000"

merchantId
string
required

Merchant identifier

Example:

"merchant_123"

customerId
string<uuid>
required

Customer identifier

Example:

"123e4567-e89b-12d3-a456-426614174001"

planId
string<uuid>
required

Plan identifier

Example:

"123e4567-e89b-12d3-a456-426614174002"

paymentMethodId
string<uuid>
required

Payment method identifier

Example:

"123e4567-e89b-12d3-a456-426614174003"

status
enum<string>
required

Subscription status

Available options:
TRIALING,
ACTIVE,
PAST_DUE,
CANCELED,
UNPAID
Example:

"ACTIVE"

currentPeriodStart
string<date-time>
required

Start of the current billing period

Example:

"2025-01-01T00:00:00.000Z"

currentPeriodEnd
string<date-time>
required

End of the current billing period

Example:

"2025-02-01T00:00:00.000Z"

cancelAtPeriodEnd
boolean
required

Whether the subscription will cancel at period end

Example:

false

nextBillingDate
string<date-time>
required

Date of the next billing charge (trial end date while trialing, otherwise the current period end date)

Example:

"2025-02-01T00:00:00.000Z"

createdAt
string<date-time>
required

Creation timestamp

Example:

"2025-01-01T00:00:00.000Z"

updatedAt
string<date-time>
required

Last update timestamp

Example:

"2025-01-15T10:00:00.000Z"

trialStart
string<date-time> | null

Trial period start date

Example:

"2025-01-01T00:00:00.000Z"

trialEnd
string<date-time> | null

Trial period end date

Example:

"2025-01-15T00:00:00.000Z"

canceledAt
string<date-time> | null

When the subscription was canceled

Example:

null

endedAt
string<date-time> | null

When the subscription ended

Example:

null

metadata
object | null

Additional metadata

plan
object

Associated plan details