Billing & Orders
Trigger immediate billing for an order
Queues a billing attempt for immediate processing, bypassing the scheduled billing date. It works on an upcoming attempt (to bill it now) and on a failed one (to retry it).
Asynchronous processing:
- A
200response with an empty body means the billing attempt was accepted: itsstatusbecomesREQUESTINGand the charge is sent to Shopify shortly after. It does not contain the payment result - A membership can’t be billed twice within 24 hours (3 hours when it bills every day). If another attempt of the same membership was billed, failed or is due within 24 hours before or after the call, this attempt ends with status
SKIPPEDeven though the call returned200: no order is created, and the attempt isn’t billed on its scheduled date either
Tracking the result:
- Webhooks:
membership.billing-successormembership.billing-failure - Polling:
GET /api/external/v2/subscription-billing-attempts/past-orders?contractId={contractId}and check the attemptstatus:REQUESTING/PROGRESS: still processingSECURITY_CHALLENGE: the card issuer requires 3D SecureSUCCESS/FAILURE: final resultSKIPPED: no order was created- Any other status, such as
CONTRACT_PAUSED,CONTRACT_CANCELLEDorSHOPIFY_EXCEPTION: the attempt stopped; stop polling
Important Notes:
- The store’s Appstle plan must include immediate orders. Without it, the call returns
400witherrorKeyfeature_access_denied - Call it only for an upcoming or failed attempt: it doesn’t refuse an attempt that has already succeeded
- A store may have a daily limit of 3 immediate orders, unless support has raised it, shared by API keys, partner tokens and Attempt Billing in the Appstle admin. Past it, the call returns
400witherrorKeyimmediate_order_daily_limit_exceededuntil midnight UTC. A call counts even when it then fails, and so does a call the limit refuses, so don’t retry a refused call the same day. See Daily limit on immediate orders - Only an
ACTIVEmembership can be billed; any other status returns400witherrorKeycontract_not_active - An attempt that is already
REQUESTINGorPROGRESSreturns400witherrorKeybillingInProgress - An unknown attempt ID, or one that belongs to another store, returns
400witherrorKeyinvalidContract - 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://membership-admin.appstle.com/api/external/v2/subscription-billing-attempts/attempt-billing/{id}import requests
url = "https://membership-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://membership-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://membership-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://membership-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://membership-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://membership-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⌘I
Trigger immediate billing for an order
curl --request PUT \
--url https://membership-admin.appstle.com/api/external/v2/subscription-billing-attempts/attempt-billing/{id}import requests
url = "https://membership-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://membership-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://membership-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://membership-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://membership-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://membership-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