Update subscription payment method

Updates the payment method for an existing subscription contract to use a different existing payment method. The new payment method must already be associated with the customer in Shopify.

Full behavior, validation rules, and side effects

Important Notes:

• The payment method must already exist in the customer’s Shopify payment methods
• Only valid, non-revoked payment methods can be used
• The update is processed through Shopify’s subscription draft system
• Payment method details are cached locally after successful update

Process Flow:

1. Validates subscription contract exists
2. Creates a draft update in Shopify
3. Updates the draft with new payment method
4. Commits the draft to apply changes
5. Caches payment instrument details locally
6. Records activity log entry

Authentication: Requires valid X-API-Key header

PUT /api/external/v2/subscription-contracts-update-existing-payment-method

Update subscription payment method

cURL

curl --request PUT \
  --url https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-existing-payment-method \
  --header 'X-API-Key: <x-api-key>'

200

Example

{
  "message": "Payment method updated successfully"
}

Headers

X-API-Key · string · required

API Key for authentication

Query Parameters

contractId · integer<int64> · required

Subscription contract ID to update payment method for. Must be a valid contract ID that belongs to the authenticated shop.

Required range: x >= 1

paymentMethodId · string · required

ID of the existing customer payment method to use. Must be a valid Shopify GraphQL payment method ID in the format 'gid://shopify/CustomerPaymentMethod/{id}'. The payment method must:

• Already exist in the customer's Shopify account
• Be in a valid state (not expired or revoked)
• Be authorized for subscription use

You can retrieve available payment methods using the customer payment methods endpoint.

Pattern: ^gid://shopify/CustomerPaymentMethod/[a-zA-Z0-9]+$

Response

200

application/json

Payment method updated successfully