Hi ${customerName},
Manage your subscription:
Manage SubscriptionLink expires ${formatDate(response.tokenExpirationTime)}
`; ``` **SMS Notification:** ```javascript const { manageSubscriptionLink } = await getPortalLink(customerId); const shortUrl = await shortenUrl(manageSubscriptionLink); await sendSMS(customerPhone, `Your subscription ships tomorrow! Manage it here: ${shortUrl}` ); ``` **Important Considerations:** **Token Expiration:** - Tokens expire after exactly 2 hours - Generate new token if expired - Don't store tokens long-term - Best practice: Generate on-demand **Domain Selection:** - Uses shop's `publicDomain` if configured - Falls back to Shopify domain (.myshopify.com) - Respects custom domain settings - Maintains brand consistency **Customer Lookup Errors:** - Email not found: Returns 400 error - Invalid customer ID: Returns error - No parameters provided: Returns 400 - Both parameters provided: Uses customerId **Security Notes:** - Tokens cannot be used across different shops - Cannot be used for different customers - Tampering invalidates token - Consider rate limiting token generation **Best Practices:** 1. **Generate On-Demand**: Create tokens when needed, not in advance 2. **Use HTTPS**: Always serve links over HTTPS 3. **Show Expiry**: Inform customers when link expires 4. **URL Shortening**: Use URL shorteners for SMS/print materials 5. **Track Usage**: Monitor which emails drive portal visits 6. **Prefer Customer ID**: Use customerId when available for faster lookup **Comparison with /manage-subscription-link/{customerId}:** - This endpoint: Flexible lookup (ID or email) - Path parameter version: Customer ID only - Both generate identical tokens - Use this for email-based flows **Authentication:** Requires valid X-API-Key header # Generate customer portal link Source: https://developers.appstle.com/subscription-admin-api/customers/generate-customer-portal-link /subscription/admin-api-swagger.json get /api/external/v2/manage-subscription-link/{customerId} Generates a secure, time-limited link that allows customers to access their subscription management portal. This link provides customers with self-service capabilities to manage their subscriptions without requiring login credentials. **Key Features:** - Generates unique encrypted token for customer authentication - Token expires after 2 hours for security - Direct access to subscription management without password - Uses store's custom domain when available - Supports white-label customer portals **Token Security:** - Token contains encrypted customer ID, shop, and timestamp - Cannot be reused after expiration - Unique token generated for each request - Cryptographically secure encryption **Customer Portal Access:** Once customers click the link, they can: - View all active subscriptions - Update payment methods - Change delivery addresses - Modify product quantities - Pause or cancel subscriptions - Update delivery schedules - Apply discount codes - View order history **Use Cases:** - Email campaigns with 'Manage Subscription' CTAs - Customer service providing quick access - Post-purchase email flows - Account management integrations - Reducing support ticket volume **URL Structure:** The generated URL follows this pattern: `https://[store-domain]/[manage-subscription-path]?token=[encrypted-token]` **Important Notes:** - Links are single-use and expire after 2 hours - New link must be generated after expiration - Customer ID must be valid and active - Store must have customer portal configured **Authentication:** Requires valid X-API-Key header # Get customer details with subscriptions Source: https://developers.appstle.com/subscription-admin-api/customers/get-customer-details-with-subscriptions /subscription/admin-api-swagger.json get /api/external/v2/subscription-customers/{id} Retrieves comprehensive customer information including their subscription contracts. This endpoint provides customer profile data along with a paginated list of their active and historical subscriptions. **Key Features:** - Customer profile information (name, email, phone, addresses) - Complete subscription history with pagination - Payment method details - Customer account state and metadata - Order history related to subscriptions - Customer tags and notes **Subscription Data Included:** - All subscription contracts (active, paused, cancelled) - Contract details with line items - Billing and delivery policies - Next billing dates and amounts - Applied discounts **Pagination:** - Subscription contracts are paginated - Default page size varies by Shopify plan - Use cursor for subsequent pages - Cursor-based pagination ensures consistency **Use Cases:** - Customer service representatives viewing customer details - Integration with CRM systems - Customer analytics and reporting - Subscription management interfaces - Billing reconciliation **Important Notes:** - Customer ID is numeric (without gid:// prefix) - Returns null if customer not found - Includes both active and inactive subscriptions - Payment methods may be masked for security **Authentication:** Requires valid X-API-Key header # Get customer payment methods from Shopify Source: https://developers.appstle.com/subscription-admin-api/customers/get-customer-payment-methods-from-shopify /subscription/admin-api-swagger.json get /api/external/v2/subscription-contract-details/shopify/customer/{customerId}/payment-methods Retrieves all payment methods associated with a customer directly from Shopify's payment API. This endpoint returns detailed information about stored payment instruments including credit/debit cards, digital wallets, and other payment methods that the customer can use for subscription billing. **What This Endpoint Does:** Queries Shopify's GraphQL API to fetch the customer's payment methods, including active instruments and optionally revoked (expired, removed, or failed) payment methods. This provides real-time payment method data directly from Shopify's payment vault. **Payment Method Types Supported:** **Credit/Debit Cards:** - Visa, Mastercard, American Express, Discover - Card last 4 digits - Expiry month and year - Card brand and type - Billing address associated with card **Digital Wallets:** - Shop Pay - Apple Pay - Google Pay - PayPal (when stored) **Alternative Payment Methods:** - Bank accounts (ACH, SEPA) - Buy Now Pay Later instruments - Store credit **Payment Method Information Returned:** **For Each Payment Method:** - **Payment Instrument ID**: Unique identifier (used for updates) - **Display Name**: Human-readable name (e.g., "Visa ending in 4242") - **Payment Type**: Card, wallet, bank account, etc. - **Status**: ACTIVE, REVOKED, EXPIRED, FAILED - **Is Default**: Whether this is the customer's default payment method - **Last 4 Digits**: For cards and bank accounts - **Expiry Date**: For cards (month/year) - **Brand**: Visa, Mastercard, Amex, etc. - **Billing Address**: Address associated with payment method - **Created Date**: When payment method was added **Query Parameters:** **allowRevokedMethod (optional, default: false):** - `false`: Returns only active, usable payment methods - `true`: Returns both active AND revoked payment methods **Revoked Payment Methods:** Include expired cards, deleted payment methods, failed instruments, and customer-removed methods. Useful for historical records and troubleshooting, but cannot be used for new billing attempts. **Use Cases:** **1. Customer Portal:** - Display saved payment methods - Allow customer to select default payment method - Show payment method update/delete options - Validate payment methods before subscription modification **2. Subscription Management:** - Verify customer has valid payment method before creating subscription - Check payment method expiry before next billing - Identify subscriptions at risk due to expiring cards - Prompt customer to update payment if needed **3. Payment Method Updates:** - List available payment methods for customer selection - Identify payment instrument ID for update operations - Validate payment method before switching subscription **4. Troubleshooting & Support:** - Debug payment failures - Verify which payment method is being used - Check if payment method is expired or revoked - Assist customer with payment issues **5. Analytics & Alerts:** - Track payment methods approaching expiry - Send proactive notifications to update cards - Analyze payment method distribution - Identify customers with no valid payment methods **Response Structure:** Returns CustomerPaymentMethodsQuery.PaymentMethods object from Shopify GraphQL: ```json { "nodes": [ { "id": "gid://shopify/CustomerPaymentMethod/abc123", "instrument": { "__typename": "CustomerCreditCard", "brand": "VISA", "lastDigits": "4242", "expiryMonth": 12, "expiryYear": 2025, "name": "John Doe" }, "revokedAt": null, "revokedReason": null, "subscriptionContracts": [...] } ] } ``` **Common Scenarios:** **Scenario 1: Customer with multiple cards** Returns array with multiple payment method objects, each representing a stored card. **Scenario 2: Customer with no payment methods** Returns empty nodes array - customer needs to add payment method. **Scenario 3: Expired card included (allowRevokedMethod=true)** Returns both active cards and expired/revoked cards with revokedAt timestamp. **Important Considerations:** **Data Source:** - Queries Shopify API in real-time (not Appstle database) - Always returns current Shopify payment method state - Subject to Shopify API rate limits **Performance:** - Response time: 300-800ms (depends on Shopify API) - Slower than database queries - Consider caching for non-critical displays **Security:** - Never returns full card numbers (PCI compliance) - Returns only last 4 digits - CVV is never stored or returned - Payment instrument IDs are tokenized references **Privacy:** - Customer ID validated against shop - Cannot query payment methods from other shops - Requires appropriate API permissions **Best Practices:** 1. **Default to Active Only**: Use `allowRevokedMethod=false` for payment selection UIs 2. **Check Expiry Dates**: Validate card expiry before using for subscriptions 3. **Cache Responsibly**: Cache for short periods (5-10 min) to reduce API calls 4. **Handle Empty Response**: Always handle case where customer has no payment methods 5. **Show User-Friendly Names**: Display brand and last 4 (e.g., "Visa •••• 4242") 6. **Indicate Default**: Highlight the default payment method clearly **Integration Examples:** **Example 1: Display payment methods in customer portal** ```javascript const paymentMethods = await fetch( `/api/external/v2/subscription-contract-details/shopify/customer/${customerId}/payment-methods`, { headers: { 'X-API-Key': 'your-key' } } ).then(r => r.json()); paymentMethods.nodes.forEach(pm => { if (pm.instrument.__typename === 'CustomerCreditCard') { console.log(`${pm.instrument.brand} ending in ${pm.instrument.lastDigits}`); if (pm.instrument.expiryYear < currentYear) { console.warn('Card expired!'); } } }); ``` **Example 2: Check for valid payment before creating subscription** ```javascript const paymentMethods = await fetch(...); const hasValidPayment = paymentMethods.nodes.some(pm => !pm.revokedAt && pm.instrument.expiryYear >= currentYear ); if (!hasValidPayment) { alert('Please add a valid payment method before subscribing'); } ``` **Related Endpoints:** - `PUT /api/external/v2/subscription-contracts-update-payment-method` - Update subscription payment method - `POST /api/external/v2/associate-shopify-customer-to-external-payment-gateways` - Add external payment method **Authentication:** Requires valid X-API-Key header # Get detailed subscription information for a customer Source: https://developers.appstle.com/subscription-admin-api/customers/get-detailed-subscription-information-for-a-customer /subscription/admin-api-swagger.json get /api/external/v2/subscription-customers-detail/valid/{customerId} Retrieves comprehensive subscription contract details for a specific customer, including subscription status, products, billing information, delivery schedules, and more. This endpoint returns full subscription objects with all associated data, making it ideal for displaying subscription management interfaces and detailed analytics. **What This Endpoint Returns:** Unlike the contract IDs endpoint which returns only numeric IDs, this endpoint provides complete SubscriptionContractDetailsDTO objects for each of the customer's subscriptions. Each object contains all information needed to display and manage a subscription. **Data Included in Response:** **Subscription Identity:** - Subscription contract ID (Shopify numeric ID) - Subscription GraphQL ID (Shopify GID format) - Internal Appstle database ID - Contract creation date **Subscription Status & Lifecycle:** - Current status (ACTIVE, PAUSED, CANCELLED, EXPIRED, FAILED) - Status reason (why paused/cancelled) - Next billing date and time - Contract anchor date - Cancellation date (if applicable) - Current billing cycle number - Min/max cycle limits **Billing Configuration:** - Billing interval (WEEK, MONTH, YEAR) - Billing interval count (e.g., every 2 weeks) - Billing policy (pricing details) - Currency code - Recurring total price - Applied discounts and pricing policies **Delivery Configuration:** - Delivery interval (WEEK, MONTH, YEAR) - Delivery interval count - Delivery method (SHIPPING, PICK_UP, LOCAL_DELIVERY) - Delivery policy details - Delivery price **Products & Line Items:** - All subscribed products and variants - Product titles, SKUs, and images - Quantities per product - Individual line item prices - Product-specific discounts - Line item attributes and custom fields **Customer Information:** - Customer ID and GraphQL ID - Customer name and email - Customer acceptance status **Address Details:** - Billing address (full address object) - Shipping address (full address object) - Address validation status **Payment Information:** - Payment instrument type - Payment method details (card last 4, etc.) - Payment gateway used **Order & Fulfillment:** - Last order ID and details - Last order date - Order note - Fulfillment status **Additional Metadata:** - Custom note attributes - Tags and labels - Internal flags and settings - Selling plan ID and group ID - Shop domain **Use Cases:** **1. Customer Portal:** - Display all subscriptions on customer dashboard - Show subscription details page - Enable subscription management actions - Display upcoming order information **2. Admin Dashboard:** - View customer's complete subscription portfolio - Analyze subscription health and status - Identify at-risk or high-value subscriptions - Generate customer subscription reports **3. Customer Support:** - Quick access to all customer subscription details - Troubleshoot billing or delivery issues - Verify subscription configurations - Assist with subscription modifications **4. Analytics & Reporting:** - Calculate customer lifetime value - Analyze subscription mix per customer - Track subscription frequency distribution - Identify cross-sell/upsell opportunities **5. Integration & Automation:** - Sync subscription data to CRM/analytics platforms - Trigger workflows based on subscription details - Build custom reporting dashboards - Export subscription data for analysis **Response Format:** Returns an array of SubscriptionContractDetailsDTO objects: ```json [ { "id": 789, "subscriptionContractId": 5234567890, "status": "ACTIVE", "nextBillingDate": "2024-03-15T00:00:00Z", "billingInterval": "MONTH", "billingIntervalCount": 1, "deliveryInterval": "MONTH", "deliveryIntervalCount": 1, "currencyCode": "USD", "currentTotalPrice": "49.99", "customerId": 12345, "customerEmail": "customer@example.com", "lineItems": [...], "billingAddress": {...}, "shippingAddress": {...} }, {...} ] ``` **Response Scenarios:** **Customer with no subscriptions:** ```json [] ``` Returns empty array with 200 OK status (not an error). **Customer with multiple subscriptions:** Array contains multiple subscription objects, each representing a separate subscription contract. **Performance Considerations:** **Response Size:** - Each subscription object can be 5-50 KB depending on line items - Customer with 10 subscriptions: ~100-500 KB response - Consider pagination or filtering for customers with 20+ subscriptions **Query Performance:** - Typical response time: 200-500ms - Slower for customers with many subscriptions or complex products - Database query is optimized with indexed lookups **Best Practices:** 1. **Cache Results**: Cache response data to minimize API calls 2. **Filter Client-Side**: Filter/sort subscriptions on client after retrieval 3. **Selective Display**: Don't display all fields if not needed 4. **Handle Empty Array**: Always gracefully handle case with no subscriptions 5. **Optimize Images**: Product images can be large - lazy load if displaying **Data Freshness:** - Data is retrieved from Appstle database (not real-time Shopify query) - Updated via webhooks with < 1 second lag typically - Use sync endpoint if data appears stale **Security Notes:** - Customer ID is validated against authenticated shop - Returns only subscriptions belonging to specified customer - Cannot access customers from other shops - Sensitive payment details (full card numbers) are never returned **Comparison with Other Endpoints:** **vs. GET /subscription-customers/valid/{customerId}:** - This endpoint: Returns complete subscription details - Valid contracts endpoint: Returns only contract IDs - Use this when you need full subscription information **vs. GET /subscription-contract-details:** - This endpoint: Filtered by single customer - Contract details endpoint: Query across all customers with filters - Use this for customer-specific views **vs. GET /subscription-contracts/contract-external/{contractId}:** - This endpoint: All contracts for a customer - Contract external endpoint: Single contract with Shopify raw data - Use this for customer overview, other for detailed single contract **Authentication:** Requires valid X-API-Key header or api_key parameter (deprecated) # Get valid subscription contract IDs for a customer Source: https://developers.appstle.com/subscription-admin-api/customers/get-valid-subscription-contract-ids-for-a-customer /subscription/admin-api-swagger.json get /api/external/v2/subscription-customers/valid/{customerId} Retrieves a set of all valid (active, paused, or otherwise non-deleted) subscription contract IDs for a specific customer. This endpoint returns only the contract IDs without detailed subscription information, making it ideal for quick lookups and validation checks. **What Are Valid Subscription Contracts?** Valid contracts are subscriptions that exist in the system and haven't been permanently deleted. This includes subscriptions in all states except those that have been hard-deleted or hidden from the system. The contract IDs returned represent subscriptions that can be queried, modified, or managed through other API endpoints. **Contract States Included:** **Active States:** - `ACTIVE` - Currently active and billing recurring subscriptions - `PAUSED` - Temporarily paused subscriptions (customer can resume) **Inactive States:** - `CANCELLED` - Cancelled subscriptions (retained for historical data) - `EXPIRED` - Subscriptions that reached their max cycle limit - `FAILED` - Subscriptions with payment failures (may be in dunning) **Excluded:** - Hard-deleted subscription records - Hidden subscriptions (marked for cleanup) - Subscriptions from test/development that were purged **Use Cases:** **1. Customer Portal:** - Check if customer has any subscriptions before showing portal - Display subscription count in dashboard - Validate customer access to subscription management **2. Integration & Automation:** - Pre-flight check before bulk operations - Verify customer has subscriptions before sending emails - Filter customers for targeted campaigns (has active subscriptions) **3. Validation & Security:** - Verify a specific contract ID belongs to a customer - Validate user permissions before showing subscription details - Check authorization for subscription modification requests **4. Analytics & Reporting:** - Count total subscriptions per customer - Identify customers with multiple subscriptions - Build customer segmentation based on subscription count **Response Format:** Returns a `SetYou've received ${analytics.totalOrders} orders
Total value: ${analytics.totalOrderRevenue}
No shipment information available yet.
'; } const fulfillments = order.fulfillmentOrders?.edges || []; fulfillments.forEach(fo => { fo.node.fulfillments?.edges?.forEach(f => { const tracking = f.node.trackingInfo?.[0]; if (tracking) { console.log(`Track with ${tracking.company}: ${tracking.number}`); console.log(`URL: ${tracking.url}`); } }); }); ``` **Best Practices:** 1. **Cache Response**: Cache for 30-60 minutes to reduce Shopify API calls 2. **Handle Nulls**: Always check for null/empty responses 3. **Parse GraphQL**: Navigate edges/nodes structure carefully 4. **Show All Tracking**: Display all fulfillments if multiple shipments 5. **Link to Carrier**: Provide clickable tracking URLs **Authentication:** Requires valid X-API-Key header # List quick checkout links Source: https://developers.appstle.com/subscription-admin-api/subscription-management/list-quick-checkout-links /subscription/admin-api-swagger.json get /api/external/v2/quick-checkout/links # Replace product variants in a subscription contract Source: https://developers.appstle.com/subscription-admin-api/subscription-management/replace-product-variants-in-a-subscription-contract /subscription/admin-api-swagger.json post /api/external/v2/subscription-contract-details/replace-variants-v3 Replaces existing product variants with new ones in a subscription contract. This endpoint supports both regular subscription products and one-time products, allowing you to swap products, update quantities, and manage the product mix in a subscription. **Key Features:** - **Bulk Replace**: Replace multiple products at once by providing lists of old and new variants - **Line-Specific Replace**: Target a specific line item using oldLineId for precise replacement - **Quantity Management**: Set new quantities for replaced products - **One-Time Products**: Add or remove one-time purchase products independently - **Discount Preservation**: Configurable discount carry-forward logic **Discount Carry Forward Options:** - **PRODUCT_THEN_EXISTING**: First tries to apply the new product's selling plan discount, then falls back to existing discount - **PRODUCT_PLAN**: Always uses the new product's selling plan discount - **EXISTING_PLAN**: Maintains the existing product's discount structure **Important Notes:** - At least one regular subscription product must remain in the contract - One-time products and free products don't count towards the minimum product requirement - The system automatically handles pricing adjustments based on billing/delivery intervals - Shipping prices are automatically recalculated after changes **Use Cases:** - Product upgrades/downgrades (e.g., switching coffee blend or size) - Quantity adjustments during product swap - Adding limited-time or seasonal products as one-time purchases - Bulk product replacements for subscription migrations **Authentication:** Requires valid X-API-Key header # Split or duplicate an existing subscription contract Source: https://developers.appstle.com/subscription-admin-api/subscription-management/split-or-duplicate-an-existing-subscription-contract /subscription/admin-api-swagger.json post /api/external/v2/subscription-contract-details/split-existing-contract Creates a new subscription contract by either splitting (moving) or duplicating selected line items from an existing contract. This endpoint allows you to divide a subscription into multiple contracts or create a copy with specific products. **Split vs Duplicate Mode:** - **Split (isSplitContract=true)**: Moves the selected line items from the original contract to a new contract. The original contract will no longer contain these items. - **Duplicate (isSplitContract=false)**: Creates a new contract with copies of the selected line items while keeping them in the original contract. **Important Notes:** - When splitting, at least one subscription product must remain in the original contract - The new contract inherits all settings from the original: customer, payment method, billing/delivery policies, shipping address, and custom attributes - Billing schedule is automatically generated for the new contract - One-time products and free products don't count towards the minimum product requirement **Use Cases:** - Split a subscription when customer wants different delivery schedules for different products - Create a gift subscription from an existing subscription - Separate products for different shipping addresses - Duplicate a subscription for testing or backup purposes **Authentication:** Requires valid X-API-Key header # Update custom attributes on a subscription contract Source: https://developers.appstle.com/subscription-admin-api/subscription-management/update-custom-attributes-on-a-subscription-contract /subscription/admin-api-swagger.json post /api/external/v2/update-custom-note-attributes Updates or replaces custom key-value attributes on a subscription contract. These attributes are stored with the subscription and can be used to track custom data, preferences, or metadata that's important for your business processes. **Custom Attributes Overview:** Custom attributes are key-value pairs that allow you to store additional information on subscriptions. They are: - Visible in the Shopify admin and accessible via API - Included in order data when subscription orders are created - Preserved across subscription lifecycle events - Useful for integrations and custom workflows **Update Modes:** - **Merge Mode (overwriteExistingAttributes=false)**: Adds new attributes and updates existing ones with matching keys. Other attributes remain unchanged. - **Replace Mode (overwriteExistingAttributes=true)**: Completely replaces all existing attributes with the provided list. **Common Use Cases:** - Store gift messages or special instructions - Track referral sources or marketing campaigns - Add internal reference numbers or tracking codes - Store customer preferences or customization options - Integration data for third-party systems **Important Notes:** - Attribute keys should not conflict with Shopify's reserved attributes - Both keys and values are stored as strings - Changes are logged in the activity history - Invalid discount codes may be automatically removed during update **Authentication:** Requires valid X-API-Key header # Update delivery interval for a subscription contract Source: https://developers.appstle.com/subscription-admin-api/subscription-management/update-delivery-interval-for-a-subscription-contract /subscription/admin-api-swagger.json put /api/external/v2/subscription-contracts-update-delivery-interval Updates the delivery interval for the specified subscription contract. This endpoint allows external API consumers to change the delivery interval count and type (of type SellingPlanInterval) used for scheduling deliveries. The service validates that the contract exists, that the new delivery interval differs from the current setting, and that it meets all business rules. Authentication is enforced via the X-API-Key header (the 'api_key' parameter is deprecated). # Update delivery price for a subscription contract Source: https://developers.appstle.com/subscription-admin-api/subscription-management/update-delivery-price-for-a-subscription-contract /subscription/admin-api-swagger.json put /api/external/v2/subscription-contracts-update-delivery-price 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: 1. Use the sync shipping price endpoint 2. Or update delivery method 3. 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 # Update maximum cycles for a subscription contract Source: https://developers.appstle.com/subscription-admin-api/subscription-management/update-maximum-cycles-for-a-subscription-contract /subscription/admin-api-swagger.json put /api/external/v2/subscription-contracts-update-max-cycles Updates the maximum number of billing cycles (orders) after which a subscription will automatically terminate. This creates a fixed-duration subscription that ends after a specific number of orders. **What are Maximum Cycles?** Maximum cycles define subscription duration limits where: - Subscription automatically cancels after the specified number of orders - No further orders are generated once maximum is reached - Useful for fixed-term offers, trials, or seasonal subscriptions - Customer is notified before final order (if configured) **Key Features:** - Cannot set below current cycle count (prevents immediate cancellation) - Setting to null creates an indefinite subscription - Automatically reschedules order queue based on new limit - Preserves all other subscription settings - Validates against current subscription progress **Current Cycle Calculation:** - Current cycle = Successful billing attempts + 1 - Failed payments don't count toward maximum - First order is cycle 1, second is cycle 2, etc. - System prevents setting max below current position **Common Use Cases:** - **Trial Subscriptions**: '3-box trial' that auto-ends - **Seasonal Programs**: '6-month summer subscription' - **Limited Series**: '12-issue magazine subscription' - **Promotional Offers**: 'First 5 boxes at special price' - **Gift Subscriptions**: Fixed duration gifts that don't renew **What Happens at Maximum:** When a subscription reaches its maximum cycles: 1. Final order is processed normally 2. Subscription status changes to CANCELLED 3. No future orders are scheduled 4. Customer receives cancellation notification 5. Cannot be reactivated (new subscription required) **Interaction with Min Cycles:** - Can have both min and max (e.g., 3 min, 12 max) - Min cycles enforces commitment period - Max cycles enforces termination - Common pattern: Commitment with defined end **Queue Management:** After updating max cycles: - System recalculates future order schedule - Removes orders beyond the new maximum - Adjusts upcoming order notifications - Updates subscription end date projections **Important Notes:** - Validation prevents accidental immediate cancellation - Changes apply to future billing cycles only - Activity log tracks old and new values - Consider customer communication for changes - Setting null removes any duration limit **Authentication:** Requires valid X-API-Key header # Update minimum cycles for a subscription contract Source: https://developers.appstle.com/subscription-admin-api/subscription-management/update-minimum-cycles-for-a-subscription-contract /subscription/admin-api-swagger.json put /api/external/v2/subscription-contracts-update-min-cycles Updates the minimum number of billing cycles (orders) that a customer must complete before they can cancel their subscription. This creates a commitment period that helps with customer retention and business predictability. **What are Minimum Cycles?** Minimum cycles represent a commitment period where: - Customers must complete a specified number of orders - Cancellation is blocked until the minimum is met - Often tied to special pricing or promotional offers - Counted from the subscription start date **Key Features:** - Updates commitment period for existing subscriptions - Can increase or decrease minimum cycles - Setting to null removes the minimum commitment - Preserves all other subscription settings - Automatically handles invalid discount codes - Updates future billing queue after change **Common Use Cases:** - **Promotional Offers**: '3-month minimum for 50% off' - **Hardware Subsidies**: '12-month commitment with free device' - **Loyalty Programs**: Reduce minimum after customer proves loyalty - **Seasonal Campaigns**: Temporary commitment requirements - **Contract Adjustments**: Customer service exceptions **Impact on Customers:** - Cannot cancel via portal until minimum cycles complete - Pause/resume typically still allowed (check settings) - Shows commitment status in customer portal - No automatic notification sent (consider sending separately) **Cycle Counting:** - Only successful billing attempts count toward minimum - Failed payments don't increment the cycle count - Skipped orders (if allowed) don't count - Current cycle = successful past orders + 1 **Interaction with Max Cycles:** - Min cycles must be less than or equal to max cycles - If max cycles exist, subscription auto-cancels after maximum - Common pattern: 3 min cycles, 12 max cycles **Best Practices:** - Clearly communicate commitment terms upfront - Consider grandfathering existing customers - Use reasonable minimums (typically 3-12 cycles) - Document reason for changes in activity logs - Send customer notification for transparency **Important Notes:** - Changes apply immediately to cancellation logic - Doesn't affect past or in-progress orders - Customer portal respects this setting automatically - Activity log tracks old and new values - Consider legal requirements in your jurisdiction **Authentication:** Requires valid X-API-Key header # Update order note for subscription Source: https://developers.appstle.com/subscription-admin-api/subscription-management/update-order-note-for-subscription /subscription/admin-api-swagger.json put /api/external/v2/subscription-contracts-update-order-note/{contractId} Updates the order note that will be added to all future orders generated by this subscription. Order notes help merchants track special instructions, customer preferences, or internal information about the subscription. **Key Features:** - Note is automatically added to all future recurring orders - Visible in both merchant portal and customer portal - Appears in Shopify order details for easy reference - Changes apply to future orders only (existing orders unchanged) **Common Use Cases:** - Customer preferences: "No nuts - severe allergy" - Delivery instructions: "Leave package at side door" - Gift messages: "Happy Birthday from Mom!" - Internal notes: "VIP customer - priority handling" - Processing instructions: "Include sample with each order" **Important Notes:** - Empty string clears the existing note - No character limit imposed by API (check Shopify limits) - HTML is not rendered - stored as plain text - Updates are logged in activity history - Note persists until explicitly changed **Order Generation:** When Appstle creates recurring orders: 1. Retrieves current order note from subscription 2. Adds note to new Shopify order 3. Note appears in order details immediately 4. Merchants can still edit individual order notes **Authentication:** Requires valid X-API-Key header # Update subscription contract status Source: https://developers.appstle.com/subscription-admin-api/subscription-management/update-subscription-contract-status /subscription/admin-api-swagger.json put /api/external/v2/subscription-contracts-update-status 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 # Update subscription delivery address and method Source: https://developers.appstle.com/subscription-admin-api/subscription-management/update-subscription-delivery-address-and-method /subscription/admin-api-swagger.json put /api/external/v2/subscription-contracts-update-shipping-address 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 # Update subscription delivery method Source: https://developers.appstle.com/subscription-admin-api/subscription-management/update-subscription-delivery-method /subscription/admin-api-swagger.json put /api/external/v2/subscription-contracts-update-delivery-method Updates the delivery method for a subscription contract, supporting standard shipping, local delivery, and customer pickup options. The delivery method determines how future orders will be fulfilled. **Delivery Method Types:** The system automatically determines the type based on the subscription's current delivery address: - **SHIPPING**: Standard shipping to customer address (default) - **LOCAL**: Local delivery within merchant's delivery zones - **PICK_UP**: Customer pickup at designated location **Two Ways to Update:** 1. **Manual Parameters**: Provide title, code, and presentment title directly 2. **Delivery Method ID**: Provide a Shopify DeliveryMethodDefinition ID to auto-populate all fields **Using Delivery Method ID:** When providing a delivery-method-id: - System fetches the method from Shopify's delivery profiles - Automatically sets title, code, and presentment title - Applies associated delivery price if defined - ID can be numeric or full GraphQL ID format **Delivery Type Requirements:** - **Standard Shipping**: No additional requirements - **Local Delivery**: Phone number must exist in delivery address - **Pickup**: Pickup location must be configured in subscription **Price Updates:** - If using delivery-method-id with a fixed price, updates delivery price - Manual updates don't change the delivery price - Price changes affect all future orders **Side Effects:** - Creates activity log entry with method details - May remove invalid discount codes automatically - Updates apply to all future orders immediately - No customer notification sent **Common Use Cases:** - Switch from standard shipping to express shipping - Change pickup location for customer convenience - Update local delivery options based on availability - Apply seasonal delivery methods **Important Notes:** - Cannot change the delivery type (shipping/local/pickup) - only the method within that type - Delivery methods must be configured in Shopify's shipping settings - Changes don't affect orders already in fulfillment **Authentication:** Requires valid X-API-Key header # Add one-time product to subscription order Source: https://developers.appstle.com/subscription-admin-api/subscription-one-time-products/add-one-time-product-to-subscription-order /subscription/admin-api-swagger.json put /api/external/v2/subscription-contract-one-offs-by-contractId-and-billing-attempt-id **Discontinued.** One-time products are no longer applied to the generated order or cleaned up afterward — this endpoint now always returns 400 and creates nothing. Do not build new integrations against it. # Get all one-time products for a subscription contract Source: https://developers.appstle.com/subscription-admin-api/subscription-one-time-products/get-all-one-time-products-for-a-subscription-contract /subscription/admin-api-swagger.json get /api/external/v2/subscription-contract-one-offs-by-contractId Retrieves all one-time products (add-ons) associated with a specific subscription contract across all billing attempts. One-time products are additional items that customers can add to their subscription orders on a non-recurring basis. Each one-time product is tied to a specific billing attempt and will only be included in that particular order. **Key Features:** - Returns ALL one-time products across all queued billing attempts - Each product includes the billing attempt ID to identify which order it belongs to - Includes product details: variant ID, quantity, title, image, and price - Products are automatically removed after the associated billing attempt is processed **Use Cases:** - Display all one-time products added to a subscription across all upcoming orders - Allow customers to review their one-time add-ons in customer portal - Enable merchants to see all one-time products for a contract - Integrate with external systems to manage subscription add-ons **Authentication:** Requires valid X-API-Key header # Get one-time products for next upcoming order Source: https://developers.appstle.com/subscription-admin-api/subscription-one-time-products/get-one-time-products-for-next-upcoming-order /subscription/admin-api-swagger.json get /api/external/v2/upcoming-subscription-contract-one-offs-by-contractId Retrieves one-time products that will be included in the next scheduled order for a subscription contract. This endpoint specifically returns products associated with the earliest queued billing attempt, making it ideal for showing customers what additional items will be in their next delivery. **Key Differences from /subscription-contract-one-offs-by-contractId:** - Returns ONLY products for the next upcoming order (not all future orders) - Finds the earliest QUEUED billing attempt by date - Returns empty array if no queued billing attempts exist - Useful for "Your Next Order" previews in customer portals **Use Cases:** - Display a preview of the next order including one-time add-ons - Calculate the total cost of the upcoming delivery - Show customers their next delivery date with associated one-time items - Allow last-minute modifications before order processing **Business Logic:** 1. Searches for billing attempts with status = QUEUED 2. Selects the one with the earliest billing date 3. Returns all one-time products for that specific billing attempt 4. Returns empty array if no queued orders exist (e.g., subscription paused/cancelled) **Authentication:** Requires valid X-API-Key header that identifies the shop # Remove one-time product from subscription order Source: https://developers.appstle.com/subscription-admin-api/subscription-one-time-products/remove-one-time-product-from-subscription-order /subscription/admin-api-swagger.json delete /api/external/v2/subscription-contract-one-offs-by-contractId-and-billing-attempt-id Removes a previously added one-time product from a specific subscription order. This permanently deletes the one-time product from the specified billing attempt. The operation is idempotent - attempting to delete a non-existent product will succeed without error. **Important Notes:** - Only removes the product from the specified billing attempt - Cannot remove products from billing attempts that are already processed - Activity logs are created for audit trails - Returns the updated list of all one-time products for the contract **Use Cases:** - Allow customers to remove unwanted add-ons before order processing - Clean up cart-like functionality in customer portals - Programmatically manage one-time product selections - Implement "undo" functionality for product additions **Business Rules:** - Contract must belong to the authenticated shop - The specific combination of contractId + billingAttemptId + variantId identifies the product to remove - No error is thrown if the product doesn't exist (idempotent operation) **Authentication:** Requires valid X-API-Key header that identifies the shop # Send payment method update email to customer Source: https://developers.appstle.com/subscription-admin-api/subscription-payments/send-payment-method-update-email-to-customer /subscription/admin-api-swagger.json put /api/external/v2/subscription-contracts-update-payment-method Triggers Shopify to send an email to the subscription customer with a secure link to update their payment method. This endpoint initiates Shopify's native payment update flow without requiring direct payment handling. **Key Features:** - Sends official Shopify payment update email to customer - Customer receives secure link to Shopify-hosted payment update page - No PCI compliance required - Shopify handles all payment data - Supports all Shopify-supported payment methods - Automatically updates subscription after customer completes the process **Process Flow:** 1. API call triggers email send request to Shopify 2. Shopify sends branded email to customer's registered email 3. Customer clicks secure link in email 4. Customer authenticates on Shopify-hosted page 5. Customer adds/updates payment method 6. Subscription automatically uses new payment method **Email Details:** - Sent from Shopify's email servers - Uses store's configured sender email - Subject line typically: "Update your payment method" - Contains secure, time-limited link - Shopify-branded with store information **Use Cases:** - Failed payment recovery - Expiring credit card updates - Customer-requested payment changes - Proactive payment method maintenance **Important Notes:** - Customer must have valid email address - Email cannot be customized (Shopify template) - Link expiration time set by Shopify - Multiple emails can be sent if needed - No webhook for completion - poll contract for updates **Rate Limiting:** - Subject to Shopify's email sending limits - Recommended: Wait 24 hours between sends to same customer - Excessive sends may be blocked by Shopify **Authentication:** Requires valid X-API-Key header # Update subscription payment method Source: https://developers.appstle.com/subscription-admin-api/subscription-payments/update-subscription-payment-method /subscription/admin-api-swagger.json put /api/external/v2/subscription-contracts-update-existing-payment-method Updates the payment method for an existing subscription contract to use a different existing payment method. The new payment method must already be associated with the customer in Shopify. **Important Notes:** - The payment method must already exist in the customer's Shopify payment methods - Only valid, non-revoked payment methods can be used - The update is processed through Shopify's subscription draft system - Payment method details are cached locally after successful update **Process Flow:** 1. Validates subscription contract exists 2. Creates a draft update in Shopify 3. Updates the draft with new payment method 4. Commits the draft to apply changes 5. Caches payment instrument details locally 6. Records activity log entry **Authentication:** Requires valid X-API-Key header # Add products or variants to an existing subscription group Source: https://developers.appstle.com/subscription-admin-api/subscription-plans/add-products-or-variants-to-an-existing-subscription-group /subscription/admin-api-swagger.json put /api/external/v2/subscription-groups/{id}/add-products Adds one or more products and/or product variants to an existing subscription group (selling plan group). This endpoint provides a simple way to expand the product catalog eligible for subscription without modifying the group's configuration or existing product assignments. **Key Features:** - Add multiple products and variants in a single request - Preserves existing product and variant assignments - Maintains the order of products as provided - Updates delivery profiles automatically if needed - Synchronously updates Shopify and returns the updated group - Optional response enhancement with added products information **Important Notes:** - Product IDs should be numeric Shopify product IDs without the gid:// prefix - Variant IDs should be numeric Shopify variant IDs without the gid:// prefix - Adding products also makes all their variants eligible for subscription - Adding specific variants limits subscription eligibility to those variants only - Duplicate products/variants are handled gracefully by Shopify - URL length limits apply to the comma-separated lists (use bulk endpoint for large additions) - Include 'x-return-short-response: true' header to get only added products/variants information in response **Use Cases:** - Launch new products with subscription options - Add seasonal items to existing subscription groups - Enable subscription for specific product variants - Expand subscription eligibility without changing plan configurations - Track which products were added in the current request **Authentication:** Requires valid X-API-Key header # Add products or variants to an existing subscription group (async) Source: https://developers.appstle.com/subscription-admin-api/subscription-plans/add-products-or-variants-to-an-existing-subscription-group-async /subscription/admin-api-swagger.json post /api/external/v2/subscription-groups/v3/{id}/add-products Same JSON body as the v2 bulk-add-products endpoint, but returns immediately with a 202 and processes the update in the background via an AWS Step Function worker instead of within the HTTP request. Use this for large batches (hundreds to thousands of IDs) that would otherwise risk hitting request/gateway timeouts. Poll GET /api/external/v2/subscription-groups/v3/{id}/add-products/status to check progress. Only one such job may run per shop at a time; a second request while one is in progress is rejected with a 400. **Authentication:** Requires valid X-API-Key header # Bulk add products or variants to an existing subscription group Source: https://developers.appstle.com/subscription-admin-api/subscription-plans/bulk-add-products-or-variants-to-an-existing-subscription-group /subscription/admin-api-swagger.json post /api/external/v2/subscription-groups/{id}/bulk-add-products Adds multiple products and/or product variants to an existing subscription group (selling plan group) using a JSON request body. This endpoint is ideal for adding large numbers of products/variants that would exceed URL length limits in the query parameter version. **Advantages over query parameter endpoint:** - No URL length restrictions - Cleaner syntax for large lists - Better for programmatic integrations - Supports the same functionality with improved scalability **Behavior:** - Identical to the query parameter endpoint in functionality - Adds products/variants to existing assignments - Preserves product order - Updates synchronously and returns the updated group — for very large batches (thousands of IDs) that risk request/gateway timeouts, use the async v3 endpoint (POST /api/external/v2/subscription-groups/v3/{id}/add-products) instead **Authentication:** Requires valid X-API-Key header # Check status of an async add-products job Source: https://developers.appstle.com/subscription-admin-api/subscription-plans/check-status-of-an-async-add-products-job /subscription/admin-api-swagger.json get /api/external/v2/subscription-groups/v3/{id}/add-products/status Polls the status of a bulk add-products job started via POST .../add-products (v3 async endpoint). Only one such job runs per shop at a time; check 'subscriptionGroupId' and 'matchesRequestedGroup' in the response to confirm it's reporting on the group you submitted, in case a newer job for a different group has since started. **Authentication:** Requires valid X-API-Key header # Create a new subscription group (selling plan group) Source: https://developers.appstle.com/subscription-admin-api/subscription-plans/create-a-new-subscription-group-selling-plan-group /subscription/admin-api-swagger.json post /api/external/v2/subscription-groups Creates a new subscription group with one or more selling plans in Shopify. A subscription group is a container for selling plans that can be applied to products and variants. Each group can contain multiple plans with different frequencies, discounts, and delivery schedules. **Key Features:** - Create multiple subscription plans within a single group - Configure complex discount tiers (up to 2 levels + custom cycles) - Set up free trials with automatic discount transitions - Define prepaid plans (PAY_AS_YOU_GO_PREPAID) with custom billing cycles - Configure member-only plans with tag-based access control - Set specific delivery dates (e.g., 15th of every month) - Add all products from store or specific collection automatically **Discount Configuration:** - First discount tier: Applied from a specific cycle (afterCycle1) - Second discount tier: Applied from another cycle (afterCycle2) - Additional cycles: Configure via appstleCycles for complex scenarios - Free trials: Automatically configure 100% discount for trial period **Product Assignment:** - Assign specific products via productIds field in request body - Assign specific variants via variantIds field in request body - Use isAddAllProduct=true to add all store products - Use collectionId with isAddAllProduct=true to add all products from a collection **Authentication:** Requires valid X-API-Key header # Get all selling plans across all subscription groups Source: https://developers.appstle.com/subscription-admin-api/subscription-plans/get-all-selling-plans-across-all-subscription-groups /subscription/admin-api-swagger.json get /api/external/v2/subscription-groups/all-selling-plans Retrieves a flattened list of all selling plans from all subscription groups in the store. This endpoint provides a consolidated view of every subscription plan available, regardless of which group it belongs to. **Response includes:** - All selling plans with their configurations - Group information for each plan (groupId and groupName) - Complete discount and pricing details - Delivery and billing frequencies - Member restrictions and settings - Free trial configurations **Use Cases:** - Build a unified subscription selector - Compare all available subscription options - Analyze pricing across all plans - Find specific plan configurations - Generate reports on subscription offerings **Differences from /subscription-groups endpoint:** - Returns plans as a flat list, not grouped - Each plan includes its parent group information - Easier to search/filter across all plans - Does not include product/variant assignments **Authentication:** Requires valid X-API-Key header # Get all subscription groups Source: https://developers.appstle.com/subscription-admin-api/subscription-plans/get-all-subscription-groups /subscription/admin-api-swagger.json get /api/external/v2/subscription-groups Retrieves a list of all subscription groups (selling plan groups) configured in the store. This endpoint provides a complete overview of all subscription offerings available. **Response includes:** - All subscription groups with their configurations - Complete selling plan details for each group - Product and variant assignments (as JSON strings) - Discount configurations and tiers - Member restrictions and settings **Use Cases:** - Display all subscription options in a custom interface - Audit subscription configurations - Export subscription data for analysis - Synchronize with external systems **Performance Notes:** - Returns all groups in a single response (no pagination) - Response size grows with number of groups and plans - Product/variant lists are JSON-encoded strings within the response **Authentication:** Requires valid X-API-Key header # Get subscription group by ID Source: https://developers.appstle.com/subscription-admin-api/subscription-plans/get-subscription-group-by-id /subscription/admin-api-swagger.json get /api/external/v2/subscription-groups/{id} Retrieves detailed information about a specific subscription group (selling plan group) by its ID. This endpoint provides complete configuration details for a single subscription group. **Response includes:** - Group name and configuration - All selling plans with complete details - Product and variant assignments - Discount tiers and configurations - Free trial settings - Member restrictions - Delivery and billing frequencies **Use Cases:** - Display detailed subscription options for editing - Verify configuration before updates - Debug subscription issues - Integration with external systems **Authentication:** Requires valid X-API-Key header # Remove products or variants from a subscription group Source: https://developers.appstle.com/subscription-admin-api/subscription-plans/remove-products-or-variants-from-a-subscription-group /subscription/admin-api-swagger.json put /api/external/v2/subscription-groups/{id}/remove-products Removes specified products and/or variants from an existing subscription group (selling plan group). This endpoint allows selective removal of products without affecting the group's configuration or other product assignments. **Key Features:** - Remove multiple products and variants in a single request - Remove all products from a specific collection - Silently ignores products/variants not currently in the group - Preserves subscription group configuration and settings - Updates synchronously and returns the modified group **Collection Removal:** - When collectionId is provided, fetches and removes all products from that collection - Collection processing is limited to 5000 products maximum - Collection removal is additive to any explicitly specified productIds/variantIds **Important Notes:** - Removing products does NOT affect existing active subscriptions - Can remove all products, leaving an empty subscription group - Products/variants not in the group are silently ignored - Use numeric IDs without gid:// prefix for products and variants **Authentication:** Requires valid X-API-Key header # Remove products or variants from ALL subscription groups Source: https://developers.appstle.com/subscription-admin-api/subscription-plans/remove-products-or-variants-from-all-subscription-groups /subscription/admin-api-swagger.json put /api/external/v2/subscription-groups/remove-products Removes specified products and/or variants from ALL subscription groups in the store. This is a powerful bulk operation that affects every subscription group simultaneously. **⚠️ WARNING:** This operation: - Affects ALL subscription groups in your store - Cannot be easily undone - Processes synchronously (may timeout for stores with many groups) - Does NOT affect existing active subscriptions **Use Cases:** - Discontinuing products from all subscription offerings - Removing seasonal items from all groups - Cleaning up deleted products from subscription groups - Compliance-driven product removals **Important Considerations:** - Each group is updated individually - If any group update fails, previous groups remain updated - Large operations may take significant time - Consider using individual group removal for better control **Authentication:** Requires valid X-API-Key header # Update subscription group details and product assignments Source: https://developers.appstle.com/subscription-admin-api/subscription-plans/update-subscription-group-details-and-product-assignments /subscription/admin-api-swagger.json put /api/external/v2/subscription-groups Updates an existing subscription group (selling plan group) including its name, selling plans configuration, and optionally manages product/variant assignments. This endpoint provides comprehensive update capabilities for both the subscription group structure and its product associations. **Key Capabilities:** - Update subscription group name - Modify existing selling plan configurations (discounts, frequencies, trials, etc.) - Add or remove products/variants through updateProducts and deleteProducts fields - Cannot add or remove selling plans - only modify existing ones - Automatically handles complex discount transitions for free trials and prepaid plans - Updates delivery profile associations if changed - Triggers asynchronous operations for metafield updates and free product checks **Important Notes:** - The 'id' field is required and must match an existing subscription group - For each selling plan in subscriptionPlans array, provide 'idNew' with the existing selling plan ID - Plan modifications maintain the same selling plan ID in Shopify - Product/variant updates are processed after group details are updated - Large product updates (allProduct=true) run asynchronously **Selling Plan Updates:** - Can change discount amounts, types, and cycles - Can modify billing/delivery frequencies - Can add/remove free trials - Can change member restrictions and tags - Can update specific day delivery settings - Can modify min/max cycles **Authentication:** Requires valid X-API-Key header # Add multiple products to subscription Source: https://developers.appstle.com/subscription-admin-api/subscription-products/add-multiple-products-to-subscription /subscription/admin-api-swagger.json put /api/external/v2/subscription-contracts-add-line-items Adds multiple product line items to an existing subscription contract in a single request. This batch operation is more efficient than making multiple individual requests and ensures all products are added with consistent processing. **Key Features:** - Batch addition of multiple products in one API call - All products are added as recurring items (not one-time) - Automatic quantity defaulting (0 or null becomes 1) - Sequential processing with full validation for each item - Returns final subscription state after all additions - Same pricing and discount logic as single-item endpoint **Processing Behavior:** - Products are added sequentially, not in parallel - If any product fails, previous additions remain - Each product goes through full validation - Existing product handling follows store settings - Activity logs created for each product added **Duplicate Product Handling:** If a product already exists in the subscription: - With 'updateExistingQuantityOnAddProduct' enabled: Updates quantity - Without setting: Adds as new line item - Setting applies to all products in the batch **Pricing and Discounts:** Each product receives: - Appropriate selling plan assignment - Discount carry-forward based on store settings - Currency and country-specific pricing - Fulfillment frequency multiplier application **Build-a-Box Validation:** - Applied if any product has _bb_id attribute - Validates total quantity after all additions - May fail entire batch if limits exceeded **Post-Processing:** After all products are added: - Build-a-Box discounts recalculated once - Product discounts synchronized - Single email notification sent - Shipping price updated once **Important Notes:** - Maximum recommended batch size: 10-20 products - Larger batches may timeout - All products become recurring items - Use single-item endpoint for one-time products **Authentication:** Requires valid X-API-Key header # Add product to subscription Source: https://developers.appstle.com/subscription-admin-api/subscription-products/add-product-to-subscription /subscription/admin-api-swagger.json put /api/external/v2/subscription-contracts-add-line-item Adds a new product line item to an existing subscription contract. Can add either recurring products that will appear in each order or one-time products that appear only in the next order. **Key Features:** - Supports both recurring and one-time product additions - Automatically applies appropriate pricing policies based on discount carry-forward settings - Handles duplicate products by updating quantity (if enabled) or adding as new line - Calculates prices based on billing/delivery frequency multipliers - Sends email notifications to customers (unless suppressed) - Creates activity logs for audit trail **Pricing Policy Application:** The system applies discounts based on the store's discount carry-forward setting: - **PRODUCT_PLAN**: Uses the discount from the product's selling plan - **EXISTING_PLAN**: Applies the discount structure from existing subscription items - **PRODUCT_THEN_EXISTING**: First attempts product plan, falls back to existing if not found **One-Time Products:** Products added with `isOneTimeProduct=true` will: - Only appear in the next scheduled order - Be automatically removed after fulfillment - Still attempt to match with appropriate selling plans - Can have subscription discounts applied if store setting allows **Duplicate Product Handling:** When adding a product that already exists in the subscription: - If store has 'updateExistingQuantityOnAddProduct' enabled and product is not one-time: Updates existing quantity - Otherwise: Adds as a new line item **Price Calculation:** - Base price is fetched considering contract currency and delivery country - Price is multiplied by fulfillment frequency ratio (billing interval / delivery interval) - Example: Monthly billing with weekly delivery = price × 4 **Authentication:** Requires valid X-API-Key header # Add product with custom price to subscription Source: https://developers.appstle.com/subscription-admin-api/subscription-products/add-product-with-custom-price-to-subscription /subscription/admin-api-swagger.json put /api/external/v2/subscription-contract-add-line-item Adds a new product line item with a custom price override to an existing subscription contract. This endpoint bypasses standard pricing and selling plans to set an exact price. **Key Features:** - Direct price control - set any price regardless of product pricing - Optional automatic discount application based on shop settings - No selling plan assignment - pure custom pricing - Supports both recurring and one-time products - Email notifications sent to customers - Activity logging for audit trails **Custom Pricing Behavior:** - Price is set exactly as provided (no calculations) - Overrides any product-level pricing - Not affected by currency or country - No automatic discounts from selling plans - Price remains fixed unless manually updated **Shop-Level Discount Application:** Despite the method name, this endpoint MAY apply discounts: - Checks shop setting: 'applySubscriptionDiscount' - If enabled, applies shop's default subscription discount - Discount type: PERCENTAGE or FIXED (per shop config) - Creates manual discount: 'PRODUCT_DISCOUNT_[lineId]' - Discount is additional to the custom price **Common Use Cases:** - **Negotiated Pricing**: Custom rates for specific customers - **Price Matching**: Match competitor pricing - **Promotional Pricing**: Special one-off prices - **Bundle Pricing**: Custom prices for package deals - **Legacy Pricing**: Honor old pricing agreements - **Test Orders**: Zero or nominal pricing for testing **Differences from Standard Add:** - No selling plan association - No pricing policy rules - No automatic tier discounts - Price doesn't adjust with frequency changes - Manual price management required **One-Time Products:** When `isOneTimeProduct=true`: - Product appears only in next order - Automatically removed after fulfillment - Custom price applies to that single order - Shop discount still applies if configured **Price Validation:** - Must be a positive number - No maximum limit enforced - Can be less than product cost (loss leader) - Currency matches shop's base currency - Decimal precision per currency rules **Important Considerations:** - No automatic price updates with product changes - Frequency changes don't affect pricing - May bypass minimum order values - Consider margin implications - Document reason for custom pricing **Post-Addition Effects:** - Customer receives product addition email - Activity log records custom price - Shipping may need recalculation - Order total updates immediately - No impact on other line items **Authentication:** Requires valid X-API-Key header # Remove multiple products from subscription Source: https://developers.appstle.com/subscription-admin-api/subscription-products/remove-multiple-products-from-subscription /subscription/admin-api-swagger.json put /api/external/v2/subscription-contracts-remove-line-items Removes multiple product line items from an existing subscription contract in a single request. Products are removed sequentially, allowing partial success if errors occur. **Key Features:** - Sequential processing - items removed one by one - Partial success allowed - previous removals persist if later ones fail - Validates each removal against current subscription state - Smart discount cleanup for line-specific discounts - Comprehensive validation for each product removal - Triggers all side effects after each successful removal **Processing Order Matters:** Items are removed in the order provided: 1. First item validated and removed 2. Second item validated against updated state 3. Continue until all processed or error occurs 4. Returns final subscription state **Validation Per Item:** - Line item must exist in subscription - At least one recurring product must remain - Build-a-Box min/max quantities maintained - Minimum cycle commitments honored - One-time and free products don't count toward minimum **Discount Handling:** When `removeDiscount=true`: - Removes discounts applied ONLY to the removed line - Preserves discounts that apply to multiple lines - Each removal evaluates discounts independently - Build-a-Box discounts auto-adjust based on quantity **Side Effects Per Removal:** Each successful removal triggers: - Activity log entry created - Customer email sent - Shipping price recalculation - Build-a-Box discount resync - Product discount adjustments **Partial Success Scenarios:** If removing 3 items and the 2nd fails: - 1st item: Successfully removed - 2nd item: Fails, error returned - 3rd item: Not attempted - Result: Subscription with 1st item removed **Performance Considerations:** - Each removal is a separate Shopify API transaction - Multiple emails may be sent to customer - Consider using single remove for 1-2 items - Large batches may timeout - Recommended max: 5-10 items per request **Build-a-Box Handling:** For Build-a-Box subscriptions: - Validates total quantity after EACH removal - May fail mid-batch if minimum breached - Discounts recalculate after each item - Consider removal order carefully **Important Notes:** - NOT atomic - no rollback on partial failure - Order of line IDs affects success probability - Customer receives email per removed item - All validations apply as if removing individually - Response shows final state after all attempts **Authentication:** Requires valid X-API-Key header # Remove product from subscription Source: https://developers.appstle.com/subscription-admin-api/subscription-products/remove-product-from-subscription /subscription/admin-api-swagger.json put /api/external/v2/subscription-contracts-remove-line-item Removes a specific product line item from an existing subscription contract. Can optionally retain prorated discounts associated with the removed product. **Key Features:** - Validates minimum subscription requirements before removal - Handles discount cleanup for line-specific discounts - Enforces minimum cycle commitments on products - Supports Build-a-Box quantity validation - Automatic retry on concurrent modification conflicts - Email notifications for subscription changes **Validation Rules:** - At least one recurring subscription product must remain after removal - One-time products and free products don't count toward the minimum - Products with minimum cycle commitments cannot be removed until fulfilled - Build-a-Box subscriptions validate against minimum/maximum quantity rules **Discount Handling:** When `removeDiscount=true` (default): - Discounts applied only to the removed line item are deleted - Discounts applied to multiple line items are retained - System automatically identifies which discounts to remove **Retry Mechanism:** The endpoint automatically retries in these scenarios: - Concurrent modification detected (another process updated the subscription) - Invalid discount code errors (removes problematic discount and retries) - This ensures reliable operation in high-traffic environments **Post-Removal Actions:** - Activity log created for audit trail - Email notification sent to customer - Shipping price recalculated asynchronously - Build-a-Box discounts resynced if applicable - Product-specific discounts resynced **Authentication:** Requires valid X-API-Key header # Update line item pricing policy with cycle-based discounts Source: https://developers.appstle.com/subscription-admin-api/subscription-products/update-line-item-pricing-policy-with-cycle-based-discounts /subscription/admin-api-swagger.json put /api/external/v2/subscription-contracts-update-line-item-pricing-policy Sets up advanced pricing rules for a subscription line item that change based on the number of successful orders (cycles). This powerful feature enables loyalty discounts, promotional pricing tiers, and subscribe-and-save models. **What are Pricing Policies?** Pricing policies define how a product's price changes over the subscription lifetime: - **Base Price**: Starting price for the product - **Cycle Discounts**: Price changes after specific numbers of orders - **Automatic Application**: System applies correct price based on order history **Supported Discount Types:** - **PERCENTAGE**: Percentage off base price (e.g., 10% off) - **FIXED**: Fixed amount off base price (e.g., $5 off) - **PRICE**: Override with new fixed price (e.g., $19.99) Note: SHIPPING and FREE_PRODUCT types are not supported by this endpoint **Cycle Counting:** - Cycles start at 1 (first order is cycle 1) - Only successful billing attempts count - Failed payments don't increment the cycle - Current cycle = 1 + count of successful past orders **Common Use Cases:** 1. **Subscribe & Save**: 10% off starting from 3rd order 2. **Loyalty Tiers**: 5% off after 3 orders, 10% after 6 orders 3. **Introductory Pricing**: First 2 orders at $9.99, then $14.99 4. **Promotional Periods**: Special price for orders 3-5 **Important Limitations:** - Maximum 2 cycle discounts per line item - Cycles must have different afterCycle values - Changes apply to future orders only - Existing orders keep their original pricing **Prepaid Subscription Handling:** For prepaid subscriptions (e.g., pay monthly for weekly delivery): - Base price is per delivery - Current price = base price × delivery frequency - Discounts apply to base price, then multiply **Side Effects:** - Sends price update email to customer - Recalculates Build-a-Box discounts - Updates product discount synchronization - Triggers shipping price recalculation - Creates detailed activity log **Authentication:** Requires valid X-API-Key header # Update multiple properties of a subscription line item Source: https://developers.appstle.com/subscription-admin-api/subscription-products/update-multiple-properties-of-a-subscription-line-item /subscription/admin-api-swagger.json put /api/external/v2/subscription-contracts-update-line-item Comprehensive endpoint for updating a subscription line item's quantity, price, product variant, and/or selling plan in a single API call. Changes are applied intelligently - only modified values trigger updates. **Key Features:** - Update any combination of: quantity, price, variant, or selling plan - Intelligent change detection - only updates what's different - Automatic handling of prepaid subscription pricing - Preserves existing discount cycles when updating price - Partial success allowed - some updates may fail while others succeed - Each change creates separate activity log entries **Prepaid Subscription Handling:** For prepaid subscriptions (billing interval > delivery interval): - When `isPricePerUnit=true`: Price is multiplied by interval ratio - Example: Monthly billing, weekly delivery = price × 4 - When `isPricePerUnit=false`: Price is used as total billing amount **Update Process:** 1. Validates line item exists in the subscription 2. Calculates interval multiplier for prepaid logic 3. Updates in order: selling plan → price → quantity → variant 4. Each update uses separate Shopify GraphQL mutation 5. Failures are logged but don't block other updates **Selling Plan Updates:** - Can update by ID or name (name takes precedence) - Only updates if different from current plan - Useful for changing delivery frequency options **Price Updates:** - Preserves existing discount cycles (up to 2 cycles) - Recalculates cycle discounts based on new base price - Triggers shipping price recalculation - Sends price update email to customer **Quantity Updates:** - Validates against min/max quantity rules - Updates Build-a-Box totals if applicable - May trigger discount recalculations **Variant Updates:** - Changes the product itself (different SKU) - Validates new variant exists and is available - May affect pricing and discounts **Important Notes:** - All parameters except contractId and lineId are optional - Provide only the values you want to change - Price is always in shop's base currency - Changes apply to future orders only **Authentication:** Requires valid X-API-Key header # Update product line item price Source: https://developers.appstle.com/subscription-admin-api/subscription-products/update-product-line-item-price /subscription/admin-api-swagger.json put /api/external/v2/subscription-contracts-update-line-item-price Updates the base price of a specific product line item within a subscription contract. This endpoint intelligently handles pricing updates while preserving existing discount structures. **Key Features:** - Updates base price while maintaining discount cycles - Automatically calculates prepaid subscription prices - Preserves existing percentage/fixed discounts - Validates actual price changes before updating - Triggers shipping and discount recalculations - Sends price update notifications to customers **Base Price vs Current Price:** - **Base Price**: The unit price before any multipliers - **Current Price**: Base price × fulfillment multiplier - For monthly billing/weekly delivery: Current = Base × 4 - For pay-per-delivery: Current = Base × 1 **Discount Preservation:** By default, this endpoint preserves existing discount cycles: - Percentage discounts adjust to new base price - Fixed discounts remain at same dollar amount - Discount schedule (after X cycles) unchanged **Prepaid Subscription Handling:** For prepaid subscriptions (billing interval > delivery interval): - Automatically calculates fulfillment multiplier - Updates current price accordingly - Ensures correct billing amounts **Post-Update Actions:** 1. Build-a-Box discount recalculation 2. Product discount synchronization 3. Shipping price updates 4. Customer email notifications 5. Activity log creation **Important Notes:** - Price changes apply to future orders only - Cannot set price below $0.01 - Maximum 2 discount cycles preserved - No update if price unchanged **Authentication:** Requires valid X-API-Key header # Update product line item quantity in subscription Source: https://developers.appstle.com/subscription-admin-api/subscription-products/update-product-line-item-quantity-in-subscription /subscription/admin-api-swagger.json put /api/external/v2/subscription-contracts-update-line-item-quantity Updates the quantity of a specific product line item within a subscription contract. This comprehensive operation handles quantity validation, discount recalculation, and special Build-a-Box constraints. **Key Features:** - Updates quantity for future orders only - Validates minimum/maximum quantities for line items - Special handling for Build-a-Box subscriptions - Automatic discount recalculation - Shipping price updates - Activity log tracking with old/new values **Build-a-Box (BAB) Validation:** For Build-a-Box subscriptions: - Enforces total minimum/maximum item counts - Only counts recurring products (excludes one-time and free items) - Validates across all BAB items in the subscription - Can be bypassed with 'allowToAddProductQuantityMinMaxReached' permission **Line Item Validation:** Individual products may have: - Minimum quantity requirements (min_quantity attribute) - Maximum quantity limits (max_quantity attribute) - These are enforced separately from BAB constraints **Post-Update Actions:** 1. **Activity Logging**: Records quantity change with old/new values 2. **BAB Discount Sync**: Recalculates Build-a-Box volume discounts 3. **Product Discount Sync**: Updates product-specific discounts 4. **Shipping Price Update**: Recalculates shipping based on new quantity **Discount Recalculation:** - Build-a-Box discounts adjust based on total quantity tiers - May remove old discount codes and apply new ones - Handles 'subscription contract has changed' retry scenarios **Important Notes:** - Line ID must be the full GraphQL ID format - Quantity must be positive (minimum 1) - Changes apply to all future orders - Past or in-progress orders are not affected **Authentication:** Requires valid X-API-Key header # Update selling plan for a subscription line item Source: https://developers.appstle.com/subscription-admin-api/subscription-products/update-selling-plan-for-a-subscription-line-item /subscription/admin-api-swagger.json put /api/external/v2/subscription-contracts-update-line-item-selling-plan Updates the selling plan associated with a specific product line item in a subscription contract. Selling plans define the delivery schedule, pricing rules, and billing policies for subscription products. **What are Selling Plans?** Selling plans are Shopify's way of defining subscription rules for products: - **Delivery Schedule**: How often the product is delivered (e.g., 'every 2 weeks', 'monthly') - **Pricing Policy**: Discounts and pricing tiers (e.g., '10% off', 'first order free') - **Billing Policy**: When and how often customer is charged - **Plan Name**: Customer-facing description like 'Deliver every month' **Key Features:** - Update by selling plan ID or name (name takes precedence if both provided) - Validates line item exists before attempting update - Only creates activity log if plan actually changes - Uses Shopify's draft system for safe updates - Preserves existing line item attributes and customizations **Common Use Cases:** - Change delivery frequency: Weekly → Monthly - Switch pricing tiers: Regular → VIP pricing - Update from old plan to new plan with better terms - Migrate products to new selling plan groups - Apply seasonal or promotional plans **Update Process:** 1. Validates subscription contract and line item exist 2. Creates a draft of the subscription contract 3. Updates the line item's selling plan in the draft 4. Commits the draft to apply changes 5. Records activity log if plan changed **Impact of Selling Plan Changes:** - **Delivery Schedule**: Next and future orders follow new schedule - **Pricing**: New plan's pricing applies from next billing - **Discounts**: Plan-specific discounts are recalculated - **Billing**: Billing frequency may change with the plan **Finding Selling Plans:** To find available selling plans: 1. Check product's selling plan groups in Shopify admin 2. Use Shopify's GraphQL API to query selling plans 3. Plans must be active and associated with the product **Important Notes:** - Both sellingPlanId and sellingPlanName are optional, but at least one required - If both provided, both are updated (name doesn't override ID) - Plan must be valid for the product variant - Changes apply to future orders only - No customer notification sent (consider sending separately) **Authentication:** Requires valid X-API-Key header # Calculate refund amount preview Source: https://developers.appstle.com/subscription-storefront-api/billing-&-payments/calculate-refund-amount-preview /subscription/storefront-api-swagger.json get /subscriptions/cp/api/subscription-billing-attempts/refund-preview/{id} Calculates the refund amount that would be issued if a specific subscription order fulfillment were refunded. This provides a preview without actually processing the refund. **What it calculates:** - Total refund amount (order amount minus processing fees) - Restocking fees (if applicable) - Gateway fees that cannot be refunded - Net refund amount customer will receive **Use Cases:** - Show customer how much they'll get back before confirming refund - Display refund breakdown in customer portal - Validate refund eligibility **Important Notes:** - This is a preview only - does not process refund - Refund amount may vary based on payment gateway - Some gateways don't refund processing fees - Refunds can only be issued for fulfilled orders **Authentication:** Customer must be logged in and own the subscription # Get backup payment recovery opt-in status Source: https://developers.appstle.com/subscription-storefront-api/billing-&-payments/get-backup-payment-recovery-opt-in-status /subscription/storefront-api-swagger.json get /subscriptions/cp/api/backup-payment-opt-in # Get past orders Source: https://developers.appstle.com/subscription-storefront-api/billing-&-payments/get-past-orders /subscription/storefront-api-swagger.json get /subscriptions/cp/api/subscription-billing-attempts/past-orders Retrieves paginated list of past (processed) billing attempts for a subscription contract or customer. Includes successful orders, failed attempts, and skipped orders. **Filter Options:** - By contract ID: Get order history for specific subscription - By customer ID: Get all orders across all customer subscriptions - Pagination: Control page size and page number **Order Information:** - Billing attempt status (SUCCESS, FAILED, SKIPPED) - Shopify order ID for successful attempts - Billing date and processing date - Order total and line items - Error messages for failed attempts **Authentication:** Requires valid X-API-Key header # Get past orders report with detailed filtering Source: https://developers.appstle.com/subscription-storefront-api/billing-&-payments/get-past-orders-report-with-detailed-filtering /subscription/storefront-api-swagger.json get /subscriptions/cp/api/subscription-billing-attempts/past-orders/report Retrieves a detailed report of past billing attempts with advanced filtering options. This endpoint provides comprehensive data for analytics, troubleshooting, and reporting purposes. **Filter Options:** - By status: SUCCESS, FAILED, SKIPPED - By date range: Filter by billing date range - By attempt count: Filter by number of retry attempts - By contract status: Filter by subscription contract status - By contract ID: Get report for specific subscription **Response Includes:** - Detailed billing attempt information - Shopify exception details for failed attempts (optional) - Retry attempt count - Processing timestamps - Order totals and line items **Authentication:** Requires valid X-API-Key header # Get subscription payment info for a contract Source: https://developers.appstle.com/subscription-storefront-api/billing-&-payments/get-subscription-payment-info-for-a-contract /subscription/storefront-api-swagger.json get /subscriptions/cp/api/subscription-payment-infos/{contractId} # Get upcoming orders (top orders) Source: https://developers.appstle.com/subscription-storefront-api/billing-&-payments/get-upcoming-orders-top-orders /subscription/storefront-api-swagger.json get /subscriptions/cp/api/subscription-billing-attempts/top-orders Retrieves upcoming (queued) billing attempts for a subscription contract or customer. Returns the next scheduled orders that have not yet been processed. **Query Options:** - Filter by contract ID to see upcoming orders for a specific subscription - Filter by customer ID to see all upcoming orders for a customer - Results are ordered by billing date (earliest first) **Use Cases:** - Display "Your Next Order" in customer portal - Show upcoming delivery schedule - Calculate upcoming charges - Preview next order contents **Authentication:** Requires valid X-API-Key header # Get URL for 3DS / SCA security challenge Source: https://developers.appstle.com/subscription-storefront-api/billing-&-payments/get-url-for-3ds-sca-security-challenge /subscription/storefront-api-swagger.json get /subscriptions/cp/api/subscription-billing-attempts/security-challenge-action-url/{id} # Process refund for subscription order Source: https://developers.appstle.com/subscription-storefront-api/billing-&-payments/process-refund-for-subscription-order /subscription/storefront-api-swagger.json put /subscriptions/cp/api/subscription-billing-attempts/refund-fulfillment/{id} Processes a refund for a fulfilled subscription order. This creates a refund in Shopify and returns the money to the customer's original payment method. **What it does:** 1. Validates order is eligible for refund (fulfilled, not already refunded) 2. Creates refund transaction in Shopify 3. Processes refund with payment gateway 4. Updates order status to 'Refunded' 5. Sends refund confirmation email to customer 6. Logs refund activity **Refund Eligibility:** - Order must be fulfilled - Cannot already be refunded - Must be within merchant's refund policy window - Payment gateway must support refunds **Refund Processing:** - Refund is processed to original payment method - Takes 5-10 business days to appear in customer's account - Processing fees are typically not refunded - Partial refunds are supported (if configured) **Important Warnings:** - This action cannot be undone - Refunded orders cannot be un-refunded - Inventory is restocked automatically - Refunds may incur gateway fees **Authentication:** Customer must be logged in and own the subscription # Recover a billing attempt stuck in progress Source: https://developers.appstle.com/subscription-storefront-api/billing-&-payments/recover-a-billing-attempt-stuck-in-progress /subscription/storefront-api-swagger.json put /subscriptions/cp/api/subscription-billing-attempts/fix-billing-attempt-in-progress/{id} # Reschedule a billing attempt to a new date Source: https://developers.appstle.com/subscription-storefront-api/billing-&-payments/reschedule-a-billing-attempt-to-a-new-date /subscription/storefront-api-swagger.json put /subscriptions/cp/api/subscription-billing-attempts/reschedule-order/{id} Changes the scheduled billing date for a billing attempt. This allows customers to adjust when their next order will be processed. **Rescheduling Options:** - Move to earlier date (if allowed by shop settings) - Move to later date - Optionally reschedule all future orders by the same offset **Important Behaviors:** - Only QUEUED billing attempts can be rescheduled - New date must be in the future - Can affect future billing schedule if rescheduleFutureOrder is true - Activity logs are created for audit trail **Use Cases:** - Customer wants to delay next delivery - Customer wants to receive order earlier - Adjust delivery schedule to align with customer needs - Coordinate deliveries with customer vacation/travel **Authentication:** Requires valid X-API-Key header # Retry a failed billing attempt Source: https://developers.appstle.com/subscription-storefront-api/billing-&-payments/retry-a-failed-billing-attempt /subscription/storefront-api-swagger.json put /subscriptions/cp/api/subscription-billing-attempts/retry-failed-billing-attempt # Skip a failed billing attempt's order Source: https://developers.appstle.com/subscription-storefront-api/billing-&-payments/skip-a-failed-billing-attempts-order /subscription/storefront-api-swagger.json put /subscriptions/cp/api/subscription-billing-attempts/skip-failed-order # Skip a specific order Source: https://developers.appstle.com/subscription-storefront-api/billing-&-payments/skip-a-specific-order /subscription/storefront-api-swagger.json put /subscriptions/cp/api/subscription-billing-attempts/skip-order/{id} Skips a specific billing attempt by ID. The order will not be processed on its scheduled date. This is useful when customers want to skip a particular delivery without canceling their subscription. **Important Behaviors:** - Only QUEUED billing attempts can be skipped - Skipped orders remain in the system with SKIPPED status - Future orders are not affected - Can be unskipped before the scheduled date if needed - Activity logs are created for audit trail **Use Cases:** - Customer is on vacation - Customer has excess inventory - Temporary delivery pause for one cycle **Authentication:** Requires valid X-API-Key header # Skip the next upcoming order for a subscription Source: https://developers.appstle.com/subscription-storefront-api/billing-&-payments/skip-the-next-upcoming-order-for-a-subscription /subscription/storefront-api-swagger.json put /subscriptions/cp/api/subscription-billing-attempts/skip-upcoming-order Skips the next scheduled billing attempt for a subscription contract without requiring the billing attempt ID. Automatically finds and skips the earliest QUEUED billing attempt. **Convenience Feature:** - No need to know the specific billing attempt ID - Automatically finds the next order - Ideal for "skip next order" functionality in customer portals **Use Cases:** - Simple "skip next delivery" button in customer portal - Quick skip without looking up billing attempt details - One-click skip functionality **Authentication:** Requires valid X-API-Key header # Trigger immediate billing for an order Source: https://developers.appstle.com/subscription-storefront-api/billing-&-payments/trigger-immediate-billing-for-an-order /subscription/storefront-api-swagger.json put /subscriptions/cp/api/subscription-billing-attempts/attempt-billing/{id} Immediately processes a billing attempt, creating an order in Shopify. This bypasses the scheduled billing date and processes the order right away. **Important Notes:** - Requires shop permission 'enableImmediatePlaceOrder' - Only QUEUED billing attempts can be processed - Creates an actual order in Shopify - Charges the customer's payment method immediately - Cannot be undone once processed **Use Cases:** - Customer requests early delivery - Process order immediately after resolving payment issue - Manual order processing for special cases **Authentication:** Requires valid X-API-Key header and shop permission # Unskip a previously skipped order Source: https://developers.appstle.com/subscription-storefront-api/billing-&-payments/unskip-a-previously-skipped-order /subscription/storefront-api-swagger.json put /subscriptions/cp/api/subscription-billing-attempts/unskip-order/{id} Reverses a skip action on a billing attempt. The order will be restored to QUEUED status and will be processed on its scheduled date. **Important Notes:** - Only works on billing attempts with SKIPPED status - Must be done before the scheduled billing date - Cannot unskip after the billing date has passed - Activity logs are created for audit trail **Use Cases:** - Customer changes their mind about skipping - Correct accidental skip actions - Restore delivery after resolving temporary issue **Authentication:** Requires valid X-API-Key header # Update backup payment recovery opt-in status Source: https://developers.appstle.com/subscription-storefront-api/billing-&-payments/update-backup-payment-recovery-opt-in-status /subscription/storefront-api-swagger.json put /subscriptions/cp/api/backup-payment-opt-in # Update subscription billing attempt Source: https://developers.appstle.com/subscription-storefront-api/billing-&-payments/update-subscription-billing-attempt /subscription/storefront-api-swagger.json put /subscriptions/cp/api/subscription-billing-attempts Updates an existing subscription billing attempt. This endpoint allows modification of billing attempt details such as billing date, order note, and other attributes. **Important Notes:** - Only QUEUED billing attempts can be updated - Cannot update attempts that are already processed or failed - Billing attempt must belong to the authenticated shop **Authentication:** Requires valid X-API-Key header # Get a subscription bundling configuration by token Source: https://developers.appstle.com/subscription-storefront-api/build-a-box-&-bundles/get-a-subscription-bundling-configuration-by-token /subscription/storefront-api-swagger.json get /subscriptions/cp/api/subscription-bundlings/by-token/{token} # Get public Build-a-Box bundle details by handle (v3) Source: https://developers.appstle.com/subscription-storefront-api/build-a-box-&-bundles/get-public-build-a-box-bundle-details-by-handle-v3 /subscription/storefront-api-swagger.json get /subscriptions/cp/api/v3/subscription-bundlings/external/get-bundle/{handle} # Get subscription bundle settings by ID Source: https://developers.appstle.com/subscription-storefront-api/build-a-box-&-bundles/get-subscription-bundle-settings-by-id /subscription/storefront-api-swagger.json get /subscriptions/cp/api/subscription-bundle-settings/{id} # List single-product Build-a-Box bundlings for the shop Source: https://developers.appstle.com/subscription-storefront-api/build-a-box-&-bundles/list-single-product-build-a-box-bundlings-for-the-shop /subscription/storefront-api-swagger.json get /subscriptions/cp/api/subscription-bundlings/single-product # Get campaign landing details Source: https://developers.appstle.com/subscription-storefront-api/campaigns/get-campaign-landing-details /subscription/storefront-api-swagger.json get /subscriptions/cp/api/campaigns/{id}/landing # List applicable customer portal campaigns Source: https://developers.appstle.com/subscription-storefront-api/campaigns/list-applicable-customer-portal-campaigns /subscription/storefront-api-swagger.json get /subscriptions/cp/api/campaigns/applicable # List applicable customer portal campaigns for multiple contracts in one call Source: https://developers.appstle.com/subscription-storefront-api/campaigns/list-applicable-customer-portal-campaigns-for-multiple-contracts-in-one-call /subscription/storefront-api-swagger.json get /subscriptions/cp/api/campaigns/applicable-bulk # Redeem a campaign offer Source: https://developers.appstle.com/subscription-storefront-api/campaigns/redeem-a-campaign-offer /subscription/storefront-api-swagger.json post /subscriptions/cp/api/campaigns/{id}/redeem # Track a campaign banner event Source: https://developers.appstle.com/subscription-storefront-api/campaigns/track-a-campaign-banner-event /subscription/storefront-api-swagger.json post /subscriptions/cp/api/campaigns/{id}/track # Get subscriptionscpapicancellation flowspublished Source: https://developers.appstle.com/subscription-storefront-api/cancellation-flow-customer-portal-resource/get-subscriptionscpapicancellation-flowspublished /subscription/storefront-api-swagger.json get /subscriptions/cp/api/cancellation-flows/published # Check Customer Account API authentication status Source: https://developers.appstle.com/subscription-storefront-api/customer-portal/check-customer-account-api-authentication-status /subscription/storefront-api-swagger.json get /subscriptions/cp/api/customer-account-api/status Checks whether the current customer has valid Customer Account API tokens stored. Used by the customer portal to determine if the customer needs to authenticate. **Use Cases:** - Check if customer is authenticated before making Customer Account API GraphQL calls - Determine whether to show 'Connect Account' button in UI - Validate token validity before attempting sensitive operations **Response:** Returns authentication status and customer ID. **Authentication:** Customer must be logged in via Shopify customer session # Get shop info for the currently signed-in shop Source: https://developers.appstle.com/subscription-storefront-api/customer-portal/get-shop-info-for-the-currently-signed-in-shop /subscription/storefront-api-swagger.json get /subscriptions/cp/api/shop-infos-by-current-login # Handle OAuth callback from Shopify Source: https://developers.appstle.com/subscription-storefront-api/customer-portal/handle-oauth-callback-from-shopify /subscription/storefront-api-swagger.json get /subscriptions/cp/api/customer-account-api/oauth/callback OAuth 2.0 callback endpoint that receives the authorization code from Shopify after customer authorization. This endpoint is called automatically by Shopify after the customer authorizes the app. **Flow:** 1. Shopify redirects customer here with authorization code and state 2. Validates state parameter to prevent CSRF 3. Exchanges authorization code for access token using PKCE verifier 4. Validates ID token (JWT) from Shopify 5. Stores access token and refresh token securely 6. Redirects customer back to original return URL **Security:** - Validates state parameter matches stored value - Uses PKCE code verifier to exchange authorization code - Validates ID token signature and claims - State expires after 10 minutes **Error Handling:** - If customer denies authorization, redirects with error parameter - If token exchange fails, redirects with error parameter - All errors are logged for debugging **Note:** This endpoint should not be called directly - it's invoked by Shopify's OAuth redirect. # Initiate Customer Account API OAuth flow Source: https://developers.appstle.com/subscription-storefront-api/customer-portal/initiate-customer-account-api-oauth-flow /subscription/storefront-api-swagger.json post /subscriptions/cp/api/customer-account-api/initiate Initiates the OAuth 2.0 authorization flow for Shopify's Customer Account API. This endpoint is used when a customer wants to grant the subscription app access to their Shopify customer account data. **What is Customer Account API?** Shopify's Customer Account API allows apps to access customer data (orders, addresses, payment methods) on behalf of the customer. This requires customer consent through an OAuth flow. **How it works:** 1. Customer portal calls this endpoint with a return URL 2. Backend generates PKCE challenge and state parameter 3. Returns authorization URL to redirect customer to Shopify 4. Customer authorizes on Shopify 5. Shopify redirects back to callback endpoint with authorization code 6. Callback endpoint exchanges code for access token **Important Notes:** - Requires customer to be logged in to the Shopify store - Only works with stores that have 'New Customer Accounts' enabled - Uses PKCE (Proof Key for Code Exchange) for security - State parameter prevents CSRF attacks - Access tokens are stored securely and used for subsequent Customer Account API calls **Authentication:** Customer must be logged in via Shopify customer session # Logout from Customer Account API Source: https://developers.appstle.com/subscription-storefront-api/customer-portal/logout-from-customer-account-api /subscription/storefront-api-swagger.json get /subscriptions/cp/api/customer-account-api/logout Logs out the customer from the Customer Account API session. This can be initiated either by the customer clicking logout in the customer portal, or by Shopify's end session callback. **What it does:** - Deletes stored access and refresh tokens - Initiates Shopify's end session flow (if tokens available) - Redirects to return URL or back to customer portal **Two scenarios:** 1. **App-initiated logout**: Customer clicks logout in portal - Portal calls this endpoint with return URL - Tokens deleted, redirects to Shopify end session endpoint - Shopify redirects back to return URL 2. **Shopify-initiated logout**: Customer logs out globally from Shopify - Shopify calls this endpoint with id_token_hint - Tokens deleted, returns success **Important:** - This only logs out from Customer Account API, not from Shopify customer account - Customer will need to re-authenticate to use Customer Account API features again - Does not affect regular customer portal access (subscription management) **Authentication:** Optional - can be called from Shopify without authentication # Proxy GraphQL queries to Shopify Customer Account API Source: https://developers.appstle.com/subscription-storefront-api/customer-portal/proxy-graphql-queries-to-shopify-customer-account-api /subscription/storefront-api-swagger.json post /subscriptions/cp/api/customer-account-api/graphql Executes GraphQL queries against Shopify's Customer Account API on behalf of the authenticated customer. This endpoint handles token management, refresh, and authentication automatically. **What you can query:** - Customer profile information - Order history and details - Saved addresses - Payment methods - Subscriptions (via Customer Account API schema) **Token Management:** - Automatically uses stored access token - Refreshes expired tokens automatically - Returns 401 if customer needs to re-authenticate **Example Queries:** ```graphql query { customer { id emailAddress { emailAddress } defaultAddress { address1 city } } } ``` **Authentication:** Customer must be logged in and have completed OAuth flow # Get cancellation management configuration Source: https://developers.appstle.com/subscription-storefront-api/customer-retention/get-cancellation-management-configuration /subscription/storefront-api-swagger.json get /subscriptions/cp/api/cancellation-managements/{id} # Get subscriptionscpapicustomer retention activitieslatest discount usage Source: https://developers.appstle.com/subscription-storefront-api/customer-retention/get-subscriptionscpapicustomer-retention-activitieslatest-discount-usage /subscription/storefront-api-swagger.json get /subscriptions/cp/api/customer-retention-activities/latest-discount-usage # Get win-back offer landing details Source: https://developers.appstle.com/subscription-storefront-api/customer-retention/get-win-back-offer-landing-details /subscription/storefront-api-swagger.json get /subscriptions/cp/api/win-back-campaigns/{id}/landing # Reactivate a subscription from a win-back offer Source: https://developers.appstle.com/subscription-storefront-api/customer-retention/reactivate-a-subscription-from-a-win-back-offer /subscription/storefront-api-swagger.json post /subscriptions/cp/api/win-back-campaigns/{id}/reactivate # Record a customer retention activity Source: https://developers.appstle.com/subscription-storefront-api/customer-retention/record-a-customer-retention-activity /subscription/storefront-api-swagger.json post /subscriptions/cp/api/customer-retention-activities # Get custom CSS for customer portal Source: https://developers.appstle.com/subscription-storefront-api/customization/get-custom-css-for-customer-portal /subscription/storefront-api-swagger.json get /subscriptions/cp/api/subscription-custom-csses/{id} Retrieves the custom CSS styling configuration for the customer portal. This endpoint returns all custom CSS rules that have been configured to customize the appearance, layout, and branding of the subscription customer portal. **What is Custom CSS?** Custom CSS allows merchants to fully customize the visual appearance of their customer portal beyond the basic theme settings. This enables complete brand alignment and creates a seamless experience that matches the merchant's main store design. **Custom CSS Capabilities:** - **Layout Customization**: - Modify page layouts and spacing - Adjust grid and flexbox configurations - Control responsive breakpoints - Customize navigation and sidebars - **Typography**: - Custom fonts and font families - Font sizes, weights, and line heights - Letter spacing and text transforms - Heading and paragraph styles - **Colors and Branding**: - Brand color palette application - Custom background colors and gradients - Button and link styling - Hover and focus states - Border colors and shadows - **Component Styling**: - Subscription card appearances - Form input styling - Button designs and interactions - Modal and dialog boxes - Navigation menus - Product images and thumbnails - **Advanced Features**: - CSS animations and transitions - Media queries for responsive design - Pseudo-elements and pseudo-classes - Custom icons using CSS - Transform and filter effects **CSS Structure:** The returned CSS includes: - Global styles for portal-wide consistency - Component-specific styles - Responsive design rules - Theme overrides - Custom animations - Print styles (optional) **Common CSS Selectors Available:** ```css /* Portal container */ .subscription-portal { } /* Subscription cards */ .subscription-card { } .subscription-card-header { } .subscription-card-body { } /* Buttons */ .btn-primary { } .btn-secondary { } .btn-cancel { } /* Forms */ .form-control { } .form-group { } .form-label { } /* Navigation */ .portal-nav { } .nav-item { } /* Product displays */ .product-item { } .product-image { } .product-title { } ``` **Use Cases:** - Apply custom branding to match main store design - Create unique visual experiences for different customer segments - Implement seasonal or promotional themes - Enhance mobile responsiveness - Add accessibility improvements (high contrast, larger fonts) - A/B test different portal designs - Integrate with design systems - Implement dark mode or theme switching **Important Notes:** - CSS is sanitized for security (XSS prevention) - Certain properties may be restricted for security reasons - External resources (fonts, images) must use HTTPS - CSS is cached for performance - changes may take a few minutes to propagate - Invalid CSS syntax is automatically filtered out - Some core portal elements have !important styles that cannot be overridden **Best Practices:** - Use specific selectors to avoid conflicts - Test across different browsers and devices - Keep CSS organized with comments - Use CSS variables for maintainability - Minify CSS for production performance - Consider accessibility in color choices (WCAG compliance) - Provide fallbacks for advanced CSS features **Security Considerations:** - CSS is sanitized to prevent code injection - External URLs are validated - JavaScript in CSS is blocked (e.g., expression(), behavior()) - Data URIs are validated for malicious content **Authentication:** Requires valid X-API-Key header # Get customer portal label translations for locale Source: https://developers.appstle.com/subscription-storefront-api/customization/get-customer-portal-label-translations-for-locale /subscription/storefront-api-swagger.json get /subscriptions/cp/api/label-translations/locale # Get customer portal settings Source: https://developers.appstle.com/subscription-storefront-api/customization/get-customer-portal-settings /subscription/storefront-api-swagger.json get /subscriptions/cp/api/customer-portal-settings/{id} Retrieves the customer portal configuration and settings for the authenticated shop. The customer portal is the self-service interface where subscribers can manage their subscriptions, update payment methods, modify delivery addresses, and more. **What is the Customer Portal?** The customer portal is a dedicated web interface that allows your subscribers to manage their subscription accounts independently. This reduces support burden and improves customer experience by enabling self-service subscription management. **Settings Returned:** - **Display Configuration**: - Portal theme and branding settings - Custom colors and logo - Layout preferences - Custom CSS selectors - **Feature Toggles**: - Enable/disable subscription pausing - Enable/disable order skipping - Enable/disable product swapping - Enable/disable frequency changes - Enable/disable quantity modifications - Enable/disable address editing - Enable/disable payment method updates - Enable/disable subscription cancellation - **Subscription Management Options**: - Maximum pause duration allowed - Minimum subscription duration requirements - Skip limits per billing cycle - Product swap availability - One-time product add-ons - **Communication Settings**: - Email notification preferences - Custom portal messaging - Support contact information - Help text and instructions - **Access Control**: - Portal authentication method - Password requirements - Magic link settings - Session duration - **Advanced Options**: - Custom domain configuration - Redirect URLs - Webhook endpoints - Analytics tracking settings **Use Cases:** - Display customer portal with correct branding and theme - Determine which features are available to subscribers - Build custom portal interfaces using your settings - Sync portal configuration across systems - Validate subscription management capabilities - Configure third-party integrations **Important Notes:** - Settings are shop-specific and unique per merchant - Some features may be restricted based on subscription plan - Changes to settings are reflected immediately in the portal - Custom CSS must be valid and secure - Portal URL is typically: shop-domain.com/apps/subscriptions **Common Configuration Scenarios:** **1. Standard Self-Service Portal:** - Allow pausing (up to 3 months) - Allow skipping (max 2 consecutive orders) - Allow frequency changes - Allow quantity updates - Allow address editing - Enable payment method updates - Enable cancellation with feedback **2. Locked-Down Portal (Minimal Self-Service):** - Disable pausing - Disable skipping - Disable cancellation (require support contact) - Allow address editing only - Allow payment method updates only **3. Full-Service Portal (Maximum Flexibility):** - Enable all subscription management features - Allow unlimited pauses and skips - Enable product swapping - Enable one-time add-ons - Allow subscription splitting/merging - Custom branding and domain **Authentication:** Requires valid X-API-Key header # Get shop customization CSS by category Source: https://developers.appstle.com/subscription-storefront-api/customization/get-shop-customization-css-by-category /subscription/storefront-api-swagger.json get /subscriptions/cp/api/shop-customizations/css/{category} # Get widget label translations for locale Source: https://developers.appstle.com/subscription-storefront-api/customization/get-widget-label-translations-for-locale /subscription/storefront-api-swagger.json get /subscriptions/cp/api/widget-label-translations/locale # Get a page of order events (paginated) Source: https://developers.appstle.com/subscription-storefront-api/delivery-&-shipping/get-a-page-of-order-events-paginated /subscription/storefront-api-swagger.json get /subscriptions/cp/api/orders/{orderId}/events # Get the live fulfillment status for an order Source: https://developers.appstle.com/subscription-storefront-api/delivery-&-shipping/get-the-live-fulfillment-status-for-an-order /subscription/storefront-api-swagger.json get /subscriptions/cp/api/orders/{orderId}/live-status # List delivery profile locations Source: https://developers.appstle.com/subscription-storefront-api/delivery-&-shipping/list-delivery-profile-locations /subscription/storefront-api-swagger.json get /subscriptions/cp/api/delivery-profiles/get-locations # Get available loyalty point redemption options Source: https://developers.appstle.com/subscription-storefront-api/loyalty-integration/get-available-loyalty-point-redemption-options /subscription/storefront-api-swagger.json get /subscriptions/cp/api/loyalty-integration/redeem-options Returns all available rewards that the customer can redeem their loyalty points for. This shows customers what they can spend their points on. **Common Redemption Options:** - Discount codes (e.g., $5 off for 500 points) - Percentage discounts (e.g., 10% off for 1000 points) - Free shipping rewards - Free products or samples - Exclusive access to sales **Response includes:** - Redemption option ID - Name and description - Points cost - Reward value (dollar amount or percentage) - Availability (minimum purchase, restrictions) - Whether customer has enough points **Filtering:** - Only shows active redemption options - Filters based on customer's tier/VIP level - Shows whether customer has sufficient points **Use Cases:** - Display 'Redeem Points' section in customer portal - Show available rewards in checkout - Encourage customers to save points for bigger rewards **Authentication:** Customer must be logged in via Shopify customer session # Get available ways to earn loyalty points Source: https://developers.appstle.com/subscription-storefront-api/loyalty-integration/get-available-ways-to-earn-loyalty-points /subscription/storefront-api-swagger.json get /subscriptions/cp/api/loyalty-integration/earn-options Returns all active point earning campaigns and rules that the customer can participate in. This shows customers how they can earn more points. **Common Earning Methods:** - Points per dollar spent on purchases - Bonus points for first subscription - Points for referring friends - Birthday bonus points - Social media follows (Instagram, Facebook, Twitter) - Product reviews - Account creation bonus **Response includes:** - Campaign name and description - Points awarded - Action required (e.g., 'Follow on Instagram') - Icon/image URL - Terms and conditions **Use Cases:** - Display 'Ways to Earn' section in customer portal - Show earning opportunities on product pages - Encourage customer engagement **Authentication:** Customer must be logged in via Shopify customer session # Get customer loyalty points and rewards data Source: https://developers.appstle.com/subscription-storefront-api/loyalty-integration/get-customer-loyalty-points-and-rewards-data /subscription/storefront-api-swagger.json get /subscriptions/cp/api/loyalty-integration/customer Retrieves the loyalty/rewards program data for the currently logged-in customer. This includes points balance, tier status, and available rewards. **Supported Loyalty Programs:** - Appstle Loyalty & Rewards - Yotpo Loyalty & Referrals - Smile.io (via Appstle integration) **What you get:** - Current points balance - Points pending (from recent orders) - VIP tier/level - Points history - Available reward redemptions **Use Cases:** - Display points balance in customer portal - Show available rewards customer can redeem - Display VIP tier badge - Show points expiration dates **Authentication:** Customer must be logged in via Shopify customer session **Note:** Requires loyalty app integration to be configured in merchant settings # Redeem loyalty points for a reward Source: https://developers.appstle.com/subscription-storefront-api/loyalty-integration/redeem-loyalty-points-for-a-reward /subscription/storefront-api-swagger.json post /subscriptions/cp/api/loyalty-integration/redeem Allows a customer to redeem their loyalty points for a specific reward option. This deducts points from their balance and generates a discount code or applies the reward. **What happens:** 1. Validates customer has enough points 2. Deducts points from customer's balance 3. Generates discount code (for discount rewards) 4. Records redemption in customer's history 5. Returns discount code or confirmation **Reward Types:** - **Discount codes**: Generates unique code customer can use at checkout - **Auto-apply discounts**: Automatically applied to next order - **Free products**: Adds free product to next order - **Free shipping**: Waives shipping on next order **Important Notes:** - Points are deducted immediately and cannot be refunded - Discount codes typically expire after 30 days - Some rewards have minimum purchase requirements - Rewards cannot be combined with other discounts (depends on configuration) **Use Cases:** - Customer clicks 'Redeem' button in customer portal - Apply points at checkout - Redeem points for subscription discount **Authentication:** Customer must be logged in via Shopify customer session # Get product swap variant groups for a contract Source: https://developers.appstle.com/subscription-storefront-api/product-catalog/get-product-swap-variant-groups-for-a-contract /subscription/storefront-api-swagger.json post /subscriptions/cp/api/product-swaps-by-variant-groups/{contractId} Retrieves product swap variant groups for the next 10 billing cycles of a specific subscription contract. This endpoint calculates and returns which products will be swapped to in future billing cycles based on configured swap automations. **Response Structure:** Returns a 2D array (`List