API DocsDocs

Update Subscription

Card Tokenization — Update Subscription

6 min readUpdated Mar 27, 2026

PUT /api/v1/payments/card/recurring/{subscriptionId}

Update plan parameters (amount, frequency, dates) or transition the subscription state (ACTIVE, PAUSED, CANCELED). All fields are optional — send only the fields you want to change.

#Headers

HeaderValue
Content-Typeapplication/json
AuthorizationBearer {token} — see Authentication

#Request Body Parameters

FieldTypeRequiredDescription
planObject — See UpdatePlanNo
statusString (PENDING, TRIALING, ACTIVE, PAUSED, CANCELED)No
FieldTypeRequiredDescription
amountStringNoTransaction amount as a decimal string in major currency units (e.g. "10.00" = ten dollars). Values with more than two decimal places are automatically rounded.
currencyStringNoThree-letter ISO 4217 currency code (e.g. USD, EUR, GBP).
frequencyString (DAILY, WEEKLY, MONTHLY, CUSTOM)No
intervalIntegerNo
startDateStringNo
endDateStringNo

#Response

FieldTypeDescription
subscriptionIdString
statusString (PENDING, TRIALING, ACTIVE, PAUSED, CANCELED)
nextChargeDateString
createdAtStringTimestamp when the transaction was created (ISO 8601 format).
planObject — See SubscriptionPlanDto
billingDetailsObject — See BillingDetails
metadataMap<String, String>Arbitrary key-value pairs for your own use (e.g. order reference, campaign ID). Returned unchanged in responses and callbacks.
failureCountInteger
lastChargeDateString
lastChargeStatusString
FieldTypeDescription
amountStringTransaction amount as a decimal string in major currency units (e.g. "10.00" = ten dollars). Values with more than two decimal places are automatically rounded.
currencyStringThree-letter ISO 4217 currency code (e.g. USD, EUR, GBP).
frequencyString (DAILY, WEEKLY, MONTHLY, CUSTOM)
intervalInteger
startDateString
endDateString
FieldTypeDescription
externalUserIdStringYour internal customer identifier. Useful for linking transactions to user accounts in your system.
firstNameStringCustomer's first name. Required for 3DS2 frictionless flow.
lastNameStringCustomer's last name. Required for 3DS2 frictionless flow.
address1StringBilling street address (line 1). Required for 3DS2 frictionless flow.
cityStringBilling city. Required for 3DS2 frictionless flow.
stateStringBilling state or province.
countryStringBilling country as an ISO 3166-1 alpha-2 code (e.g. US, GB, DE).
postalCodeStringBilling ZIP or postal code.
phoneStringCustomer's phone number (including country code). Required for 3DS2 frictionless flow.
emailStringCustomer's email address.
dateOfBirthStringCustomer's date of birth in YYYY-MM-DD format. Required for 3DS2 frictionless flow.
{
  "plan": {
    "amount": "100.00",
    "currency": "USD",
    "frequency": "DAILY",
    "interval": 12345,
    "startDate": "2025-07-17",
    "endDate": "2025-07-17"
  },
  "status": "PENDING"
}
{
  "subscriptionId": "192.168.1.1",
  "status": "PENDING",
  "nextChargeDate": "2025-07-17",
  "createdAt": "example_createdAt",
  "plan": {
    "amount": "100.00",
    "currency": "USD",
    "frequency": "DAILY",
    "interval": 12345,
    "startDate": "2025-07-17",
    "endDate": "2025-07-17"
  },
  "billingDetails": {
    "externalUserId": "example_externalUserId",
    "firstName": "John",
    "lastName": "Doe",
    "address1": "123 Main St",
    "city": "New York",
    "state": "NY",
    "country": "US",
    "postalCode": "10001",
    "phone": "+12125551234",
    "email": "test@example.com",
    "dateOfBirth": "2025-07-17"
  },
  "metadata": {
    "key1": "value1"
  },
  "failureCount": 12345,
  "lastChargeDate": "2025-07-17",
  "lastChargeStatus": "example_lastChargeStatus"
}

Idempotency: The requestId field ensures idempotent processing. If you retry a request with the same requestId, the original response is returned without reprocessing.

#Error Responses

HTTP StatusDescription
400Bad Request — missing or invalid parameters. Check the response body for field-level details.
401Unauthorized — missing, expired, or invalid bearer token. Re-authenticate via POST /api/v1/auth.
404Not Found — the requested resource does not exist.
500Internal Server Error — an unexpected error occurred. Retry with exponential backoff.
curl -X PUT https://sandbox.api.exirom.com/api/v1/payments/card/recurring/12345 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
  "plan": {
    "amount": "100.00",
    "currency": "USD",
    "frequency": "DAILY",
    "interval": 12345,
    "startDate": "2025-07-17",
    "endDate": "2025-07-17"
  },
  "status": "PENDING"
}'

#Try It

SandboxTry it
https://sandbox.api.exirom.com/api
Was this helpful?
PreviousGET /v1/payments/card/recurring/{subscriptionId}
NextDELETE /v1/payments/card/recurring/{subscriptionId}