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.
When the customer is charged:
- The call doesn’t create an order or charge the customer, and it doesn’t change
nextBillingDate - The new line is billed with the contract’s next scheduled order and with every order after it; a one-time line is billed with the next order only
- To bill sooner, use Trigger immediate billing for an order (
PUT /api/external/v2/subscription-billing-attempts/attempt-billing/{id}). It bills every line on the contract, not only the new one
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 removed automatically after the next order bills successfully
- 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
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": "_appstle-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"
}Query Parameters
When true, product will only be included in the next order and automatically removed after that order bills successfully. 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
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": "_appstle-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"
}