Skip to content
External APIs
/
/
Replace product variants...

External APIs (0.0.1)

Comprehensive API documentation for managing subscriptions, payments, and related operations. These APIs allow you to programmatically manage subscription lifecycles, handle payments, configure products, and integrate subscription functionality into your applications.

Download OpenAPI description
external-api-swagger.json
external-api-swagger.yaml
Languages
Servers
https://subscription-admin.appstle.com

Subscription Management

Core APIs for managing the complete subscription lifecycle including creation, updates, pausing, resuming, and cancellation of subscriptions.

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

Subscription contract ID

isSplitContractboolean

Split or duplicate mode

Default false
attemptBillingboolean

Attempt billing immediately

Default false
api_keystringDeprecated

API Key (Deprecated)

Headers
X-API-Keystringrequired

API Key

Bodyapplication/jsonrequiredArray [
string
]
curl -i -X POST \
  'https://subscription-admin.appstle.com/api/external/v2/subscription-contract-details/split-existing-contract?contractId=0&isSplitContract=false&attemptBilling=false&api_key=string' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: string' \
  -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

Query
api_keystringDeprecated

API Key (Deprecated)

Headers
X-API-Keystringrequired

API Key

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://subscription-admin.appstle.com/api/external/v2/subscription-contract-details/replace-variants-v3?api_key=string' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: string' \
  -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": [ … ]
  }
}

Create a new subscription contract

Request

Creates a new subscription contract for a customer with specified products, billing frequency, and delivery details. This endpoint allows you to programmatically create subscriptions with custom pricing, delivery schedules, and multiple line items. The subscription will be created in Shopify and synchronized with the Appstle system.

Important Notes:

  • Customer must have at least one valid payment method
  • If paymentMethodId is not provided, the default payment method will be used
  • If delivery interval is not specified, it defaults to the billing interval
  • Custom pricing policies can be applied per line item
  • All monetary values are in the store's base currency unless currencyCode is specified
  • CustomAttributes and line item customAttributes use Shopify's AttributeInput format: {"key": "string", "value": "string"}

Pricing Policy Types:

  • SELLING_PLAN_PRICING_POLICY: Uses the default pricing from the selling plan
  • CUSTOM_PRICING_POLICY: Allows custom discount cycles defined in pricingPolicy array
  • NO_PRICING_POLICY: Uses the base price without any discounts

Authentication: Requires valid X-API-Key header

Query
api_keystringDeprecated

API Key (Deprecated)

Headers
X-API-Keystringrequired

API Key

Bodyapplication/jsonrequired
customerIdstringrequired

Shopify customer ID (numeric ID without gid prefix)

Example: "987654321"
paymentMethodIdstring

Customer payment method ID. If not provided, the default payment method will be used. Can be null if createWithoutPaymentMethod is true.

Example: "gid://shopify/CustomerPaymentMethod/abc123"
createWithoutPaymentMethodboolean

If true, creates subscription without payment method. Status will be set to PAUSED. Charges cannot be processed until a valid payment method is added.

Default false
Example: false
statusstringrequired

Initial status of the subscription contract

Enum"ACTIVE""PAUSED""CANCELLED""EXPIRED""FAILED""$UNKNOWN""ACTIVE""PAUSED""CANCELLED""EXPIRED"
Example: "ACTIVE"
nextBillingDatestring(date-time)required

Date when the next billing/order will occur

Example: "2024-02-01T00:00:00Z"
billingIntervalTypestringrequired

Billing frequency interval type

Enum"DAY""WEEK""MONTH""YEAR""$UNKNOWN""DAY""WEEK""MONTH""YEAR"
Example: "MONTH"
billingIntervalCountinteger(int32)>= 1required

Number of intervals between billings

Example: 1
maxCyclesinteger(int32)>= 1

Maximum number of billing cycles. Null for unlimited

Example: 12
minCyclesinteger(int32)>= 1

Minimum number of billing cycles required before cancellation is allowed

Example: 3
deliveryIntervalTypestring

Delivery frequency interval type. If not specified, uses billing interval

Enum"DAY""WEEK""MONTH""YEAR""$UNKNOWN""DAY""WEEK""MONTH""YEAR"
Example: "MONTH"
deliveryIntervalCountinteger(int32)>= 1

Number of intervals between deliveries. If not specified, uses billing interval count

Example: 1
deliveryFirstNamestring

Delivery address first name

Example: "John"
deliveryLastNamestring

Delivery address last name

Example: "Doe"
deliveryAddress1stringrequired

Delivery address line 1

Example: "123 Main St"
deliveryAddress2string

Delivery address line 2

Example: "Apt 4B"
deliveryProvinceCodestring

Delivery address province/state code (ISO 3166-2)

Example: "NY"
deliveryCitystringrequired

Delivery address city

Example: "New York"
deliveryZipstring

Delivery address postal/zip code

Example: "10001"
deliveryCountryCodestringrequired

Delivery address country code (ISO 3166-1 alpha-2)

Example: "US"
deliveryPhonestring

Delivery phone number

Example: "+1234567890"
deliveryPriceAmountnumber(double)

Fixed delivery price amount in store currency

Example: 5.99
currencyCodestring

Currency code for the subscription (ISO 4217). If not provided, uses store default currency

Example: "USD"
linesArray of objects(SubscriptionContractLineDTO)required

Product line items to include in the subscription

lines[].​quantityinteger(int32)>= 1required

Quantity of the product variant

Example: 2
lines[].​variantIdstringrequired

Shopify product variant ID (numeric ID without gid prefix)

Example: "42549172011164"
lines[].​productIdstring

Shopify product ID (numeric ID without gid prefix)

Example: "7234567890123"
lines[].​sellingPlanIdstring

Selling plan ID to apply to this line item. Required for subscription pricing

Example: "gid://shopify/SellingPlan/123456"
lines[].​currentPricenumber(double)

Current price per unit after discounts. If not provided, calculated from selling plan

Example: 25.99
lines[].​unitPricenumber(double)

Base price per unit before any discounts

Example: 29.99
lines[].​customAttributesArray of objects(AttributeInput)

Custom attributes for this line item

Example: [{"key":"engraving","value":"Happy Birthday"}]
lines[].​linePricingPolicystring

Pricing policy type for subscription line items

Enum"SELLING_PLAN_PRICING_POLICY""CUSTOM_PRICING_POLICY""NO_PRICING_POLICY"
Example: "SELLING_PLAN_PRICING_POLICY"
lines[].​pricingPolicyArray of objects(AppstleCycle)

Custom pricing policy cycles when linePricingPolicy is CUSTOM_PRICING_POLICY

allowDeliveryAddressOverrideboolean

Allow customer to change delivery address in customer portal

Default false
Example: false
allowDeliveryPriceOverrideboolean

Allow delivery price to be overridden

Default false
Example: false
customAttributesobject(AttributeInput)

Custom attributes to attach to the subscription contract

Example: [{"key":"subscription_type","value":"premium"},{"key":"gift_message","value":"Happy Birthday!"}]
curl -i -X POST \
  'https://subscription-admin.appstle.com/api/external/v2/subscription-contract-details/create-subscription-contract?api_key=string' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: string' \
  -d '{
    "customerId": "987654321",
    "paymentMethodId": "gid://shopify/CustomerPaymentMethod/abc123",
    "createWithoutPaymentMethod": false,
    "status": "ACTIVE",
    "nextBillingDate": "2024-02-01T00:00:00Z",
    "billingIntervalType": "MONTH",
    "billingIntervalCount": 1,
    "maxCycles": 12,
    "minCycles": 3,
    "deliveryIntervalType": "MONTH",
    "deliveryIntervalCount": 1,
    "deliveryFirstName": "John",
    "deliveryLastName": "Doe",
    "deliveryAddress1": "123 Main St",
    "deliveryAddress2": "Apt 4B",
    "deliveryProvinceCode": "NY",
    "deliveryCity": "New York",
    "deliveryZip": "10001",
    "deliveryCountryCode": "US",
    "deliveryPhone": "+1234567890",
    "deliveryPriceAmount": 5.99,
    "currencyCode": "USD",
    "lines": [
      {
        "quantity": 2,
        "variantId": "42549172011164",
        "productId": "7234567890123",
        "sellingPlanId": "gid://shopify/SellingPlan/123456",
        "currentPrice": 25.99,
        "unitPrice": 29.99,
        "customAttributes": [
          {
            "key": "engraving",
            "value": "Happy Birthday"
          }
        ],
        "linePricingPolicy": "SELLING_PLAN_PRICING_POLICY",
        "pricingPolicy": [
          {
            "afterCycle": 3,
            "discountType": "PERCENTAGE",
            "value": 10,
            "freeVariantId": 42549172011164,
            "freeProductHandle": "free-gift-product",
            "repeatingCycle": true,
            "repeatingNumberOfCycle": 6,
            "preventDuplicationFreeProduct": true
          }
        ]
      }
    ],
    "allowDeliveryAddressOverride": false,
    "allowDeliveryPriceOverride": false,
    "customAttributes": [
      {
        "key": "subscription_type",
        "value": "premium"
      },
      {
        "key": "gift_message",
        "value": "Happy Birthday!"
      }
    ]
  }'

Responses

Subscription contract successfully created

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-01T00:00:00Z",
  "billingPolicy": {
    "interval": "MONTH",
    "intervalCount": 1,
    "minCycles": 3,
    "maxCycles": 12
  },
  "deliveryPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "customer": {
    "id": "gid://shopify/Customer/987654321",
    "email": "customer@example.com",
    "firstName": "John",
    "lastName": "Doe"
  },
  "deliveryPrice": {
    "amount": "5.99",
    "currencyCode": "USD"
  },
  "lines": {
    "edges": [ … ]
  }
}

Subscription Payments

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

Operations

Subscription Contracts

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

Operations

Subscription Products

APIs for managing products within subscriptions including adding, removing, updating quantities, and swapping products.

Operations

Billing & Payments

APIs for handling billing operations, payment processing, and financial transactions related to subscriptions.

Operations

Subscription Discounts

APIs for managing discounts and promotional codes applied to subscriptions.

Operations

Subscription One-Time Products

APIs for managing one-time add-on products that can be purchased alongside recurring subscription items.

Operations

Subscription Plans

APIs for managing subscription plans, pricing tiers, and plan configurations.

Operations

Build-a-Box & Bundles

APIs for managing customizable product boxes and bundles where customers can select multiple items.

Operations

Product Catalog

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

Operations

Operations & Settings

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

Operations

Customer Portal

APIs powering the customer-facing portal where subscribers can manage their own subscriptions.

Operations

Customers

APIs for managing customer information, profiles, and account details.

Operations