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

Changes the delivery shipping address for a subscription contract. This allows customers to update where their subscription orders are delivered.

Key Features:

• Full Address Update: Change complete shipping address in one call
• Address Validation: System validates address format and country codes
• Immediate Effect: New address applies to the next delivery
• Activity Logging: All address changes are logged for audit trail
• International Support: Supports addresses in all countries

Required Address Fields:

• firstName: Recipient's first name
• lastName: Recipient's last name
• address1: Street address line 1
• city: City name
• countryCode: ISO 3166-1 alpha-2 country code (e.g., US, CA, GB)
• zip: Postal/ZIP code

Optional Address Fields:

• address2: Apartment, suite, unit number
• company: Company name (for business addresses)
• phone: Contact phone number
• provinceCode: State/province code (e.g., CA, NY, ON)

Common Use Cases:

• Customer Moved: Update address after relocation
• Temporary Address: Ship to vacation home or temporary location
• Gift Recipient: Change recipient for gift subscriptions
• Correct Typos: Fix address errors from initial signup
• Business to Home: Switch between business and residential addresses
• Seasonal Address: Update for snowbird/seasonal residents

Country and Province Codes:

• countryCode: Use ISO 3166-1 alpha-2 codes
  • Examples: US (United States), CA (Canada), GB (United Kingdom), AU (Australia)
• provinceCode: Use ISO 3166-2 subdivision codes
  • US Examples: CA (California), NY (New York), TX (Texas)
  • Canada Examples: ON (Ontario), BC (British Columbia), QC (Quebec)

Address Validation:

• Format Validation: System checks required fields are present
• Country Validation: Verifies country code is valid
• Province Validation: Checks province code matches country
• Postal Code: Validates postal code format for country

Important Notes:

• Shipping Rate Recalculation: New address may have different shipping costs
• Delivery Method: System automatically selects appropriate delivery method
• Next Order Only: Only affects future orders, not orders already placed
• Address Book: Consider updating customer's default address separately
• PO Boxes: Some delivery methods may not support PO Box addresses

Shipping Cost Impact:

• Changing address may change shipping costs for future deliveries
• International addresses typically have higher shipping costs
• Remote/rural areas may have additional delivery fees
• Consider notifying customer of cost changes

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

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