Skip to main content

Update Membership Payment Method API

Update the payment method on an active membership subscription contract using the Rivo REST API.

Written by Stuart Chaney

Update Membership Payment Method API

Use this endpoint to update the payment method used for a customer’s active membership subscription.
​

This endpoint is intended for server-side integrations.

This endpoint is gated by account access. If you receive a feature-enabled error, contact your Rivo account manager.


​
​

Before You Begin

  • Make sure you have a valid Rivo REST API key.
    See Manage API keys.

  • Have the subscription contract ID you want to target.

  • Have the Shopify customer payment method ID you want to use.


​
​

Endpoint

PUT /merchant_api/v1/memberships/subscription_contracts/{id}/payment_method
​

{id} is the subscription contract ID.
​

Headers

  • Authorization: {your_api_key}

  • Content-Type: application/json


​

Body

{ "payment_method_id": "gid://shopify/CustomerPaymentMethod/999"}

You can send payment_method_id as a full Shopify GID or as the numeric ID value.


​
​

Example Request

curl --request PUT \ --url https://developer-api.rivo.io/merchant_api/v1/memberships/subscription_contracts/123456/payment_method \ --header 'Authorization: your_api_key_here' \ --header 'Content-Type: application/json' \ --data '{"payment_method_id":"gid://shopify/CustomerPaymentMethod/999"}'


​
​

Success Response

On success, the API returns 200 OK with the updated subscription contract object.

{ "data": { "type": "subscription_contract", "id": 123456, "attributes": { "remote_id": 123456, "customer_id": 7855248179442, "origin_order_id": 99887766, "status": "active", "billing_interval": "month", "last_payment_status": "paid", "next_billing_date_at": "2026-04-01T00:00:00Z", "remote_created_at": "2026-01-10T17:03:22Z", "remote_updated_at": "2026-03-17T09:12:01Z", "currency_code": "USD" } }}


​
​

Error Responses

Status

Error message

When it happens

400

Validation error for missing required params

payment_method_id is missing

401

Unauthorized

API key is missing or invalid

404

SubscriptionContractNotFound

The contract ID does not exist for your store

422

This is a feature your account manager must enable

Endpoint access is not enabled

422

Customer not found for subscription contract

The contract does not resolve to a valid customer

422

Failed to update payment method

Update failed upstream

429

Rate limit exceeded. Retry after 1 second.

Too many Merchant API requests in a short window


​
​

Notes

  • Use this endpoint for active membership subscriptions.

  • The default Merchant API rate limit is 15 requests per second per store.

  • If needed, you can also pass your API key as access_token in query parameters. Using the Authorization header is recommended.

Related Articles
Did this answer your question?