Add product to subscription

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.

Full behavior, validation rules, and side effects

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

PUT /api/external/v2/subscription-contracts-add-line-item

Add product to subscription

cURL

curl --request PUT \
  --url https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-add-line-item \
  --header 'X-API-Key: <x-api-key>'

200

Success Response

{
  "id": "gid://shopify/SubscriptionContract/123456789",
  "status": "ACTIVE",
  "nextBillingDate": "2024-03-01T00:00:00Z",
  "customer": {
    "id": "gid://shopify/Customer/987654321",
    "email": "[e-mail]",
    "firstName": "John",
    "lastName": "Doe"
  },
  "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",
          "currentPrice": {
            "amount": "29.99",
            "currencyCode": "USD"
          },
          "sellingPlanId": "gid://shopify/SellingPlan/123456",
          "sellingPlanName": "Deliver every month"
        }
      },
      {
        "node": {
          "id": "gid://shopify/SubscriptionLine/222222",
          "quantity": 1,
          "variantId": "gid://shopify/ProductVariant/98765432101",
          "currentPrice": {
            "amount": "19.99",
            "currencyCode": "USD"
          },
          "customAttributes": [
            {
              "key": "_one_time_product",
              "value": "true"
            }
          ]
        }
      }
    ]
  }
}

Headers

X-API-Key · string · required

API Key for authentication

Query Parameters

contractId · string · required

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

Pattern: ^[0-9]+$

api_key · string

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

quantity · integer · required

Quantity of product to add. Must be a positive integer

Required range: 1 <= x <= 999

variantId · string · required

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

Pattern: ^([0-9]+|gid://shopify/ProductVariant/[0-9]+)$

isOneTimeProduct · boolean · default: false

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

Response

200

application/json

Product 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