# Billing & Payments

APIs for handling billing operations, payment processing, and financial transactions related to subscriptions.

## Update billing interval for a subscription contract

 - [PUT /api/external/v2/subscription-contracts-update-billing-interval](https://developers.subscription.appstle.com/external-api-swagger/billing-and-payments/updatebillingintervalv2.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 /api/external/v2/subscription-contracts-update-billing-date](https://developers.subscription.appstle.com/external-api-swagger/billing-and-payments/updatenextbillingdatev2.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

## Update subscription billing attempt

 - [PUT /api/external/v2/subscription-billing-attempts](https://developers.subscription.appstle.com/external-api-swagger/billing-and-payments/updatesubscriptionbillingattemptv2.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

## Unskip a previously skipped order

 - [PUT /api/external/v2/subscription-billing-attempts/unskip-order/{id}](https://developers.subscription.appstle.com/external-api-swagger/billing-and-payments/unskiporderv2.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 /api/external/v2/subscription-billing-attempts/skip-upcoming-order](https://developers.subscription.appstle.com/external-api-swagger/billing-and-payments/skipfirstupcomingorderv2.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 /api/external/v2/subscription-billing-attempts/skip-order/{id}](https://developers.subscription.appstle.com/external-api-swagger/billing-and-payments/skiporderv2.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 /api/external/v2/subscription-billing-attempts/reschedule-order/{id}](https://developers.subscription.appstle.com/external-api-swagger/billing-and-payments/rescheduleorderv2.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 /api/external/v2/subscription-billing-attempts/attempt-billing/{id}](https://developers.subscription.appstle.com/external-api-swagger/billing-and-payments/attemptbillingv2.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 order note for a billing attempt

 - [PUT /api/external/v2/subscription-billing-attempts-update-order-note/{id}](https://developers.subscription.appstle.com/external-api-swagger/billing-and-payments/updateordernotev2_1.md): Updates the order note (customer note) for a billing attempt. This note will be included when the order is created in Shopify.

Use Cases:
- Add delivery instructions
- Include gift messages
- Add special handling notes
- Store customer preferences for this order

Important Notes:
- Only works on QUEUED billing attempts
- Note is included in the Shopify order when created
- Can be updated multiple times before order is processed

Authentication: Requires valid X-API-Key header

## Get upcoming orders (top orders)

 - [GET /api/external/v2/subscription-billing-attempts/top-orders](https://developers.subscription.appstle.com/external-api-swagger/billing-and-payments/gettopordersv2.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 /api/external/v2/subscription-billing-attempts/past-orders](https://developers.subscription.appstle.com/external-api-swagger/billing-and-payments/getpastordersv2.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 /api/external/v2/subscription-billing-attempts/past-orders/report](https://developers.subscription.appstle.com/external-api-swagger/billing-and-payments/getpastordersreport.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

## Associate external payment gateway customer with Shopify customer

 - [GET /api/external/v2/associate-shopify-customer-to-external-payment-gateways](https://developers.subscription.appstle.com/external-api-swagger/billing-and-payments/associateshopifycustomertoexternalpaymentgateways.md): Links a customer's payment profile from an external payment gateway (Stripe, Braintree, PayPal, Authorize.Net) to their Shopify customer account. This enables Shopify subscription billing to charge payment methods stored in external gateways, which is essential for migrating existing subscriptions or integrating with legacy payment systems.

What This Endpoint Does:
Creates a connection between a Shopify customer and their corresponding customer profile in an external payment gateway. This allows Shopify's subscription system to send billing requests to the external gateway using the stored payment credentials, effectively enabling subscriptions to bill through payment methods managed outside of Shopify.

Supported Payment Gateways:

1. Stripe (paymentGateway=stripe):
- Requires: customerProfileId (Stripe customer ID, e.g., cus_xxxxx)
- Requires: paymentProfileId (Stripe payment method ID, e.g., pm_xxxxx or card ID)
- Links Shopify customer to Stripe customer and stored card/payment method

2. Braintree (paymentGateway=braintree):
- Requires: customerProfileId (Braintree customer ID)
- Requires: paymentProfileId (Braintree payment method token)
- Supports credit cards and PayPal accounts stored in Braintree vault

3. PayPal (paymentGateway=paypal):
- Requires: paymentProfileId (PayPal billing agreement ID)
- Optional: customerProfileId (not required for PayPal)
- Links Shopify customer to PayPal billing agreement

4. Authorize.Net (paymentGateway=authorize_net):
- Requires: customerProfileId (Authorize.Net customer profile ID)
- Requires: paymentProfileId (Authorize.Net payment profile ID)
- Links to Customer Information Manager (CIM) profiles

Request Parameters:

Required Parameters:
- paymentGateway (string): Gateway name - stripe, braintree, paypal, or authorize_net
- paymentProfileId (string): Payment method/card ID in the external gateway
- customerId OR email (one required): Shopify customer identifier

Optional Parameters:
- customerProfileId (string): Customer ID in external gateway (required for Stripe, Braintree, Authorize.Net; optional for PayPal)

Customer Identification:

By Customer ID (recommended):
- Provide Shopify customerId if known
- Fastest and most reliable method
- Avoids ambiguity with duplicate emails

By Email:
- Provide customer email if customer ID unknown
- System looks up Shopify customer by email
- If exactly one match: Uses that customer
- If multiple matches: Returns error (ambiguous)
- If no matches: Creates new Shopify customer with that email

Use Cases:

1. Subscription Migration:
- Migrating subscriptions from legacy platform to Shopify
- Preserving existing payment methods during migration
- Avoiding customer disruption by not requiring payment re-entry
- Maintaining payment history and customer profiles

2. Payment Gateway Integration:
- Using external payment processor for compliance reasons
- Leveraging existing payment gateway relationships
- Maintaining payment data in external PCI-compliant vault
- Integrating with enterprise payment infrastructure

3. Multi-Platform Sync:
- Syncing payment methods from other sales channels
- Centralizing payment methods across platforms
- Enabling subscriptions for existing customer base

4. Custom Checkout Flows:
- Building custom subscription checkout with external gateway
- Collecting payment via external gateway, then linking to Shopify
- Supporting payment methods not natively available in Shopify

Process Flow:

1. Customer Lookup:
   - If customerId provided: Use directly
   - If email provided: Search for existing Shopify customer
   - If email not found: Create new Shopify customer

2. Validation:
   - Validate payment gateway name
   - Check required parameters for selected gateway
   - Verify customer belongs to authenticated shop

3. Gateway Association:
   - Call Shopify GraphQL mutation for gateway-specific association
   - Link customer profile ID and payment profile ID
   - Store association in Shopify's payment instrument vault

4. Response:
   - Return Shopify's raw GraphQL response
   - Response includes payment instrument ID for future use
   - Contains success/error details from Shopify API

Example Requests:

Stripe Example:

GET /api/external/v2/associate-shopify-customer-to-external-payment-gateways?
  paymentGateway=stripe&
  customerId=12345&
  customerProfileId=cus_ABC123&
  paymentProfileId=pm_XYZ789


Braintree with Email:

GET /api/external/v2/associate-shopify-customer-to-external-payment-gateways?
  paymentGateway=braintree&
  email=customer@example.com&
  customerProfileId=bt_customer_123&
  paymentProfileId=bt_card_token_456


PayPal Example:

GET /api/external/v2/associate-shopify-customer-to-external-payment-gateways?
  paymentGateway=paypal&
  customerId=12345&
  paymentProfileId=B-12345BILLING67890


Important Considerations:

Gateway Setup:
- External payment gateway must be installed and configured in Shopify
- Gateway must be activated for subscription billing
- Appropriate credentials and API keys must be configured

Data Validation:
- Payment profile IDs are not validated against external gateway
- Invalid IDs will be accepted but will fail during actual billing
- Test associations before migrating production subscriptions

Customer Creation:
- If customer doesn't exist and email provided, new customer is created
- Created customers have minimal information (just email initially)
- Consider adding additional customer details after creation

Security:
- This endpoint does NOT store or handle actual payment credentials
- Only references/tokens to external gateway profiles are used
- Payment data remains in external gateway's PCI-compliant vault
- Shopify never receives sensitive card data

Best Practices:

1. Test First: Test with sandbox/test gateway credentials before production
2. Verify Gateway Active: Ensure external gateway is properly configured in Shopify
3. Use Customer ID: Prefer customerId over email to avoid ambiguity
4. Handle Errors: Implement robust error handling for gateway failures
5. Validate Externally: Verify payment profiles exist in external gateway before associating
6. Document IDs: Keep mapping of Shopify customer IDs to external gateway IDs

Migration Workflow Example:


For each legacy subscription:
1. Get customer email and Stripe customer ID from legacy system
2. Call this endpoint to link Shopify customer to Stripe customer
3. Create subscription contract in Shopify using returned payment instrument
4. Verify subscription created successfully
5. Mark legacy subscription as migrated
6. Test billing with external gateway


Troubleshooting:

"More than one customer found for email":
- Multiple Shopify customers exist with same email
- Solution: Use specific customerId instead of email

"Invalid payment gateway":
- Gateway name misspelled or unsupported
- Solution: Use exact values: stripe, braintree, paypal, authorize_net

"customerProfileId required":
- Missing required parameter for Stripe/Braintree/Authorize.Net
- Solution: Provide customer ID from external gateway

Response Format:
Returns Shopify's raw GraphQL mutation response containing payment instrument details and success/error information.

Related Endpoints:
- GET /api/external/v2/subscription-contract-details/shopify/customer/{customerId}/payment-methods - Verify association successful
- PUT /api/external/v2/subscription-contracts-update-payment-method - Use associated payment for subscription

Authentication: Requires valid X-API-Key header