Get all one-time products for a subscription contract
Retrieves all one-time products (add-ons) associated with a specific subscription contract across all billing attempts. One-time products are additional items that customers can add to their subscription orders on a non-recurring basis. Each one-time product is tied to a specific billing attempt and will only be included in that particular order.
Key Features:
- Returns ALL one-time products across all queued billing attempts
- Each product includes the billing attempt ID to identify which order it belongs to
- Includes product details: variant ID, quantity, title, image, and price
- Products are automatically removed after the associated billing attempt is processed
Use Cases:
- Display all one-time products added to a subscription across all upcoming orders
- Allow customers to review their one-time add-ons in customer portal
- Enable merchants to see all one-time products for a contract
- Integrate with external systems to manage subscription add-ons
Authentication: Requires valid X-API-Key header
curl --request GET \
--url https://subscription-admin.appstle.com/api/external/v2/subscription-contract-one-offs-by-contractId \
--header 'X-API-Key: <x-api-key>'import requests
url = "https://subscription-admin.appstle.com/api/external/v2/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/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/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/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/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/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": 11111,
"contractId": 67890,
"createdAt": "2024-01-15T10:30:00Z",
"currencyCode": "USD",
"id": 12345,
"image": "https://cdn.shopify.com/s/files/1/0000/0000/products/filter.jpg",
"price": "9.99",
"productTitle": "Coffee Filters - Pack of 100",
"quantity": 2,
"shop": "example-shop.myshopify.com",
"updatedAt": "2024-01-15T10:30:00Z",
"variantId": 22222,
"variantTitle": "Standard Size"
},
{
"billingAttemptId": 11112,
"contractId": 67890,
"createdAt": "2024-01-16T14:20:00Z",
"currencyCode": "USD",
"id": 12346,
"image": "https://cdn.shopify.com/s/files/1/0000/0000/products/scoop.jpg",
"price": "14.99",
"productTitle": "Coffee Scoop",
"quantity": 1,
"shop": "example-shop.myshopify.com",
"updatedAt": "2024-01-16T14:20:00Z",
"variantId": 33333,
"variantTitle": "Stainless Steel"
}
]{
"detail": "Contract does not belong to this shop",
"status": 400,
"title": "Invalid contract",
"type": "https://example.com/errors/bad-request"
}{
"detail": "Valid X-API-Key header is required",
"status": 401,
"title": "Authentication required",
"type": "https://example.com/errors/unauthorized"
}{
"detail": "API key does not have permission to view one-time products",
"status": 403,
"title": "Insufficient permissions",
"type": "https://example.com/errors/forbidden"
}Headers
API Key for authentication. This key identifies your shop and must be included in the X-API-Key header.
Query Parameters
API Key (Deprecated - Use X-API-Key header instead)
The unique identifier of the subscription contract to retrieve one-time products for Must be a valid contract ID that belongs to the authenticated shop
x >= 1Response
Successfully retrieved one-time products
The Shopify store domain that owns this subscription
^[a-zA-Z0-9][a-zA-Z0-9-]*\.myshopify\.com$"example-store.myshopify.com"
The billing attempt ID this one-time product is associated with. This determines which upcoming order will include this product.
x >= 154321
Unique identifier of the one-time product record
12345
The price per unit of this product in the shop's base currency. This may include any applicable discounts.
0 <= x <= 999999.9919.99
The quantity of this product to include in the order
1 <= x <= 9992
The subscription contract ID this one-time product belongs to
x >= 198765
The handle/slug of the product variant for URL-friendly identification
^[a-z0-9]+(?:-[a-z0-9]+)*$"premium-coffee-blend-500g"
The Shopify product variant ID for this one-time product
x >= 142549172011164
curl --request GET \
--url https://subscription-admin.appstle.com/api/external/v2/subscription-contract-one-offs-by-contractId \
--header 'X-API-Key: <x-api-key>'import requests
url = "https://subscription-admin.appstle.com/api/external/v2/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/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/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/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/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/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": 11111,
"contractId": 67890,
"createdAt": "2024-01-15T10:30:00Z",
"currencyCode": "USD",
"id": 12345,
"image": "https://cdn.shopify.com/s/files/1/0000/0000/products/filter.jpg",
"price": "9.99",
"productTitle": "Coffee Filters - Pack of 100",
"quantity": 2,
"shop": "example-shop.myshopify.com",
"updatedAt": "2024-01-15T10:30:00Z",
"variantId": 22222,
"variantTitle": "Standard Size"
},
{
"billingAttemptId": 11112,
"contractId": 67890,
"createdAt": "2024-01-16T14:20:00Z",
"currencyCode": "USD",
"id": 12346,
"image": "https://cdn.shopify.com/s/files/1/0000/0000/products/scoop.jpg",
"price": "14.99",
"productTitle": "Coffee Scoop",
"quantity": 1,
"shop": "example-shop.myshopify.com",
"updatedAt": "2024-01-16T14:20:00Z",
"variantId": 33333,
"variantTitle": "Stainless Steel"
}
]{
"detail": "Contract does not belong to this shop",
"status": 400,
"title": "Invalid contract",
"type": "https://example.com/errors/bad-request"
}{
"detail": "Valid X-API-Key header is required",
"status": 401,
"title": "Authentication required",
"type": "https://example.com/errors/unauthorized"
}{
"detail": "API key does not have permission to view one-time products",
"status": 403,
"title": "Insufficient permissions",
"type": "https://example.com/errors/forbidden"
}