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 status of a subscription contract. This allows pausing, resuming, or activating subscriptions to control billing and delivery.

Key Features:

• Pause Subscriptions: Temporarily stop billing and deliveries
• Resume Subscriptions: Reactivate paused subscriptions
• Activate Subscriptions: Start inactive subscriptions
• Activity Logging: All status changes are logged for audit trail
• Customer Restrictions: Includes minimum cycle checks when called from customer portal

Status Values:

• ACTIVE: Subscription is active and billing/delivering normally
• PAUSED: Subscription is temporarily paused (no billing, no deliveries)
• CANCELLED: Subscription is cancelled (use DELETE endpoint instead)

Pause vs. Cancel:

• Pause: Temporary hold, customer can resume anytime
• Cancel: Permanent termination, requires creating new subscription to restart

Common Use Cases:

• Vacation Hold: Customer going on vacation, pause deliveries temporarily
• Financial Pause: Customer needs temporary break from payments
• Product Surplus: Customer has too much product, pause until they use it
• Seasonal Pause: Pause subscriptions during off-season (e.g., lawn care in winter)
• Resume After Pause: Customer ready to restart after temporary hold
• Reactivate Failed: Reactivate subscription after payment method updated

Pause Behavior:

• Billing Paused: No charges while paused
• Deliveries Paused: No orders created while paused
• Next Billing Date: Preserved or recalculated on resume (merchant setting)
• Unlimited Duration: Pauses can be indefinite unless merchant sets limits

Resume Behavior:

• Immediate Reactivation: Subscription becomes active immediately
• Next Billing Date: Calculated based on pause duration settings
• Deliveries Resume: Next delivery scheduled according to interval

Customer Portal Restrictions: When called from customer portal (vs. merchant API):

• Minimum Cycles: Cannot pause/cancel until minimum billing cycles met
• Freeze Period: Updates may be frozen until minimum requirements satisfied
• Retention Rules: Special retention discounts may be offered on cancellation

Important Notes:

• Customer Communication: Consider sending email notifications on status changes
• Billing Cycles Not Lost: Paused cycles don't count toward minimums
• No Pro-rata: No refunds or credits when pausing mid-cycle

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

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

Changes the delivery/shipping frequency of a subscription contract. This allows customers to modify how often they receive their subscription orders.

Key Features:

• Flexible Delivery: Change delivery frequency (daily, weekly, monthly, yearly)
• Custom Intervals: Set custom interval counts (e.g., every 2 weeks, every 3 months)
• Independent from Billing: Delivery interval can differ from billing interval
• Immediate Effect: Changes apply to the next delivery cycle
• Activity Logging: All changes are logged for audit trail

Delivery Interval Options:

• DAY: Daily delivery (intervalCount: how many days)
• WEEK: Weekly delivery (intervalCount: how many weeks)
• MONTH: Monthly delivery (intervalCount: how many months)
• YEAR: Yearly delivery (intervalCount: how many years)

Common Examples:

• intervalCount=1, interval=MONTH: Deliver monthly
• intervalCount=2, interval=WEEK: Deliver every 2 weeks
• intervalCount=3, interval=MONTH: Deliver quarterly
• intervalCount=1, interval=WEEK: Deliver weekly
• intervalCount=6, interval=MONTH: Deliver twice a year

Billing vs. Delivery Intervals: These can be different! For example:

• Bill monthly, deliver weekly: Customer pays monthly but receives weekly shipments
• Bill quarterly, deliver monthly: Customer pays every 3 months but receives monthly shipments
• Bill annually, deliver monthly: Customer pays yearly upfront for monthly deliveries

Common Use Cases:

• Customer wants deliveries less frequently (save on shipping)
• Customer wants deliveries more frequently (use products faster)
• Adjust delivery to match consumption rate
• Seasonal frequency changes (more in summer, less in winter)
• Align deliveries with schedule (delivery when home from vacation)

Important Notes:

• Billing Date Unchanged: Only affects delivery schedule, not billing schedule
• Next Delivery Date: System recalculates next delivery date based on new interval
• Order Fulfillment: Each delivery creates a new order at the specified interval
• Prepaid Memberships: Particularly useful for prepaid plans with multiple deliveries

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

Changes the billing frequency of a subscription contract. This allows customers to modify how often they are charged for their membership.

Key Features:

• Flexible Billing: Change billing frequency (daily, weekly, monthly, yearly)
• Custom Intervals: Set custom interval counts (e.g., every 2 weeks, every 3 months)
• Immediate Effect: Changes apply to the next billing cycle
• Independent from Delivery: Billing interval can differ from delivery interval
• Activity Logging: All changes are logged for audit trail

Billing Interval Options:

• DAY: Daily billing (intervalCount: how many days)
• WEEK: Weekly billing (intervalCount: how many weeks)
• MONTH: Monthly billing (intervalCount: how many months)
• YEAR: Yearly billing (intervalCount: how many years)

Common Examples:

• intervalCount=1, interval=MONTH: Bill monthly
• intervalCount=2, interval=WEEK: Bill every 2 weeks
• intervalCount=3, interval=MONTH: Bill quarterly
• intervalCount=6, interval=MONTH: Bill semi-annually
• intervalCount=1, interval=YEAR: Bill annually

Common Use Cases:

• Customer wants to change from monthly to quarterly billing
• Switch from annual to monthly payments
• Adjust billing frequency to match cash flow
• Promotional frequency changes
• Align billing with payday schedules

Important Notes:

• Next Billing Date: System recalculates the next billing date based on new interval
• Pro-rata Billing: No pro-rata adjustment; new interval starts from next billing date
• Minimum Cycles: Respects minimum billing cycle requirements if configured
• Customer Portal Protection: Includes freeze checks if called from customer portal

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

Updates the next billing date for a subscription contract. This reschedules when the next payment will be charged for the membership.

Key Features:

• Flexible Rescheduling: Move billing date forward or backward
• Immediate Effect: Changes take effect immediately in the billing schedule
• Automatic Adjustments: Future billing dates recalculate based on frequency
• Customer Portal Compatible: Can be triggered from customer self-service portal
• Activity Logging: All changes are tracked in activity logs

Billing Date Update Rules:

• New date must be in the future (past dates are rejected)
• Cannot update if contract is paused or cancelled
• Cannot update if minimum billing cycles enforcement is active
• Date format must be ISO 8601 with timezone (e.g., 2024-12-25T10:00:00Z)
• Subsequent billing dates auto-calculate based on delivery frequency

Common Use Cases:

• Customer requests to postpone next delivery/billing
• Align billing date with customer payday or preference
• Skip a billing cycle due to vacation or temporary hold
• Synchronize multiple subscriptions to bill on same day
• Resolve payment timing conflicts or scheduling issues
• Adjust for seasonal demand or customer availability

Important Notes:

• Changing billing date does NOT change the billing cycle frequency
• If minimum cycles are configured, this may be restricted
• Activity logs capture old date, new date, and change source
• Customer receives updated billing schedule notification

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

Replaces an existing product variant with a new variant in a subscription contract. This allows customers to swap products in their membership while maintaining their subscription.

Key Features:

• Product Swapping: Replace any line item's variant with a different variant
• Quantity Preservation: Maintains the same quantity after variant swap
• Price Updates: New variant pricing is applied automatically
• Flexible Identification: Identify old variant by lineId OR variantId
• Activity Logging: All variant changes are logged for audit trail

Identification Methods: You can identify the old variant using either:

• oldLineId: The Shopify line item ID from the subscription contract
• oldVariantId: The Shopify product variant ID At least one of these must be provided.

Common Use Cases:

• Customer wants to change product flavor/color/size in their membership
• Swap discontinued products with new alternatives
• Change product preferences mid-subscription
• Update seasonal product selections
• Replace out-of-stock variants with alternatives

Important Notes:

• Immediate Effect: Variant change applies to the next billing cycle
• Validation: System validates new variant exists and is available
• Same Product: Old and new variants can be from different products
• Price Changes: Customer is charged the new variant's price

Variant ID Format:

• Accepts both numeric IDs and GraphQL IDs (gid://shopify/ProductVariant/...)
• System automatically converts to correct format

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