External (0.0.1)

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Updates the payment method for a subscription contract by refreshing payment instrument from Shopify customer. This endpoint syncs the subscription's payment method with the customer's default payment method in Shopify.

Payment Method Update Process:

• Fetch Latest Payment: Retrieves customer's current default payment method from Shopify
• Update Contract: Associates new payment method with subscription contract
• Validate Payment: Ensures payment method is valid and active
• Sync Changes: Updates payment instrument in subscription billing system

Key Features:

• Automatic Sync: Pulls latest payment method from Shopify customer record
• Payment Validation: Verifies new payment method is usable for billing
• Contract Update: Updates Shopify subscription contract with new payment
• Failed Billing Recovery: Useful for updating payment after billing failures

Use Cases:

• Customer updates credit card and wants to apply to existing subscription
• Recover from failed billing by allowing payment method update
• Sync payment methods in customer portal workflows
• Update expired or invalid payment methods
• Switch between multiple saved payment methods
• Integration with custom payment update flows

Important Notes:

• Customer must have a default payment method in Shopify
• Payment method must be valid and not expired
• Updates are reflected immediately for future billing
• Does not retry failed billing attempts automatically

Authentication: Requires API key authentication via X-API-Key header or api_key parameter

Updates the persistent order note attached to a subscription contract. This note is automatically included with EVERY future recurring order generated from this subscription, appearing in Shopify admin order details and printable packing slips.

IMPORTANT: Recurring vs One-Time Notes

• This Endpoint (Contract Note): Applies to ALL FUTURE ORDERS permanently
• Billing Attempt Note (/subscription-billing-attempts-update-order-note): Applies to ONE SPECIFIC ORDER only
• Combined Behavior: If both notes exist, they are concatenated in the Shopify order

How It Works:

1. Accepts subscription contract ID and new order note text
2. Stores note in subscription contract record
3. Every time a new order is created (monthly, weekly, etc.), note is automatically added
4. Previous contract note is replaced (not appended)
5. Empty string clears the existing note
6. Does NOT affect past orders already created

Character Limits & Validation:

• Maximum Length: 5000 characters (Shopify order note limit)
• Encoding: UTF-8 supported (emojis, international characters allowed)
• HTML: Plain text only - HTML tags display as text
• Line Breaks: Use \n for line breaks (preserved in Shopify)
• Special Characters: Automatically escaped for safety

Common Use Cases:

1. Permanent Delivery Instructions

Example: "Always leave package at back door. Do not ring doorbell (baby sleeping)."
Use Case: Customer wants same delivery instructions for all future orders
Applies To: Every monthly shipment permanently

2. Gift Subscription Messages

Example: "This is a gift subscription for Mom. Happy Birthday! Love, Sarah"
Use Case: Gift subscription with recurring message
Applies To: All orders until subscription ends or note is changed

3. Special Handling Requirements

Example: "FRAGILE - Glass bottles. Handle with care. Keep upright during shipping."
Use Case: Delicate products requiring special warehouse handling
Applies To: Every fulfillment automatically

4. Customer Preferences

Example: "Customer is allergic to peanuts. NO peanut products. Double-check packaging."
Use Case: Critical dietary restrictions or preferences
Applies To: All future orders for safety compliance

5. Internal Merchant Notes

Example: "VIP customer - priority processing. Include bonus samples."
Use Case: Internal fulfillment team instructions
Applies To: All shipments to provide consistent VIP treatment

6. Clearing Unwanted Notes

Example: orderNote="" (empty string)
Use Case: Customer moved, no longer needs "Leave at neighbor" note
Result: Future orders have no contract note (one-time notes still possible)

Where Note Appears:

• Shopify Admin: Order details page under "Notes"
• Packing Slips: Printed on warehouse packing slips (if enabled)
• Order Confirmation Emails: May appear in customer emails (theme-dependent)
• Fulfillment Apps: Visible to third-party logistics providers
• Order APIs: Accessible via Shopify Order REST/GraphQL APIs

When to Use Contract Note vs Billing Attempt Note:

Error Handling:

400 - Bad Request:

• Order note exceeds 5000 character limit
• Contract ID doesn't belong to authenticated shop
• Contract is in invalid state

404 - Contract Not Found:

• Subscription contract ID doesn't exist
• Contract was deleted
• Wrong shop (contract belongs to different store)

Integration Best Practices:

1. Display Character Counter: Show "450 / 5000 characters" in UI
2. Preview Formatting: Show how line breaks will appear
3. Confirm Permanent Changes: Warn user "This note will appear on ALL future orders"
4. Sanitize Input: Strip HTML tags, prevent injection attacks
5. Show Current Note: Pre-fill form with existing note before update

Authentication: Requires API key authentication via X-API-Key header or api_key parameter

Sets the minimum number of billing cycles (payments) required before a customer can cancel their subscription. This is commonly used to enforce commitment periods or prevent early cancellations.

Key Features:

• Commitment Enforcement: Require customers to stay subscribed for a minimum period
• Cancellation Prevention: Blocks cancellation until minimum cycles are met
• Contract Terms: Implements contractual minimum billing requirements
• Flexible Duration: Set any number from 0 (no minimum) to higher values

Common Use Cases:

• 3-Month Minimum: Set minCycles=3 for quarterly commitment
• Annual Contract: Set minCycles=12 for yearly subscriptions
• Trial Completion: Require 1-2 cycles before allowing cancellation
• Remove Restriction: Set minCycles=0 or null to remove minimum

Behavior:

• Customer portal will show "X cycles remaining until cancellation allowed"
• Cancellation button disabled until minimum met
• Does not affect pausing subscriptions
• Applies to future billing cycles, not retroactive

Parameters:

• contractId (required): The subscription contract ID
• minCycles (optional): Number of minimum cycles (null or 0 = no minimum)

Authentication: Requires API key authentication via X-API-Key header or api_key parameter