# Product Catalog

APIs for managing the product catalog including product information, variants, and inventory.

## Get all product swaps for a shop

 - [GET /api/external/v2/product-swaps](https://developers.subscription.appstle.com/external-api-swagger/product-catalog/getallproductswaps.md): Retrieves all configured product swap automations for the authenticated shop. Product swaps allow automatic replacement of products in subscription orders based on billing cycles or recurring schedules.

What are Product Swaps?
Product swaps enable merchants to automatically replace products in subscription orders at specific billing cycles. This is useful for seasonal products, progression paths (e.g., beginner → intermediate → advanced), or variety subscriptions.

Key Features:
- View all configured swap automations
- See source and destination product mappings
- Check which billing cycles trigger swaps
- Identify recurring vs one-time swaps
- Review discount carry-forward settings

Swap Configuration Types:
- One-Time Swap: Occurs at a specific billing cycle
- Recurring Swap: Occurs at every order
- Conditional Swap: Based on billing cycle number

Use Cases:
- Seasonal product rotations (summer → fall → winter products)
- Subscription progression (trial → full product)
- Variety boxes with automatic product rotation
- Product lifecycle management in subscriptions
- A/B testing different products in subscriptions

Authentication: Requires valid X-API-Key header

## Get product swap variant groups for a contract

 - [POST /api/external/v2/product-swaps-by-variant-groups/{contractId}](https://developers.subscription.appstle.com/external-api-swagger/product-catalog/getproductswapsbyvariantidv2.md): Retrieves product swap variant groups for the next 10 billing cycles of a specific subscription contract. This endpoint calculates and returns which products will be swapped to in future billing cycles based on configured swap automations.

Response Structure:
Returns a 2D array (List>):
- Outer array: Represents the next 10 billing cycles
- Inner arrays: Contains the variant(s) that will be swapped to for that specific cycle
- Index 0: Variants for the next (upcoming) billing cycle
- Index 1: Variants for the cycle after that
- And so on for the next 10 cycles

Variant Details:
Each variant object includes:
- variantId: Shopify variant ID
- quantity: Number of units to swap
- title: Variant title (e.g., "Medium Roast - 12oz")
- image: Product/variant image URL
- productTitle: Full product name
- productId: Shopify product GID
- variantTitle: Full display name combining product and variant titles
- swapId: ID of the swap automation rule that triggered this swap

How It Works:
1. Takes the current products in the subscription
2. Applies configured swap automations for the next 10 cycles
3. Calculates which products will be swapped based on:
   - Billing cycle number
   - Swap rule configurations (forBillingCycle, checkForEveryRecurringOrder)
   - Rule sequence/priority
4. Returns the projected product lineup for each cycle

Use Cases:
- Preview upcoming product swaps in customer portals
- Show customers their subscription product timeline
- Build interactive swap calendars
- Display "what you'll receive" for future orders
- Debug and verify swap automation configurations

Important Notes:
- Returns 10 cycles even if no swaps are configured (returns current products)
- Multiple variants in an inner array means multiple products will be in that order
- Empty inner arrays indicate no products for that cycle (rare edge case)
- The swapId can be used to trace which automation rule triggered the swap

Authentication: Requires valid X-API-Key header

## Get all one-time products for a subscription contract

 - [GET /api/external/v2/subscription-contract-one-offs-by-contractId](https://developers.subscription.appstle.com/external-api-swagger/product-catalog/getoneoffsforsubscriptioncontractv2.md): Retrieves all one-time products (add-ons) associated with a specific subscription contract across all billing attempts. One-time products are additional items that customers can add to their subscription orders on a non-recurring basis. Each one-time product is tied to a specific billing attempt and will only be included in that particular order.

Key Features:
- Returns ALL one-time products across all queued billing attempts
- Each product includes the billing attempt ID to identify which order it belongs to
- Includes product details: variant ID, quantity, title, image, and price
- Products are automatically removed after the associated billing attempt is processed

Use Cases:
- Display all one-time products added to a subscription across all upcoming orders
- Allow customers to review their one-time add-ons in customer portal
- Enable merchants to see all one-time products for a contract
- Integrate with external systems to manage subscription add-ons

Authentication: Requires valid X-API-Key header

## Get a specific product swap by ID

 - [GET /api/external/v2/product-swaps/{id}](https://developers.subscription.appstle.com/external-api-swagger/product-catalog/getproductswap.md): Retrieves detailed information about a specific product swap automation configuration. This endpoint returns complete details about the source products, destination products, swap triggers, and all associated settings.

Response Details:
- Complete swap configuration
- Source product variants with images and quantities
- Destination product variants with images and quantities
- Billing cycle triggers and conditions
- Discount carry-forward settings
- Email notification preferences
- Swap status and history

Source and Destination Variants:
Both source and destination variants are returned as JSON strings containing:
- Variant ID
- Display name/title
- Product image URL
- Quantity to swap
- Product metadata

Swap Timing:
- forBillingCycle: If set, swap occurs at this specific cycle number
- checkForEveryRecurringOrder: If true, swap happens on every order
- updatedFirstOrder: If true, can affect the initial subscription order

Discount Handling:
- NONE: No discount carried forward
- PERCENTAGE: Percentage discount is maintained
- FIXED_AMOUNT: Fixed amount discount is maintained
- PRICE: Specific price point is maintained

Authentication: Requires valid X-API-Key header

## Delete a product swap automation

 - [DELETE /api/external/v2/product-swaps/{id}](https://developers.subscription.appstle.com/external-api-swagger/product-catalog/deleteproductswap.md): Permanently deletes a product swap automation configuration. Once deleted, the swap will no longer be applied to any subscription orders. Existing subscriptions that have already had products swapped are not affected.

Deletion Behavior:
- Permanently removes the swap automation
- Does not reverse past swaps that have already occurred
- Future orders will not have this swap applied
- Cannot be undone - swap configuration must be recreated if needed

Impact on Subscriptions:
- Active Subscriptions: Will continue with current products (no automatic reversion)
- Future Orders: Swap will not be applied
- Past Orders: Already swapped products remain unchanged
- Queued Swaps: Pending swaps for this automation are cancelled

When to Delete:
- Discontinuing a seasonal product rotation
- Removing outdated swap rules
- Cleaning up test or experimental swaps
- Product lines being discontinued
- Correcting misconfigured swaps

Important Notes:
- This operation is permanent and cannot be undone
- Consider deactivating instead of deleting if you might reuse the configuration
- Activity logs for past swaps are retained
- Customers are not automatically notified of swap deletion

Best Practices:
- Review affected subscriptions before deletion
- Consider communicating changes to affected customers
- Export swap configuration if you might need it later
- Use deactivation for temporary pauses instead of deletion

Authentication: Requires valid X-API-Key header