> ## Documentation Index > Fetch the complete documentation index at: https://docs.revolv3.com/llms.txt > Use this file to discover all available pages before exploring further. # Replace Subscription Primary Payment Method > Replaces the **primary payment method** associated with an active subscription. This operation is typically used when a customer updates their card, bank account, or switches to a different saved method for ongoing billing. You must provide the `subscriptionId` and the new payment method details. The new method will be used for all **future charges**, starting with the next billing cycle (or immediately, if a payment is due). This endpoint helps ensure billing continuity in case of expired cards, failed payments, or customer-initiated updates. ## OpenAPI ````yaml /api-reference/swagger.json put /api/Subscriptions/{subscriptionId}/payment-method openapi: 3.0.4 info: title: Revolv3 OpenApi Spec description: Spec for Revolv3 version: 1.29.1 servers: - url: 'https://api-sandbox.revolv3.com ' security: [] paths: /api/Subscriptions/{subscriptionId}/payment-method: put: tags: - Subscriptions summary: Replace Subscription Primary Payment Method description: "Replaces the **primary payment method** associated with an active subscription.\r\nThis operation is typically used when a customer updates their card, bank account, or switches to a different saved method for ongoing billing.\r\n\r\nYou must provide the `subscriptionId` and the new payment method details.\r\nThe new method will be used for all **future charges**, starting with the next billing cycle (or immediately, if a payment is due).\r\n\r\nThis endpoint helps ensure billing continuity in case of expired cards, failed payments, or customer-initiated updates." parameters: - name: subscriptionId in: path required: true schema: maximum: 1000000000 minimum: 1 type: integer format: int64 requestBody: content: application/json-patch+json: schema: $ref: >- #/components/schemas/ReplaceSubscriptionPrimaryPaymentMethodRequestDTO example: existingPaymentMethod: null paymentMethod: taxAmount: 2.57 originalNetworkTransactionId: test-transaction-id billingAddress: addressId: null addressLine1: 100 Main Street addressLine2: null city: Irvine state: CA postalCode: '92602' phoneNumber: null email: null country: US creditCard: paymentAccountNumber: '4111111111111111' expirationDate: '1025' securityCode: null networkToken: null ach: null googlePay: null applePay: null merchantPaymentMethodRefId: null billingFirstName: John billingLastName: Doe billingFullName: null application/json: schema: $ref: >- #/components/schemas/ReplaceSubscriptionPrimaryPaymentMethodRequestDTO example: existingPaymentMethod: null paymentMethod: taxAmount: 2.57 originalNetworkTransactionId: test-transaction-id billingAddress: addressId: null addressLine1: 100 Main Street addressLine2: null city: Irvine state: CA postalCode: '92602' phoneNumber: null email: null country: US creditCard: paymentAccountNumber: '4111111111111111' expirationDate: '1025' securityCode: null networkToken: null ach: null googlePay: null applePay: null merchantPaymentMethodRefId: null billingFirstName: John billingLastName: Doe billingFullName: null text/json: schema: $ref: >- #/components/schemas/ReplaceSubscriptionPrimaryPaymentMethodRequestDTO example: existingPaymentMethod: null paymentMethod: taxAmount: 2.57 originalNetworkTransactionId: test-transaction-id billingAddress: addressId: null addressLine1: 100 Main Street addressLine2: null city: Irvine state: CA postalCode: '92602' phoneNumber: null email: null country: US creditCard: paymentAccountNumber: '4111111111111111' expirationDate: '1025' securityCode: null networkToken: null ach: null googlePay: null applePay: null merchantPaymentMethodRefId: null billingFirstName: John billingLastName: Doe billingFullName: null application/*+json: schema: $ref: >- #/components/schemas/ReplaceSubscriptionPrimaryPaymentMethodRequestDTO example: existingPaymentMethod: null paymentMethod: taxAmount: 2.57 originalNetworkTransactionId: test-transaction-id billingAddress: addressId: null addressLine1: 100 Main Street addressLine2: null city: Irvine state: CA postalCode: '92602' phoneNumber: null email: null country: US creditCard: paymentAccountNumber: '4111111111111111' expirationDate: '1025' securityCode: null networkToken: null ach: null googlePay: null applePay: null merchantPaymentMethodRefId: null billingFirstName: John billingLastName: Doe billingFullName: null responses: '200': description: OK content: text/plain: schema: $ref: '#/components/schemas/SubscriptionDTO' example: subscriptionId: 1 customerId: 1 merchantSubscriptionRefId: 1234-5678-9101 networkTransactionId: null billingIntervalType: Months billingIntervalCount: 1 subscriptionStatusType: Current subscriptionCancelType: Immediate initialBillDate: 22-Jun-26 nextBillDate: 22-Jul-26 taxAddress: null paymentMethodIds: - 1 - 2 cancelledAt: null billingPlans: - subscriptionBillingPlanId: 1 subscriptionId: 0 name: Billing Plan 1 value: 10.99 startDate: 22-Jun-26 cyclesRemaining: -1 cycleCount: 0 valueType: Standard - subscriptionBillingPlanId: 2 subscriptionId: 0 name: Billing Plan 2 value: 14.99 startDate: 22-Jul-26 cyclesRemaining: 12 cycleCount: 0 valueType: Standard message: null paymentProcessor: null processorMerchantId: null processorRawResponse: null currency: null responseMessage: null responseCode: null application/json: schema: $ref: '#/components/schemas/SubscriptionDTO' example: subscriptionId: 1 customerId: 1 merchantSubscriptionRefId: 1234-5678-9101 networkTransactionId: null billingIntervalType: Months billingIntervalCount: 1 subscriptionStatusType: Current subscriptionCancelType: Immediate initialBillDate: 22-Jun-26 nextBillDate: 22-Jul-26 taxAddress: null paymentMethodIds: - 1 - 2 cancelledAt: null billingPlans: - subscriptionBillingPlanId: 1 subscriptionId: 0 name: Billing Plan 1 value: 10.99 startDate: 22-Jun-26 cyclesRemaining: -1 cycleCount: 0 valueType: Standard - subscriptionBillingPlanId: 2 subscriptionId: 0 name: Billing Plan 2 value: 14.99 startDate: 22-Jul-26 cyclesRemaining: 12 cycleCount: 0 valueType: Standard message: null paymentProcessor: null processorMerchantId: null processorRawResponse: null currency: null responseMessage: null responseCode: null text/json: schema: $ref: '#/components/schemas/SubscriptionDTO' example: subscriptionId: 1 customerId: 1 merchantSubscriptionRefId: 1234-5678-9101 networkTransactionId: null billingIntervalType: Months billingIntervalCount: 1 subscriptionStatusType: Current subscriptionCancelType: Immediate initialBillDate: 22-Jun-26 nextBillDate: 22-Jul-26 taxAddress: null paymentMethodIds: - 1 - 2 cancelledAt: null billingPlans: - subscriptionBillingPlanId: 1 subscriptionId: 0 name: Billing Plan 1 value: 10.99 startDate: 22-Jun-26 cyclesRemaining: -1 cycleCount: 0 valueType: Standard - subscriptionBillingPlanId: 2 subscriptionId: 0 name: Billing Plan 2 value: 14.99 startDate: 22-Jul-26 cyclesRemaining: 12 cycleCount: 0 valueType: Standard message: null paymentProcessor: null processorMerchantId: null processorRawResponse: null currency: null responseMessage: null responseCode: null '400': description: Bad Request content: text/plain: schema: $ref: '#/components/schemas/StatusMessageResponse' example: message: Unable to perform the request action with provided data. application/json: schema: $ref: '#/components/schemas/StatusMessageResponse' example: message: Unable to perform the request action with provided data. text/json: schema: $ref: '#/components/schemas/StatusMessageResponse' example: message: Unable to perform the request action with provided data. '401': description: Unauthorized content: text/plain: schema: $ref: '#/components/schemas/StatusMessageResponse' example: message: Attempted to perform an unauthorized operation. application/json: schema: $ref: '#/components/schemas/StatusMessageResponse' example: message: Attempted to perform an unauthorized operation. text/json: schema: $ref: '#/components/schemas/StatusMessageResponse' example: message: Attempted to perform an unauthorized operation. '404': description: Not Found content: text/plain: schema: $ref: '#/components/schemas/StatusMessageResponse' example: message: Unable to find an entity with the provided data. application/json: schema: $ref: '#/components/schemas/StatusMessageResponse' example: message: Unable to find an entity with the provided data. text/json: schema: $ref: '#/components/schemas/StatusMessageResponse' example: message: Unable to find an entity with the provided data. security: - Bearer: [] components: schemas: ReplaceSubscriptionPrimaryPaymentMethodRequestDTO: type: object properties: existingPaymentMethod: $ref: '#/components/schemas/ExistingPaymentMethodDTO' paymentMethod: $ref: '#/components/schemas/ReplaceSubscriptionPrimaryPaymentMethodDTO' additionalProperties: false SubscriptionDTO: type: object properties: subscriptionId: maximum: 1000000000 minimum: 1 type: integer format: int64 customerId: maximum: 1000000000 minimum: 1 type: integer format: int64 merchantSubscriptionRefId: maxLength: 100 minLength: 0 type: string nullable: true networkTransactionId: maxLength: 100 minLength: 0 type: string nullable: true billingIntervalType: maxLength: 50 minLength: 0 type: string nullable: true billingIntervalCount: maximum: 1000000000 minimum: 1 type: integer format: int32 subscriptionStatusType: maxLength: 50 minLength: 0 type: string nullable: true subscriptionCancelType: maxLength: 50 minLength: 0 type: string nullable: true initialBillDate: maxLength: 20 minLength: 0 type: string nullable: true nextBillDate: maxLength: 20 minLength: 0 type: string nullable: true taxAddress: $ref: '#/components/schemas/AddressDTO' paymentMethodIds: type: array items: type: integer format: int64 nullable: true cancelledAt: maxLength: 40 type: string format: date-time nullable: true billingPlans: type: array items: $ref: '#/components/schemas/SubscriptionBillingPlanDTO' nullable: true message: maxLength: 500 minLength: 0 type: string nullable: true paymentProcessor: maxLength: 100 minLength: 0 type: string nullable: true processorMerchantId: maxLength: 100 minLength: 0 type: string nullable: true processorRawResponse: maxLength: 10000 minLength: 0 type: string nullable: true currency: maxLength: 3 minLength: 0 type: string nullable: true responseMessage: maxLength: 500 minLength: 0 type: string nullable: true responseCode: maxLength: 10 minLength: 0 type: string nullable: true additionalProperties: false StatusMessageResponse: type: object properties: message: type: string nullable: true errors: type: array items: type: string nullable: true fluentValidatorErrors: type: array items: $ref: '#/components/schemas/ValidationFailure' nullable: true additionalProperties: false ExistingPaymentMethodDTO: type: object properties: paymentMethodAuthorizationId: maximum: 1000000000 minimum: 1 type: integer format: int64 nullable: true paymentMethodId: maximum: 1000000000 minimum: 1 type: integer format: int64 nullable: true taxAmount: maximum: 10000000 minimum: 0 type: number format: double nullable: true originalNetworkTransactionId: maxLength: 100 minLength: 0 type: string nullable: true additionalProperties: false ReplaceSubscriptionPrimaryPaymentMethodDTO: type: object properties: billingFirstName: maxLength: 100 minLength: 0 type: string description: "**Conditional**: either both BillingFirstName and BillingLastName or BillingFullName must be provided.\r\n\r\nThe customers’s first name associated with a payment method that is used for billing purposes." billingLastName: maxLength: 100 minLength: 0 type: string description: "**Conditional**: either both BillingFirstName and BillingLastName or BillingFullName must be provided.\r\n\r\nThe customers’s last name associated with a payment method that is used for billing purposes." billingFullName: maxLength: 200 minLength: 0 type: string description: "**Conditional**: either BillingFullName or both BillingFirstName and BillingLastName must be provided.\r\n\r\nThe customers’s full name associated with a payment method that is used for billing purposes. " billingAddress: allOf: - $ref: '#/components/schemas/CreateAddressRequestDTO' description: >- The address associated with a payment method that is used for billing purposes. Either an Address ID or detailed address information can be provided. creditCard: allOf: - $ref: '#/components/schemas/CreditCardDTO' description: "**Conditional**: one payment method type is required.\r\n\r\nPayment card information." ach: allOf: - $ref: '#/components/schemas/AchDTO' description: "**Conditional**: one payment method type is required.\r\n\r\nACH account information." googlePay: allOf: - $ref: '#/components/schemas/GooglePayDTO' description: "**Conditional**: one payment method type is required.\r\n\r\nGoogle Pay information." applePay: $ref: '#/components/schemas/ApplePayDto' merchantPaymentMethodRefId: maxLength: 100 type: string description: Merchant's unique identifier for the payment method. taxAmount: maximum: 10000000 minimum: 0 type: number format: double nullable: true originalNetworkTransactionId: maxLength: 100 minLength: 0 type: string nullable: true additionalProperties: false AddressDTO: type: object properties: addressId: type: integer description: The unique identifier of the address. format: int64 addressLine1: maxLength: 40 minLength: 2 type: string description: Address. nullable: true addressLine2: maxLength: 40 minLength: 0 type: string description: Supplemental information for the address. city: maxLength: 25 minLength: 2 type: string description: City. nullable: true state: maxLength: 2 minLength: 2 type: string description: Two-letter state abbreviation. nullable: true postalCode: maxLength: 20 minLength: 2 type: string description: Postal Code. nullable: true phoneNumber: maxLength: 20 minLength: 0 type: string description: >- The phone number associated with a payment method that is used for billing purposes. email: maxLength: 100 minLength: 0 type: string description: The email associated with a billing address. format: email country: maxLength: 2 minLength: 2 type: string description: Country. nullable: true additionalProperties: false SubscriptionBillingPlanDTO: type: object properties: subscriptionBillingPlanId: maximum: 1000000000 minimum: 1 type: integer format: int64 subscriptionId: maximum: 1000000000 minimum: 1 type: integer format: int64 name: maxLength: 100 minLength: 0 type: string nullable: true value: maximum: 10000000 minimum: 0 type: number format: double startDate: maxLength: 20 minLength: 0 type: string nullable: true cyclesRemaining: maximum: 1000000000 minimum: 0 type: integer format: int32 cycleCount: maximum: 100 minimum: -1 type: integer format: int32 valueType: maxLength: 50 minLength: 0 type: string nullable: true additionalProperties: false ValidationFailure: type: object properties: propertyName: type: string nullable: true errorMessage: type: string nullable: true attemptedValue: nullable: true customState: nullable: true severity: $ref: '#/components/schemas/Severity' errorCode: type: string nullable: true formattedMessagePlaceholderValues: type: object additionalProperties: nullable: true nullable: true additionalProperties: false CreateAddressRequestDTO: type: object properties: addressLine1: maxLength: 3000 minLength: 0 type: string description: Address. nullable: true addressLine2: maxLength: 3000 minLength: 0 type: string description: Supplemental information for the address. city: maxLength: 3000 minLength: 0 type: string description: City. nullable: true state: maxLength: 2 minLength: 0 type: string description: State. nullable: true postalCode: maxLength: 20 minLength: 2 type: string description: Postal Code. nullable: true phoneNumber: maxLength: 20 minLength: 7 pattern: ^(?=.*\d)\+?[0-9\s\-\(\)\.]{7,20}$ type: string description: >- The phone number associated with a payment method that is used for billing purposes. email: maxLength: 3000 minLength: 0 type: string description: The email associated with a billing address. format: email country: maxLength: 2 minLength: 0 type: string description: >- The input must be a valid Alpha2 code, Alpha3 code, UN code, or full country name. addressId: maximum: 1000000000 minimum: 1 type: integer description: The unique identifier of the address. format: int64 additionalProperties: false CreditCardDTO: type: object properties: paymentAccountNumber: maxLength: 19 minLength: 8 type: string description: "**Conditional**: the PAN is required if the credit card payment method type is supplied in the request.\r\nThe number must be a valid credit card number and will be verified using the Luhn algorithm. Minimum length of 8 characters. Maximum length of 25 characters.\r\n\r\nPayment Account Number (PAN)." expirationDate: maxLength: 7 minLength: 0 type: string description: "**Conditional**: the expiration date is required if the credit card payment method type is supplied in the request.\r\n\r\nThe card expiration date." format: MMYY, MM/YY, MMYYYY, or MM/YYYY securityCode: maxLength: 4 minLength: 3 type: string description: "The card verification code. It is considered best practice to always include this value for card-not-present transactions.\r\n\r\nFailure to do so may lead to higher rates of declines, an increase in chargeback cases, and/or transaction downgrades." networkToken: allOf: - $ref: '#/components/schemas/NetworkTokenDto' description: External Network Token information. additionalProperties: false AchDTO: required: - accountNumber - routingNumber type: object properties: routingNumber: maxLength: 9 minLength: 9 pattern: ^[0-9]{9}$ type: string description: "**Conditional**: the routing number is required if the ACH payment method type is supplied in the request.\r\n\r\nThe 9-digit ACH routing number of the account." accountNumber: maxLength: 17 minLength: 4 pattern: ^[0-9]{4,17}$ type: string description: "**Conditional**: the account number is required if the ACH payment method type is supplied in the request.\r\nThe length should be between 4 and 17 characters.\r\n\r\nThe US bank account number from which the payment will be debited." accountType: maxLength: 20 type: string description: "**Conditional**: the account type is required if the ACH payment method type is supplied in the request.\r\n\r\nBank account type. Allowed values: Checking, Savings. Case-insensitive." additionalProperties: false GooglePayDTO: type: object properties: googlePayPaymentDataResponse: type: string description: "**Conditional**: the GooglePayPaymentDataResponse is required if the Google Pay payment method type is supplied in the request.\r\nMust contain the valid serialized JSON object.\r\n\r\nThe data returned by Google Pay." additionalProperties: false ApplePayDto: type: object properties: applePayToken: type: string nullable: true additionalProperties: false Severity: enum: - Error - Warning - Info type: string NetworkTokenDto: type: object properties: token: maxLength: 19 type: string description: Network token issued by a card network for a card. cryptogram: maxLength: 40 type: string description: >- One-time digital “stamp” of payment. Needed for all CIT (customer-initiated transactions), and the cryptogram will have to be generated by the same TR-TSP that provisioned the token. electronicCommerceIndicator: maxLength: 2 type: string description: >- An online payment security label indicating whether additional protection (such as 3-D Secure) was applied. paymentAccountReference: maxLength: 100 type: string description: >- A permanent unique identifier of a payment account that a payment system assigns to a card and uses instead of a real PAN within network tokens. expirationDate: maxLength: 7 minLength: 0 type: string description: Expiration date of the network token. format: MMYY, MM/YY, MMYYYY, or MM/YYYY nullable: true additionalProperties: false securitySchemes: Bearer: type: http scheme: bearer bearerFormat: JWT ````