curl --request PUT \
--url https://api-sandbox.revolv3.com/api/Subscriptions/{subscriptionId}/payment-method \
--header 'Content-Type: application/json-patch+json' \
--header 'x-revolv3-token: <api-key>' \
--data '
{
"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
}
}
'import requests
url = "https://api-sandbox.revolv3.com/api/Subscriptions/{subscriptionId}/payment-method"
payload = {
"existingPaymentMethod": None,
"paymentMethod": {
"taxAmount": 2.57,
"originalNetworkTransactionId": "test-transaction-id",
"billingAddress": {
"addressId": None,
"addressLine1": "100 Main Street",
"addressLine2": None,
"city": "Irvine",
"state": "CA",
"postalCode": "92602",
"phoneNumber": None,
"email": None,
"country": "US"
},
"creditCard": {
"paymentAccountNumber": "4111111111111111",
"expirationDate": "1025",
"securityCode": None,
"networkToken": None
},
"ach": None,
"googlePay": None,
"applePay": None,
"merchantPaymentMethodRefId": None,
"billingFirstName": "John",
"billingLastName": "Doe",
"billingFullName": None
}
}
headers = {
"x-revolv3-token": "<api-key>",
"Content-Type": "application/json-patch+json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {'x-revolv3-token': '<api-key>', 'Content-Type': 'application/json-patch+json'},
body: JSON.stringify({
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
}
})
};
fetch('https://api-sandbox.revolv3.com/api/Subscriptions/{subscriptionId}/payment-method', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-sandbox.revolv3.com/api/Subscriptions/{subscriptionId}/payment-method",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'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
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json-patch+json",
"x-revolv3-token: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-sandbox.revolv3.com/api/Subscriptions/{subscriptionId}/payment-method"
payload := strings.NewReader("{\n \"existingPaymentMethod\": null,\n \"paymentMethod\": {\n \"taxAmount\": 2.57,\n \"originalNetworkTransactionId\": \"test-transaction-id\",\n \"billingAddress\": {\n \"addressId\": null,\n \"addressLine1\": \"100 Main Street\",\n \"addressLine2\": null,\n \"city\": \"Irvine\",\n \"state\": \"CA\",\n \"postalCode\": \"92602\",\n \"phoneNumber\": null,\n \"email\": null,\n \"country\": \"US\"\n },\n \"creditCard\": {\n \"paymentAccountNumber\": \"4111111111111111\",\n \"expirationDate\": \"1025\",\n \"securityCode\": null,\n \"networkToken\": null\n },\n \"ach\": null,\n \"googlePay\": null,\n \"applePay\": null,\n \"merchantPaymentMethodRefId\": null,\n \"billingFirstName\": \"John\",\n \"billingLastName\": \"Doe\",\n \"billingFullName\": null\n }\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("x-revolv3-token", "<api-key>")
req.Header.Add("Content-Type", "application/json-patch+json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://api-sandbox.revolv3.com/api/Subscriptions/{subscriptionId}/payment-method")
.header("x-revolv3-token", "<api-key>")
.header("Content-Type", "application/json-patch+json")
.body("{\n \"existingPaymentMethod\": null,\n \"paymentMethod\": {\n \"taxAmount\": 2.57,\n \"originalNetworkTransactionId\": \"test-transaction-id\",\n \"billingAddress\": {\n \"addressId\": null,\n \"addressLine1\": \"100 Main Street\",\n \"addressLine2\": null,\n \"city\": \"Irvine\",\n \"state\": \"CA\",\n \"postalCode\": \"92602\",\n \"phoneNumber\": null,\n \"email\": null,\n \"country\": \"US\"\n },\n \"creditCard\": {\n \"paymentAccountNumber\": \"4111111111111111\",\n \"expirationDate\": \"1025\",\n \"securityCode\": null,\n \"networkToken\": null\n },\n \"ach\": null,\n \"googlePay\": null,\n \"applePay\": null,\n \"merchantPaymentMethodRefId\": null,\n \"billingFirstName\": \"John\",\n \"billingLastName\": \"Doe\",\n \"billingFullName\": null\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.revolv3.com/api/Subscriptions/{subscriptionId}/payment-method")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["x-revolv3-token"] = '<api-key>'
request["Content-Type"] = 'application/json-patch+json'
request.body = "{\n \"existingPaymentMethod\": null,\n \"paymentMethod\": {\n \"taxAmount\": 2.57,\n \"originalNetworkTransactionId\": \"test-transaction-id\",\n \"billingAddress\": {\n \"addressId\": null,\n \"addressLine1\": \"100 Main Street\",\n \"addressLine2\": null,\n \"city\": \"Irvine\",\n \"state\": \"CA\",\n \"postalCode\": \"92602\",\n \"phoneNumber\": null,\n \"email\": null,\n \"country\": \"US\"\n },\n \"creditCard\": {\n \"paymentAccountNumber\": \"4111111111111111\",\n \"expirationDate\": \"1025\",\n \"securityCode\": null,\n \"networkToken\": null\n },\n \"ach\": null,\n \"googlePay\": null,\n \"applePay\": null,\n \"merchantPaymentMethodRefId\": null,\n \"billingFirstName\": \"John\",\n \"billingLastName\": \"Doe\",\n \"billingFullName\": null\n }\n}"
response = http.request(request)
puts response.read_body{
"subscriptionId": 1,
"customerId": 1,
"merchantSubscriptionRefId": "1234-5678-9101",
"networkTransactionId": null,
"billingIntervalType": "Months",
"billingIntervalCount": 1,
"subscriptionStatusType": "Current",
"subscriptionCancelType": "Immediate",
"initialBillDate": "11/3/2026",
"nextBillDate": "12/3/2026",
"taxAddress": null,
"paymentMethodIds": [
1,
2
],
"cancelledAt": null,
"billingPlans": [
{
"subscriptionBillingPlanId": 1,
"subscriptionId": 0,
"name": "Billing Plan 1",
"value": 10.99,
"startDate": "11/3/2026",
"cyclesRemaining": -1,
"cycleCount": 0,
"valueType": "Standard"
},
{
"subscriptionBillingPlanId": 2,
"subscriptionId": 0,
"name": "Billing Plan 2",
"value": 14.99,
"startDate": "12/3/2026",
"cyclesRemaining": 12,
"cycleCount": 0,
"valueType": "Standard"
}
],
"message": null,
"paymentProcessor": null,
"processorMerchantId": null,
"processorRawResponse": null,
"currency": null,
"responseMessage": null,
"responseCode": null
}{
"message": "Unable to perform the request action with provided data.",
"serverRequestId": "4bf92f3577b34da6a3ce929d0e0e4736",
"clientRequestId": "cddab9d1-7caa-43d9-8b1d-f688134c44b0"
}{
"message": "Attempted to perform an unauthorized operation.",
"serverRequestId": "4bf92f3577b34da6a3ce929d0e0e4736",
"clientRequestId": "cddab9d1-7caa-43d9-8b1d-f688134c44b0"
}{
"message": "Unable to find an entity with the provided data.",
"serverRequestId": "4bf92f3577b34da6a3ce929d0e0e4736",
"clientRequestId": "cddab9d1-7caa-43d9-8b1d-f688134c44b0"
}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.
curl --request PUT \
--url https://api-sandbox.revolv3.com/api/Subscriptions/{subscriptionId}/payment-method \
--header 'Content-Type: application/json-patch+json' \
--header 'x-revolv3-token: <api-key>' \
--data '
{
"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
}
}
'import requests
url = "https://api-sandbox.revolv3.com/api/Subscriptions/{subscriptionId}/payment-method"
payload = {
"existingPaymentMethod": None,
"paymentMethod": {
"taxAmount": 2.57,
"originalNetworkTransactionId": "test-transaction-id",
"billingAddress": {
"addressId": None,
"addressLine1": "100 Main Street",
"addressLine2": None,
"city": "Irvine",
"state": "CA",
"postalCode": "92602",
"phoneNumber": None,
"email": None,
"country": "US"
},
"creditCard": {
"paymentAccountNumber": "4111111111111111",
"expirationDate": "1025",
"securityCode": None,
"networkToken": None
},
"ach": None,
"googlePay": None,
"applePay": None,
"merchantPaymentMethodRefId": None,
"billingFirstName": "John",
"billingLastName": "Doe",
"billingFullName": None
}
}
headers = {
"x-revolv3-token": "<api-key>",
"Content-Type": "application/json-patch+json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {'x-revolv3-token': '<api-key>', 'Content-Type': 'application/json-patch+json'},
body: JSON.stringify({
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
}
})
};
fetch('https://api-sandbox.revolv3.com/api/Subscriptions/{subscriptionId}/payment-method', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-sandbox.revolv3.com/api/Subscriptions/{subscriptionId}/payment-method",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'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
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json-patch+json",
"x-revolv3-token: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-sandbox.revolv3.com/api/Subscriptions/{subscriptionId}/payment-method"
payload := strings.NewReader("{\n \"existingPaymentMethod\": null,\n \"paymentMethod\": {\n \"taxAmount\": 2.57,\n \"originalNetworkTransactionId\": \"test-transaction-id\",\n \"billingAddress\": {\n \"addressId\": null,\n \"addressLine1\": \"100 Main Street\",\n \"addressLine2\": null,\n \"city\": \"Irvine\",\n \"state\": \"CA\",\n \"postalCode\": \"92602\",\n \"phoneNumber\": null,\n \"email\": null,\n \"country\": \"US\"\n },\n \"creditCard\": {\n \"paymentAccountNumber\": \"4111111111111111\",\n \"expirationDate\": \"1025\",\n \"securityCode\": null,\n \"networkToken\": null\n },\n \"ach\": null,\n \"googlePay\": null,\n \"applePay\": null,\n \"merchantPaymentMethodRefId\": null,\n \"billingFirstName\": \"John\",\n \"billingLastName\": \"Doe\",\n \"billingFullName\": null\n }\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("x-revolv3-token", "<api-key>")
req.Header.Add("Content-Type", "application/json-patch+json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://api-sandbox.revolv3.com/api/Subscriptions/{subscriptionId}/payment-method")
.header("x-revolv3-token", "<api-key>")
.header("Content-Type", "application/json-patch+json")
.body("{\n \"existingPaymentMethod\": null,\n \"paymentMethod\": {\n \"taxAmount\": 2.57,\n \"originalNetworkTransactionId\": \"test-transaction-id\",\n \"billingAddress\": {\n \"addressId\": null,\n \"addressLine1\": \"100 Main Street\",\n \"addressLine2\": null,\n \"city\": \"Irvine\",\n \"state\": \"CA\",\n \"postalCode\": \"92602\",\n \"phoneNumber\": null,\n \"email\": null,\n \"country\": \"US\"\n },\n \"creditCard\": {\n \"paymentAccountNumber\": \"4111111111111111\",\n \"expirationDate\": \"1025\",\n \"securityCode\": null,\n \"networkToken\": null\n },\n \"ach\": null,\n \"googlePay\": null,\n \"applePay\": null,\n \"merchantPaymentMethodRefId\": null,\n \"billingFirstName\": \"John\",\n \"billingLastName\": \"Doe\",\n \"billingFullName\": null\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.revolv3.com/api/Subscriptions/{subscriptionId}/payment-method")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["x-revolv3-token"] = '<api-key>'
request["Content-Type"] = 'application/json-patch+json'
request.body = "{\n \"existingPaymentMethod\": null,\n \"paymentMethod\": {\n \"taxAmount\": 2.57,\n \"originalNetworkTransactionId\": \"test-transaction-id\",\n \"billingAddress\": {\n \"addressId\": null,\n \"addressLine1\": \"100 Main Street\",\n \"addressLine2\": null,\n \"city\": \"Irvine\",\n \"state\": \"CA\",\n \"postalCode\": \"92602\",\n \"phoneNumber\": null,\n \"email\": null,\n \"country\": \"US\"\n },\n \"creditCard\": {\n \"paymentAccountNumber\": \"4111111111111111\",\n \"expirationDate\": \"1025\",\n \"securityCode\": null,\n \"networkToken\": null\n },\n \"ach\": null,\n \"googlePay\": null,\n \"applePay\": null,\n \"merchantPaymentMethodRefId\": null,\n \"billingFirstName\": \"John\",\n \"billingLastName\": \"Doe\",\n \"billingFullName\": null\n }\n}"
response = http.request(request)
puts response.read_body{
"subscriptionId": 1,
"customerId": 1,
"merchantSubscriptionRefId": "1234-5678-9101",
"networkTransactionId": null,
"billingIntervalType": "Months",
"billingIntervalCount": 1,
"subscriptionStatusType": "Current",
"subscriptionCancelType": "Immediate",
"initialBillDate": "11/3/2026",
"nextBillDate": "12/3/2026",
"taxAddress": null,
"paymentMethodIds": [
1,
2
],
"cancelledAt": null,
"billingPlans": [
{
"subscriptionBillingPlanId": 1,
"subscriptionId": 0,
"name": "Billing Plan 1",
"value": 10.99,
"startDate": "11/3/2026",
"cyclesRemaining": -1,
"cycleCount": 0,
"valueType": "Standard"
},
{
"subscriptionBillingPlanId": 2,
"subscriptionId": 0,
"name": "Billing Plan 2",
"value": 14.99,
"startDate": "12/3/2026",
"cyclesRemaining": 12,
"cycleCount": 0,
"valueType": "Standard"
}
],
"message": null,
"paymentProcessor": null,
"processorMerchantId": null,
"processorRawResponse": null,
"currency": null,
"responseMessage": null,
"responseCode": null
}{
"message": "Unable to perform the request action with provided data.",
"serverRequestId": "4bf92f3577b34da6a3ce929d0e0e4736",
"clientRequestId": "cddab9d1-7caa-43d9-8b1d-f688134c44b0"
}{
"message": "Attempted to perform an unauthorized operation.",
"serverRequestId": "4bf92f3577b34da6a3ce929d0e0e4736",
"clientRequestId": "cddab9d1-7caa-43d9-8b1d-f688134c44b0"
}{
"message": "Unable to find an entity with the provided data.",
"serverRequestId": "4bf92f3577b34da6a3ce929d0e0e4736",
"clientRequestId": "cddab9d1-7caa-43d9-8b1d-f688134c44b0"
}Headers
Optional identifier generated by the client to match its own logs with this request.
Allowed values: 1 to 128 characters, letters, digits and ., _, :, -.
Examples: order-12345, 3f2b8c1e-9d4a-4e7b-a1c5-6b0d2e8f7a91 (GUID), checkout:2026-11-02.17, retry_1.order-12345.
A valid value is returned in the Client-Request-Id response header and is stored with Revolv3 request logs, so it can be used when contacting support.
An invalid value is ignored and the request is processed normally. Do not send sensitive data in this header.
1 - 128^[A-Za-z0-9._:-]{1,128}$Body
Response
OK

