Skip to content
Customer Portal APIs
/Product Catalog/
Get product swap variant...

Customer Portal APIs (0.0.1)

Comprehensive API documentation for the customer-facing subscription portal. These APIs enable customers to manage their subscriptions, update billing information, modify delivery schedules, and access their account details through your storefront.

Important: These APIs must be called from your shop's domain (e.g., https://www.myshop.com/apps/subscriptions/cp/api/**) and require customer authentication. Unauthenticated requests will return a 401 Unauthorized error.

Download OpenAPI description
customer-portal-swagger.json
customer-portal-swagger.yaml
Languages
Servers
https://www.myshop.com/apps

Customer Portal

Core customer portal APIs for managing customer account settings, authentication, and portal configurations.

Operations

Subscription Management

APIs for customers to view and manage their subscription contracts including status updates, frequency changes, and cancellations.

Operations

Billing & Payments

APIs for managing payment methods, billing information, and processing subscription payments.

Operations

Product Catalog

APIs for retrieving product information, selling plans, variant data, and subscription-enabled products available to customers.

Operations

Get product swap variant groups for a contract

Request

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<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

Path
contractIdinteger(int64)required
Bodyapplication/jsonrequired
variantQuantityListArray of objects(VariantQuantity)
curl -i -X POST \
  'https://www.myshop.com/apps/subscriptions/cp/api/product-swaps-by-variant-groups/{contractId}' \
  -H 'Content-Type: application/json' \
  -d '{
    "variantQuantityList": [
      {
        "variantId": 0,
        "quantity": 0,
        "title": "string",
        "image": "string",
        "productTitle": "string",
        "productId": "string",
        "variantTitle": "string",
        "swapId": 0
      }
    ]
  }'

Responses

Product swap variant groups returned successfully - Returns swappable variants for the next 10 billing cycles. Each element in the outer array represents the variants that will be swapped to for a specific billing cycle.

Bodyapplication/json
Response
application/json
[
  [
    { … },
    { … }
  ],
  [
    { … }
  ]
]

Delivery & Shipping

APIs for managing delivery schedules, shipping addresses, delivery methods, and tracking order status.

Customer Retention

APIs for handling subscription cancellations, retention activities, and customer feedback management.

Loyalty Integration

APIs for integrating loyalty programs with subscriptions including points redemption and earning options.

Customization

APIs for accessing portal customization settings, translations, and theme configurations.