# Operations & Settings

APIs for managing operational settings, configurations, and administrative functions.

## Create a new shipping/delivery profile (V3)

 - [POST /api/external/v2/delivery-profiles/v3/create-shipping-profile](https://developers.subscription.appstle.com/external-api-swagger/operations-and-settings/createshippingprofilev3external.md): Creates a new shipping or delivery profile for subscription orders using the V3 request format. This is the latest version with the most comprehensive delivery profile configuration capabilities.

Enhancements in V3:
- Full support for all Shopify delivery profile features
- Advanced rate calculation options
- Support for weight-based and price-based rates
- Enhanced zone and country management
- Better handling of delivery conditions and rules

Key Features:
- Define complex shipping rate structures
- Configure multiple delivery methods per zone
- Set up conditional rates based on weight, price, or item count
- Manage detailed shipping zones with province-level granularity
- Full control over delivery profile settings

Authentication: Requires valid X-API-Key header

## Create a new shipping/delivery profile (V2)

 - [POST /api/external/v2/delivery-profiles/v2/create-shipping-profile](https://developers.subscription.appstle.com/external-api-swagger/operations-and-settings/createshippingprofilev2external.md): Creates a new shipping or delivery profile for subscription orders using the V2 request format. This version provides enhanced configuration options for delivery methods, zones, and pricing.

Enhancements in V2:
- Improved zone configuration
- Better support for multiple delivery methods
- Enhanced rate definition capabilities
- Support for conditional delivery rates

Key Features:
- Define custom shipping rates per zone
- Configure local delivery options
- Set up local pickup methods
- Manage shipping zones and countries
- Assign profiles to specific products or variants

Authentication: Requires valid X-API-Key header

## Create a new shipping/delivery profile

 - [POST /api/external/v2/delivery-profiles/create-shipping-profile](https://developers.subscription.appstle.com/external-api-swagger/operations-and-settings/createshippingprofilev2.md): Creates a new shipping or delivery profile for subscription orders. This endpoint allows you to configure custom shipping rates, delivery methods, and shipping zones for your subscription products. Delivery profiles control how subscription products are shipped to customers.

Key Features:
- Define custom shipping rates per zone
- Configure local delivery options
- Set up local pickup methods
- Manage shipping zones and countries
- Assign profiles to specific products or variants

Delivery Method Types:
- SHIPPING: Standard shipping with carrier rates or custom rates
- LOCAL_DELIVERY: Local delivery service within specific areas
- PICKUP: Customer pickup from store locations

Important Notes:
- Each delivery profile must have a unique name
- At least one delivery method is required
- Shipping rates can be set per zone and per weight/price range
- Profiles can be assigned to subscription products to control their shipping behavior

Authentication: Requires valid X-API-Key header

## Replace products in subscriptions in bulk

 - [POST /api/external/v2/bulk-automations/replace-product](https://developers.subscription.appstle.com/external-api-swagger/operations-and-settings/replaceproductv2.md): Replaces old product variants with new product variants across multiple subscription contracts in bulk. This powerful operation allows merchants to update products in active subscriptions when products are discontinued, reformulated, or repackaged.

What is Product Replacement?
Product replacement updates the products in active subscriptions by swapping out old variant IDs with new variant IDs. This is commonly needed when:
- Products are discontinued and replaced with new versions
- Product packaging changes (size, quantity)
- Product reformulations or recipe updates
- SKU consolidation or reorganization
- Seasonal product variations
- Price structure changes

Key Features:
- Bulk Operation: Update thousands of subscriptions simultaneously
- Multi-Variant Support: Replace multiple old variants with new ones in single request
- Flexible Mapping: One-to-one, many-to-one, or one-to-many variant replacements
- Selective or Universal: Target specific subscriptions or all subscriptions
- Asynchronous Processing: Large batches processed in background
- Price Preservation Options: Maintain existing subscription pricing or update to new prices
- Activity Logging: All replacements are logged for audit trail

Operation Modes:
1. Specific Subscriptions: Provide subscription contract IDs to update only those subscriptions
2. All Subscriptions: Set allSubscriptions=true to replace products in ALL active subscriptions containing the old variants

How It Works:
1. Identify old variant IDs that need to be replaced
2. Identify new variant IDs that will replace them
3. Optionally specify which subscriptions to update (or use allSubscriptions=true)
4. Submit the bulk replacement request
5. System validates all variant IDs exist and are accessible
6. Bulk automation task is created and queued
7. Each subscription is updated with new variants
8. Customers receive updated subscription details
9. Next orders will include the new products

Variant ID Mapping:
The replacement supports flexible mapping between old and new variants:

One-to-One Replacement:
json
{
  "oldVariantIds": [111111],
  "newVariantIds": [222222]
}

Old variant 111111 is replaced with new variant 222222

Multiple Variants Replacement:
json
{
  "oldVariantIds": [111111, 333333, 555555],
  "newVariantIds": [222222, 444444, 666666]
}

Each old variant is replaced with its corresponding new variant (by position)

Request Structure:
json
{
  "subscriptionIds": [
    "gid://shopify/SubscriptionContract/123456",
    "gid://shopify/SubscriptionContract/123457"
  ]
}


Query Parameters:
- api_key (required): Your API authentication key
- allSubscriptions (optional): Set to true to update all subscriptions, false/omit to update only specified IDs
- newVariantIds (required): Comma-separated list of new variant IDs (e.g., 222222,444444,666666)
- oldVariantIds (required): Comma-separated list of old variant IDs to replace (e.g., 111111,333333,555555)

Use Cases:

1. Product Discontinuation:
When a product is being discontinued:
- Identify replacement product
- Map old variant IDs to new variant IDs
- Update all subscriptions containing the old product
- Notify customers of the change

2. Packaging Updates:
When product packaging changes (e.g., 10oz to 12oz):
- Create new variant for new package size
- Replace old variant across subscriptions
- Adjust pricing if needed

3. Product Reformulation:
When product recipes or formulas change:
- Create new product variant for reformulated version
- Bulk replace old formula with new formula
- Maintain customer subscription frequency and pricing

4. SKU Consolidation:
When consolidating multiple variants into a single SKU:
- Map multiple old variant IDs to single new variant ID
- Update all affected subscriptions
- Simplify inventory management

5. Seasonal Product Rotation:
For seasonal subscription boxes:
- Replace summer variants with fall variants
- Update all active seasonal subscriptions
- Maintain subscription continuity

Important Considerations:
- Pricing Impact: New variants may have different prices - verify pricing strategy
- Inventory Levels: Ensure adequate inventory for new variants
- Customer Communication: Consider notifying customers before replacement
- Variant Compatibility: New variants should be appropriate replacements
- One Operation at a Time: Only one bulk operation can run per shop simultaneously
- Irreversible: Product replacements cannot be automatically undone (must be manually reversed)
- Subscription Contract IDs: Must use Shopify GraphQL ID format

Processing Time:
- Small batches (1000): Minutes to hours
- Processing time depends on number of subscriptions and line items

Best Practices:
1. Test First: Test with a small subset of subscriptions before bulk operation
2. Verify Variants: Confirm all variant IDs are correct and products are active
3. Check Inventory: Ensure sufficient stock of new variants
4. Customer Communication: Notify affected customers about product changes
5. Price Review: Review and confirm pricing for new variants
6. Backup Data: Export subscription data before making bulk changes
7. Monitor Progress: Track bulk operation status to completion
8. Audit Trail: Document reason for replacement for future reference

Error Scenarios:
- Another bulk operation running: 400 error
- Invalid variant IDs: Operation may fail or skip invalid variants
- Mismatched array lengths: Ensure oldVariantIds and newVariantIds have same count
- Product not found: Variants must exist in your Shopify store
- Unauthorized access: Can only modify subscriptions belonging to your shop

Customer Impact:
- Next subscription order will contain new products
- Previous orders are not affected
- Subscription price may change if new variant has different price
- Customer portal reflects the new product immediately
- Subscription frequency and schedule remain unchanged

Authentication: Requires valid api_key parameter (X-API-Key header support coming soon)

## Hide subscriptions in bulk

 - [POST /api/external/v2/bulk-automations/hide-subscriptions](https://developers.subscription.appstle.com/external-api-swagger/operations-and-settings/hidesubscriptionsv2.md): Hides multiple subscription contracts from customer view in bulk. This operation allows merchants to quickly hide subscriptions from appearing in the customer portal without canceling or deleting them.

What Does 'Hide' Mean?
Hiding a subscription makes it invisible to customers in their customer portal while keeping the subscription data intact. The subscription is not deleted or canceled - it's simply hidden from the customer's view. This is useful for:
- Temporarily removing subscriptions from customer access
- Managing test or dummy subscriptions
- Handling subscription disputes or issues
- Preparing subscriptions for migration or cleanup

Key Features:
- Bulk Operation: Process multiple subscriptions in a single request
- Non-Destructive: Subscriptions are hidden, not deleted
- Reversible: Hidden subscriptions can be unhidden later
- Asynchronous Processing: Large batches are processed in the background
- Conflict Detection: Prevents multiple simultaneous bulk operations

Operation Modes:
1. Specific Subscriptions: Provide a list of subscription contract IDs to hide
2. All Subscriptions: Set allSubscriptions=true to hide all active subscriptions (use with caution)

How It Works:
1. Submit a request with subscription IDs or allSubscriptions flag
2. System validates the subscription IDs belong to your shop
3. A bulk automation task is created and queued
4. Each subscription is marked as hidden
5. Subscriptions disappear from customer portal immediately
6. Subscriptions remain in merchant admin for management

Request Body Structure:
json
{
  "subscriptionIds": [
    "gid://shopify/SubscriptionContract/123456",
    "gid://shopify/SubscriptionContract/123457",
    "gid://shopify/SubscriptionContract/123458"
  ]
}


Use Cases:
- Subscription Cleanup: Hide test or duplicate subscriptions created during setup
- Customer Service: Temporarily hide problematic subscriptions while resolving issues
- Migration Preparation: Hide old subscriptions before migrating to new plans
- Dispute Management: Hide subscriptions involved in billing disputes
- Seasonal Management: Hide seasonal subscriptions during off-season
- Batch Processing: Clean up subscriptions that meet certain criteria

Important Notes:
- Only one bulk operation can run at a time per shop
- If a bulk operation is already in progress, the request will fail with 400 error
- Subscription IDs must be in Shopify GraphQL ID format (gid://shopify/SubscriptionContract/xxxxx)
- Hidden subscriptions stop appearing in customer portal but remain active for billing
- You can unhide subscriptions later through the admin interface
- Using allSubscriptions=true will hide ALL subscriptions - use with extreme caution

Processing Time:
- Small batches (1000): May take several minutes to hours
- Progress can be tracked through the bulk automation status endpoint

Best Practices:
- Always specify exact subscription IDs rather than using allSubscriptions=true
- Test with a small batch first before processing large numbers
- Keep track of hidden subscription IDs for future reference
- Document the reason for hiding subscriptions for audit purposes
- Monitor bulk operation status to ensure completion
- Consider notifying customers before hiding their subscriptions

Workflow Example:
1. Identify subscriptions to hide (e.g., test subscriptions with specific tags)
2. Extract their subscription contract IDs
3. Call this endpoint with the list of IDs
4. Verify 204 No Content response indicating successful queue
5. Monitor processing status through admin or status endpoint
6. Confirm subscriptions are hidden from customer portal

Error Scenarios:
- Another bulk operation is running: 400 error with message about operation in progress
- Invalid subscription IDs: Silently skips invalid IDs, processes valid ones
- Unauthorized subscription access: Only subscriptions belonging to your shop are processed
- Empty subscription list: Operation completes successfully with no action

Authentication: Requires valid api_key parameter (X-API-Key header support coming soon)

## Get cancellation management configuration

 - [GET /api/external/v2/cancellation-managements/{id}](https://developers.subscription.appstle.com/external-api-swagger/operations-and-settings/getcancellationmanagementv2.md): Retrieves the cancellation management and retention settings for the authenticated shop. These settings control the subscription cancellation flow, retention strategies, and customer feedback collection when subscribers attempt to cancel their subscriptions.

What is Cancellation Management?
Cancellation management is a retention system that helps merchants reduce subscription churn by understanding why customers cancel and offering alternatives before they leave. It includes cancellation flows, feedback collection, retention offers (discounts, pauses, frequency changes), and automated win-back strategies.

Configuration Components:

1. Cancellation Flow Settings:
- Enable/disable self-service cancellation in customer portal
- Require customer to contact support for cancellation
- Multi-step cancellation confirmation process
- Cancellation cooldown period (prevent accidental cancellations)
- Minimum subscription duration before cancellation allowed
- Immediate vs. end-of-billing-cycle cancellation

2. Cancellation Reasons & Feedback:
- Predefined cancellation reasons list
- Custom cancellation reason options
- Required vs. optional feedback
- Free-form text feedback field
- Rating/satisfaction scale
- Exit survey questions
- Feedback sent to merchant email/dashboard

Common Cancellation Reasons:
- Too expensive / Can't afford
- Don't use product enough / Have too much inventory
- Product quality issues
- Switching to competitor
- Delivery issues / Shipping problems
- Forgot to cancel earlier
- Temporary pause needed (moving, travel, etc.)
- Product doesn't meet expectations
- Customer service issues
- Other (with text field)

3. Retention Offers (Save Flow):
- Display retention offers before final cancellation
- Offer discount (percentage or fixed amount)
- Offer free product/gift with next order
- Suggest subscription pause instead of cancel
- Suggest frequency change (deliver less often)
- Offer to skip next order
- Offer to swap products
- Personalized offers based on cancellation reason

Example Retention Logic:

Reason: "Too expensive"
  → Offer: 20% discount for next 3 months
  → Offer: Switch to smaller/cheaper variant

Reason: "Have too much inventory"
  → Offer: Pause for 1-3 months
  → Offer: Change from monthly to every 2 months
  → Offer: Skip next 2 deliveries

Reason: "Product quality issues"
  → Offer: Free replacement on next order
  → Offer: Try different product variant
  → Route to customer support


4. UI/UX Configuration:
- Cancellation button placement and styling
- Warning messages and modal dialogs
- Progress indicator for multi-step flow
- Retention offer presentation (modal, inline, etc.)
- Confirmation messages
- Post-cancellation survey

5. Automation & Notifications:
- Send cancellation confirmation email
- Notify merchant of cancellations
- Trigger win-back email campaigns
- Schedule feedback review
- Alert for high cancellation rate
- Integration with CRM/analytics tools

6. Metrics & Analytics:
- Track cancellation rate
- Categorize cancellation reasons
- Measure retention offer acceptance rate
- Calculate customer lifetime value at cancellation
- Identify churn patterns and trends
- A/B test different retention strategies

7. Advanced Features:
- Conditional retention offers based on:
  - Customer lifetime value
  - Subscription duration
  - Product type
  - Cancellation history
  - Customer segment
- Win-back campaigns for cancelled subscribers
- Automatic re-engagement emails (30, 60, 90 days post-cancel)
- Special offers to reactivate cancelled subscriptions

Cancellation Flow Examples:

Basic Flow (No Retention):
1. Customer clicks "Cancel Subscription"
2. Confirmation dialog: "Are you sure?"
3. Optional: Select cancellation reason
4. Subscription cancelled immediately or at period end
5. Confirmation email sent

Advanced Retention Flow:
1. Customer clicks "Cancel Subscription"
2. "Before you go..." - Select cancellation reason
3. Display personalized retention offer based on reason
4. Customer chooses: Accept offer OR Continue to cancel
5. If continue: Additional offers or final confirmation
6. If still cancelling: Exit survey
7. Cancellation processed
8. Thank you message + feedback confirmation
9. Follow-up email campaign

Use Cases:
- Configure cancellation flow in customer portal
- Customize retention offers and messaging
- Analyze cancellation patterns and trends
- Build custom cancellation interfaces
- Integrate with customer support tools
- Generate churn reports and analytics
- A/B test different retention strategies
- Automate win-back campaigns

Important Notes:
- Always comply with consumer protection laws regarding cancellation
- Make cancellation process clear and accessible (FTC guidelines)
- Don't make cancellation unnecessarily difficult
- Respect customer's decision to cancel
- Use retention offers ethically (not dark patterns)
- Store cancellation feedback for product improvement
- GDPR/privacy compliance for feedback data

Best Practices:
- Keep cancellation process simple (2-3 steps max)
- Offer genuine value in retention offers
- Personalize offers based on cancellation reason
- Make pause/skip options prominent
- Use cancellation feedback to improve product/service
- Set up automated win-back campaigns
- Monitor cancellation rate and take action on trends
- Train customer support on retention strategies
- Test different retention messaging and offers
- Honor cancellations promptly and professionally

Legal & Compliance:
- FTC regulations require easy cancellation (Click-to-Cancel rule)
- California automatic renewal law compliance
- European consumer protection directives
- Clear disclosure of cancellation terms
- Process cancellations within legal timeframes
- Provide confirmation of cancellation

Authentication: Requires valid X-API-Key header

## Get/Search activity logs

 - [GET /api/external/v2/activity-logs](https://developers.subscription.appstle.com/external-api-swagger/operations-and-settings/getallactivitylogs.md): Retrieves activity logs for all subscription-related events and changes in the authenticated shop. Activity logs provide a comprehensive audit trail of all subscription activities, changes, and system events.

What are Activity Logs?
Activity logs are detailed records of every action, event, and change that occurs within your subscription system. They capture who made the change, when it happened, what was changed, and the result of the operation. This provides full traceability and audit capabilities for compliance, debugging, and customer support.

Log Information Captured:
- Entity Information:
  - Entity ID: The specific subscription, billing attempt, or resource affected
  - Entity Type: Type of resource (subscription, billing attempt, plan, settings, etc.)
  - Event Type: Specific action performed (see Event Types below)
  - Event Source: Origin of the event (customer portal, merchant portal, API, system, etc.)

- Event Details:
  - Status: SUCCESS, FAILURE, or INFO
  - Timestamp: When the event occurred
  - Activity By: User or system that triggered the event
  - Client IP: IP address of the requester (if applicable)
  - Additional Info: Detailed JSON payload with before/after values and context

Entity Types:
- SUBSCRIPTION_BILLING_ATTEMPT - Billing and payment attempt events
- SUBSCRIPTION_CONTRACT_DETAILS - Subscription contract modifications
- SUBSCRIPTION_GROUP_PLAN - Subscription plan changes
- SHIPPING_PROFILE - Delivery profile and shipping updates
- CANCELLATION_MANAGEMENT - Subscription cancellation events
- DUNNING_MANAGEMENT - Payment retry and dunning activities
- PRODUCT_SWAP - Product replacement events
- FREQUENCY_SWAP - Billing/delivery frequency changes
- EMAIL_TEMPLATE - Email template modifications
- SHOP_INFO - Shop settings and configuration changes
- SUBSCRIPTION_WIDGET_SETTINGS - Widget configuration updates
- CUSTOMER_PORTAL_SETTINGS - Portal settings modifications
- SUBSCRIPTION_BUNDLING - Bundle and bundling rule changes

Event Sources:
- CUSTOMER_PORTAL - Changes made by subscribers through the customer portal
- MERCHANT_PORTAL - Changes made by merchants in the admin panel
- MERCHANT_EXTERNAL_API - Changes made via API by merchants or integrations
- SHOPIFY_EVENT - Events triggered by Shopify webhooks
- SHOPIFY_FLOW - Events triggered by Shopify Flow automations
- SYSTEM_EVENT - Automated system events (scheduled tasks, sync operations)
- MERCHANT_PORTAL_BULK_AUTOMATION - Bulk operations initiated from admin panel

Common Event Types:
- Subscription Changes: CONTRACT_PAUSED, CONTRACT_ACTIVATED, CONTRACT_CANCELLED, CONTRACT_CREATED
- Product Changes: PRODUCT_ADD, PRODUCT_REMOVE, PRODUCT_REPLACE, PRODUCT_QUANTITY_CHANGE, PRODUCT_PRICE_CHANGE
- Billing Changes: NEXT_BILLING_DATE_CHANGE, BILLING_INTERVAL_CHANGE, BILLING_ATTEMPT_TRIGGERED, BILLING_ATTEMPT_SKIPPED
- Delivery Changes: DELIVERY_INTERVAL_CHANGE, SHIPPING_ADDRESS_CHANGE, DELIVERY_METHOD_UPDATED
- Payment Changes: PAYMENT_METHOD_UPDATED, SWITCH_PAYMENT_METHODS
- Email Events: SEND_UPCOMING_ORDER_EMAIL, SEND_TRANSACTION_FAILED_EMAIL, SEND_SUBSCRIPTION_CREATED_EMAIL
- Discount Events: DISCOUNT_APPLIED, DISCOUNT_REMOVED, PRICING_POLICY_DISCOUNT_APPLIED
- One-Time Products: ONE_TIME_PURCHASE_PRODUCT_ADDED, ONE_TIME_PURCHASE_PRODUCT_REMOVED

Query Parameters and Filtering:

You can filter activity logs using query parameters. All filters support standard operations:
- equals - Exact match
- in - Match any value in list
- greaterThan, lessThan - Date range filtering
- contains - Partial text match

Example Filter Queries:

1. Get all failed billing attempts:
   ?entityType.equals=SUBSCRIPTION_BILLING_ATTEMPT&eventType.equals=BILLING_ATTEMPT_TRIGGERED&status.equals=FAILURE

2. Get all customer portal changes:
   ?eventSource.equals=CUSTOMER_PORTAL

3. Get logs for a specific subscription:
   ?entityId.equals=123456&entityType.equals=SUBSCRIPTION_CONTRACT_DETAILS

4. Get logs within date range:
   ?createAt.greaterThan=2024-01-01T00:00:00Z&createAt.lessThan=2024-01-31T23:59:59Z

5. Get all cancellation events:
   ?eventType.equals=CONTRACT_CANCELLED

6. Get all API-triggered changes:
   ?eventSource.equals=MERCHANT_EXTERNAL_API

Pagination:

Results are paginated. Use standard Spring Data pagination parameters:
- page - Page number (zero-indexed, default: 0)
- size - Page size (default: 20, max: 100)
- sort - Sort criteria (e.g., createAt,desc or id,asc)

Example: ?page=0&size=50&sort=createAt,desc

Use Cases:
- Audit and Compliance: Track all changes for regulatory compliance and internal auditing
- Customer Support: Review subscription history to troubleshoot customer issues
- Debugging: Investigate failed operations and system errors
- Analytics: Analyze customer behavior and subscription lifecycle patterns
- Reporting: Generate reports on subscription changes, cancellations, and modifications
- Integration Monitoring: Track API usage and automated workflow executions
- Security: Monitor for unusual activity patterns or unauthorized changes

Important Notes:
- Activity logs are immutable and cannot be modified or deleted via API
- Logs are retained according to your subscription plan's retention policy
- The additionalInfo field contains detailed JSON with event-specific context
- For large exports, consider using pagination and filtering to reduce data transfer
- Logs are scoped to your shop - you can only access logs for your own subscriptions
- System events may not have an activityBy value as they're automated

Response Headers:
- X-Total-Count - Total number of matching records
- Link - Pagination links (first, last, next, prev)

Authentication: Requires valid api_key query parameter with appropriate permissions