Get past orders
Retrieves a paginated list of past (processed) billing attempts for one subscription contract, for a customer or, on the Admin API, for the whole shop. Includes successful orders, failed attempts, and skipped orders. Upcoming (QUEUED) orders are not included.
Initial (checkout) order. The order the customer placed at checkout that created the subscription is not a billing attempt, so a call for the whole shop or for a customer does not list it, and a shop with no renewals yet returns an empty list. When you filter by contractId, the checkout order is added as the last row of the last page, or as the only row when the contract has no renewals yet. That row’s id is null, its status is SUCCESS, its orderAmount covers only this subscription’s lines, and X-Total-Count does not count it. A contract with no checkout order, such as an imported one, has no such row. To sync checkout orders for the whole shop, use GET /api/external/v2/subscription-contract-details (fields orderId, orderName, orderAmount, createdAt), filtering by fromCreatedDate / toCreatedDate for incremental syncs.
Filter Options:
- No filter: on the Admin API, past orders of every contract in the shop (use this for bulk syncs instead of calling once per contract). On the Storefront API, past orders of the signed-in customer
- By contract ID: Get order history for specific subscription
- By
customerId(Admin API only): past orders of all of that customer’s contracts - If both
contractIdandcustomerIdare passed,contractIdtakes precedence
Pagination:
- Query parameters:
page(zero-based, default 0),size(default 20, recommended max 250) - Results are sorted by attempt time (or billing date when not yet attempted), newest first
- Response headers:
X-Total-Count(total number of records) andLink(next/prev/first/last page URLs) - Keep requesting the next page until the response is an empty array or
pagereaches the last page
Example (Admin API, all past orders of the shop):
GET /api/external/v2/subscription-billing-attempts/past-orders?page=0&size=250
Notes:
- New orders created while paging shift results between pages; de-duplicate on
id, or use the past orders report endpoint with a fixedtoDayfor a stable window - Line items (
variantList) are served from cached Shopify order data. For orders not yet cached the list may be empty on the first request and is populated on subsequent requests
Status:
SUCCESS: the charge succeeded and Shopify created the orderFAILURE: Shopify declined the payment or rejected the chargeSHOPIFY_EXCEPTION: Shopify returned an error when Appstle asked it to chargeSKIPPED_DUNNING_MGMT: the charge kept failing, and the store’s failed-payment settings skipped the renewalSKIPPED: the renewal was skipped. A renewal skipped ahead of time is listed right away, with its futurebillingDateSKIPPED_INVENTORY_MGMT: the renewal was held for an out-of-stock itemCONTRACT_PAUSEDorCONTRACT_CANCELLED: the renewal came due while the contract was paused or cancelled, so it wasn’t charged- The response schema lists every value. This endpoint has no
statusfilter, so readstatuson each row. The past orders report endpoint takes astatusparameter
Failed charges:
- On a
FAILURE,SHOPIFY_EXCEPTIONorSKIPPED_DUNNING_MGMTrow,billingAttemptResponseMessagesays why the charge failed. When Shopify declined the payment, it holds Shopify’s failure notification as a JSON string: parse it and readerror_codeanderror_message. Otherwise it holds Shopify’s error text attemptCountis how many charges Appstle has sent for the renewal- A retry reuses the same row (same
id), so a failed row can later becomeSUCCESS. It keeps the last failure’sbillingAttemptResponseMessage
Order Information:
- Billing attempt status
- Shopify order ID for successful attempts
- Billing date and processing date
- Order total and line items
- Error messages for failed attempts
Authentication: Requires a signed-in customer. Call it through Shopify’s App Proxy on the store’s domain: the proxy signs the request and attaches the customer, so you send no API key.
curl --request GET \
--url https://www.myshop.com/apps/subscriptions/cp/api/subscription-billing-attempts/past-ordersimport requests
url = "https://www.myshop.com/apps/subscriptions/cp/api/subscription-billing-attempts/past-orders"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://www.myshop.com/apps/subscriptions/cp/api/subscription-billing-attempts/past-orders', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://www.myshop.com/apps/subscriptions/cp/api/subscription-billing-attempts/past-orders';
const options = {method: 'GET'};
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://www.myshop.com/apps/subscriptions/cp/api/subscription-billing-attempts/past-orders",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$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://www.myshop.com/apps/subscriptions/cp/api/subscription-billing-attempts/past-orders"
req, _ := http.NewRequest("GET", 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://www.myshop.com/apps/subscriptions/cp/api/subscription-billing-attempts/past-orders")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_bodyQuery Parameters
Response
Successfully retrieved past orders
Shopify's ID for the most recent charge Shopify created for this renewal. Each new one replaces it. It is null until Shopify has created one, for example on a renewal that has so far only been held for out-of-stock items. A renewal combined into another one carries the combined charge's ID, so two renewals can share it: key on id, not on this field.
Why the last charge for this renewal failed. When Shopify declined the payment, it is Shopify's failure notification as a JSON string: parse it and read error_code and error_message. When Shopify rejected the charge or returned an error, it is Shopify's error text. It is null until a charge fails, and a renewal that later succeeds keeps the last failure's value.
Whether Appstle will check stock again for this renewal, following the store's out-of-stock retry settings. It only matters while status is SKIPPED_INVENTORY_MGMT and the subscription is active. It is not cleared when the renewal is later billed or the subscription is cancelled, so read status first.
Why some lines were left out of this order: INVENTORY_MANAGEMENT (out-of-stock items), MANUAL (products set to be skipped for this order) or ORPHANED_FREE_PRODUCT (a free product left out because no paid product from its plan is in the order). It holds one reason even when several apply. null when no lines were left out.
INVENTORY_MANAGEMENT, MANUAL, ORPHANED_FREE_PRODUCT Where this renewal stands. QUEUED: scheduled and not yet charged. SUCCESS: the charge succeeded and Shopify created the order. FAILURE: Shopify declined the payment or rejected the charge. SHOPIFY_EXCEPTION: Shopify returned an error when Appstle asked it to charge. SKIPPED_DUNNING_MGMT: the charge kept failing, and the store's failed-payment settings skipped the renewal. SKIPPED: the renewal was skipped. SKIPPED_INVENTORY_MGMT: held for an out-of-stock item. CONTRACT_PAUSED or CONTRACT_CANCELLED: the renewal came due while the contract was paused or cancelled, so it wasn't charged.
SUCCESS, FAILURE, REQUESTING, PROGRESS, QUEUED, SKIPPED, SOCIAL_CONNECTION_NULL, CONTRACT_CANCELLED, CONTRACT_ENDED, CONTRACT_PAUSED, AUTO_CHARGE_DISABLED, SHOPIFY_EXCEPTION, SKIPPED_DUNNING_MGMT, SKIPPED_INVENTORY_MGMT, IMMEDIATE_TRIGGERED, SECURITY_CHALLENGE, CONTRACT_PAUSED_MAX_CYCLES, REFUNDED, SKIPPED_DEMO_SHOP, SKIPPED_SHOP_INFO_NOT_FOUND, SKIPPED_BILLING_DATE_STALE, SKIPPED_DUNNING_NOT_CONFIGURED, PENDING_CONSOLIDATION curl --request GET \
--url https://www.myshop.com/apps/subscriptions/cp/api/subscription-billing-attempts/past-ordersimport requests
url = "https://www.myshop.com/apps/subscriptions/cp/api/subscription-billing-attempts/past-orders"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://www.myshop.com/apps/subscriptions/cp/api/subscription-billing-attempts/past-orders', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://www.myshop.com/apps/subscriptions/cp/api/subscription-billing-attempts/past-orders';
const options = {method: 'GET'};
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://www.myshop.com/apps/subscriptions/cp/api/subscription-billing-attempts/past-orders",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$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://www.myshop.com/apps/subscriptions/cp/api/subscription-billing-attempts/past-orders"
req, _ := http.NewRequest("GET", 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://www.myshop.com/apps/subscriptions/cp/api/subscription-billing-attempts/past-orders")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body