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
Updates the fixed delivery price for all future orders in a subscription contract. This allows manual override of calculated shipping rates with a custom delivery fee.
Key Features:
- Sets a fixed delivery price regardless of shipping calculations
- Overrides any dynamic shipping rates from carriers
- Applies to all future orders immediately
- Can set to 0 for free delivery
- Automatically handles invalid discount codes
- Tracks price changes in activity log
How Delivery Pricing Works:
- Calculated Rates: Default behavior uses carrier rates and rules
- Manual Override: This endpoint sets a fixed price
- Precedence: Manual price overrides all calculations
- Currency: Always in shop's base currency
Common Use Cases:
- Free Shipping Promotions: Set to 0.00
- Flat Rate Shipping: Fixed price regardless of location
- VIP Customer Rates: Special shipping prices
- Subscription Perks: Reduced delivery fees
- Price Corrections: Fix shipping calculation errors
- Regional Adjustments: Custom rates for specific areas
Impact on Orders:
- Next order uses new delivery price
- All future recurring orders affected
- Existing orders keep original pricing
- Customer sees updated total immediately
- No recalculation on address changes
Price Validation:
- Must be a valid decimal number
- Can be 0 for free shipping
- No maximum limit enforced
- Negative values typically rejected by Shopify
- Currency precision respected (e.g., 2 decimals for USD)
Side Effects:
- Invalid discount codes automatically removed
- Activity log created with old/new prices
- No customer email notification sent
- Shipping tax recalculated if applicable
- Total order value updated
Reverting to Calculated Rates: To restore dynamic shipping calculations:
- Use the sync shipping price endpoint
- Or update delivery method
- Manual price remains until explicitly changed
Important Notes:
- Price includes all delivery charges (shipping + handling)
- Does not affect delivery method or speed
- Consider customer communication for increases
- May affect subscription profitability
- Some payment methods may decline on total changes
Authentication: Requires valid X-API-Key header
Query
The unique identifier of the subscription contract
Example: contractId=123456789
New delivery price to be applied to the subscription contract. This is a fixed price that overrides any calculated shipping rates. Set to 0 for free delivery. Price must be in the shop's base currency.
Example: deliveryPrice=9.99
- https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-delivery-price
- 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-update-delivery-price?contractId=123456789&deliveryPrice=9.99&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", "displayName": "John Doe" }, "deliveryPrice": { "amount": "9.99", "currencyCode": "USD" }, "deliveryMethod": { "__typename": "SubscriptionDeliveryMethodShipping", "shippingOption": { … } }, "lines": { "edges": [ … ] }, "totalPrice": { "amount": "49.98", "currencyCode": "USD" } }
Request
Updates the status of a subscription contract to ACTIVE, PAUSED, or CANCELLED. This endpoint manages the lifecycle of subscriptions with automatic state tracking and notifications.
Status Transitions:
- ACTIVE: Resumes a paused subscription, enabling future billing and deliveries
- PAUSED: Temporarily suspends all billing and deliveries until manually resumed
- CANCELLED: Permanently terminates the subscription (irreversible)
Key Features:
- Validates status transitions (prevents same-status updates)
- Tracks status change timestamps for audit trails
- Sends automated email notifications to customers
- Creates detailed activity logs for each status change
- Handles concurrent modifications with automatic retry
- Adjusts next billing date when resuming subscriptions
Permission Requirements (Customer Portal): When called from customer portal context:
- PAUSED status requires 'pauseResumeSub' permission
- ACTIVE status (resuming) requires 'resumeSub' permission
- CANCELLED status requires 'cancelSub' permission
- External API calls bypass these permission checks
Status Change Side Effects:
- Activating: Recalculates next billing date, marks activation timestamp
- Pausing: Stops all scheduled orders, marks pause timestamp
- Cancelling: Terminates subscription permanently, marks cancellation timestamp
Error Recovery: The system automatically handles:
- Invalid discount codes by removing them and retrying
- Concurrent modifications by retrying the operation
- This ensures reliable status updates in production environments
Important Notes:
- Status values are case-insensitive
- Cancelled subscriptions cannot be reactivated
- Paused subscriptions retain all settings and can be resumed
- Email notifications are sent automatically unless internally suppressed
Authentication: Requires valid X-API-Key header
Query
Subscription contract ID to update. Provide the numeric ID without the gid:// prefix
Example: contractId=123456789
New status for the subscription contract. Case-insensitive.
Enum"ACTIVE""PAUSED""CANCELLED""active""paused""cancelled"
Examples: Pause subscription
Resume subscription
Cancel subscription
- https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-status
- 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-update-status?contractId=123456789&status=ACTIVE&api_key=string' \
-H 'X-API-Key: sk_live_1234567890abcdef'Response
No contentRequest
Updates the shipping address or delivery method for a subscription contract. Supports standard shipping, local delivery, and pickup options with comprehensive address validation.
Delivery Method Types:
- SHIPPING: Standard shipping to customer address (default)
- LOCAL: Local delivery within specified zip codes
- PICK_UP: Customer pickup at designated location
Key Features:
- Zip code restrictions for customer portal access
- Optional ShipperHQ address validation
- Automatic phone number handling for local delivery
- Email notifications to customers
- Shipping price recalculation
- Activity log tracking with old/new addresses
Zip Code Validation (Customer Portal Only): When called from customer portal:
- Standard shipping: Validates against 'allowToSpecificZipCode' setting
- Local delivery: Validates against 'allowToSpecificZipCodeForLocalDelivery' setting
- External API calls bypass zip code restrictions
Address Validation:
- If ShipperHQ is configured, addresses are validated for deliverability
- Invalid addresses will return appropriate error messages
- Helps prevent failed deliveries and shipping issues
Special Handling:
- Local delivery addresses missing phone numbers are auto-populated
- Uses customer's phone if available, otherwise defaults to placeholder
- Handles missing address components gracefully
Post-Update Actions:
- Sends 'SHIPPING_ADDRESS_UPDATED' email to customer
- Creates activity log with address change details
- Triggers asynchronous shipping price recalculation
- May remove invalid discount codes automatically
Important Notes:
- Province codes should use ISO 3166-2 format (e.g., 'NY' for New York)
- Country codes should use ISO 3166-1 alpha-2 format (e.g., 'US')
- Phone numbers should include country code for international addresses
- Pickup locations must be pre-configured in Shopify
Authentication: Requires valid X-API-Key header
Query
Bodyapplication/jsonrequiredSubscription contract ID to update. Provide the numeric ID without the gid:// prefix
Example: contractId=123456789
New shipping address and delivery method details
- https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-shipping-address
- 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-update-shipping-address?contractId=123456789&api_key=string' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: sk_live_1234567890abcdef' \
-d '{
"methodType": "SHIPPING",
"firstName": "John",
"lastName": "Doe",
"company": "Acme Corp",
"address1": "456 New Street",
"address2": "Suite 200",
"city": "Los Angeles",
"provinceCode": "CA",
"countryCode": "US",
"zip": "90001",
"phone": "+12135551234"
}'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" }, "deliveryMethod": { "__typename": "SubscriptionDeliveryMethodShipping", "address": { … } }, "deliveryPrice": { "amount": "7.99", "currencyCode": "USD" } }