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.

Full behavior, validation rules, and side effects

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/v2/subscription-contracts-add-line-items

cURL

Add Three Products

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

200

Success Response

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

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

200

application/json

Products successfully added to subscription

get__typename · string

id · string

createdAt · object

updatedAt · object

nextBillingDate · object

status · enum<string>

Available options: ACTIVE, PAUSED, CANCELLED, EXPIRED, FAILED, $UNKNOWN

deliveryPrice · object

Show child attributes

lastPaymentStatus · enum<string>

Available options: SUCCEEDED, FAILED, $UNKNOWN

billingPolicy · object

Show child attributes

deliveryPolicy · object

Show child attributes

lines · object

Show child attributes

customerPaymentMethod · object

Show child attributes

deliveryMethod · object

Show child attributes

originOrder · object

Show child attributes

customer · object

Show child attributes

discounts · object

Show child attributes

note · string

customAttributes · object[]

Show child attributes

billingAttempts · object

Show child attributes