Subscription Products

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.

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

subscription-contracts-add-line-item

Add product to subscription

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

import requests

url = "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-add-line-item"

headers = {"X-API-Key": "<x-api-key>"}

response = requests.put(url, headers=headers)

print(response.text)

const options = {method: 'PUT', headers: {'X-API-Key': '<x-api-key>'}};

fetch('https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-add-line-item', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const url = 'https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-add-line-item';
const options = {method: 'PUT', headers: {'X-API-Key': '<x-api-key>'}};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-add-line-item",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-add-line-item"

	req, _ := http.NewRequest("PUT", url, nil)

	req.Header.Add("X-API-Key", "<x-api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-add-line-item")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["X-API-Key"] = '<x-api-key>'

response = http.request(request)
puts response.read_body

{
  "billingPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "customer": {
    "email": "customer@example.com",
    "firstName": "John",
    "id": "gid://shopify/Customer/987654321",
    "lastName": "Doe"
  },
  "deliveryPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "id": "gid://shopify/SubscriptionContract/123456789",
  "lines": {
    "edges": [
      {
        "node": {
          "currentPrice": {
            "amount": "29.99",
            "currencyCode": "USD"
          },
          "id": "gid://shopify/SubscriptionLine/111111",
          "quantity": 2,
          "sellingPlanId": "gid://shopify/SellingPlan/123456",
          "sellingPlanName": "Deliver every month",
          "variantId": "gid://shopify/ProductVariant/42549172011164"
        }
      },
      {
        "node": {
          "currentPrice": {
            "amount": "19.99",
            "currencyCode": "USD"
          },
          "customAttributes": [
            {
              "key": "_one_time_product",
              "value": "true"
            }
          ],
          "id": "gid://shopify/SubscriptionLine/222222",
          "quantity": 1,
          "variantId": "gid://shopify/ProductVariant/98765432101"
        }
      }
    ]
  },
  "nextBillingDate": "2024-03-01T00:00:00Z",
  "status": "ACTIVE"
}

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

Product 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

Add product with custom price to subscription

Add multiple products to subscription

Add product to subscription

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

import requests

url = "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-add-line-item"

headers = {"X-API-Key": "<x-api-key>"}

response = requests.put(url, headers=headers)

print(response.text)

const options = {method: 'PUT', headers: {'X-API-Key': '<x-api-key>'}};

fetch('https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-add-line-item', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const url = 'https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-add-line-item';
const options = {method: 'PUT', headers: {'X-API-Key': '<x-api-key>'}};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-add-line-item",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-add-line-item"

	req, _ := http.NewRequest("PUT", url, nil)

	req.Header.Add("X-API-Key", "<x-api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-add-line-item")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["X-API-Key"] = '<x-api-key>'

response = http.request(request)
puts response.read_body

{
  "billingPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "customer": {
    "email": "customer@example.com",
    "firstName": "John",
    "id": "gid://shopify/Customer/987654321",
    "lastName": "Doe"
  },
  "deliveryPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "id": "gid://shopify/SubscriptionContract/123456789",
  "lines": {
    "edges": [
      {
        "node": {
          "currentPrice": {
            "amount": "29.99",
            "currencyCode": "USD"
          },
          "id": "gid://shopify/SubscriptionLine/111111",
          "quantity": 2,
          "sellingPlanId": "gid://shopify/SellingPlan/123456",
          "sellingPlanName": "Deliver every month",
          "variantId": "gid://shopify/ProductVariant/42549172011164"
        }
      },
      {
        "node": {
          "currentPrice": {
            "amount": "19.99",
            "currencyCode": "USD"
          },
          "customAttributes": [
            {
              "key": "_one_time_product",
              "value": "true"
            }
          ],
          "id": "gid://shopify/SubscriptionLine/222222",
          "quantity": 1,
          "variantId": "gid://shopify/ProductVariant/98765432101"
        }
      }
    ]
  },
  "nextBillingDate": "2024-03-01T00:00:00Z",
  "status": "ACTIVE"
}