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 (0.0.1)
Download OpenAPI description
Languages
Servers
https://subscription-admin.appstle.com
Request
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
Query
Subscription contract ID to remove discount from
Example: contractId=123456789
ID of the discount to be removed. Must be the full GraphQL ID including the gid:// prefix. You can find discount IDs by querying the subscription contract and looking at the discounts collection. Format example: gid://shopify/SubscriptionManualDiscount/123456789
Example: discountId=gid://shopify/SubscriptionManualDiscount/123456789
- https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-remove-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-remove-discount?contractId=123456789&discountId=gid%3A%2F%2Fshopify%2FSubscriptionManualDiscount%2F123456789&api_key=string' \
-H 'X-API-Key: string'Response
application/json
{ "id": "gid://shopify/SubscriptionContract/123456789", "status": "ACTIVE", "nextBillingDate": "2024-04-01T00:00:00Z", "customer": { "id": "gid://shopify/Customer/987654321", "email": "customer@example.com" }, "lines": { "edges": [ … ] }, "discounts": { "edges": [] }, "deliveryPrice": { "amount": "5.99", "currencyCode": "USD" } }
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": [ … ] } }