External APIs (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 minimum number of billing cycles (orders) that a customer must complete before they can cancel their subscription. This creates a commitment period that helps with customer retention and business predictability.

What are Minimum Cycles? Minimum cycles represent a commitment period where:

• Customers must complete a specified number of orders
• Cancellation is blocked until the minimum is met
• Often tied to special pricing or promotional offers
• Counted from the subscription start date

Key Features:

• Updates commitment period for existing subscriptions
• Can increase or decrease minimum cycles
• Setting to null removes the minimum commitment
• Preserves all other subscription settings
• Automatically handles invalid discount codes
• Updates future billing queue after change

Common Use Cases:

• Promotional Offers: '3-month minimum for 50% off'
• Hardware Subsidies: '12-month commitment with free device'
• Loyalty Programs: Reduce minimum after customer proves loyalty
• Seasonal Campaigns: Temporary commitment requirements
• Contract Adjustments: Customer service exceptions

Impact on Customers:

• Cannot cancel via portal until minimum cycles complete
• Pause/resume typically still allowed (check settings)
• Shows commitment status in customer portal
• No automatic notification sent (consider sending separately)

Cycle Counting:

• Only successful billing attempts count toward minimum
• Failed payments don't increment the cycle count
• Skipped orders (if allowed) don't count
• Current cycle = successful past orders + 1

Interaction with Max Cycles:

• Min cycles must be less than or equal to max cycles
• If max cycles exist, subscription auto-cancels after maximum
• Common pattern: 3 min cycles, 12 max cycles

Best Practices:

• Clearly communicate commitment terms upfront
• Consider grandfathering existing customers
• Use reasonable minimums (typically 3-12 cycles)
• Document reason for changes in activity logs
• Send customer notification for transparency

Important Notes:

• Changes apply immediately to cancellation logic
• Doesn't affect past or in-progress orders
• Customer portal respects this setting automatically
• Activity log tracks old and new values
• Consider legal requirements in your jurisdiction

Authentication: Requires valid X-API-Key header

Updates the maximum number of billing cycles (orders) after which a subscription will automatically terminate. This creates a fixed-duration subscription that ends after a specific number of orders.

What are Maximum Cycles? Maximum cycles define subscription duration limits where:

• Subscription automatically cancels after the specified number of orders
• No further orders are generated once maximum is reached
• Useful for fixed-term offers, trials, or seasonal subscriptions
• Customer is notified before final order (if configured)

Key Features:

• Cannot set below current cycle count (prevents immediate cancellation)
• Setting to null creates an indefinite subscription
• Automatically reschedules order queue based on new limit
• Preserves all other subscription settings
• Validates against current subscription progress

Current Cycle Calculation:

• Current cycle = Successful billing attempts + 1
• Failed payments don't count toward maximum
• First order is cycle 1, second is cycle 2, etc.
• System prevents setting max below current position

Common Use Cases:

• Trial Subscriptions: '3-box trial' that auto-ends
• Seasonal Programs: '6-month summer subscription'
• Limited Series: '12-issue magazine subscription'
• Promotional Offers: 'First 5 boxes at special price'
• Gift Subscriptions: Fixed duration gifts that don't renew

What Happens at Maximum: When a subscription reaches its maximum cycles:

1. Final order is processed normally
2. Subscription status changes to CANCELLED
3. No future orders are scheduled
4. Customer receives cancellation notification
5. Cannot be reactivated (new subscription required)

Interaction with Min Cycles:

• Can have both min and max (e.g., 3 min, 12 max)
• Min cycles enforces commitment period
• Max cycles enforces termination
• Common pattern: Commitment with defined end

Queue Management: After updating max cycles:

• System recalculates future order schedule
• Removes orders beyond the new maximum
• Adjusts upcoming order notifications
• Updates subscription end date projections

Important Notes:

• Validation prevents accidental immediate cancellation
• Changes apply to future billing cycles only
• Activity log tracks old and new values
• Consider customer communication for changes
• Setting null removes any duration limit

Authentication: Requires valid X-API-Key header

Updates the delivery method for a subscription contract, supporting standard shipping, local delivery, and customer pickup options. The delivery method determines how future orders will be fulfilled.

Delivery Method Types: The system automatically determines the type based on the subscription's current delivery address:

• SHIPPING: Standard shipping to customer address (default)
• LOCAL: Local delivery within merchant's delivery zones
• PICK_UP: Customer pickup at designated location

Two Ways to Update:

1. Manual Parameters: Provide title, code, and presentment title directly
2. Delivery Method ID: Provide a Shopify DeliveryMethodDefinition ID to auto-populate all fields

Using Delivery Method ID: When providing a delivery-method-id:

• System fetches the method from Shopify's delivery profiles
• Automatically sets title, code, and presentment title
• Applies associated delivery price if defined
• ID can be numeric or full GraphQL ID format

Delivery Type Requirements:

• Standard Shipping: No additional requirements
• Local Delivery: Phone number must exist in delivery address
• Pickup: Pickup location must be configured in subscription

Price Updates:

• If using delivery-method-id with a fixed price, updates delivery price
• Manual updates don't change the delivery price
• Price changes affect all future orders

Side Effects:

• Creates activity log entry with method details
• May remove invalid discount codes automatically
• Updates apply to all future orders immediately
• No customer notification sent

Common Use Cases:

• Switch from standard shipping to express shipping
• Change pickup location for customer convenience
• Update local delivery options based on availability
• Apply seasonal delivery methods

Important Notes:

• Cannot change the delivery type (shipping/local/pickup) - only the method within that type
• Delivery methods must be configured in Shopify's shipping settings
• Changes don't affect orders already in fulfillment

Authentication: Requires valid X-API-Key header