# Subscription Payments

APIs for managing subscription payment methods, processing payments, handling payment retries, and updating billing information.

## Send payment method update email to customer

 - [PUT /api/external/v2/subscription-contracts-update-payment-method](https://developers.subscription.appstle.com/external-api-swagger/subscription-payments/updatepaymentmethodv2.md): Triggers Shopify to send an email to the subscription customer with a secure link to update their payment method. This endpoint initiates Shopify's native payment update flow without requiring direct payment handling.

Key Features:
- Sends official Shopify payment update email to customer
- Customer receives secure link to Shopify-hosted payment update page
- No PCI compliance required - Shopify handles all payment data
- Supports all Shopify-supported payment methods
- Automatically updates subscription after customer completes the process

Process Flow:
1. API call triggers email send request to Shopify
2. Shopify sends branded email to customer's registered email
3. Customer clicks secure link in email
4. Customer authenticates on Shopify-hosted page
5. Customer adds/updates payment method
6. Subscription automatically uses new payment method

Email Details:
- Sent from Shopify's email servers
- Uses store's configured sender email
- Subject line typically: "Update your payment method"
- Contains secure, time-limited link
- Shopify-branded with store information

Use Cases:
- Failed payment recovery
- Expiring credit card updates
- Customer-requested payment changes
- Proactive payment method maintenance

Important Notes:
- Customer must have valid email address
- Email cannot be customized (Shopify template)
- Link expiration time set by Shopify
- Multiple emails can be sent if needed
- No webhook for completion - poll contract for updates

Rate Limiting:
- Subject to Shopify's email sending limits
- Recommended: Wait 24 hours between sends to same customer
- Excessive sends may be blocked by Shopify

Authentication: Requires valid X-API-Key header

## Update subscription payment method

 - [PUT /api/external/v2/subscription-contracts-update-existing-payment-method](https://developers.subscription.appstle.com/external-api-swagger/subscription-payments/updateexistingpaymentmethodv2.md): 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