> ## Documentation Index > Fetch the complete documentation index at: https://developers.appstle.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. **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 ## OpenAPI ````yaml /subscription/admin-api-swagger.json put /api/external/v2/subscription-contracts-update-existing-payment-method openapi: 3.0.1 info: description: >- Comprehensive API documentation for managing subscriptions, payments, and related operations. These APIs allow you to programmatically manage subscription lifecycles, handle payments, configure products, and integrate subscription functionality into your applications. title: Admin APIs version: 0.0.1 servers: - url: https://subscription-admin.appstle.com security: [] tags: - description: >- Core APIs for managing the complete subscription lifecycle including creation, updates, pausing, resuming, and cancellation of subscriptions. name: Subscription Management - description: >- APIs for managing subscription payment methods, processing payments, handling payment retries, and updating billing information. name: Subscription Payments - description: >- APIs for managing subscription contracts including delivery schedules, pricing, order notes, billing cycles, and shipping addresses. name: Subscription Contracts - description: >- APIs for managing products within subscriptions including adding, removing, updating quantities, and swapping products. name: Subscription Products - description: >- APIs for handling billing operations, payment processing, and financial transactions related to subscriptions. name: Billing & Payments - description: >- APIs for managing discounts and promotional codes applied to subscriptions. name: Subscription Discounts - description: >- APIs for managing one-time add-on products that can be purchased alongside recurring subscription items. name: Subscription One-Time Products - description: >- APIs for managing subscription plans, pricing tiers, and plan configurations. name: Subscription Plans - description: >- APIs for managing customizable product boxes and bundles where customers can select multiple items. name: Build-a-Box & Bundles - description: >- APIs for managing the product catalog including product information, variants, and inventory. name: Product Catalog - description: >- APIs for managing operational settings, configurations, and administrative functions. name: Operations & Settings - description: >- APIs powering the customer-facing portal where subscribers can manage their own subscriptions. name: Customer Portal - description: APIs for managing customer information, profiles, and account details. name: Customers - description: >- APIs for retrieving aggregated subscription data, customer subscription history, and account-level subscription information. name: Subscription Data - description: >- APIs for managing delivery profiles, shipping rates, free shipping configuration, and delivery method options on subscriptions. name: Delivery & Shipping - description: >- APIs for managing storefront customization including custom CSS, theme settings, label translations, and merchant-defined widget configuration. name: Customization - description: >- APIs for configuring cancellation flows, retention offers, cancellation reason management, and win-back automation. name: Customer Retention paths: /api/external/v2/subscription-contracts-update-existing-payment-method: put: tags: - Subscription Payments - Subscription Contracts summary: Update subscription payment method description: >- 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. **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 operationId: updateExistingPaymentMethodV2 parameters: - description: >- Subscription contract ID to update payment method for. Must be a valid contract ID that belongs to the authenticated shop. example: 123456789 in: query name: contractId required: true schema: format: int64 minimum: 1 type: integer - description: >- 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. example: gid://shopify/CustomerPaymentMethod/cdb2bbe581599b20439ebf636a380b8b in: query name: paymentMethodId required: true schema: pattern: ^gid://shopify/CustomerPaymentMethod/[a-zA-Z0-9]+$ type: string - description: API Key for authentication example: sk_live_1234567890abcdef in: header name: X-API-Key required: true schema: type: string responses: '200': content: application/json: example: message: Payment method updated successfully description: Payment method updated successfully '400': content: application/json: examples: Contract Not Found: description: Contract Not Found value: detail: No subscription contract found with the specified ID instance: >- /api/external/v2/subscription-contracts-update-existing-payment-method status: 400 title: Contract does not exist type: https://example.com/errors/bad-request Invalid Payment Method: description: Invalid Payment Method value: detail: Payment method ID is required and must be valid instance: >- /api/external/v2/subscription-contracts-update-existing-payment-method status: 400 title: UserGeneratedError:Invalid payment method provided type: https://example.com/errors/bad-request Invalid Payment Method Status: description: Invalid Payment Method Status value: detail: >- The payment method cannot be used because it is expired or revoked instance: >- /api/external/v2/subscription-contracts-update-existing-payment-method status: 400 title: UserGeneratedError:Payment method is expired type: https://example.com/errors/bad-request Payment Method Not Found: description: Payment Method Not Found value: detail: >- The specified payment method does not exist or is not associated with this customer instance: >- /api/external/v2/subscription-contracts-update-existing-payment-method status: 400 title: UserGeneratedError:Payment method not found type: https://example.com/errors/bad-request Shopify API Error: description: Shopify API Error value: detail: >- Shopify returned an error when attempting to update the payment method instance: >- /api/external/v2/subscription-contracts-update-existing-payment-method status: 400 title: >- UserGeneratedError:Unable to update payment method at this time type: https://example.com/errors/bad-request description: Invalid request or update failed '401': content: application/json: example: detail: Valid X-API-Key header is required instance: >- /api/external/v2/subscription-contracts-update-existing-payment-method status: 401 title: Authentication required type: https://example.com/errors/unauthorized description: Authentication required '403': content: application/json: example: detail: API key does not have permission to update payment methods instance: >- /api/external/v2/subscription-contracts-update-existing-payment-method status: 403 title: Insufficient permissions type: https://example.com/errors/forbidden description: Insufficient permissions to update payment method '404': description: Subscription contract not found '422': content: application/json: example: detail: >- Cannot update payment method while subscription has pending charges instance: >- /api/external/v2/subscription-contracts-update-existing-payment-method status: 422 title: Payment method update failed type: https://example.com/errors/unprocessable-entity description: Payment method update failed due to business rules ````