Subscription One-Time Products
Get one-time products for next upcoming order
Retrieves one-time products that will be included in the next scheduled order for a subscription contract. This endpoint specifically returns products associated with the earliest queued billing attempt, making it ideal for showing customers what additional items will be in their next delivery.
Key Differences from /subscription-contract-one-offs-by-contractId:
- Returns ONLY products for the next upcoming order (not all future orders)
- Finds the earliest QUEUED billing attempt by date
- Returns empty array if no queued billing attempts exist
- Useful for “Your Next Order” previews in customer portals
Use Cases:
- Display a preview of the next order including one-time add-ons
- Calculate the total cost of the upcoming delivery
- Show customers their next delivery date with associated one-time items
- Allow last-minute modifications before order processing
Business Logic:
- Searches for billing attempts with status = QUEUED
- Selects the one with the earliest billing date
- Returns all one-time products for that specific billing attempt
- Returns empty array if no queued orders exist (e.g., subscription paused/cancelled)
Authentication: Requires valid X-API-Key header that identifies the shop
GET
/
api
/
external
/
v2
/
upcoming-subscription-contract-one-offs-by-contractId
Get one-time products for next upcoming order
curl --request GET \
--url https://subscription-admin.appstle.com/api/external/v2/upcoming-subscription-contract-one-offs-by-contractId \
--header 'X-API-Key: <x-api-key>'import requests
url = "https://subscription-admin.appstle.com/api/external/v2/upcoming-subscription-contract-one-offs-by-contractId"
headers = {"X-API-Key": "<x-api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<x-api-key>'}};
fetch('https://subscription-admin.appstle.com/api/external/v2/upcoming-subscription-contract-one-offs-by-contractId', 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/upcoming-subscription-contract-one-offs-by-contractId';
const options = {method: 'GET', 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/upcoming-subscription-contract-one-offs-by-contractId",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
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/upcoming-subscription-contract-one-offs-by-contractId"
req, _ := http.NewRequest("GET", 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/upcoming-subscription-contract-one-offs-by-contractId")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<x-api-key>'
response = http.request(request)
puts response.read_body[
{
"billingAttemptId": 54321,
"id": 12345,
"price": 19.99,
"quantity": 2,
"shop": "example-store.myshopify.com",
"subscriptionContractId": 98765,
"variantHandle": "premium-coffee-blend-500g",
"variantId": 42549172011164
},
{
"billingAttemptId": 54321,
"id": 12346,
"price": 8.99,
"quantity": 1,
"shop": "example-store.myshopify.com",
"subscriptionContractId": 98765,
"variantHandle": "coffee-filters-pack-100",
"variantId": 42549172011165
}
]Headers
Query Parameters
Response
Successfully retrieved one-time products for the next order
⌘I
Get one-time products for next upcoming order
curl --request GET \
--url https://subscription-admin.appstle.com/api/external/v2/upcoming-subscription-contract-one-offs-by-contractId \
--header 'X-API-Key: <x-api-key>'import requests
url = "https://subscription-admin.appstle.com/api/external/v2/upcoming-subscription-contract-one-offs-by-contractId"
headers = {"X-API-Key": "<x-api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<x-api-key>'}};
fetch('https://subscription-admin.appstle.com/api/external/v2/upcoming-subscription-contract-one-offs-by-contractId', 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/upcoming-subscription-contract-one-offs-by-contractId';
const options = {method: 'GET', 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/upcoming-subscription-contract-one-offs-by-contractId",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
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/upcoming-subscription-contract-one-offs-by-contractId"
req, _ := http.NewRequest("GET", 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/upcoming-subscription-contract-one-offs-by-contractId")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<x-api-key>'
response = http.request(request)
puts response.read_body[
{
"billingAttemptId": 54321,
"id": 12345,
"price": 19.99,
"quantity": 2,
"shop": "example-store.myshopify.com",
"subscriptionContractId": 98765,
"variantHandle": "premium-coffee-blend-500g",
"variantId": 42549172011164
},
{
"billingAttemptId": 54321,
"id": 12346,
"price": 8.99,
"quantity": 1,
"shop": "example-store.myshopify.com",
"subscriptionContractId": 98765,
"variantHandle": "coffee-filters-pack-100",
"variantId": 42549172011165
}
]