One-Time Add-Ons

Add one-time product to upcoming order

Adds a one-time product (one-off) to a specific upcoming billing attempt for a membership contract. The product will be included only in the specified order and will not become part of the recurring subscription.

Key Features:

One-Time Addition: Product added to single order only
Billing Cycle Targeting: Specify exact order to add item to
No Subscription Impact: Doesn’t change recurring items
Instant Upsell: Add products between regular billing cycles
Customer Flexibility: Allow members to add extras to next order
Activity Logging: Tracks who added the item (merchant vs API)

Required Parameters:

Contract ID: Target subscription contract
Billing Attempt ID: Specific upcoming order to add item to
Variant ID: Shopify product variant to add
Variant Handle: Product handle for identification

How It Works:

Validates contract exists and belongs to shop
Checks if contract is not frozen (minimum cycles)
Verifies billing attempt is upcoming (not already processed)
Adds variant to the specified billing attempt
Returns updated list of all one-offs for the contract
Logs activity for audit trail

Use Cases:

Customer wants to add a bonus product to next delivery
Merchant offers limited-time add-on to existing members
Trial/sample products added to specific orders
Holiday specials or seasonal items
Promotional gifts or rewards
One-time upsells in customer portal

Business Rules:

Item added only to specified billing attempt
Cannot add to past or completed orders
Contract must not be frozen/minimum cycle locked
Duplicate items increment quantity

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

PUT

api

external

subscription-contract-one-offs-by-contractId-and-billing-attempt-id

Add one-time product to upcoming order

curl --request PUT \
  --url https://membership-admin.appstle.com/api/external/v2/subscription-contract-one-offs-by-contractId-and-billing-attempt-id

const options = {method: 'PUT'};

fetch('https://membership-admin.appstle.com/api/external/v2/subscription-contract-one-offs-by-contractId-and-billing-attempt-id', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const url = 'https://membership-admin.appstle.com/api/external/v2/subscription-contract-one-offs-by-contractId-and-billing-attempt-id';
const options = {method: 'PUT'};

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://membership-admin.appstle.com/api/external/v2/subscription-contract-one-offs-by-contractId-and-billing-attempt-id",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
]);

$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://membership-admin.appstle.com/api/external/v2/subscription-contract-one-offs-by-contractId-and-billing-attempt-id"

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

	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://membership-admin.appstle.com/api/external/v2/subscription-contract-one-offs-by-contractId-and-billing-attempt-id")

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

request = Net::HTTP::Put.new(url)

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

[
  {
    "shop": "my-store.myshopify.com",
    "billingAttemptId": 123,
    "id": 789,
    "subscriptionContractId": 123,
    "variantHandle": "<string>",
    "variantId": 123
  }
]

Headers

X-API-Key

string

Query Parameters

api_key

string

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

contractId

integer<int64>

required

Subscription contract ID

billingAttemptId

integer<int64>

required

Billing attempt ID to add the item to

variantId

integer<int64>

required

Product variant ID to add

variantHandle

string

required

Product handle for identification

Response

One-off product successfully added, returns updated list of all one-offs

shop

string

required

Shop domain identifier

Example:

"my-store.myshopify.com"

billingAttemptId

integer<int64>

Associated billing attempt ID

integer<int64>

Unique identifier of the one-off item

Example:

789

subscriptionContractId

integer<int64>

Associated subscription contract ID

variantHandle

string

Product variant handle for the one-off item

variantId

integer<int64>

Shopify product variant ID of the one-off item

Add one-time product to upcoming order

curl --request PUT \
  --url https://membership-admin.appstle.com/api/external/v2/subscription-contract-one-offs-by-contractId-and-billing-attempt-id

const options = {method: 'PUT'};

fetch('https://membership-admin.appstle.com/api/external/v2/subscription-contract-one-offs-by-contractId-and-billing-attempt-id', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const url = 'https://membership-admin.appstle.com/api/external/v2/subscription-contract-one-offs-by-contractId-and-billing-attempt-id';
const options = {method: 'PUT'};

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://membership-admin.appstle.com/api/external/v2/subscription-contract-one-offs-by-contractId-and-billing-attempt-id",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
]);

$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://membership-admin.appstle.com/api/external/v2/subscription-contract-one-offs-by-contractId-and-billing-attempt-id"

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

	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://membership-admin.appstle.com/api/external/v2/subscription-contract-one-offs-by-contractId-and-billing-attempt-id")

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

request = Net::HTTP::Put.new(url)

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

[
  {
    "shop": "my-store.myshopify.com",
    "billingAttemptId": 123,
    "id": 789,
    "subscriptionContractId": 123,
    "variantHandle": "<string>",
    "variantId": 123
  }
]

Get Started

Guides

Partner Integration

Webhooks

Admin API

Customer Portal API

Add one-time product to upcoming order

Headers

Query Parameters

Response