# Subscription Contracts

APIs for managing subscription contracts including delivery schedules, pricing, order notes, billing cycles, and shipping addresses.

## Update multiple line item attributes for a subscription contract

 - [PUT /api/external/v2/subscription-contracts-update-multiple-line-item-attributes](https://developers.subscription.appstle.com/external-api-swagger/subscription-contracts/updatemultiplelineitemattributesv2.md): Updates custom attributes for multiple line items within a subscription contract. The request body must be a JSON object where each key is a line item identifier (as a String) and each value is a list of AttributeInfo objects containing attribute key/value pairs. For example: { "gid://shopify/SubscriptionLineItem/987654321": [ { "key": "color", "value": "red" }, { "key": "size", "value": "M" } ] }. The service validates that the contract exists and that each specified line item is eligible for update. Authentication is performed via the X-API-Key header (the 'api_key' parameter is deprecated).

## Update line item attributes for a subscription contract

 - [PUT /api/external/v2/subscription-contracts-update-line-item-attributes](https://developers.subscription.appstle.com/external-api-swagger/subscription-contracts/updatelineitemattributesv2.md): Updates the custom attributes for a specific line item within a subscription contract. This endpoint accepts a contract ID, a line item ID, and a list of attribute objects (each containing key/value pairs) to update. It uses the underlying service to perform validation (such as contract existence, freeze status, and attribute-based cycle limits) before applying the update. The operation is intended for external API consumers, and authentication is performed via the X-API-Key header. Deprecated api_key parameter is supported for backward compatibility.

## Update Subscription contract frequency by selling plan

 - [PUT /api/external/v2/subscription-contracts-update-frequency-by-selling-plan](https://developers.subscription.appstle.com/external-api-swagger/subscription-contracts/updatefrequencybysellingplanv2.md)

## Replace all line item attributes in bulk across subscription contracts

 - [PUT /api/external/v2/subscription-contracts-bulk-update-line-item-attributes](https://developers.subscription.appstle.com/external-api-swagger/subscription-contracts/updatemultiplecontractslineitemattributesv2.md): This API replaces all existing attributes for the specified line items within subscription contracts. Use carefully, as any attributes not included in the request will be removed.

## Retrieve subscription contracts

 - [GET /api/external/v2/subscription-contract-details](https://developers.subscription.appstle.com/external-api-swagger/subscription-contracts/getallsubscriptioncontractdetails.md): Retrieves a paginated list of subscription contracts with powerful filtering capabilities. This endpoint enables complex queries to find specific subscriptions based on various criteria including dates, customer information, product details, and subscription characteristics.

Key Features:
- Comprehensive filtering across 20+ parameters
- Full pagination support with customizable page size
- Partial text matching for customer and order searches
- Date range filtering for multiple date fields
- Product and variant filtering within line items
- Order amount range filtering
- Plan type differentiation (prepaid vs pay-per-delivery)

Pagination:
- Uses Spring's Pageable format
- Default page size: 20 items
- Maximum page size: 2000 items (exceeding this limit will result in a 400 error)
- Returns total count in X-Total-Count header
- Provides navigation links in Link header

IMPORTANT - Sorting Limitations:
Due to the use of native SQL queries, sort parameters MUST use database column names (snake_case) rather than Java field names (camelCase).

Common sorting examples:
- sort=next_billing_date,asc (NOT nextBillingDate)
- sort=customer_name,desc (NOT customerName)
- sort=created_at,asc (NOT createdAt)
- sort=subscription_contract_id,desc (NOT subscriptionContractId)
- sort=order_amount,asc (NOT orderAmount)

Date Format:
All date parameters use ISO 8601 format with timezone:
yyyy-MM-dd'T'HH:mm:ssXXX
Examples: 2024-03-15T10:30:00+00:00 or 2024-03-15T10:30:00Z

Date Range Filtering:
- For created, updated dates: Can use either 'from', 'to', or both
- For next billing date: Both 'from' and 'to' must be provided together (current limitation)

Text Search Behavior:
- Customer name searches both name and email fields
- Order name searches current and historical orders (in subscription_billing_attempt table)
- All text searches are case-insensitive
- Partial matches are supported (contains logic)
- Subscription contract ID search supports partial numeric matching

Plan Type Classification:
- prepaid: Billing interval > delivery interval
- non-prepaid: Billing interval = delivery interval

Performance Considerations:
- Complex filters (especially JSON searches and order amount calculations) may impact response time
- Use specific filters when possible
- Consider smaller page sizes for complex queries
- Product, variant, and selling plan searches use JSON_SEARCH which may be slow on large datasets

Authentication: Requires valid X-API-Key header (the deprecated 'api_key' query parameter is still accepted but not recommended)

## Retrieve raw Shopify GraphQL response for a subscription contract

 - [GET /api/external/v2/contract-raw-response](https://developers.subscription.appstle.com/external-api-swagger/subscription-contracts/getcontractrawresponse.md): Fetches the complete, unprocessed JSON response directly from Shopify's GraphQL API for the specified subscription contract. This endpoint returns the full subscription data structure as provided by Shopify, including all nested objects and relationships.

Use Cases:
- Debugging subscription issues
- Accessing all available subscription data
- Understanding the complete data structure
- Building custom integrations

Response Structure:
The response includes complete details about:
- Customer information (email, name, ID)
- Line items (products, quantities, pricing)
- Billing and delivery policies
- Payment method details
- Discounts and pricing policies
- Order history and billing attempts
- Custom attributes and notes

Note: This is a direct Shopify response with GraphQL type information (__typename fields)

Authentication: Requires valid X-API-Key header

## Cancel a subscription contract

 - [DELETE /api/external/v2/subscription-contracts/{id}](https://developers.subscription.appstle.com/external-api-swagger/subscription-contracts/deletesubscriptioncontractv2.md): Cancels an existing subscription contract. This operation terminates all future billing and delivery cycles for the subscription. The cancellation takes effect immediately.

Important Notes:
- Any pending/scheduled orders will be cancelled
- The customer will receive a cancellation confirmation email if SUBSCRIPTION_CANCELLED email template is enabled
- Cancellation feedback and notes are stored for analytics and reporting
- Minimum cycle requirements ARE enforced via API (unlike internal cancellations)
- If the subscription is under a free trial period, minimum cycles are not enforced

Validation Rules:
- Contract must exist and belong to the authenticated shop
- Contract must not already be cancelled
- Must have completed minimum required billing cycles (unless in trial)

Post-Cancellation:
- Status changes to 'cancelled' (lowercase)
- Any pause settings are cleared
- Cancellation feedback and notes are saved
- Activity log entry is created
- Cancellation email is sent (if enabled)
- Any invalid discount codes are automatically removed

Authentication: Requires valid X-API-Key header