# Billing & Payments APIs for managing payment methods, billing information, and processing subscription payments. ## Update billing interval for a subscription contract - [PUT /subscriptions/cp/api/subscription-contracts-update-billing-interval](https://developers.subscription.appstle.com/customer-portal-swagger/billing-and-payments/updatebillinginterval.md): Updates the billing frequency (how often the customer is charged) for a subscription contract. This comprehensive operation recalculates billing dates, adjusts pricing, updates selling plans, and may also modify delivery intervals. Key Features: - Changes billing frequency while maintaining subscription continuity - Automatically adjusts delivery interval when linked to billing - Recalculates next billing date based on store settings - Reprices all line items for the new frequency - Finds and applies matching selling plans - Handles anchor day adjustments for consistent billing - Validates prepaid subscription constraints Billing Interval Types: - DAY: Daily billing (use with caution) - WEEK: Weekly billing (e.g., every 1, 2, 3 weeks) - MONTH: Monthly billing (e.g., every 1, 2, 3 months) - YEAR: Annual billing Validation Rules: - Cannot set the same interval as current (no-op prevention) - For prepaid subscriptions: billing interval must exceed delivery interval - Example: Can't bill monthly if delivering weekly (would be paying for 1 delivery but receiving 4) Next Billing Date Calculation: The system uses sophisticated logic to determine the new billing date: 1. Starts from current or last successful billing date 2. Applies store timezone and order time preferences 3. Ensures date is in the future 4. Respects day-of-week preferences if configured 5. May keep current date if 'enableChangeFromNextBillingDate' is false Side Effects: - Delivery Interval: Updated if currently equal to billing interval - Line Item Pricing: Recalculated based on new frequency multiplier - Selling Plans: Finds and applies best matching plans for products - Anchor Days: Updates billing anchor for consistent scheduling - Email Notifications: Sends 'ORDER_FREQUENCY_UPDATED' to customer - Activity Logs: Records both billing and delivery changes Prepaid vs Pay-Per-Delivery: - Pay-per-delivery: Billing and delivery intervals typically match - Prepaid: Customer pays upfront for multiple deliveries - This endpoint enforces prepaid logic to prevent undercharging Authentication: Requires valid X-API-Key header ## Update next billing date for a subscription contract - [PUT /subscriptions/cp/api/subscription-contracts-update-billing-date](https://developers.subscription.appstle.com/customer-portal-swagger/billing-and-payments/updatenextbillingdate.md): Reschedules the next billing date for an active subscription contract. This endpoint allows you to change when the next order will be created and processed. Key Features: - Updates the next billing date to the specified date - Optionally reschedules all future orders based on the new date - Syncs the updated date to Shopify - Sends confirmation email to customer The rescheduleFutureOrder Parameter: - true (default): Updates the next billing date AND recalculates all future queued orders based on the new date. Use this to shift the entire billing schedule. - false: Only updates the next billing date. Other queued orders remain unchanged. Use this for one-time date adjustments. Important Notes: - The new date must be in the future (with 10 minute grace period) - Date is validated against the shop's timezone - If anchor days are configured, future orders may align to those anchors Process Flow: 1. Validates the contract exists and belongs to the shop 2. Validates the new date is not in the past 3. Updates the billing attempt to the new date 4. Syncs the updated nextBillingDate to Shopify 5. If rescheduleFutureOrder=true, regenerates the queue from the new date 6. Sends confirmation email to customer 7. Records activity log entry Date Format: - Must be ISO 8601 format with timezone - Examples: 2024-03-15T12:00:00Z, 2024-03-15T12:00:00+05:30 - URL encode the date when passing as query parameter Timezone Handling: - The provided date is used as-is for the billing attempt - Validation (past date check) uses the shop's configured timezone - All dates in the response are in UTC (Z suffix) Date Restrictions (Customer Portal Only): When called from customer portal context: - Minimum days from today (skipDaysFromCurrentDate setting) - Maximum days from today (billingDateRestrictToDays setting) - External API calls bypass these restrictions Authentication: Requires valid X-API-Key header ## Unskip a previously skipped order - [PUT /subscriptions/cp/api/subscription-billing-attempts/unskip-order/{id}](https://developers.subscription.appstle.com/customer-portal-swagger/billing-and-payments/unskiporder.md): 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 ## Skip the next upcoming order for a subscription - [PUT /subscriptions/cp/api/subscription-billing-attempts/skip-upcoming-order](https://developers.subscription.appstle.com/customer-portal-swagger/billing-and-payments/skipfirstupcomingorder.md): 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 ## Skip a specific order - [PUT /subscriptions/cp/api/subscription-billing-attempts/skip-order/{id}](https://developers.subscription.appstle.com/customer-portal-swagger/billing-and-payments/skiporder.md): 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 ## Reschedule a billing attempt to a new date - [PUT /subscriptions/cp/api/subscription-billing-attempts/reschedule-order/{id}](https://developers.subscription.appstle.com/customer-portal-swagger/billing-and-payments/rescheduleorder.md): 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 ## Trigger immediate billing for an order - [PUT /subscriptions/cp/api/subscription-billing-attempts/attempt-billing/{id}](https://developers.subscription.appstle.com/customer-portal-swagger/billing-and-payments/attemptbilling.md): 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 ## Update subscription billing attempt - [PUT /subscriptions/cp/api/subscription-billing-attempts](https://developers.subscription.appstle.com/customer-portal-swagger/billing-and-payments/updatesubscriptionbillingattempt.md): 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 upcoming orders (top orders) - [GET /subscriptions/cp/api/subscription-billing-attempts/top-orders](https://developers.subscription.appstle.com/customer-portal-swagger/billing-and-payments/gettopordersforcp.md): 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 past orders - [GET /subscriptions/cp/api/subscription-billing-attempts/past-orders](https://developers.subscription.appstle.com/customer-portal-swagger/billing-and-payments/getpastordersforcp.md): 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 - [GET /subscriptions/cp/api/subscription-billing-attempts/past-orders/report](https://developers.subscription.appstle.com/customer-portal-swagger/billing-and-payments/getpastordersreportforcp.md): 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