Comprehensive API documentation for managing subscriptions, payments, and related operations. These APIs allow you to programmatically manage subscription lifecycles, handle payments, configure products, and integrate subscription functionality into your applications.
External APIs
/- Add custom discount to subscription
Remove discount from subscription
Apply discount code to subscription
Add custom discount to su...
External APIs (0.0.1)
Download OpenAPI description
Languages
Servers
https://subscription-admin.appstle.com
Request
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
- https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-apply-discount
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X PUT \
'https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-apply-discount?contractId=123456789&discountCode=SAVE10&api_key=string' \
-H 'X-API-Key: sk_live_1234567890abcdef'Response
application/json
{ "id": "gid://shopify/SubscriptionContract/123456789", "status": "ACTIVE", "nextBillingDate": "2024-03-01T00:00:00Z", "customer": { "id": "gid://shopify/Customer/987654321", "email": "customer@example.com", "firstName": "John", "lastName": "Doe" }, "lines": { "edges": [ … ] }, "discounts": { "edges": [ … ] } }
Request
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
Query
Subscription contract ID to apply discount to. Provide the numeric ID without the gid:// prefix
Example: contractId=123456789
Discount percentage (1-100). Required when discountType is PERCENTAGE
Example: percentage=10
Custom title for the discount. If not provided, a default title will be generated
Example: discountTitle=Loyalty Discount
Number of billing cycles the discount applies to. Leave null for unlimited duration
Example: recurringCycleLimit=3
Application method: true = apply to each line item individually, false = apply to order subtotal
Default false
Fixed discount amount in store currency. Required when discountType is FIXED or PRICE
Example: amount=10.99
Type of discount to apply
Enum"PERCENTAGE""FIXED""PRICE"
Example: discountType=PERCENTAGE
- https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-add-discount
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X PUT \
'https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-add-discount?contractId=123456789&percentage=10&discountTitle=Loyalty+Discount&recurringCycleLimit=3&appliesOnEachItem=false&amount=10.99&discountType=PERCENTAGE&api_key=string' \
-H 'X-API-Key: sk_live_1234567890abcdef'Response
application/json
{ "id": "gid://shopify/SubscriptionContract/123456789", "status": "ACTIVE", "nextBillingDate": "2024-04-01T12:00:00Z", "customer": { "id": "gid://shopify/Customer/987654321", "email": "customer@example.com" }, "lines": { "edges": [ … ] }, "discounts": { "edges": [ … ] } }