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 base price of a specific product line item within a subscription contract. This endpoint intelligently handles pricing updates while preserving existing discount structures.

Key Features:

• Updates base price while maintaining discount cycles
• Automatically calculates prepaid subscription prices
• Preserves existing percentage/fixed discounts
• Validates actual price changes before updating
• Triggers shipping and discount recalculations
• Sends price update notifications to customers

Base Price vs Current Price:

• Base Price: The unit price before any multipliers
• Current Price: Base price × fulfillment multiplier
• For monthly billing/weekly delivery: Current = Base × 4
• For pay-per-delivery: Current = Base × 1

Discount Preservation: By default, this endpoint preserves existing discount cycles:

• Percentage discounts adjust to new base price
• Fixed discounts remain at same dollar amount
• Discount schedule (after X cycles) unchanged

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

• Automatically calculates fulfillment multiplier
• Updates current price accordingly
• Ensures correct billing amounts

Post-Update Actions:

1. Build-a-Box discount recalculation
2. Product discount synchronization
3. Shipping price updates
4. Customer email notifications
5. Activity log creation

Important Notes:

• Price changes apply to future orders only
• Cannot set price below $0.01
• Maximum 2 discount cycles preserved
• No update if price unchanged

Authentication: Requires valid X-API-Key header

Removes multiple product line items from an existing subscription contract in a single request. Products are removed sequentially, allowing partial success if errors occur.

Key Features:

• Sequential processing - items removed one by one
• Partial success allowed - previous removals persist if later ones fail
• Validates each removal against current subscription state
• Smart discount cleanup for line-specific discounts
• Comprehensive validation for each product removal
• Triggers all side effects after each successful removal

Processing Order Matters: Items are removed in the order provided:

1. First item validated and removed
2. Second item validated against updated state
3. Continue until all processed or error occurs
4. Returns final subscription state

Validation Per Item:

• Line item must exist in subscription
• At least one recurring product must remain
• Build-a-Box min/max quantities maintained
• Minimum cycle commitments honored
• One-time and free products don't count toward minimum

Discount Handling: When removeDiscount=true:

• Removes discounts applied ONLY to the removed line
• Preserves discounts that apply to multiple lines
• Each removal evaluates discounts independently
• Build-a-Box discounts auto-adjust based on quantity

Side Effects Per Removal: Each successful removal triggers:

• Activity log entry created
• Customer email sent (except one-time products)
• Shipping price recalculation
• Build-a-Box discount resync
• Product discount adjustments

Partial Success Scenarios: If removing 3 items and the 2nd fails:

• 1st item: Successfully removed
• 2nd item: Fails, error returned
• 3rd item: Not attempted
• Result: Subscription with 1st item removed

Performance Considerations:

• Each removal is a separate Shopify API transaction
• Multiple emails may be sent to customer
• Consider using single remove for 1-2 items
• Large batches may timeout
• Recommended max: 5-10 items per request

Build-a-Box Handling: For Build-a-Box subscriptions:

• Validates total quantity after EACH removal
• May fail mid-batch if minimum breached
• Discounts recalculate after each item
• Consider removal order carefully

Important Notes:

• NOT atomic - no rollback on partial failure
• Order of line IDs affects success probability
• Customer receives email per removed item
• All validations apply as if removing individually
• Response shows final state after all attempts

Authentication: Requires valid X-API-Key header

Removes a specific product line item from an existing subscription contract. Can optionally retain prorated discounts associated with the removed product.

Key Features:

• Validates minimum subscription requirements before removal
• Handles discount cleanup for line-specific discounts
• Enforces minimum cycle commitments on products
• Supports Build-a-Box quantity validation
• Automatic retry on concurrent modification conflicts
• Email notifications for subscription changes

Validation Rules:

• At least one recurring subscription product must remain after removal
• One-time products and free products don't count toward the minimum
• Products with minimum cycle commitments cannot be removed until fulfilled
• Build-a-Box subscriptions validate against minimum/maximum quantity rules

Discount Handling: When removeDiscount=true (default):

• Discounts applied only to the removed line item are deleted
• Discounts applied to multiple line items are retained
• System automatically identifies which discounts to remove

Retry Mechanism: The endpoint automatically retries in these scenarios:

• Concurrent modification detected (another process updated the subscription)
• Invalid discount code errors (removes problematic discount and retries)
• This ensures reliable operation in high-traffic environments

Post-Removal Actions:

• Activity log created for audit trail
• Email notification sent to customer (except for one-time products)
• Shipping price recalculated asynchronously
• Build-a-Box discounts resynced if applicable
• Product-specific discounts resynced

Authentication: Requires valid X-API-Key header