> ## Documentation Index
> Fetch the complete documentation index at: https://docs.therius.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Update a Subscription's Payment Method

> Replace the card on a subscription. Changing the card is a CIT and may need 3D Secure — record a card you already CIT'd, or run a zero-value CIT here.

`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:

<CardGroup cols={2}>
  <Card title="Record mode — card.tokenData" icon="shield-check">
    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.**
  </Card>

  <Card title="CIT mode — card.nonceData / card.cardData" icon="credit-card">
    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.
  </Card>
</CardGroup>

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:

<Steps>
  <Step title="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`.
  </Step>

  <Step title="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.)
  </Step>
</Steps>

<Note>
  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.
</Note>

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

<RequestExample>
  ```bash Record mode theme={"dark"}
  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..." } }
    }'
  ```

  ```bash CIT mode theme={"dark"}
  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>" } }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={"dark"}
  {}
  ```
</ResponseExample>


## OpenAPI

````yaml POST /subscription/{id}/payment-method
openapi: 3.1.0
info:
  title: Therius API
  description: REST API for payments, subscriptions, and billing plans.
  version: 1.0.0
servers:
  - url: https://api.therius.io/v1
    description: Production
  - url: https://api-sandbox.therius.io/v1
    description: Sandbox
security:
  - bearerAuth: []
paths:
  /subscription/{id}/payment-method:
    post:
      tags:
        - Subscriptions
      summary: Update the card on a subscription
      operationId: updateSubscriptionPaymentMethod
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - merchantCode
                - card
              properties:
                merchantCode:
                  type: string
                  description: Your merchant account identifier.
                card:
                  $ref: '#/components/schemas/SubscriptionCardUpdate'
      responses:
        '200':
          description: Payment method updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
components:
  schemas:
    SubscriptionCardUpdate:
      description: >-
        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`.
      allOf:
        - $ref: '#/components/schemas/CardInstrument'
        - type: object
          properties:
            networkTransactionId:
              type: string
              description: >-
                Record mode only. The scheme mandate reference (Network
                Transaction ID) returned by the original CIT. Optional when the
                token already carries its mandate; required when recording a
                card that was CIT'd outside Therius.
            networkReferenceId:
              type: string
              description: >-
                Record mode only. The Mastercard TLID (or scheme equivalent)
                from the original CIT, alongside `networkTransactionId`.
                Defaults to `networkTransactionId` when omitted.
    Subscription:
      type: object
      description: >-
        A customer enrollment in a plan. `plan` is embedded on
        single-subscription responses. Invoice/event history is not included
        here - use the invoice endpoints.
      properties:
        id:
          type: string
          description: Subscription UUID.
        merchantId:
          type: integer
          description: The merchant account that owns the subscription.
        planId:
          type: integer
          description: ID of the plan this subscription is enrolled in.
        customerEmail:
          type: string
          description: Subscriber email, used for billing and dunning notifications.
        customerName:
          type: string
          description: Subscriber name as it appears on invoices.
        customerDocument:
          type: string
          description: >-
            Subscriber national ID / tax document, where a market requires it
            (e.g. Brazil CPF/CNPJ).
        cardBrand:
          type: string
          description: Brand of the card on the mandate, e.g. `visa`.
        status:
          type: string
          enum:
            - pending
            - trialing
            - active
            - past_due
            - suspended
            - paused
            - cancelled
            - completed
          description: >-
            `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`.
        currentPeriodStart:
          type: string
          format: date-time
          description: Start of the current billing period.
        currentPeriodEnd:
          type: string
          format: date-time
          description: End of the current billing period.
        nextBillingDate:
          type: string
          format: date-time
          description: When the next renewal charge is scheduled.
        trialStart:
          type: string
          format: date-time
          description: Trial start, when the plan has a trial.
        trialEnd:
          type: string
          format: date-time
          description: Trial end - the first real charge date.
        dunningAttemptCount:
          type: integer
          description: Failed-renewal retry attempts made in the current dunning sequence.
        activatedAt:
          type: string
          format: date-time
          description: When the subscription first became `active`.
        cancelledAt:
          type: string
          format: date-time
        pausedAt:
          type: string
          format: date-time
        suspendedAt:
          type: string
          format: date-time
        startAt:
          type: string
          format: date-time
          description: Deferred start, when creation set a future `startAt`.
        cyclesCompleted:
          type: integer
          description: Number of billing cycles charged so far.
        completedAt:
          type: string
          format: date-time
          description: When the subscription reached `maxBillingCycles`.
        parentSubscriptionId:
          type: string
          description: Parent subscription UUID, for add-on hierarchies.
        propagateLifecycle:
          type: boolean
          description: Whether pause/cancel on the parent cascades to this subscription.
        pendingPlanId:
          type: integer
          description: >-
            Plan the subscription will switch to at the next cycle, set by a
            `next_billing` change-plan.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        plan:
          $ref: '#/components/schemas/Plan'
    CardInstrument:
      description: >-
        The payment instrument. Provide exactly ONE of `cardData`, `nonceData`,
        or `tokenData` — they are interchangeable alternatives, not fields to
        send together. `cardData` carries a raw PAN and requires your server to
        be PCI DSS compliant; `nonceData` is a single-use nonce from the Therius
        JS SDK; `tokenData` reuses a stored `vt_...` vault token.
      oneOf:
        - title: Raw card (PCI DSS)
          type: object
          required:
            - cardData
          properties:
            cardData:
              $ref: '#/components/schemas/CardData'
        - title: SDK nonce
          type: object
          required:
            - nonceData
          properties:
            nonceData:
              $ref: '#/components/schemas/NonceData'
        - title: Vault token
          type: object
          required:
            - tokenData
          properties:
            tokenData:
              $ref: '#/components/schemas/TokenData'
    Plan:
      type: object
      description: >-
        A reusable billing plan. `amount` is a flat integer in the currency
        minor units (with separate `currency` + `exponent`) - not an Amount
        object.
      properties:
        id:
          type: integer
          description: The plan unique integer ID.
        merchantId:
          type: integer
          description: The merchant account that owns the plan.
        name:
          type: string
        description:
          type: string
        interval:
          type: string
          enum:
            - day
            - week
            - month
            - year
          description: Billing interval unit. Immutable after creation.
        intervalCount:
          type: integer
          description: >-
            Number of `interval` units between charges - `month` + `3` bills
            quarterly.
        amount:
          type: integer
          description: >-
            Recurring charge in the currency minor units (e.g. `2999` = $29.99
            at exponent 2). Immutable after creation.
        currency:
          type: string
          description: ISO 4217 currency code. Immutable after creation.
        exponent:
          type: integer
          description: >-
            Decimal places for `amount` / `introAmount` - `2` for USD, `0` for
            JPY.
        trialPeriodDays:
          type: integer
          description: Free-trial length in days before the first charge. `0` for no trial.
        introAmount:
          type: integer
          description: >-
            Introductory charge in minor units for the first
            `introBillingCycles` cycles, if set.
        introBillingCycles:
          type: integer
          description: >-
            How many initial cycles are billed at `introAmount` before the rate
            reverts to `amount`.
        maxBillingCycles:
          type: integer
          description: >-
            Total cycles after which the subscription auto-completes. `0` =
            open-ended.
        availableCountries:
          type: array
          items:
            type: string
          description: >-
            ISO 3166-1 alpha-2 codes the plan is offered in. Empty = available
            everywhere.
        isActive:
          type: boolean
          description: >-
            Whether the plan accepts new subscribers. Existing subscriptions are
            unaffected when this is `false`.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    CardData:
      type: object
      description: >-
        Raw card details. Only if your server is PCI DSS compliant to handle raw
        PANs — otherwise collect the card with the Therius JS SDK and send
        `nonceData`.
      properties:
        cardNumber:
          type: string
          description: Full PAN, digits only.
          example: '4111111111111111'
        cardholderName:
          type: string
          description: Name as it appears on the card.
          example: Ada Lovelace
        expiryMonth:
          type: string
          description: Two-digit expiry month, e.g. `12`.
          example: '12'
        expiryYear:
          type: string
          description: Four-digit expiry year, e.g. `2030`.
          example: '2030'
        cvv:
          type: string
          description: Card verification value (3 or 4 digits).
          example: '123'
        tokenize:
          type: boolean
          description: >-
            Set to `true` to save this card as a reusable token. Requires
            `shopper.id` in the request.
        cardAddress:
          $ref: '#/components/schemas/CardAddress'
        documentNumber:
          type: string
          description: Cardholder tax/document ID, required by some LATAM acquirers.
        typeOverride:
          type: string
          description: Override the detected card type, e.g. `debit`.
    NonceData:
      type: object
      description: >-
        Single-use nonce from the Therius JS SDK — no card data touches your
        server. Nonces are single-use and expire after a short window.
      properties:
        nonce:
          type: string
          description: The nonce string returned by the SDK.
        cardholderName:
          type: string
          description: Cardholder name.
        cardAddress:
          $ref: '#/components/schemas/CardAddress'
        tokenize:
          type: boolean
          description: >-
            Save the card as a token after payment. Requires `shopper.id` in the
            request.
        typeOverride:
          type: string
          description: Override the detected card type.
    TokenData:
      type: object
      description: A `vt_...` vault token for a card the shopper previously tokenized.
      properties:
        token:
          type: string
          description: Token ID returned from a prior tokenization.
        cvv:
          type: string
          description: CVV, if re-collection is required by the acquirer.
        cardAddress:
          $ref: '#/components/schemas/CardAddress'
    CardAddress:
      type: object
      properties:
        line1:
          type: string
        line2:
          type: string
        city:
          type: string
        state:
          type: string
        postalCode:
          type: string
        country:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Your secret API key: `Bearer prv_production_xxx` (production) or `Bearer
        prv_sandbox_xxx` (sandbox).

````