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 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

Adds a new product line item to an existing subscription contract. Can add either recurring products that will appear in each order or one-time products that appear only in the next order.

Key Features:

• Supports both recurring and one-time product additions
• Automatically applies appropriate pricing policies based on discount carry-forward settings
• Handles duplicate products by updating quantity (if enabled) or adding as new line
• Calculates prices based on billing/delivery frequency multipliers
• Sends email notifications to customers (unless suppressed)
• Creates activity logs for audit trail

Pricing Policy Application: The system applies discounts based on the store's discount carry-forward setting:

• PRODUCT_PLAN: Uses the discount from the product's selling plan
• EXISTING_PLAN: Applies the discount structure from existing subscription items
• PRODUCT_THEN_EXISTING: First attempts product plan, falls back to existing if not found

One-Time Products: Products added with isOneTimeProduct=true will:

• Only appear in the next scheduled order
• Be automatically removed after fulfillment
• Still attempt to match with appropriate selling plans
• Can have subscription discounts applied if store setting allows

Duplicate Product Handling: When adding a product that already exists in the subscription:

• If store has 'updateExistingQuantityOnAddProduct' enabled and product is not one-time: Updates existing quantity
• Otherwise: Adds as a new line item

Price Calculation:

• Base price is fetched considering contract currency and delivery country
• Price is multiplied by fulfillment frequency ratio (billing interval / delivery interval)
• Example: Monthly billing with weekly delivery = price × 4

Authentication: Requires valid X-API-Key header