Add product line item to subscription contract

Adds a new product (line item) to an existing subscription contract. This allows customers or merchants to add products to their recurring subscription orders.

Full behavior, validation rules, and side effects

Key Features:

• Add Products: Include new products in future subscription deliveries
• Quantity Control: Specify how many units of the product to add
• Price Override: Set custom pricing for the added product
• Immediate Effect: Changes apply to next billing cycle
• Activity Logging: All additions are tracked in activity logs

Required Parameters:

• contractId: Subscription contract ID to modify
• variantId: Shopify product variant ID (with gid:// prefix or numeric)
• quantity: Number of units to add (must be positive integer)
• price: Price per unit in shop’s base currency

Product Variant ID Format: Accepts two formats:

• Shopify GID: gid://shopify/ProductVariant/12345678901
• Numeric ID: 12345678901

Price Behavior:

• Price is per unit, not total
• Must be in shop’s base currency (USD, EUR, etc.)
• Can override product’s default price
• Does not include taxes or shipping
• Total line item cost = price × quantity

Line Item Addition Rules:

• Product variant must exist in Shopify catalog
• Product must be active and available
• Variant must have sufficient inventory (if tracked)
• Contract must be ACTIVE or PAUSED (not CANCELLED)
• Cannot add duplicate variants (use update quantity instead)

Common Use Cases:

• Customer adds complementary product to existing subscription
• Upsell additional products through customer portal
• Merchant adds bonus items to customer subscriptions
• Build custom “add-on” product selection interfaces
• Cross-sell related products to existing subscribers
• Create bundle upgrades (add multiple products at once)

Post-Addition Effects:

• Next billing amount increases by (price × quantity)
• Product appears in all future subscription deliveries
• Customer receives confirmation of subscription update
• Activity log records the addition with source (portal/merchant)
• Contract’s next billing date remains unchanged

Integration Example:

PUT /api/external/v2/subscription-contract-add-line-item?
  contractId=123456&
  variantId=gid://shopify/ProductVariant/987654321&
  quantity=2&
  price=19.99

This adds 2 units of variant 987654321 at $19.99 each ($39.98 total) to contract 123456.

Important Notes:

• Changes apply to NEXT billing cycle, not current/past orders
• If product is out of stock, order may be delayed or skipped
• Price changes don’t affect historical orders
• Consider inventory availability before adding products

Authentication: Requires API key authentication via X-API-Key header or api_key parameter

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

Add product line item to subscription contract

cURL

curl --request PUT \
  --url https://membership-admin.appstle.com/api/external/v2/subscription-contract-add-line-item

200

{
  "get__typename": "<string>",
  "id": "<string>",
  "createdAt": {},
  "updatedAt": {},
  "nextBillingDate": {},
  "deliveryPrice": {
    "get__typename": "<string>",
    "amount": {}
  },
  "billingPolicy": {
    "get__typename": "<string>",
    "intervalCount": 123,
    "anchors": [
      {
        "get__typename": "<string>",
        "cutoffDay": 123,
        "day": 123,
        "month": 123
      }
    ],
    "maxCycles": 123,
    "minCycles": 123
  },
  "deliveryPolicy": {
    "get__typename": "<string>",
    "intervalCount": 123,
    "anchors": [
      {
        "get__typename": "<string>",
        "cutoffDay": 123,
        "day": 123,
        "month": 123
      }
    ]
  },
  "lines": {
    "get__typename": "<string>",
    "nodes": [
      {
        "get__typename": "<string>"
      }
    ],
    "pageInfo": {
      "get__typename": "<string>",
      "hasPreviousPage": true,
      "hasNextPage": true,
      "startCursor": "<string>",
      "endCursor": "<string>"
    }
  },
  "customerPaymentMethod": {
    "get__typename": "<string>",
    "id": "<string>",
    "instrument": {
      "get__typename": "<string>"
    },
    "revokedAt": {}
  },
  "deliveryMethod": {
    "get__typename": "<string>",
    "id": "<string>",
    "serviceCode": "<string>",
    "minDeliveryDateTime": {},
    "maxDeliveryDateTime": {},
    "additionalInformation": {
      "get__typename": "<string>",
      "instructions": "<string>"
    },
    "brandedPromise": {
      "get__typename": "<string>",
      "handle": "<string>",
      "name": "<string>"
    }
  },
  "originOrder": {
    "get__typename": "<string>",
    "id": "<string>",
    "name": "<string>",
    "fulfillmentOrders": {
      "get__typename": "<string>",
      "nodes": [
        {
          "get__typename": "<string>"
        }
      ],
      "pageInfo": {
        "get__typename": "<string>",
        "hasPreviousPage": true,
        "hasNextPage": true,
        "startCursor": "<string>",
        "endCursor": "<string>"
      }
    }
  },
  "customer": {
    "get__typename": "<string>",
    "id": "<string>",
    "email": "<string>",
    "displayName": "<string>",
    "firstName": "<string>",
    "lastName": "<string>",
    "phone": "<string>"
  },
  "discounts": {
    "get__typename": "<string>",
    "nodes": [
      {
        "get__typename": "<string>",
        "createdAt": {},
        "deliveredAt": {},
        "estimatedDeliveryAt": {},
        "id": "<string>",
        "inTransitAt": {},
        "name": "<string>",
        "requiresShipping": true,
        "service": {
          "get__typename": "<string>",
          "handle": "<string>",
          "serviceName": "<string>"
        },
        "trackingInfo": [
          {
            "get__typename": "<string>",
            "url": {},
            "number": "<string>",
            "company": "<string>"
          }
        ]
      }
    ],
    "pageInfo": {
      "get__typename": "<string>",
      "hasPreviousPage": true,
      "hasNextPage": true,
      "startCursor": "<string>",
      "endCursor": "<string>"
    }
  },
  "note": "<string>",
  "customAttributes": [
    {
      "get__typename": "<string>",
      "key": "<string>",
      "value": "<string>"
    }
  ],
  "billingAttempts": {
    "get__typename": "<string>",
    "nodes": [
      {
        "get__typename": "<string>",
        "completedAt": {},
        "createdAt": {},
        "id": "<string>",
        "idempotencyKey": "<string>",
        "ready": true
      }
    ]
  }
}

Headers

X-API-Key · string

Query Parameters

contractId · integer<int64> · required

Subscription contract ID

api_key · string

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

quantity · integer<int32> · required

Quantity of product to add

variantId · string · required

Shopify product variant ID (with or without gid:// prefix)

price · number<double> · required

Price per unit in shop's base currency

Response

200

application/json

Line item successfully added to subscription contract

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