Update Subscription

PATCH

/api/:account_id/subscriptions/:subscription_id

Update subscription-level fields.

Updates subscription metadata and settings. Some fields trigger Restate lifecycle re-evaluation:

cancel_at_period_end: Changes next action (STOP vs SCHEDULE_BILLING)
trial_end/trial_period_days: Changes SCHEDULE_ACTIVATION timing

Fields that do NOT trigger lifecycle re-evaluation:

description: Just metadata
default_payment_method_id: Affects payment collection, not scheduling
coupon_id/promotion_code: Only affects invoice amounts

Note: To update subscription items (prices, quantities), use the separate PATCH /{subscription_id}/items endpoint which handles proration.

Works for both User and API Key authentication. Account access is automatically validated via endpoint dependency.

Update subscription-level fields. Updates subscription metadata and settings. Some fields trigger Restate lifecycle re-evaluation: - **cancel_at_period_end**: Changes next action (STOP vs SCHEDULE_BILLING) - **trial_end/trial_period_days**: Changes SCHEDULE_ACTIVATION timing Fields that do NOT trigger lifecycle re-evaluation: - **description**: Just metadata - **default_payment_method_id**: Affects payment collection, not scheduling - **coupon_id/promotion_code**: Only affects invoice amounts Note: To update subscription items (prices, quantities), use the separate PATCH /{subscription_id}/items endpoint which handles proration. Works for both User and API Key authentication. Account access is automatically validated via endpoint dependency.

Authentication

AuthorizationBearer

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

Path parameters

subscription_idstringRequired

account_idstringRequired

Request

This endpoint expects an object.

descriptionstring or nullOptional

default_payment_method_idstring or nullOptional

statement_descriptor_suffixstring or nullOptional

cancel_at_period_endboolean or nullOptional

trial_enddatetime or nullOptional

trial_period_daysinteger or nullOptional>=1

coupon_idstring or nullOptional

promotion_codestring or nullOptional

custom_fieldsmap from strings to any or nullOptional

Custom field values to set on this subscription. Keys must match defined field keys for the subscription entity type. Set a key to null to delete that field's value.

collection_methodenum or nullOptional

Collection method for invoices (charge_automatically or send_invoice)

net_dinteger or nullOptional>=0

Payment terms in days (Net X). 0 means due immediately.

show_payment_linkboolean or nullOptional

When true, invoices generated for this subscription will include the 'Pay online' link on the PDF and email.

metadatamap from strings to any or nullOptional

Replaces existing metadata entirely. Use empty dict to clear.

Response

Successful Response

subscription_idstring

updated_fieldslist of strings

lifecycle_triggeredbooleanOptionalDefaults to false

voided_invoice_idslist of stringsOptional

Errors

409

Conflict Error

422

Unprocessable Entity Error

$	curl -X PATCH https://app.paymentkit.com/api/account_id/subscriptions/subscription_id \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{}'

1	{
2	"subscription_id": "string",
3	"updated_fields": [
4	"string"
5	],
6	"lifecycle_triggered": false,
7	"voided_invoice_ids": [
8	"string"
9	]
10	}