Billing & Payments
Trigger immediate billing for an order
Queues a billing attempt for immediate processing, bypassing the scheduled billing date.
Asynchronous processing:
- A successful response means the billing attempt was accepted and processing has started; it does not contain the payment result
- The charge is sent to Shopify shortly after the call and the result is reported asynchronously
- Track the result with
billingAttemptIdfrom the response. It can differ from the ID you sent, depending on the store’s Manual Order Processing setting
What happens to the schedule: The store’s When billing manually setting decides (Shop Settings → Order Settings → Manual Order Processing). This endpoint has no parameter to override it. New stores start on Process upcoming scheduled order.
- Process upcoming scheduled order: the attempt you send is billed now instead of on its date, and the other upcoming orders keep their dates. No extra order is created.
billingAttemptIdequalsrequestedBillingAttemptId, andbillingDatekeeps the order’s scheduled date. This is the option that sends the upcoming order early - Create extra order only: an extra one-time order is placed now, and the attempt you sent still bills on its date.
billingAttemptIdis a new attempt for the extra order, withbillingDateset to now - Create extra order and recalculate schedule: an extra one-time order is placed now, and the future schedule is recalculated from today.
billingAttemptIdis a new attempt, withbillingDateset to now - Whichever option is set, a failed attempt you retry (status
FAILURE,SHOPIFY_EXCEPTION,SKIPPED_INVENTORY_MGMTorSKIPPED_DUNNING_MGMT) is billed again in place, with the same ID
Tracking the result:
- Webhooks:
subscription.billing-successorsubscription.billing-failure - Polling:
GET /api/external/v2/subscription-billing-attempts/past-orders?contractId={contractId}and check the attemptstatus:IMMEDIATE_TRIGGERED/PROGRESS: still processingSECURITY_CHALLENGE: the card issuer requires 3D Secure; no webhook is sent for this stateSUCCESS/FAILURE: final result
Important Notes:
- The store’s Appstle plan must include Order now (placing orders immediately). Paid plans include it today and the Free plan doesn’t; a store on an older or custom plan may not have it, and support@appstle.com can check. Without it, the call returns
400with the titleUserGeneratedError:You don't have permission to place immediate orders. Please upgrade your plan to enable this feature. - Creates an actual order in Shopify and charges the customer’s payment method
- Cannot be undone once processed
Authentication: Requires a valid X-API-Key header with a Read & Write key
PUT
/
api
/
external
/
v2
/
subscription-billing-attempts
/
attempt-billing
/
{id}
Trigger immediate billing for an order
curl --request PUT \
--url https://subscription-admin.appstle.com/api/external/v2/subscription-billing-attempts/attempt-billing/{id}import requests
url = "https://subscription-admin.appstle.com/api/external/v2/subscription-billing-attempts/attempt-billing/{id}"
response = requests.put(url)
print(response.text)const options = {method: 'PUT'};
fetch('https://subscription-admin.appstle.com/api/external/v2/subscription-billing-attempts/attempt-billing/{id}', 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-billing-attempts/attempt-billing/{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://subscription-admin.appstle.com/api/external/v2/subscription-billing-attempts/attempt-billing/{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://subscription-admin.appstle.com/api/external/v2/subscription-billing-attempts/attempt-billing/{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://subscription-admin.appstle.com/api/external/v2/subscription-billing-attempts/attempt-billing/{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{
"billingAttemptId": 123456,
"billingDate": "2026-09-26T10:15:30Z",
"contractId": 987654321,
"message": "Billing attempt has been queued for immediate processing. The payment result is not included in this response. Track it via the subscription.billing-success / subscription.billing-failure webhooks, or poll GET /api/external/v2/subscription-billing-attempts/past-orders?contractId={contractId} using the returned billingAttemptId.",
"requestedBillingAttemptId": 123456,
"status": "IMMEDIATE_TRIGGERED"
}{
"billingAttemptId": 123457,
"billingDate": "2023-11-07T05:31:56Z",
"contractId": 987654321,
"message": "<string>",
"requestedBillingAttemptId": 123456,
"status": "IMMEDIATE_TRIGGERED"
}{
"billingAttemptId": 123457,
"billingDate": "2023-11-07T05:31:56Z",
"contractId": 987654321,
"message": "<string>",
"requestedBillingAttemptId": 123456,
"status": "IMMEDIATE_TRIGGERED"
}{
"detail": "This API key is read-only and cannot perform write operations.",
"status": 403,
"title": "Forbidden"
}Response
Billing attempt accepted and queued for immediate processing
Acknowledgement that an immediate billing attempt was accepted and queued for processing. The payment result is delivered asynchronously.
Current status of the billing attempt
Available options:
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 Example:
"IMMEDIATE_TRIGGERED"
⌘I
Trigger immediate billing for an order
curl --request PUT \
--url https://subscription-admin.appstle.com/api/external/v2/subscription-billing-attempts/attempt-billing/{id}import requests
url = "https://subscription-admin.appstle.com/api/external/v2/subscription-billing-attempts/attempt-billing/{id}"
response = requests.put(url)
print(response.text)const options = {method: 'PUT'};
fetch('https://subscription-admin.appstle.com/api/external/v2/subscription-billing-attempts/attempt-billing/{id}', 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-billing-attempts/attempt-billing/{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://subscription-admin.appstle.com/api/external/v2/subscription-billing-attempts/attempt-billing/{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://subscription-admin.appstle.com/api/external/v2/subscription-billing-attempts/attempt-billing/{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://subscription-admin.appstle.com/api/external/v2/subscription-billing-attempts/attempt-billing/{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{
"billingAttemptId": 123456,
"billingDate": "2026-09-26T10:15:30Z",
"contractId": 987654321,
"message": "Billing attempt has been queued for immediate processing. The payment result is not included in this response. Track it via the subscription.billing-success / subscription.billing-failure webhooks, or poll GET /api/external/v2/subscription-billing-attempts/past-orders?contractId={contractId} using the returned billingAttemptId.",
"requestedBillingAttemptId": 123456,
"status": "IMMEDIATE_TRIGGERED"
}{
"billingAttemptId": 123457,
"billingDate": "2023-11-07T05:31:56Z",
"contractId": 987654321,
"message": "<string>",
"requestedBillingAttemptId": 123456,
"status": "IMMEDIATE_TRIGGERED"
}{
"billingAttemptId": 123457,
"billingDate": "2023-11-07T05:31:56Z",
"contractId": 987654321,
"message": "<string>",
"requestedBillingAttemptId": 123456,
"status": "IMMEDIATE_TRIGGERED"
}{
"detail": "This API key is read-only and cannot perform write operations.",
"status": 403,
"title": "Forbidden"
}