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

Creates a custom discount and applies it to a subscription contract. This endpoint allows you to create on-the-fly discounts without requiring pre-existing discount codes in Shopify.

Discount Creation & Application:

• Custom Discount: Creates discount directly on subscription contract
• Flexible Types: Supports percentage off or fixed amount off
• Cycle Limits: Optional limit on number of billing cycles discount applies
• Item-Level Control: Option to apply discount to each item vs entire order
• Immediate Effect: Discount applies to next billing cycle

Discount Parameters:

• Percentage: Percentage discount (e.g., 15 for 15% off) - use for discountType='PERCENTAGE'
• Amount: Fixed amount discount (e.g., 10.00 for $10 off) - use for discountType='FIXED_AMOUNT'
• Title: Display name for the discount (e.g., 'Loyalty Discount')
• Cycle Limit: Number of billing cycles discount applies (null = unlimited)
• Applies On Each Item: true = per-item discount, false = order-level discount

Discount Types:

• PERCENTAGE: Percentage-based discount (use 'percentage' parameter)
• FIXED_AMOUNT: Fixed dollar amount discount (use 'amount' parameter)

Cycle Limit Examples:

• recurringCycleLimit=1: Discount for first order only
• recurringCycleLimit=3: Discount for first 3 orders
• recurringCycleLimit=null: Discount applies forever

Use Cases:

• Customer retention offers (e.g., 20% off next 3 orders)
• Loyalty rewards and point redemptions
• Win-back campaigns with limited-time discounts
• Customer service compensation discounts
• Referral program rewards
• First-order discounts for new subscribers
• Seasonal promotions on existing subscriptions

Example Scenarios:

1. Retention Offer: 25% off for 2 billing cycles
   • percentage=25, recurringCycleLimit=2, discountType='PERCENTAGE'
2. Loyalty Reward: $5 off every order forever
   • amount=5.00, recurringCycleLimit=null, discountType='FIXED_AMOUNT'
3. First Order Deal: 50% off first order only
   • percentage=50, recurringCycleLimit=1, discountType='PERCENTAGE'

Returns: Updated subscription contract object with discount applied

Authentication: Requires API key authentication via X-API-Key header or api_key parameter

Replaces an existing product variant with a new variant in a subscription contract. This allows customers to swap products in their membership while maintaining their subscription.

Key Features:

• Product Swapping: Replace any line item's variant with a different variant
• Quantity Preservation: Maintains the same quantity after variant swap
• Price Updates: New variant pricing is applied automatically
• Flexible Identification: Identify old variant by lineId OR variantId
• Activity Logging: All variant changes are logged for audit trail

Identification Methods: You can identify the old variant using either:

• oldLineId: The Shopify line item ID from the subscription contract
• oldVariantId: The Shopify product variant ID At least one of these must be provided.

Common Use Cases:

• Customer wants to change product flavor/color/size in their membership
• Swap discontinued products with new alternatives
• Change product preferences mid-subscription
• Update seasonal product selections
• Replace out-of-stock variants with alternatives

Important Notes:

• Immediate Effect: Variant change applies to the next billing cycle
• Validation: System validates new variant exists and is available
• Same Product: Old and new variants can be from different products
• Price Changes: Customer is charged the new variant's price

Variant ID Format:

• Accepts both numeric IDs and GraphQL IDs (gid://shopify/ProductVariant/...)
• System automatically converts to correct format

Authentication: Requires API key authentication via X-API-Key header or api_key parameter

Adds a new product (line item) to an existing subscription contract. This allows customers or merchants to add products to their recurring subscription orders.

Key Features:

• Add Products: Include new products in future subscription deliveries
• Quantity Control: Specify how many units of the product to add
• Price Override: Set custom pricing for the added product
• Immediate Effect: Changes apply to next billing cycle
• Activity Logging: All additions are tracked in activity logs

Required Parameters:

• contractId: Subscription contract ID to modify
• variantId: Shopify product variant ID (with gid:// prefix or numeric)
• quantity: Number of units to add (must be positive integer)
• price: Price per unit in shop's base currency

Product Variant ID Format: Accepts two formats:

• Shopify GID: gid://shopify/ProductVariant/12345678901
• Numeric ID: 12345678901

Price Behavior:

• Price is per unit, not total
• Must be in shop's base currency (USD, EUR, etc.)
• Can override product's default price
• Does not include taxes or shipping
• Total line item cost = price × quantity

Line Item Addition Rules:

• Product variant must exist in Shopify catalog
• Product must be active and available
• Variant must have sufficient inventory (if tracked)
• Contract must be ACTIVE or PAUSED (not CANCELLED)
• Cannot add duplicate variants (use update quantity instead)

Common Use Cases:

• Customer adds complementary product to existing subscription
• Upsell additional products through customer portal
• Merchant adds bonus items to customer subscriptions
• Build custom "add-on" product selection interfaces
• Cross-sell related products to existing subscribers
• Create bundle upgrades (add multiple products at once)

Post-Addition Effects:

• Next billing amount increases by (price × quantity)
• Product appears in all future subscription deliveries
• Customer receives confirmation of subscription update
• Activity log records the addition with source (portal/merchant)
• Contract's next billing date remains unchanged

Integration Example:

PUT /api/external/v2/subscription-contract-add-line-item?
  contractId=123456&
  variantId=gid://shopify/ProductVariant/987654321&
  quantity=2&
  price=19.99

This adds 2 units of variant 987654321 at $19.99 each ($39.98 total) to contract 123456.

Important Notes:

• Changes apply to NEXT billing cycle, not current/past orders
• If product is out of stock, order may be delayed or skipped
• Price changes don't affect historical orders
• Consider inventory availability before adding products

Authentication: Requires API key authentication via X-API-Key header or api_key parameter