--- title: "Update a subscription" method: PUT path: "/subscription/v3/{id}" tags: ["Subscriptions"] --- # Update a subscription `PUT /subscription/v3/{id}` Updates an existing payment subscription or payment plan for the given `id`. The ID needed for the path parameter is returned in the response for the [Create a subscription](https://docs.nexiopay.com/reference/createsubscription) endpoint. Alternately, you can get the `id` for a subscription if you have a `customerRef` for the [View customer subscriptions](https://docs.nexiopay.com/reference/viewcustomersubscriptions) endpoint. > ๐Ÿ“˜ Note > > - Card token, currency, and customer reference number cannot be updated. If you need to change any of these values, [delete](https://docs.nexiopay.com/reference/deletesubscription) the existing subscription or payment plan and [create](https://docs.nexiopay.com/reference/createsubscription) a new one. > - For an existing payment plan, none of the schedule parameters can be updated. If you need to change any of those, [delete](https://docs.nexiopay.com/reference/deletesubscription) the existing payment plan and [create](https://docs.nexiopay.com/reference/createsubscription) a new one. > - The only user with rights to edit the subscription or payment plan is the original creator. See the `user` parameter that is returned in the [View a subscription](https://docs.nexiopay.com/reference/viewsubscription) or [View customer subscriptions](https://docs.nexiopay.com/reference/viewcustomersubscriptions) endpoints. > โš ๏ธ Try It > > To use the Try It feature for this endpoint, you can use the credentials for your [Sandbox API user](https://docs.nexiopay.com/docs/sandbox-environments).

You can also use the following test account. Copy the value and paste it into the appropriate space in the Try It section to the right. > username: `docs@nexiopay.com` > password: `JZdzoXpdDeH6VA`

Include a subscription ID in the path parameter of the request for a subscription created by the test account.
## Request parameters - id - payment - payment.tokenex - payment.tokenex.firstSix - payment.tokenex.lastFour - payment.isAuthOnly - payment.shouldUpdateCard - payment.processingOptions - payment.processingOptions.saveCardToken - payment.processingOptions.retryOnSoftDecline - payment.processingOptions.checkFraud - payment.processingOptions.shouldUseFingerprint - payment.processingOptions.check3ds - payment.processingOptions.verboseResponse - payment.processingOptions.paymentType - payment.processingOptions.paymentOptionTag - payment.processingOptions.merchantId - payment.processingOptions.customerRedirectUrl - payment.data - payment.data.settlementCurrency - payment.data.customer - payment.data.customer.invoice - payment.data.customer.orderNumber - payment.data.customer.orderDate - payment.data.customer.birthDate - payment.data.customer.nationalIdentificationNumber - payment.data.customer.companyName - payment.data.customer.firstName - payment.data.customer.lastName - payment.data.customer.email - payment.data.customer.phone - payment.data.customer.billToAddressOne - payment.data.customer.billToAddressTwo - payment.data.customer.billToCity - payment.data.customer.billToState - payment.data.customer.billToPostal - payment.data.customer.billToCountry - payment.data.customer.billToPhone - payment.data.customer.shipToAddressOne - payment.data.customer.shipToAddressTwo - payment.data.customer.shipToCity - payment.data.customer.shipToState - payment.data.customer.shipToPostal - payment.data.customer.shipToCountry - payment.data.customer.shipToPhone - payment.data.customer.createdAtDate - schedule - schedule.interval - schedule.intervalCount - schedule.duration - schedule.dateInitialBillingEnd - schedule.intialBillingAmount - schedule.dateCancelAfter ## Response parameters - customerRef - active - accountId - id - payment - payment.tokenex - payment.tokenex.token - payment.tokenex.firstSix - payment.tokenex.lastFour - payment.shouldUpdateCard - payment.isAuthOnly - payment.processingOptions - payment.processingOptions.saveCardToken - payment.processingOptions.retryOnSoftDecline - payment.processingOptions.checkFraud - payment.processingOptions.shouldUseFingerprint - payment.processingOptions.check3ds - payment.processingOptions.verboseResponse - payment.processingOptions.paymentType - payment.processingOptions.paymentOptionTag - payment.processingOptions.merchantId - payment.processingOptions.customerRedirectUrl - payment.data - payment.data.amount - payment.data.currency - payment.data.settlementCurrency - payment.data.customer - payment.data.customer.customerRef - payment.data.customer.invoice - payment.data.customer.orderNumber - payment.data.customer.orderDate - payment.data.customer.birthDate - payment.data.customer.nationalIdentificationNumber - payment.data.customer.companyName - payment.data.customer.firstName - payment.data.customer.lastName - payment.data.customer.email - payment.data.customer.phone - payment.data.customer.billToAddressOne - payment.data.customer.billToAddressTwo - payment.data.customer.billToCity - payment.data.customer.billToState - payment.data.customer.billToPostal - payment.data.customer.billToCountry - payment.data.customer.billToPhone - payment.data.customer.shipToAddressOne - payment.data.customer.shipToAddressTwo - payment.data.customer.shipToCity - payment.data.customer.shipToState - payment.data.customer.shipToPostal - payment.data.customer.shipToCountry - payment.data.customer.shipToPhone - payment.data.customer.createdAtDate - schedule - schedule.interval - schedule.intervalCount - schedule.initialBalance - schedule.balance - schedule.duration - schedule.dateInitialBillingEnd - schedule.intialBillingAmount - schedule.dateCancelAfter - schedule.scheduleType - userName - dateCreated - dateLastModified - dateLastRun - dateNextRun - paymentResult - paymentResult.amount - paymentResult.authCode - paymentResult.transactionStatus - paymentResult.transactionDate - paymentResult.transactionType - paymentResult.merchantId - paymentResult.currency - paymentResult.id - paymentResult.asyncTraceId - paymentResult.redirectUrl - paymentResult.message - paymentResult.status - paymentResult.gatewayResponse - paymentResult.gatewayResponse.gatewayName - paymentResult.gatewayResponse.refNumber - paymentResult.data - paymentResult.data.amount - paymentResult.data.currency - paymentResult.data.settlementCurrency - paymentResult.data.customer - paymentResult.data.customer.customerRef - paymentResult.data.customer.orderNumber - paymentResult.data.customer.orderDate - paymentResult.data.customer.invoice - paymentResult.data.customer.birthDate - paymentResult.data.customer.nationalIdentificationNumber - paymentResult.data.customer.companyName - paymentResult.data.customer.firstName - paymentResult.data.customer.lastName - paymentResult.data.customer.email - paymentResult.data.customer.phone - paymentResult.data.customer.billToAddressOne - paymentResult.data.customer.billToAddressTwo - paymentResult.data.customer.billToCity - paymentResult.data.customer.billToState - paymentResult.data.customer.billToPostal - paymentResult.data.customer.billToCountry - paymentResult.data.customer.billToPhone - paymentResult.data.customer.shipToAddressOne - paymentResult.data.customer.shipToAddressTwo - paymentResult.data.customer.shipToCity - paymentResult.data.customer.shipToState - paymentResult.data.customer.shipToPostal - paymentResult.data.customer.shipToCountry - paymentResult.data.customer.shipToPhone - paymentResult.data.customer.createdAt - paymentResult.card - paymentResult.card.cardHolder - paymentResult.card.cardNumber - paymentResult.card.expirationMonth - paymentResult.card.expirationYear - paymentResult.token - paymentResult.token.firstSix - paymentResult.token.lastFour - paymentResult.token.token - paymentResult.kountResponse - paymentResult.kountResponse.status - paymentResult.kountResponse.rules - lastPaymentStatus - lastSuccessfulPaymentDate - exp
## Path parameters - `id` string, required ## Request body - object โ€” Include any parameters that you want to update. However, note that the card token, currency, and customer reference number cannot be updated. If you need to change any of these values, [delete](https://docs.nexiopay.com/reference/deletesubscription) the existing subscription and [create](https://docs.nexiopay.com/reference/createsubscription) a new one. In addition, for an existing payment plan, none of the schedule parameters can be updated. If you need to change any of those for a payment plan, you must delete the existing one and then create a new one. - `payment` object โ€” Payment information for the initial transaction and for recurring (scheduled) transactions. - `data` object โ€” Transaction and customer data. You cannot update the currency. - `amount` number โ€” The transaction amount to change for the existing subscription or payment plan. The maximum value has 16 digits total, including up to two of those digits after the decimal point. - `customer` object โ€” Customer information for checking fraud or for use of the processing gateway, when applicable. You cannot change the `customerRef` for an existing subscription or payment plan. - `orderNumber` string โ€” **Conditionally required.** The order number. This parameter is not required by the API (it is required for transactions where [decline recovery](https://docs.nexiopay.com/docs/recover) is used). **However, Nexio strongly recommends that you include this for every transaction. Ideally, this value should be unique to the merchant.** This value is cached in the one-time-use token. > ๐Ÿ›‘ Important > > If you run 3DS transactions and you do not use a unique order number, there will be payment flows that you won't be able to reconcile. Nexio recommends a format for the order number of a unique value that also includes an attempt number so that you can track attempts per order, such as when a payment attempt fails. For example, something like `[order_number]-[attempt_number]`. - `orderDate` string โ€” The date of the customer's order. This field is required by certain gateways. For information on gateway-specific required fields, see the [Connections](https://docs.nexiopay.com/docs/connections) documentation. Use any of the following formats for the date: - Four-digit year, two-digit month and day, separated with hyphens: YYYY-MM-DD.
For example, `2021-08-26`. - [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html) date expressed in UTC.It must include the 3 decimal places for milliseconds.
For example, `2001-08-26T13:35:00.978Z` or `1990-12-05T00:00:00.000Z`. - UNIX date (as an integer representing seconds).
For example, `1630006518`. > #### Note > This is NOT a quick way to schedule a transaction. Specifying a date in the future does not cause the order to be run automatically at the indicated date or time. - `invoice` string โ€” The invoice number. - `firstName` string โ€” The customer's first name, as it appears on the card. - `lastName` string โ€” The customer's last name, as it appears on the card. - `birthDate` string โ€” The customer's date of birth. Use any of the following formats for the date: - Four-digit year, two-digit month and day, separated with hyphens: YYYY-MM-DD.
For example, `2001-08-26`. - [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html) date expressed in UTC. It must include the 3 decimal places for milliseconds.
For example, `2001-08-26T13:35:00.184Z` or `1990-06-24T00:00:00.000Z`. - UNIX date (as an integer representing seconds).
For example, `998854500`. - `nationalIdentificationNumber` NationalIdentificationNumber โ€” unresolved $ref - `email` Email โ€” unresolved $ref - `phone` Phone โ€” unresolved $ref - `companyName` CompanyName โ€” unresolved $ref - `billToAddressOne` BillToAddressOne โ€” unresolved $ref - `billToAddressTwo` string โ€” Additional street address information, if required. - `billToCity` BillToCity โ€” unresolved $ref - `billToState` string โ€” The state or province on file with the card provider. (If in the US, this must be the [two-character state abbreviation](https://pe.usps.com/text/pub28/28apb.htm)). - `billToPostal` BillToPostal โ€” unresolved $ref - `billToCountry` BillToCountry โ€” unresolved $ref - `billToPhone` BillToPhone โ€” unresolved $ref - `shipToAddressOne` string โ€” The shipping address, if different from the billing address. - `shipToAddressTwo` string โ€” Additional shipping address information, if required. - `shipToCity` ShipToCity โ€” unresolved $ref - `shipToState` string โ€” The shipping state or province. (If in the US, this must be the [two-character state abbreviation](https://pe.usps.com/text/pub28/28apb.htm).) - `shipToPostal` ShipToPostal โ€” unresolved $ref - `shipToCountry` ShipToCountry โ€” unresolved $ref - `shipToPhone` ShipToPhone โ€” unresolved $ref - `createdAtDate` CreatedAtDate โ€” unresolved $ref - `settlementCurrency` string โ€” The [three-character ISO code](https://en.wikipedia.org/wiki/ISO_4217) for the currency in which future transactions will be settled for the existing subscription or payment plan. - `isAuthOnly` boolean โ€” `true` - Sets all future transactions to authorize only.
`false` - Sets all future transactions to authorize and capture.
> #### Note > Auth only transactions run on a schedule must be captured in your own code base. > *Default: The value set when the subscription was created.* - `processingOptions` object โ€” Processing options to use for the initial and subsequent (recurring scheduled) transactions. - `paymentType` 'initialScheduled' | 'initialUnscheduled' | 'scheduled' | 'unscheduledCit' | 'unscheduledMit' | 'initialMoto', required โ€” The type of transaction being processed using stored payment credentials. Use this parameter to properly flag initial and subsequent transactions. For more information about this parameter and when to use each option, see the [Payment type (paymentType) reference table](https://docs.nexiopay.com/docs/constant-transaction-values#payment-type-paymenttype) in Guides. **Note:** Cardholder authentication (3D Secure) may be required depending on card issuer requirements. For more information, see [3D Secure overview](https://docs.nexiopay.com/docs/3d-secure-1) in Guides. - `paymentOptionTag` string โ€” A custom value used to route transactions to a specific gateway or merchant account. Contact [Integrations Support](https://docs.nexiopay.com/page/contact-us) to designate a `paymentOptionTag` for a given merchant account. - `saveCardToken` boolean โ€” Set to `false` to opt out of saving a card token when a transaction is run. - `retryOnSoftDecline` boolean โ€” Specifies whether to enable the transaction for [decline recovery](https://docs.nexiopay.com/docs/recover). Set to `true` to flag the transaction as enabled for decline recovery. Eligible declined transactions are automatically scheduled for retry according to the recommendation engine. To enable this feature, the subscription or payment plan schedule must have an interval that equates to 30 or more days. - `checkFraud` boolean โ€” Set to `false` to opt out of sending a request to Kount. Note: During testing you may trigger specific Kount responses by including any of the values shown in the [verification](https://docs.nexiopay.com/docs/testing-kount-verification#test-kount-verification-table) table. - `shouldUseFingerprint` boolean โ€” This parameter applies when a [device fingerprint](https://docs.nexiopay.com/docs/device-fingerprinting) was created while saving a card token. The card's stored fingerprint will be used by default, but you may choose not to use it by setting this parameter to false. > #### Note > To change your merchant's default setting, contact [Integrations Support](https://docs.nexiopay.com/page/contact-us). - `check3ds` boolean โ€” Integrations Support sets this flag to `true` for merchants by default on the backend when the merchant will be handling transactions in 3DS-mandated regions. If needed, you can override this value. When set to `true`, this indicates that your system is equipped to handle a 3DS (three-domain secure) redirect flow being returned from the request. - `customerRedirectUrl` string โ€” The URL to which the customer will be redirected after completing a [3D Secure](https://docs.nexiopay.com/docs/using-3ds-to-run-transactions) authentication. The customer will be sent here whether the transaction succeeds or fails. This URL must use the HTTPS protocol. - `merchantId` MerchantId โ€” unresolved $ref - `verboseResponse` boolean โ€” Set to `true` to include additional information in the response. - `shouldUpdateCard` boolean โ€” The card's account updater [enrollment tag](https://docs.nexiopay.com/docs/checking-a-cards-enrollment-tag). When true, the card token is tagged for being sent to the account updater provider. > #### Note > The card will not be registered until the merchant account is enrolled. See the [Enrollment tag table](https://docs.nexiopay.com/docs/checking-a-cards-enrollment-tag#enrollment-tag-table) for more information. - `schedule` object โ€” The schedule for recurring transactions. Note that you cannot change the type from a subscription to a payment plan. Additionally, you cannot change the schedule of an existing payment plan. - `interval` 'day' | 'week' | 'month' | 'year' โ€” The schedule's time period. - `intervalCount` integer โ€” The number of times the `interval` will pass between transactions. The maximum payment plan or subscription interval length is one year. An `intervalCount` of `0` means that only one transaction runs. This value must be greater than or equal to 0. See the [subscription schedule examples table](https://docs.nexiopay.com/docs/getting-started-with-subscriptions#subscription-schedule-examples-table) for examples of how the interval and interval count create the schedule. - `duration` integer โ€” The anticipated number of transactions that may run for the subscription. This value is for information purposes because the system does not automatically end the subscription after the given number of transactions. Instead, use the `dateCancelAfter` parameter to end the subscription automatically. - `dateCancelAfter` string, date โ€” The date to end the subscription. If the `dateNextRun` parameter (from the response) occurs after the `dateCancelAfter` date, the system sets the subscription to be inactive (`active` is set to `false`). Use any of the following formats for the date: - Four-digit year, two-digit month and day, separated with hyphens: YYYY-MM-DD.
For example, `2021-08-26`. - [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html) date expressed in UTC, with as much of the time part as wanted.
For example, `2021-08-26T13:35:18Z` or `2023-12-05T00:00Z`. - Dates with month spelled out (or abbreviated or a number) and with days and years as numbers.
For example, `Aug 8 23` or `8 August 2023`. Note that two-digit years may be interpreted as days, depending on the location in the string and the number used for the day (`23 Aug 24` will be intepreted as August 23, 2024). Regardless of the format sent in the request, the system returns the value in the response in the format of four-digit year, two-digit month and day, separated with hyphens: YYYY-MM-DD. For example, `2021-08-26`. If not included in the request, this value is not returned. - `initialBillingAmount` number โ€” The transaction amount during the initial billing period. This allows you to specify a discounted amount from the regular subscription (such as a trial period). You can instead use a value of zero (0) for indicating a free trial situation. This amount gets used for any transactions that occur before the `dateInitialBillingEnd`. After that date, the value from `payment.data.amount` gets used for transactions. If not included in the request, the value is `null` by default. - `dateInitialBillingEnd` string, date โ€” The date at which the initial billing period ends. This allows you to specify a discounted amount from the regular subscription (such as a trial period). Transactions prior to this date use the value from the `initialBillingAmount`. Transactions after this date use the value from `payment.data.amount`. If this parameter is set to the current date or earlier, the system immediately runs a payment using the `payment.data.amount` value. Use any of the following formats for the date: - Four-digit year, two-digit month and day, separated with hyphens: YYYY-MM-DD.
For example, `2024-08-26`. - [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html) date expressed in UTC, with as much of the time part as wanted.
For example, `2024-08-26T13:35:18Z` or `2024-12-05T00:00Z`. - Dates with month spelled out or abbreviated and with days and years as numbers.
For example, `Aug 8 23` or `8 August 2023`. Note that two-digit years may be interpreted as days, depending on the location in the string and the number used for the day (`23 Aug 24` will be intepreted as August 23, 2024). Regardless of the format sent in the request, the system returns the value in the response in the format of four-digit year, two-digit month and day, separated with hyphens: YYYY-MM-DD. For example, `2024-08-26`. If not included in the request, this value is not returned. ## Response `200` Success - object โ€” Details on the subscription schedule. - `customerRef` string โ€” Customer identifier. You can use this field to pass a customer ID to the gateway or APM or to manage user subscriptions. This value is cached in the one-time-use token. - `active` Active โ€” unresolved $ref - `accountId` string โ€” Your Nexio account number. You can get this value from the response for the [Who am I](https://docs.nexiopay.com/reference/whoami) endpoint. - `id` Id โ€” unresolved $ref - `payment` object โ€” Payment information for future payments - `isAuthOnly` IsAuthOnly โ€” unresolved $ref - `data` object โ€” Transaction and customer data. - `amount` Amount โ€” unresolved $ref - `currency` Currency โ€” unresolved $ref - `customer` Customer โ€” unresolved $ref - `cart` Cart โ€” unresolved $ref - `customFields` CustomFields โ€” unresolved $ref - `description` Description โ€” unresolved $ref - `descriptor` Descriptor โ€” unresolved $ref - `lodging` Lodging โ€” unresolved $ref - `tokenex` object โ€” Card token information. Card tokens can be used to process through any MID on your account. They are not restricted to a specific merchant account or currency. - `token` string โ€” The card token that will be used to process future transactions. Card tokens can be used to process through any MID on your account. They are not restricted to a specific merchant account or currency. - `firstSix` FirstSix โ€” unresolved $ref - `lastFour` LastFour โ€” unresolved $ref - `processingOptions` ProcessingOptions โ€” unresolved $ref - `schedule` Schedule โ€” unresolved $ref - `userName` UserName โ€” unresolved $ref - `dateCreated` DateCreated โ€” unresolved $ref - `dateLastModified` DateLastModified โ€” unresolved $ref - `dateLastRun` DateLastRun โ€” unresolved $ref - `dateNextRun` DateNextRun โ€” unresolved $ref ## Other responses - `401` โ€” Unauthorized. For help with this error and other error codes, see [Common errors](https://docs.nexiopay.com/docs/common-errors) in the Guides area. --- [API](https://skmtc.dev/nexiopay/apis/payments-api-reference.md) ยท [All operations](https://skmtc.dev/nexiopay/apis/payments-api-reference/llms.txt) ยท [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nexiopay/payments-api-reference/revisions/b414b73979e5/schema)