Subscription Products

Add multiple products to subscription

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

PUT

api

external

subscription-contracts-add-line-items

curl --request PUT \
  --url https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-add-line-items \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <x-api-key>' \
  --data '
{
  "42549172011164": 1,
  "42549172043932": 2,
  "42549172076700": 1
}
'

{
  "billingPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "customer": {
    "email": "customer@example.com",
    "id": "gid://shopify/Customer/987654321"
  },
  "deliveryPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "discounts": {
    "edges": [
      {
        "node": {
          "id": "gid://shopify/SubscriptionManualDiscount/444444",
          "targetType": "ALL_LINES",
          "title": "BUILD_A_BOX_DISCOUNT_ABC123",
          "value": {
            "percentage": 20
          }
        }
      }
    ]
  },
  "id": "gid://shopify/SubscriptionContract/123456789",
  "lines": {
    "edges": [
      {
        "node": {
          "currentPrice": {
            "amount": "59.98",
            "currencyCode": "USD"
          },
          "id": "gid://shopify/SubscriptionLine/111111",
          "quantity": 2,
          "sellingPlanId": "gid://shopify/SellingPlan/123456",
          "sellingPlanName": "Deliver every month",
          "title": "Premium Coffee - Dark Roast",
          "variantId": "gid://shopify/ProductVariant/42549172011164"
        }
      },
      {
        "node": {
          "currentPrice": {
            "amount": "24.99",
            "currencyCode": "USD"
          },
          "id": "gid://shopify/SubscriptionLine/222222",
          "quantity": 1,
          "sellingPlanId": "gid://shopify/SellingPlan/123456",
          "sellingPlanName": "Deliver every month",
          "title": "Organic Tea - Green",
          "variantId": "gid://shopify/ProductVariant/42549172043932"
        }
      },
      {
        "node": {
          "currentPrice": {
            "amount": "19.98",
            "currencyCode": "USD"
          },
          "id": "gid://shopify/SubscriptionLine/333333",
          "quantity": 2,
          "sellingPlanId": "gid://shopify/SellingPlan/123456",
          "sellingPlanName": "Deliver every month",
          "title": "Coffee Filters - 100 pack",
          "variantId": "gid://shopify/ProductVariant/42549172076700"
        }
      }
    ]
  },
  "nextBillingDate": "2024-04-01T12:00:00Z",
  "status": "ACTIVE"
}

Headers

X-API-Key

string

required

API Key for authentication

Query Parameters

contractId

integer<int64>

required

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

Required range: x >= 1

api_key

string

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

Body

application/json

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.

The body is of type string.

Response

Products successfully added to subscription

billingAttempts

object

Show child attributes

billingPolicy

object

Show child attributes

createdAt

object

customAttributes

object[]

Show child attributes

customer

object

Show child attributes

customerPaymentMethod

object

Show child attributes

deliveryMethod

object

Show child attributes

deliveryPolicy

object

Show child attributes

deliveryPrice

object

Show child attributes

discounts

object

Show child attributes

get__typename

string

lastPaymentStatus

enum<string>

Available options:

SUCCEEDED,

FAILED,

$UNKNOWN

lines

object

Show child attributes

nextBillingDate

object

note

string

originOrder

object

Show child attributes

status

enum<string>

Available options:

ACTIVE,

PAUSED,

CANCELLED,

EXPIRED,

FAILED,

$UNKNOWN

updatedAt

object

curl --request PUT \
  --url https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-add-line-items \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <x-api-key>' \
  --data '
{
  "42549172011164": 1,
  "42549172043932": 2,
  "42549172076700": 1
}
'

{
  "billingPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "customer": {
    "email": "customer@example.com",
    "id": "gid://shopify/Customer/987654321"
  },
  "deliveryPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "discounts": {
    "edges": [
      {
        "node": {
          "id": "gid://shopify/SubscriptionManualDiscount/444444",
          "targetType": "ALL_LINES",
          "title": "BUILD_A_BOX_DISCOUNT_ABC123",
          "value": {
            "percentage": 20
          }
        }
      }
    ]
  },
  "id": "gid://shopify/SubscriptionContract/123456789",
  "lines": {
    "edges": [
      {
        "node": {
          "currentPrice": {
            "amount": "59.98",
            "currencyCode": "USD"
          },
          "id": "gid://shopify/SubscriptionLine/111111",
          "quantity": 2,
          "sellingPlanId": "gid://shopify/SellingPlan/123456",
          "sellingPlanName": "Deliver every month",
          "title": "Premium Coffee - Dark Roast",
          "variantId": "gid://shopify/ProductVariant/42549172011164"
        }
      },
      {
        "node": {
          "currentPrice": {
            "amount": "24.99",
            "currencyCode": "USD"
          },
          "id": "gid://shopify/SubscriptionLine/222222",
          "quantity": 1,
          "sellingPlanId": "gid://shopify/SellingPlan/123456",
          "sellingPlanName": "Deliver every month",
          "title": "Organic Tea - Green",
          "variantId": "gid://shopify/ProductVariant/42549172043932"
        }
      },
      {
        "node": {
          "currentPrice": {
            "amount": "19.98",
            "currencyCode": "USD"
          },
          "id": "gid://shopify/SubscriptionLine/333333",
          "quantity": 2,
          "sellingPlanId": "gid://shopify/SellingPlan/123456",
          "sellingPlanName": "Deliver every month",
          "title": "Coffee Filters - 100 pack",
          "variantId": "gid://shopify/ProductVariant/42549172076700"
        }
      }
    ]
  },
  "nextBillingDate": "2024-04-01T12:00:00Z",
  "status": "ACTIVE"
}

Get Started

Guides

Partner Integration

Webhooks

Admin API

Storefront API

Resources

Add multiple products to subscription

Headers

Query Parameters

Body

Response