Skip to content
External APIs
/
/
Add product to subscripti...

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

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

Add multiple products to subscription

Request

Adds multiple product line items to an existing subscription contract in a single request. This batch operation is more efficient than making multiple individual requests and ensures all products are added with consistent processing.

Key Features:

  • Batch addition of multiple products in one API call
  • All products are added as recurring items (not one-time)
  • Automatic quantity defaulting (0 or null becomes 1)
  • Sequential processing with full validation for each item
  • Returns final subscription state after all additions
  • Same pricing and discount logic as single-item endpoint

Processing Behavior:

  • Products are added sequentially, not in parallel
  • If any product fails, previous additions remain
  • Each product goes through full validation
  • Existing product handling follows store settings
  • Activity logs created for each product added

Duplicate Product Handling: If a product already exists in the subscription:

  • With 'updateExistingQuantityOnAddProduct' enabled: Updates quantity
  • Without setting: Adds as new line item
  • Setting applies to all products in the batch

Pricing and Discounts: Each product receives:

  • Appropriate selling plan assignment
  • Discount carry-forward based on store settings
  • Currency and country-specific pricing
  • Fulfillment frequency multiplier application

Build-a-Box Validation:

  • Applied if any product has _bb_id attribute
  • Validates total quantity after all additions
  • May fail entire batch if limits exceeded

Post-Processing: After all products are added:

  • Build-a-Box discounts recalculated once
  • Product discounts synchronized
  • Single email notification sent
  • Shipping price updated once

Important Notes:

  • Maximum recommended batch size: 10-20 products
  • Larger batches may timeout
  • All products become recurring items
  • Use single-item endpoint for one-time products

Authentication: Requires valid X-API-Key header

Query
contractIdinteger(int64)>= 1required

Subscription contract ID to add products to. Provide the numeric ID without the gid:// prefix

Example: contractId=123456789
api_keystringDeprecated

API Key (Deprecated - Use X-API-Key header instead)

Headers
X-API-Keystringrequired

API Key for authentication

Example: sk_live_1234567890abcdef
Bodyapplication/jsonrequired

Map of variant IDs to quantities. Keys are variant IDs (numeric only, no gid:// prefix), values are quantities to add. Null or 0 quantities default to 1.

string
curl -i -X PUT \
  'https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-add-line-items?contractId=123456789&api_key=string' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: sk_live_1234567890abcdef' \
  -d '{
    "42549172011164": 1,
    "42549172043932": 2,
    "42549172076700": 1
  }'

Responses

Products successfully added to subscription

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-04-01T12:00:00Z",
  "customer": {
    "id": "gid://shopify/Customer/987654321",
    "email": "customer@example.com"
  },
  "billingPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "deliveryPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "lines": {
    "edges": [ … ]
  },
  "discounts": {
    "edges": [ … ]
  }
}

Add product to subscription

Request

Adds a new product line item to an existing subscription contract. Can add either recurring products that will appear in each order or one-time products that appear only in the next order.

Key Features:

  • Supports both recurring and one-time product additions
  • Automatically applies appropriate pricing policies based on discount carry-forward settings
  • Handles duplicate products by updating quantity (if enabled) or adding as new line
  • Calculates prices based on billing/delivery frequency multipliers
  • Sends email notifications to customers (unless suppressed)
  • Creates activity logs for audit trail

Pricing Policy Application: The system applies discounts based on the store's discount carry-forward setting:

  • PRODUCT_PLAN: Uses the discount from the product's selling plan
  • EXISTING_PLAN: Applies the discount structure from existing subscription items
  • PRODUCT_THEN_EXISTING: First attempts product plan, falls back to existing if not found

One-Time Products: Products added with isOneTimeProduct=true will:

  • Only appear in the next scheduled order
  • Be automatically removed after fulfillment
  • Still attempt to match with appropriate selling plans
  • Can have subscription discounts applied if store setting allows

Duplicate Product Handling: When adding a product that already exists in the subscription:

  • If store has 'updateExistingQuantityOnAddProduct' enabled and product is not one-time: Updates existing quantity
  • Otherwise: Adds as a new line item

Price Calculation:

  • Base price is fetched considering contract currency and delivery country
  • Price is multiplied by fulfillment frequency ratio (billing interval / delivery interval)
  • Example: Monthly billing with weekly delivery = price × 4

Authentication: Requires valid X-API-Key header

Query
contractIdstring^[0-9]+$required

Subscription contract ID to add product to. Provide the numeric ID without the gid:// prefix

Example: contractId=123456789
quantityinteger[ 1 .. 999 ]required

Quantity of product to add. Must be a positive integer

Example: quantity=2
variantIdstring^([0-9]+|gid://shopify/ProductVariant/[0-9]+)...required

Shopify variant ID of the product to add. Can be provided as numeric ID or with gid:// prefix

Example: variantId=42549172011164
isOneTimeProductboolean

When true, product will only be included in the next order and automatically removed after fulfillment. When false, product will be included in all future orders until manually removed or subscription ends. One-time products are useful for samples, gifts, or limited-time additions

Default false
api_keystringDeprecated

API Key (Deprecated - Use X-API-Key header instead)

Headers
X-API-Keystringrequired

API Key for authentication

Example: sk_live_1234567890abcdef
curl -i -X PUT \
  'https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-add-line-item?contractId=123456789&quantity=2&variantId=42549172011164&isOneTimeProduct=false&api_key=string' \
  -H 'X-API-Key: sk_live_1234567890abcdef'

Responses

Product successfully added to subscription

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

Add product with custom price to subscription

Request

Adds a new product line item with a custom price override to an existing subscription contract. This endpoint bypasses standard pricing and selling plans to set an exact price.

Key Features:

  • Direct price control - set any price regardless of product pricing
  • Optional automatic discount application based on shop settings
  • No selling plan assignment - pure custom pricing
  • Supports both recurring and one-time products
  • Email notifications sent to customers
  • Activity logging for audit trails

Custom Pricing Behavior:

  • Price is set exactly as provided (no calculations)
  • Overrides any product-level pricing
  • Not affected by currency or country
  • No automatic discounts from selling plans
  • Price remains fixed unless manually updated

Shop-Level Discount Application: Despite the method name, this endpoint MAY apply discounts:

  • Checks shop setting: 'applySubscriptionDiscount'
  • If enabled, applies shop's default subscription discount
  • Discount type: PERCENTAGE or FIXED (per shop config)
  • Creates manual discount: 'PRODUCT_DISCOUNT_[lineId]'
  • Discount is additional to the custom price

Common Use Cases:

  • Negotiated Pricing: Custom rates for specific customers
  • Price Matching: Match competitor pricing
  • Promotional Pricing: Special one-off prices
  • Bundle Pricing: Custom prices for package deals
  • Legacy Pricing: Honor old pricing agreements
  • Test Orders: Zero or nominal pricing for testing

Differences from Standard Add:

  • No selling plan association
  • No pricing policy rules
  • No automatic tier discounts
  • Price doesn't adjust with frequency changes
  • Manual price management required

One-Time Products: When isOneTimeProduct=true:

  • Product appears only in next order
  • Automatically removed after fulfillment
  • Custom price applies to that single order
  • Shop discount still applies if configured

Price Validation:

  • Must be a positive number
  • No maximum limit enforced
  • Can be less than product cost (loss leader)
  • Currency matches shop's base currency
  • Decimal precision per currency rules

Important Considerations:

  • No automatic price updates with product changes
  • Frequency changes don't affect pricing
  • May bypass minimum order values
  • Consider margin implications
  • Document reason for custom pricing

Post-Addition Effects:

  • Customer receives product addition email
  • Activity log records custom price
  • Shipping may need recalculation
  • Order total updates immediately
  • No impact on other line items

Authentication: Requires valid X-API-Key header

Query
contractIdinteger(int64)required

Subscription contract ID to add product to

Example: contractId=123456789
quantityinteger(int32)required

Quantity of product to add

Example: quantity=1
variantIdstringrequired

Shopify variant ID of the product to add

Example: variantId=42549172011164
pricenumber(double)[ 0.01 .. 999999.99 ]required

Custom price for the product (in store currency). This exact price will be charged regardless of the product's normal price, selling plans, or frequency. If the shop has 'applySubscriptionDiscount' enabled, an additional discount may be applied on top of this price.

Example: price=19.99
isOneTimeProductboolean

When true, product will only be included in the next order; when false, in all future orders

Default false
api_keystringDeprecated

API Key (Deprecated - Use X-API-Key header instead)

Headers
X-API-Keystringrequired

API Key for authentication

curl -i -X PUT \
  'https://subscription-admin.appstle.com/api/external/v2/subscription-contract-add-line-item?contractId=123456789&quantity=1&variantId=42549172011164&price=19.99&isOneTimeProduct=false&api_key=string' \
  -H 'X-API-Key: string'

Responses

Product successfully added to subscription with custom price

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-04-01T00:00:00Z",
  "customer": {
    "id": "gid://shopify/Customer/987654321",
    "email": "customer@example.com"
  },
  "lines": {
    "edges": [ … ]
  }
}

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