# Subscription Discounts

APIs for managing discounts and promotional codes applied to subscriptions.

## Remove discount from subscription

 - [PUT /api/external/v2/subscription-contracts-remove-discount](https://developers.subscription.appstle.com/external-api-swagger/subscription-discounts/removediscountv2.md): Removes a specific discount from a subscription contract based on the discount ID. This will affect the pricing of all future orders generated by the subscription.

Key Features:
- Removes any type of discount: automatic, manual, or code-based
- Uses Shopify's draft system for safe removal
- Immediate effect on future order pricing
- Cannot be undone - discount must be re-applied if needed
- Activity log tracks removed discounts

Finding Discount IDs:
Discount IDs can be found in the subscription contract's discount collection:
- Query the subscription contract to see discounts.edges[].node.id
- Format: gid://shopify/SubscriptionManualDiscount/123456
- Each discount has a unique ID regardless of type

Types of Discounts:
- Manual Discounts: Applied via API (percentage, fixed, price)
- Code Discounts: Applied using discount codes
- Automatic Discounts: Applied by Shopify based on rules
- Build-a-Box Discounts: Volume-based discounts
- Selling Plan Discounts: Built into the subscription plan

Impact on Pricing:
When a discount is removed:
- Future orders use full price (no discount)
- Existing orders are not affected
- Other discounts remain active
- Shipping prices may be recalculated
- Customer sees updated pricing immediately

Common Use Cases:
- End promotional period discounts
- Remove expired or invalid discount codes
- Clear discounts before applying new ones
- Customer service adjustments
- Correct pricing errors

Important Notes:
- Cannot remove selling plan built-in discounts
- No customer notification sent (consider sending separately)
- Cannot selectively remove - removes entire discount
- Build-a-Box discounts may auto-reapply based on quantity
- Some discounts may be required by business rules

Post-Removal Considerations:
- Customer may notice price increase on next order
- May affect customer retention if unexpected
- Consider grace periods or notifications
- Document reason for removal in your system

Authentication: Requires valid X-API-Key header

## Apply discount code to subscription

 - [PUT /api/external/v2/subscription-contracts-apply-discount](https://developers.subscription.appstle.com/external-api-swagger/subscription-discounts/applydiscountcodev2.md): Applies a Shopify discount code to an existing subscription contract. The discount will be applied to future orders generated by this subscription.

Key Features:
- Validates discount code through Shopify's discount system
- Prevents duplicate discount code applications
- Uses database locking to prevent race conditions
- Automatically recalculates shipping prices if needed
- Creates audit trail through activity logs
- Returns updated subscription with discount details

Discount Code Validation:
- Must be an active Shopify discount code in the store
- Must be applicable to subscription orders
- Cannot be applied if already active on the subscription
- Subject to Shopify's discount rules and restrictions

Customer Portal Restrictions:
When called from customer portal context:
- If 'enableAllowOnlyOneDiscountCode' is enabled, customers cannot apply additional codes
- This restriction ensures single discount policy enforcement
- External API calls bypass this restriction

Concurrency Protection:
- Uses database-level locking on the subscription contract
- Prevents simultaneous discount applications
- Ensures data consistency in high-traffic scenarios

Post-Application Effects:
- Discount applies to all future orders from the subscription
- May trigger shipping price recalculation
- Creates 'DISCOUNT_APPLIED' activity log entry
- Updates subscription's discount collection

Important Notes:
- Discount codes are case-sensitive
- Invalid or expired codes will return appropriate errors
- Discounts stack according to Shopify's combination rules
- Some discounts may not be compatible with subscriptions

Authentication: Requires valid X-API-Key header

## Add custom discount to subscription

 - [PUT /api/external/v2/subscription-contracts-add-discount](https://developers.subscription.appstle.com/external-api-swagger/subscription-discounts/adddiscountv2.md): Creates and applies a custom manual discount to an existing subscription contract. This powerful endpoint supports multiple discount types and configurations for flexible pricing strategies.

Discount Types:
- PERCENTAGE: Percentage off the order (e.g., 10% off)
- FIXED: Fixed amount off the order (e.g., $10 off)
- PRICE: Override price (sets total to specific amount)

Key Features:
- Custom discount titles for easy identification
- Cycle limits for time-bound promotions
- Per-item or subtotal application options
- Stacks with other discounts per Shopify rules
- Automatic shipping price recalculation
- Activity logging for audit trails

Application Methods:
- Subtotal Discount (appliesOnEachItem=false): Applied to order total after line item calculations
- Per-Item Discount (appliesOnEachItem=true): Applied to each line item individually

Cycle Limits:
- Set recurringCycleLimit to apply discount for specific number of orders
- Leave null for unlimited duration
- Useful for '3 months at 20% off' promotions

Retention Campaigns:
This endpoint integrates with cancellation retention workflows:
- Can trigger merchant notifications
- Tracks discount usage for retention analytics
- Helps prevent churn with targeted offers

Important Notes:
- Discounts apply to future orders only
- Cannot modify discounts once applied (must remove and re-add)
- Some discount combinations may not be allowed by Shopify
- Price overrides should be used carefully

Authentication: Requires valid X-API-Key header