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

Applies an existing Shopify discount code to a subscription contract. The discount code must already exist in Shopify and be valid for subscription usage.

Discount Application Process:

• Code Validation: Verifies discount code exists in Shopify
• Eligibility Check: Ensures code is valid for subscription use
• Contract Update: Applies discount to subscription contract
• Price Recalculation: Updates subscription pricing with discount applied
• Activity Logging: Records discount application event

Key Features:

• Existing Code Support: Uses Shopify discount codes already created in admin
• Automatic Validation: Checks code validity and subscription eligibility
• Immediate Application: Discount applies to next billing cycle
• Contract Synchronization: Keeps Shopify contract in sync with discount

Discount Code Requirements:

• Must exist in Shopify admin
• Must be active and not expired
• Must be eligible for subscription purchases
• Usage limits must not be exceeded

Use Cases:

• Allow customers to apply promotional codes to existing subscriptions
• Customer service applying retention discounts
• Reward program integration with discount codes
• Referral program discount application
• Seasonal promotion code application
• Win-back campaign discount codes

Returns: Updated subscription contract object with discount applied

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

Adds a new product variant to a subscription contract's recurring line items. The product will be included in all future recurring orders.

Product Addition Process:

• Variant Validation: Verifies product variant exists and is available
• Add to Contract: Adds line item to subscription's recurring products
• Quantity Setting: Sets initial quantity for the product
• Price Calculation: Calculates pricing including any applicable discounts
• Shipping Update: May recalculate shipping if weight/dimensions change
• Activity Logging: Records product addition event

Key Features:

• Recurring Addition: Product added to every future order
• Quantity Control: Specify exact quantity to add
• Discount Inheritance: New item inherits subscription-level discounts
• Immediate Effect: Applies to next billing cycle
• Freeze Protection: Validates subscription isn't frozen before minimum cycles

Variant ID Format:

• Accepts Shopify variant ID as string
• Can be numeric ID or GraphQL format
• Example: "12345678" or "gid://shopify/ProductVariant/12345678"

Use Cases:

• Customer upgrades subscription to include more products
• Cross-sell additional products to existing subscribers
• Allow customers to customize subscriptions in portal
• Add seasonal products to subscriptions
• Build-a-box subscription customization
• Upsell workflows during customer interactions

Important Notes:

• Product must be available for purchase
• Subscription must not be frozen (before min cycles)
• Price updates automatically with subscription billing
• Quantity must be positive integer

Returns: Updated subscription contract object with new line item

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

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