# Subscription Management APIs for customers to view and manage their subscription contracts including status updates, frequency changes, and cancellations. ## Update subscription contract status - [PUT /subscriptions/cp/api/subscription-contracts-update-status](https://developers.subscription.appstle.com/customer-portal-swagger/subscription-management/updatestatus.md): 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 - [PUT /subscriptions/cp/api/subscription-contracts-update-shipping-address](https://developers.subscription.appstle.com/customer-portal-swagger/subscription-management/updateshippingaddress.md): 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 custom attributes on a subscription contract - [POST /subscriptions/cp/api/update-custom-note-attributes](https://developers.subscription.appstle.com/customer-portal-swagger/subscription-management/updateordernoteattributes.md): 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 ## Split or duplicate an existing subscription contract - [POST /subscriptions/cp/api/subscription-contract-details/split-existing-contract](https://developers.subscription.appstle.com/customer-portal-swagger/subscription-management/splitexistingcontract.md): 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 ## Replace product variants in a subscription contract - [POST /subscriptions/cp/api/subscription-contract-details/replace-variants-v3](https://developers.subscription.appstle.com/customer-portal-swagger/subscription-management/replacevariantsv3.md): 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 ## Get variant contextual pricing - [GET /subscriptions/cp/api/data/variant-contextual-pricing](https://developers.subscription.appstle.com/customer-portal-swagger/subscription-management/getvariantcontextualpricing.md): Retrieves contextual pricing information for a product variant based on currency and country. This endpoint provides localized pricing data for international subscriptions and multi-currency support. Pricing Information Returned: - Base price in specified currency - Compare-at price (if applicable) - Country-specific pricing adjustments - Tax information for the region - Currency conversion data Parameters: - variantId - Shopify variant ID (required) - currencyCode - ISO 4217 currency code (e.g., USD, EUR, GBP) (required) - countryCode - ISO 3166-1 country code (e.g., US, GB, CA) (optional) Use Cases: - Display localized pricing in customer portal - Calculate subscription totals for international customers - Support multi-currency subscriptions - Show accurate pricing based on customer location - Validate pricing before subscription creation Important Notes: - Requires Shopify Markets or multi-currency setup - Prices are returned in the requested currency - Country-specific pricing takes precedence over currency-only pricing - Returns 404 if variant doesn't exist or isn't available in specified market Authentication: Requires valid api_key parameter ## Get selling plans for products - [GET /subscriptions/cp/api/data/products-selling-plans](https://developers.subscription.appstle.com/customer-portal-swagger/subscription-management/getproductsellingplandata.md): Retrieves all selling plans (subscription plans) associated with a set of products. This endpoint is useful for determining which subscription options are available for specific products. Selling Plan Information: - Selling plan ID and name - Billing and delivery frequencies - Pricing policies (discounts) - Plan description and options - Product associations Use Cases: - Display subscription options on product pages - Validate subscription plan availability - Build subscription plan selector UI - Sync plan data across systems Request: - Accepts multiple product IDs as comma-separated values - Returns aggregated selling plans from all products Authentication: Requires valid api_key parameter ## Get products data with pagination - [GET /subscriptions/cp/api/data/products](https://developers.subscription.appstle.com/customer-portal-swagger/subscription-management/getproductsdata_1.md): Retrieves paginated product catalog data from Shopify, optionally filtered by search term, selling plans, or subscription contracts. This endpoint provides access to your store's product catalog with subscription-specific information. What This Endpoint Returns: Product information including: - Product ID, title, handle, and description - Product images and media - Variants with pricing and availability - Associated selling plans (subscription plans) - Product status and tags - Vendor and product type Pagination: Uses cursor-based pagination for efficient data retrieval: - next=true - Get next page of results - cursor - Pagination cursor from previous response - Returns cursor for next page in response Filtering Options: 1. Search (search parameter): - Search by product title, description, or SKU - Partial matching supported - Case-insensitive 2. Selling Plan Filter (sellingPlanIds parameter): - Filter products by subscription plans - Comma-separated list of selling plan IDs - Only returns products with specified plans 3. Contract Filter (contractId parameter): - Get products available for specific subscription - Useful for product swap functionality - Returns products compatible with contract Use Cases: - Display product catalog in custom subscription UI - Build product selection for subscription creation - Implement product swap functionality - Search products for subscription management - Sync product data to external systems Authentication: Requires valid api_key parameter ## Get single product data by ID - [GET /subscriptions/cp/api/data/product](https://developers.subscription.appstle.com/customer-portal-swagger/subscription-management/getproductdata.md): Retrieves detailed information for a specific product by its Shopify product ID. Returns complete product details including all variants, images, and selling plan associations. Product Information Returned: - Basic Details: Title, description, handle, status - Variants: All product variants with pricing - Images: Product images and variant-specific images - Selling Plans: Associated subscription plans - Metadata: Tags, vendor, product type - Options: Color, size, and other variant options Use Cases: - Display product details in subscription management UI - Validate product availability for subscriptions - Get pricing information for subscription creation - Fetch product data for order processing Authentication: Requires valid api_key parameter ## Get delivery options for subscription contract - [GET /subscriptions/cp/api/data/contract-delivery-options](https://developers.subscription.appstle.com/customer-portal-swagger/subscription-management/getcontractdeliveryoptions.md): Retrieves all valid delivery methods available for a specific subscription contract. Returns shipping profiles and delivery options based on the contract's delivery address and product characteristics. Delivery Information Returned: - Available shipping profiles - Delivery methods for each profile - Shipping rates and costs - Delivery speed (standard, express, etc.) - Method names and descriptions - Eligibility based on address and products Filtering Behavior: By default, returns only delivery methods valid for the contract: - Matches delivery address country/region - Compatible with subscription products - Available for contract weight/dimensions Include All Methods: Use header X-Include-All-Methods: true to return all delivery methods regardless of eligibility. Useful for admin UIs where you want to show all options. Use Cases: - Display delivery method selector in customer portal - Allow customers to change shipping method - Calculate shipping costs for subscription - Validate delivery method during subscription updates - Show upgrade options (standard to express) Common Scenarios: Customer Portal - Change Delivery Speed: 1. Call this endpoint with contractId 2. Display available methods to customer 3. Customer selects preferred method 4. Update subscription with new delivery method ID Subscription Creation - Delivery Selection: 1. Get delivery options for draft contract 2. Present options during checkout/signup 3. Create subscription with selected method Important Notes: - Delivery options depend on current contract address - Changing address may change available methods - Costs may vary based on products in subscription - Some methods may have minimum order requirements - International shipping may have additional restrictions Authentication: Requires X-API-Key header