Update a Subscription's Payment Method

POST

subscription

{id}

payment-method

curl -X POST https://api.therius.io/v1/subscription/sub_abc123def456/payment-method \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantCode": "MERCHANT_001",
    "card": { "tokenData": { "token": "vt_9f2c..." } }
  }'

curl -X POST https://api.therius.io/v1/subscription/sub_abc123def456/payment-method \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantCode": "MERCHANT_001",
    "card": { "nonceData": { "nonce": "<fresh nonce from JS SDK>" } }
  }'

{}

POST /subscription/{id}/payment-method replaces the card on a subscription and its stored-credential mandate, so every future renewal (a Merchant Initiated Transaction, MIT) cites the right networkTransactionId / networkReferenceId. Changing the card on a subscription is always a Cardholder Initiated Transaction (CIT), and a CIT may require 3D Secure. There are two ways to supply the new card:

Record mode — card.tokenData

The token is a card that already completed a CIT elsewhere. You run the CIT (with 3DS if the issuer asks) through /payment/authorization or /payment/purchase, then attach the resulting token here. No gateway call, no 3DS on this endpoint. Use this for any card that needs 3D Secure.

CIT mode — card.nonceData / card.cardData

Runs a zero-value CIT here to validate the card and establish a fresh mandate, and can reactivate a suspended subscription. This CIT cannot carry out a 3D Secure challenge — a card that requires 3DS will fail.

Either mode resets the scheme retry sequence and fires subscription.payment_method_updated.

Record mode (recommended)

Because this endpoint’s own CIT can’t do a 3DS challenge, the reliable way to change a card is to run the CIT yourself where 3DS is supported, then record it:

Run a 3DS-capable CIT

Call /payment/authorization (a zero-value or small auth) or /payment/purchase with card.nonceData.tokenize: true (or card.cardData.tokenize: true) and a shopper.id. Handle any actionRequired / 3DS challenge with the JS SDK exactly as you would for a normal payment. On success the response returns a vault token and card.networkTransactionId / card.networkReferenceId.

Attach the token to the subscription

POST /subscription/{id}/payment-method with card.tokenData.token set to that vault token. Therius reads the mandate the token stored at its CIT — you don’t need to pass networkTransactionId yourself. (Pass it explicitly only when the card was CIT’d outside Therius.)

Record mode cannot reactivate a suspended subscription — it runs no charge to confirm the new card works. For a suspended subscription, use CIT mode (below), or run a recovery charge yourself first.

Provide exactly one card instrument — see the parameters panel above for the full field list (tokenData.token for record mode; nonceData/cardData for CIT mode; optional networkTransactionId/networkReferenceId for a card CIT’d outside Therius).

Response

Returns 200 OK with the updated subscription object.

Webhook events fired

Event	When
`subscription.payment_method_updated`	Always, on success. Payload carries `mode: "record"` for record mode.
`subscription.reactivated`	CIT mode only — additionally fired when the subscription was `suspended` and the new CIT + recovery charge succeeded.

Errors

Code	Meaning
`400`	Card missing; record mode on a `suspended` subscription; the token carries no CIT mandate and no `networkTransactionId` was passed; or the subscription is `cancelled`.
`402`	CIT mode — the card authorization was declined.
`404`	Subscription not found.
`422`	No/invalid card instrument, or an expired/used nonce.

curl -X POST https://api.therius.io/v1/subscription/sub_abc123def456/payment-method \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantCode": "MERCHANT_001",
    "card": { "tokenData": { "token": "vt_9f2c..." } }
  }'

curl -X POST https://api.therius.io/v1/subscription/sub_abc123def456/payment-method \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantCode": "MERCHANT_001",
    "card": { "nonceData": { "nonce": "<fresh nonce from JS SDK>" } }
  }'

{}

Authorizations

Authorization

string

header

required

Your secret API key: Bearer prv_production_xxx (production) or Bearer prv_sandbox_xxx (sandbox).

Path Parameters

string

required

Body

application/json

merchantCode

string

required

Your merchant account identifier.

card

Raw card (PCI DSS) · object

required

Card input for replacing the card on a subscription. Changing the card is always a CIT and a CIT may require 3D Secure — pick the mode that fits:

• Record mode (tokenData): the token is a card that already completed a CIT elsewhere. Run your own 3DS-capable CIT via /payment/authorization or /payment/purchase (with card.<x>.tokenize: true + shopper.id), then attach the resulting vt_... token here. No gateway call, no 3DS. The mandate is read from the token; pass networkTransactionId / networkReferenceId explicitly only for a card CIT'd outside Therius. Cannot reactivate a suspended subscription.

• CIT mode (nonceData / cardData): runs a zero-value CIT here and can reactivate a suspended subscription — but this CIT cannot carry out a 3D Secure challenge, so a card that requires 3DS will fail. Use record mode for those.

Provide exactly ONE of cardData, nonceData, or tokenData.

Raw card (PCI DSS)
SDK nonce
Vault token

Show child attributes

Response

200 - application/json

Payment method updated

A customer enrollment in a plan. plan is embedded on single-subscription responses. Invoice/event history is not included here - use the invoice endpoints.

string

Subscription UUID.

merchantId

integer

The merchant account that owns the subscription.

planId

integer

ID of the plan this subscription is enrolled in.

customerEmail

string

Subscriber email, used for billing and dunning notifications.

customerName

string

Subscriber name as it appears on invoices.

customerDocument

string

Subscriber national ID / tax document, where a market requires it (e.g. Brazil CPF/CNPJ).

cardBrand

string

Brand of the card on the mandate, e.g. visa.

status

enum<string>

pending - awaiting first charge; trialing - in a free trial; active - billing normally; past_due - a renewal failed and dunning is running; suspended - dunning exhausted, needs a new CIT (POST /subscription/{id}/payment-method in CIT mode) to recover; paused - billing stopped on request, resumable; cancelled - terminated; completed - reached maxBillingCycles.

Available options:

pending,

trialing,

active,

past_due,

suspended,

paused,

cancelled,

completed

currentPeriodStart

string<date-time>

Start of the current billing period.

currentPeriodEnd

string<date-time>

End of the current billing period.

nextBillingDate

string<date-time>

When the next renewal charge is scheduled.

trialStart

string<date-time>

Trial start, when the plan has a trial.

trialEnd

string<date-time>

Trial end - the first real charge date.

dunningAttemptCount

integer

Failed-renewal retry attempts made in the current dunning sequence.

activatedAt

string<date-time>

When the subscription first became active.

cancelledAt

string<date-time>

pausedAt

string<date-time>

suspendedAt

string<date-time>

startAt

string<date-time>

Deferred start, when creation set a future startAt.

cyclesCompleted

integer

Number of billing cycles charged so far.

completedAt

string<date-time>

When the subscription reached maxBillingCycles.

parentSubscriptionId

string

Parent subscription UUID, for add-on hierarchies.

propagateLifecycle

boolean

Whether pause/cancel on the parent cascades to this subscription.

pendingPlanId

integer

Plan the subscription will switch to at the next cycle, set by a next_billing change-plan.

createdAt

string<date-time>

updatedAt

string<date-time>

plan

object

A reusable billing plan. amount is a flat integer in the currency minor units (with separate currency + exponent) - not an Amount object.

Show child attributes

curl -X POST https://api.therius.io/v1/subscription/sub_abc123def456/payment-method \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantCode": "MERCHANT_001",
    "card": { "tokenData": { "token": "vt_9f2c..." } }
  }'

curl -X POST https://api.therius.io/v1/subscription/sub_abc123def456/payment-method \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantCode": "MERCHANT_001",
    "card": { "nonceData": { "nonce": "<fresh nonce from JS SDK>" } }
  }'

{}

Payments

Tokenization

Subscriptions

Subscription Plans

SDK Session

Update a Subscription's Payment Method

Record mode — card.tokenData

CIT mode — card.nonceData / card.cardData

Record mode (recommended)

Response

Webhook events fired

Errors

Authorizations

Path Parameters

Body

Response

Record mode — card.tokenData

CIT mode — card.nonceData / card.cardData

​Record mode (recommended)

​Response

​Webhook events fired

​Errors

Authorizations

Path Parameters

Body

Response

Record mode (recommended)

Response

Webhook events fired

Errors