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

Comprehensive endpoint for updating a subscription line item's quantity, price, product variant, and/or selling plan in a single API call. Changes are applied intelligently - only modified values trigger updates.

Key Features:

• Update any combination of: quantity, price, variant, or selling plan
• Intelligent change detection - only updates what's different
• Automatic handling of prepaid subscription pricing
• Preserves existing discount cycles when updating price
• Partial success allowed - some updates may fail while others succeed
• Each change creates separate activity log entries

Prepaid Subscription Handling: For prepaid subscriptions (billing interval > delivery interval):

• When isPricePerUnit=true: Price is multiplied by interval ratio
• Example: Monthly billing, weekly delivery = price × 4
• When isPricePerUnit=false: Price is used as total billing amount

Update Process:

1. Validates line item exists in the subscription
2. Calculates interval multiplier for prepaid logic
3. Updates in order: selling plan → price → quantity → variant
4. Each update uses separate Shopify GraphQL mutation
5. Failures are logged but don't block other updates

Selling Plan Updates:

• Can update by ID or name (name takes precedence)
• Only updates if different from current plan
• Useful for changing delivery frequency options

Price Updates:

• Preserves existing discount cycles (up to 2 cycles)
• Recalculates cycle discounts based on new base price
• Triggers shipping price recalculation
• Sends price update email to customer

Quantity Updates:

• Validates against min/max quantity rules
• Updates Build-a-Box totals if applicable
• May trigger discount recalculations

Variant Updates:

• Changes the product itself (different SKU)
• Validates new variant exists and is available
• May affect pricing and discounts

Important Notes:

• All parameters except contractId and lineId are optional
• Provide only the values you want to change
• Price is always in shop's base currency
• Changes apply to future orders only

Authentication: Requires valid X-API-Key header

Updates the selling plan associated with a specific product line item in a subscription contract. Selling plans define the delivery schedule, pricing rules, and billing policies for subscription products.

What are Selling Plans? Selling plans are Shopify's way of defining subscription rules for products:

• Delivery Schedule: How often the product is delivered (e.g., 'every 2 weeks', 'monthly')
• Pricing Policy: Discounts and pricing tiers (e.g., '10% off', 'first order free')
• Billing Policy: When and how often customer is charged
• Plan Name: Customer-facing description like 'Deliver every month'

Key Features:

• Update by selling plan ID or name (name takes precedence if both provided)
• Validates line item exists before attempting update
• Only creates activity log if plan actually changes
• Uses Shopify's draft system for safe updates
• Preserves existing line item attributes and customizations

Common Use Cases:

• Change delivery frequency: Weekly → Monthly
• Switch pricing tiers: Regular → VIP pricing
• Update from old plan to new plan with better terms
• Migrate products to new selling plan groups
• Apply seasonal or promotional plans

Update Process:

1. Validates subscription contract and line item exist
2. Creates a draft of the subscription contract
3. Updates the line item's selling plan in the draft
4. Commits the draft to apply changes
5. Records activity log if plan changed

Impact of Selling Plan Changes:

• Delivery Schedule: Next and future orders follow new schedule
• Pricing: New plan's pricing applies from next billing
• Discounts: Plan-specific discounts are recalculated
• Billing: Billing frequency may change with the plan

Finding Selling Plans: To find available selling plans:

1. Check product's selling plan groups in Shopify admin
2. Use Shopify's GraphQL API to query selling plans
3. Plans must be active and associated with the product

Important Notes:

• Both sellingPlanId and sellingPlanName are optional, but at least one required
• If both provided, both are updated (name doesn't override ID)
• Plan must be valid for the product variant
• Changes apply to future orders only
• No customer notification sent (consider sending separately)

Authentication: Requires valid X-API-Key header

Updates the quantity of a specific product line item within a subscription contract. This comprehensive operation handles quantity validation, discount recalculation, and special Build-a-Box constraints.

Key Features:

• Updates quantity for future orders only
• Validates minimum/maximum quantities for line items
• Special handling for Build-a-Box subscriptions
• Automatic discount recalculation
• Shipping price updates
• Activity log tracking with old/new values

Build-a-Box (BAB) Validation: For Build-a-Box subscriptions:

• Enforces total minimum/maximum item counts
• Only counts recurring products (excludes one-time and free items)
• Validates across all BAB items in the subscription
• Can be bypassed with 'allowToAddProductQuantityMinMaxReached' permission

Line Item Validation: Individual products may have:

• Minimum quantity requirements (min_quantity attribute)
• Maximum quantity limits (max_quantity attribute)
• These are enforced separately from BAB constraints

Post-Update Actions:

1. Activity Logging: Records quantity change with old/new values
2. BAB Discount Sync: Recalculates Build-a-Box volume discounts
3. Product Discount Sync: Updates product-specific discounts
4. Shipping Price Update: Recalculates shipping based on new quantity

Discount Recalculation:

• Build-a-Box discounts adjust based on total quantity tiers
• May remove old discount codes and apply new ones
• Handles 'subscription contract has changed' retry scenarios

Important Notes:

• Line ID must be the full GraphQL ID format
• Quantity must be positive (minimum 1)
• Changes apply to all future orders
• Past or in-progress orders are not affected

Authentication: Requires valid X-API-Key header