Subscription Products

Add product with custom price to subscription

Adds a new product line item with a custom price override to an existing subscription contract. This endpoint bypasses standard pricing and selling plans to set an exact price.

Key Features:

Direct price control - set any price regardless of product pricing
Optional automatic discount application based on shop settings
No selling plan assignment - pure custom pricing
Supports both recurring and one-time products
Email notifications sent to customers
Activity logging for audit trails

Custom Pricing Behavior:

Price is set exactly as provided (no calculations)
Overrides any product-level pricing
Not affected by currency or country
No automatic discounts from selling plans
Price remains fixed unless manually updated

Shop-Level Discount Application: Despite the method name, this endpoint MAY apply discounts:

Checks shop setting: ‘applySubscriptionDiscount’
If enabled, applies shop’s default subscription discount
Discount type: PERCENTAGE or FIXED (per shop config)
Creates manual discount: ‘PRODUCT_DISCOUNT_[lineId]’
Discount is additional to the custom price

Common Use Cases:

Negotiated Pricing: Custom rates for specific customers
Price Matching: Match competitor pricing
Promotional Pricing: Special one-off prices
Bundle Pricing: Custom prices for package deals
Legacy Pricing: Honor old pricing agreements
Test Orders: Zero or nominal pricing for testing

Differences from Standard Add:

No selling plan association
No pricing policy rules
No automatic tier discounts
Price doesn’t adjust with frequency changes
Manual price management required

One-Time Products: When isOneTimeProduct=true:

Product appears only in next order
Automatically removed after fulfillment
Custom price applies to that single order
Shop discount still applies if configured

Price Validation:

Must be a positive number
No maximum limit enforced
Can be less than product cost (loss leader)
Currency matches shop’s base currency
Decimal precision per currency rules

Important Considerations:

No automatic price updates with product changes
Frequency changes don’t affect pricing
May bypass minimum order values
Consider margin implications
Document reason for custom pricing

Post-Addition Effects:

Customer receives product addition email
Activity log records custom price
Shipping may need recalculation
Order total updates immediately
No impact on other line items

Authentication: Requires valid X-API-Key header

PUT

api

external

subscription-contract-add-line-item

Add product with custom price to subscription

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

import requests

url = "https://subscription-admin.appstle.com/api/external/v2/subscription-contract-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-contract-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-contract-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-contract-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-contract-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-contract-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

{
  "customer": {
    "email": "customer@example.com",
    "id": "gid://shopify/Customer/987654321"
  },
  "id": "gid://shopify/SubscriptionContract/123456789",
  "lines": {
    "edges": [
      {
        "node": {
          "currentPrice": {
            "amount": "29.99",
            "currencyCode": "USD"
          },
          "id": "gid://shopify/SubscriptionLine/111111",
          "quantity": 1,
          "sellingPlanId": null,
          "sellingPlanName": null,
          "title": "Premium Coffee - Dark Roast",
          "variantId": "gid://shopify/ProductVariant/42549172011164"
        }
      },
      {
        "node": {
          "currentPrice": {
            "amount": "19.99",
            "currencyCode": "USD"
          },
          "discountAllocations": [
            {
              "discount": {
                "__typename": "SubscriptionManualDiscount",
                "id": "gid://shopify/SubscriptionManualDiscount/333333",
                "title": "PRODUCT_DISCOUNT_222222",
                "type": "MANUAL",
                "value": {
                  "percentage": 10
                }
              }
            }
          ],
          "id": "gid://shopify/SubscriptionLine/222222",
          "quantity": 1,
          "sellingPlanId": null,
          "sellingPlanName": null,
          "title": "Special Edition Box",
          "variantId": "gid://shopify/ProductVariant/98765432101"
        }
      }
    ]
  },
  "nextBillingDate": "2024-04-01T00:00:00Z",
  "status": "ACTIVE"
}

Headers

X-API-Key

string

required

API Key for authentication

Query Parameters

contractId

integer<int64>

required

Subscription contract ID to add product to

api_key

string

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

quantity

integer<int32>

required

Quantity of product to add

variantId

string

required

Shopify variant ID of the product to add

price

number<double>

required

Custom price for the product (in store currency). This exact price will be charged regardless of the product's normal price, selling plans, or frequency. If the shop has 'applySubscriptionDiscount' enabled, an additional discount may be applied on top of this price.

Required range: 0.01 <= x <= 999999.99

isOneTimeProduct

boolean

default:false

When true, product will only be included in the next order; when false, in all future orders

Response

Product successfully added to subscription with custom price

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

Unskip a previously skipped order

Add product to subscription

Add product with custom price to subscription

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

import requests

url = "https://subscription-admin.appstle.com/api/external/v2/subscription-contract-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-contract-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-contract-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-contract-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-contract-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-contract-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

{
  "customer": {
    "email": "customer@example.com",
    "id": "gid://shopify/Customer/987654321"
  },
  "id": "gid://shopify/SubscriptionContract/123456789",
  "lines": {
    "edges": [
      {
        "node": {
          "currentPrice": {
            "amount": "29.99",
            "currencyCode": "USD"
          },
          "id": "gid://shopify/SubscriptionLine/111111",
          "quantity": 1,
          "sellingPlanId": null,
          "sellingPlanName": null,
          "title": "Premium Coffee - Dark Roast",
          "variantId": "gid://shopify/ProductVariant/42549172011164"
        }
      },
      {
        "node": {
          "currentPrice": {
            "amount": "19.99",
            "currencyCode": "USD"
          },
          "discountAllocations": [
            {
              "discount": {
                "__typename": "SubscriptionManualDiscount",
                "id": "gid://shopify/SubscriptionManualDiscount/333333",
                "title": "PRODUCT_DISCOUNT_222222",
                "type": "MANUAL",
                "value": {
                  "percentage": 10
                }
              }
            }
          ],
          "id": "gid://shopify/SubscriptionLine/222222",
          "quantity": 1,
          "sellingPlanId": null,
          "sellingPlanName": null,
          "title": "Special Edition Box",
          "variantId": "gid://shopify/ProductVariant/98765432101"
        }
      }
    ]
  },
  "nextBillingDate": "2024-04-01T00:00:00Z",
  "status": "ACTIVE"
}