Skip to content
Customer Portal APIs
/
/
Replace product variants...

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

Split or duplicate an existing subscription contract

Request

Creates a new subscription contract by either splitting (moving) or duplicating selected line items from an existing contract. This endpoint allows you to divide a subscription into multiple contracts or create a copy with specific products.

Split vs Duplicate Mode:

  • Split (isSplitContract=true): Moves the selected line items from the original contract to a new contract. The original contract will no longer contain these items.
  • Duplicate (isSplitContract=false): Creates a new contract with copies of the selected line items while keeping them in the original contract.

Important Notes:

  • When splitting, at least one subscription product must remain in the original contract
  • The new contract inherits all settings from the original: customer, payment method, billing/delivery policies, shipping address, and custom attributes
  • Billing schedule is automatically generated for the new contract
  • One-time products and free products don't count towards the minimum product requirement

Use Cases:

  • Split a subscription when customer wants different delivery schedules for different products
  • Create a gift subscription from an existing subscription
  • Separate products for different shipping addresses
  • Duplicate a subscription for testing or backup purposes

Authentication: Requires valid X-API-Key header

Query
contractIdinteger(int64)required
isSplitContractboolean
Default false
attemptBillingboolean
Default false
Bodyapplication/jsonrequiredArray [
string
]
curl -i -X POST \
  'https://www.myshop.com/apps/subscriptions/cp/api/subscription-contract-details/split-existing-contract?contractId=0&isSplitContract=false&attemptBilling=false' \
  -H 'Content-Type: application/json' \
  -d '[
    "string"
  ]'

Responses

Contract successfully split/duplicated

Bodyapplication/json
get__typenamestring
idstring
createdAtobject
updatedAtobject
nextBillingDateobject
statusstring
Enum"ACTIVE""PAUSED""CANCELLED""EXPIRED""FAILED""$UNKNOWN"
deliveryPriceobject(DeliveryPrice)
lastPaymentStatusstring
Enum"SUCCEEDED""FAILED""$UNKNOWN"
billingPolicyobject(BillingPolicy)
deliveryPolicyobject(DeliveryPolicy)
linesobject(Lines)
customerPaymentMethodobject(CustomerPaymentMethod)
deliveryMethodobject(DeliveryMethod)
originOrderobject(OriginOrder)
customerobject(Customer)
discountsobject(Discounts)
notestring
customAttributesArray of objects(CustomAttribute1)
billingAttemptsobject(BillingAttempts)
Response
application/json
{
  "id": "gid://shopify/SubscriptionContract/987654321",
  "status": "ACTIVE",
  "nextBillingDate": "2024-02-15T00:00:00Z",
  "originOrder": {
    "id": "gid://shopify/Order/123456789"
  },
  "customer": {
    "id": "gid://shopify/Customer/111111",
    "email": "customer@example.com"
  },
  "billingPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "deliveryPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "lines": {
    "edges": [ … ]
  },
  "customAttributes": [
    { … },
    { … }
  ]
}

Replace product variants in a subscription contract

Request

Replaces existing product variants with new ones in a subscription contract. This endpoint supports both regular subscription products and one-time products, allowing you to swap products, update quantities, and manage the product mix in a subscription.

Key Features:

  • Bulk Replace: Replace multiple products at once by providing lists of old and new variants
  • Line-Specific Replace: Target a specific line item using oldLineId for precise replacement
  • Quantity Management: Set new quantities for replaced products
  • One-Time Products: Add or remove one-time purchase products independently
  • Discount Preservation: Configurable discount carry-forward logic

Discount Carry Forward Options:

  • PRODUCT_THEN_EXISTING: First tries to apply the new product's selling plan discount, then falls back to existing discount
  • PRODUCT_PLAN: Always uses the new product's selling plan discount
  • EXISTING_PLAN: Maintains the existing product's discount structure

Important Notes:

  • At least one regular subscription product must remain in the contract
  • One-time products and free products don't count towards the minimum product requirement
  • The system automatically handles pricing adjustments based on billing/delivery intervals
  • Shipping prices are automatically recalculated after changes

Use Cases:

  • Product upgrades/downgrades (e.g., switching coffee blend or size)
  • Quantity adjustments during product swap
  • Adding limited-time or seasonal products as one-time purchases
  • Bulk product replacements for subscription migrations

Authentication: Requires valid X-API-Key header

Bodyapplication/jsonrequired
shopstringrequired

The Shop of the subscription contract to modify

Example: "abcStore.myshopify.com"
contractIdinteger(int64)required

The ID of the subscription contract to modify

Example: 123456789
oldVariantsArray of integers(int64)

List of variant IDs to remove from the subscription. These are numeric Shopify variant IDs. Either provide oldVariants OR oldLineId, not both.

Example: [42549172011164,42549172022222]
newVariantsobject

Map of new variant IDs to their quantities. Key is the numeric Shopify variant ID, value is the desired quantity. If a variant already exists in the subscription and the system is configured to update existing quantities, the quantity will be added to the existing quantity.

Example: {"42549172033333":2,"42549172044444":1}
newOneTimeVariantsobject

Map of one-time product variant IDs to add with their quantities. These products will be charged only once with the next order and won't recur. Useful for add-ons, samples, or limited-time offers.

Example: {"42549172066666":1,"42549172077777":2}
oldOneTimeVariantsArray of integers(int64)

List of one-time product variant IDs to remove from the subscription. Only removes one-time products that haven't been fulfilled yet.

Example: [42549172055555,42549172088888]
oldLineIdstring

Specific subscription line ID to replace. Use this for targeted replacement of a single line item. When provided, oldVariants should be empty. Format: gid://shopify/SubscriptionLine/[ID]

Example: "gid://shopify/SubscriptionLine/987654321"
eventSourcestring
Enum"CUSTOMER_PORTAL""MERCHANT_PORTAL""SHOPIFY_EVENT""SYSTEM_EVENT""MERCHANT_PORTAL_BULK_AUTOMATION""MERCHANT_EXTERNAL_API""SHOPIFY_FLOW"
carryForwardDiscountstring

Determines how discounts are applied to new products when replacing variants. If not specified, uses the merchant's default setting.

Enum"NONE""EXISTING_PLAN""PRODUCT_PLAN""PRODUCT_THEN_EXISTING""PRODUCT_THEN_EXISTING""PRODUCT_PLAN""EXISTING_PLAN"
Example: "PRODUCT_THEN_EXISTING"
stopSwapEmailsboolean

If true, suppresses email notifications about the product swap. Default is false (emails will be sent).

Default false
Example: false
curl -i -X POST \
  https://www.myshop.com/apps/subscriptions/cp/api/subscription-contract-details/replace-variants-v3 \
  -H 'Content-Type: application/json' \
  -d '{
    "shop": "abcStore.myshopify.com",
    "contractId": 123456789,
    "oldVariants": [
      42549172011164,
      42549172022222
    ],
    "newVariants": {
      "42549172033333": 2,
      "42549172044444": 1
    },
    "newOneTimeVariants": {
      "42549172066666": 1,
      "42549172077777": 2
    },
    "oldOneTimeVariants": [
      42549172055555,
      42549172088888
    ],
    "oldLineId": "gid://shopify/SubscriptionLine/987654321",
    "eventSource": "CUSTOMER_PORTAL",
    "carryForwardDiscount": "PRODUCT_THEN_EXISTING",
    "stopSwapEmails": false
  }'

Responses

Products successfully replaced

Bodyapplication/json
get__typenamestring
idstring
createdAtobject
updatedAtobject
nextBillingDateobject
statusstring
Enum"ACTIVE""PAUSED""CANCELLED""EXPIRED""FAILED""$UNKNOWN"
deliveryPriceobject(DeliveryPrice)
lastPaymentStatusstring
Enum"SUCCEEDED""FAILED""$UNKNOWN"
billingPolicyobject(BillingPolicy)
deliveryPolicyobject(DeliveryPolicy)
linesobject(Lines)
customerPaymentMethodobject(CustomerPaymentMethod)
deliveryMethodobject(DeliveryMethod)
originOrderobject(OriginOrder)
customerobject(Customer)
discountsobject(Discounts)
notestring
customAttributesArray of objects(CustomAttribute1)
billingAttemptsobject(BillingAttempts)
Response
application/json
{
  "id": "gid://shopify/SubscriptionContract/123456789",
  "status": "ACTIVE",
  "nextBillingDate": "2024-02-15T00:00:00Z",
  "lines": {
    "edges": [ … ]
  }
}

Get variant contextual pricing

Request

Retrieves contextual pricing information for a product variant based on currency and country. This endpoint provides localized pricing data for international subscriptions and multi-currency support.

Pricing Information Returned:

  • Base price in specified currency
  • Compare-at price (if applicable)
  • Country-specific pricing adjustments
  • Tax information for the region
  • Currency conversion data

Parameters:

  • variantId - Shopify variant ID (required)
  • currencyCode - ISO 4217 currency code (e.g., USD, EUR, GBP) (required)
  • countryCode - ISO 3166-1 country code (e.g., US, GB, CA) (optional)

Use Cases:

  • Display localized pricing in customer portal
  • Calculate subscription totals for international customers
  • Support multi-currency subscriptions
  • Show accurate pricing based on customer location
  • Validate pricing before subscription creation

Important Notes:

  • Requires Shopify Markets or multi-currency setup
  • Prices are returned in the requested currency
  • Country-specific pricing takes precedence over currency-only pricing
  • Returns 404 if variant doesn't exist or isn't available in specified market

Authentication: Requires valid api_key parameter

Query
variantIdinteger(int64)required
countryCodestring
currencyCodestringrequired
curl -i -X GET \
  'https://www.myshop.com/apps/subscriptions/cp/api/data/variant-contextual-pricing?variantId=0&countryCode=string&currencyCode=string'

Responses

Contextual pricing retrieved successfully

Body*/*
get__typenamestring
idstring
titlestring
mediaobject(Media)
productobject(Product)
priceobject
contextualPricingobject(ContextualPricing)
skustring

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

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.