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

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

Adds multiple product line items to an existing subscription contract in a single request. This batch operation is more efficient than making multiple individual requests and ensures all products are added with consistent processing.

Key Features:

• Batch addition of multiple products in one API call
• All products are added as recurring items (not one-time)
• Automatic quantity defaulting (0 or null becomes 1)
• Sequential processing with full validation for each item
• Returns final subscription state after all additions
• Same pricing and discount logic as single-item endpoint

Processing Behavior:

• Products are added sequentially, not in parallel
• If any product fails, previous additions remain
• Each product goes through full validation
• Existing product handling follows store settings
• Activity logs created for each product added

Duplicate Product Handling: If a product already exists in the subscription:

• With 'updateExistingQuantityOnAddProduct' enabled: Updates quantity
• Without setting: Adds as new line item
• Setting applies to all products in the batch

Pricing and Discounts: Each product receives:

• Appropriate selling plan assignment
• Discount carry-forward based on store settings
• Currency and country-specific pricing
• Fulfillment frequency multiplier application

Build-a-Box Validation:

• Applied if any product has _bb_id attribute
• Validates total quantity after all additions
• May fail entire batch if limits exceeded

Post-Processing: After all products are added:

• Build-a-Box discounts recalculated once
• Product discounts synchronized
• Single email notification sent
• Shipping price updated once

Important Notes:

• Maximum recommended batch size: 10-20 products
• Larger batches may timeout
• All products become recurring items
• Use single-item endpoint for one-time products

Authentication: Requires valid X-API-Key header