Billing & Orders

Retry billing for failed attempt

Immediately triggers a billing attempt for a subscription contract, bypassing the normal scheduled billing time. This endpoint processes the billing asynchronously via Shopify’s Subscription Billing API, creating an order and charging the customer’s payment method.

How Billing Retry Works:

Validation: Checks if shop has enableImmediatePlaceOrder permission (premium feature)
Async Trigger: Queues billing job in background (returns immediately)
Shopify API Call: Sends subscriptionBillingAttemptCreate mutation to Shopify
Payment Processing: Charges customer’s stored payment method
Order Creation: Creates Shopify order if payment succeeds
Notification: Sends order confirmation email to customer (if enabled)
Webhook Events: Triggers SUBSCRIPTION_BILLING_ATTEMPTS_SUCCESS or _FAILURE webhook

When to Use This Endpoint:

Payment Failed Previously: Customer updated credit card, retry failed billing
Scheduled Too Far Out: Customer wants early delivery, bill before scheduled date
Payment Method Updated: Customer just added new payment method, retry immediately
Manual Recovery: Merchant intervention to recover failed subscription
Testing/QA: Validate subscription billing flow in test environments
Customer Request: Expedited order fulfillment for urgent needs

Important Limitations & Restrictions:

Permission Required: Only available to shops with enableImmediatePlaceOrder permission
- This is a premium feature - free plans will receive 400 error
- Upgrade subscription plan in Appstle admin to enable
Rate Limiting: Maximum 5 billing attempts per contract per hour (anti-abuse)
Billing Attempt Status: Can retry attempts with status QUEUED, SCHEDULED, or FAILED
Cannot Retry: Billing attempts with status SUCCESS (order already created)
Duplicate Prevention: Shopify prevents duplicate orders within 24-hour window
Payment Method Required: Contract must have valid payment method attached

Asynchronous Processing Details: This endpoint returns immediately (200 OK) before billing completes. Actual billing happens in background:

Success Response: Means billing job was queued, NOT that payment succeeded
Actual Result: Check via webhooks or poll /subscription-billing-attempts endpoint
Processing Time: Typically 5-30 seconds depending on Shopify API response time
Timeout Handling: Background job retries up to 3 times if Shopify API times out

Checking Billing Result (Recommended Flow):

Step 1: Call this endpoint to trigger billing
  PUT /subscription-billing-attempts/attempt-billing/123456
  Response: 200 OK (billing queued)

Step 2: Wait 10-15 seconds for processing

Step 3: Poll billing attempt status
  GET /subscription-billing-attempts?id=123456
  Check 'status' field:
  - SUCCESS: Order created, payment captured
  - FAILED: Payment declined or error occurred
  - PROCESSING: Still in progress, poll again

Step 4: (Alternative) Use webhooks for real-time updates
  Configure webhook: SUBSCRIPTION_BILLING_ATTEMPTS_SUCCESS
  Receive notification when billing completes

Common Error Scenarios:

400 - Permission Denied: “You don’t have permission to place immediate orders”
- Solution: Upgrade to premium plan with enableImmediatePlaceOrder feature
400 - Rate Limit: “Too many billing attempts. Maximum 5 per hour per contract.”
- Solution: Wait before retrying, investigate why billing keeps failing
400 - Invalid Status: “Cannot retry billing attempt with status SUCCESS”
- Solution: Order already created successfully, check order history
404 - Not Found: “Billing attempt not found”
- Solution: Verify billing attempt ID belongs to this shop
500 - Shopify API Error: Background job may fail if Shopify API is down
- Solution: Retry after 5 minutes, check Shopify status page

Payment Failure Reasons (Check After Async Processing): After billing processes, if status becomes FAILED, common reasons include:

Card Declined: Insufficient funds, expired card, fraud detection
Invalid Payment Method: Customer deleted payment method
3D Secure Failed: Authentication challenge not completed
Gateway Error: Payment processor (Stripe/Shopify Payments) issue
Inventory Shortage: Product out of stock, cannot fulfill order
Subscription Canceled: Contract canceled between retry trigger and processing

Integration Best Practices:

Always Check Permission First: Call /shop-info or similar to verify feature access
Implement Webhooks: Don’t rely on polling - use webhooks for real-time status
User Communication: Warn user “Billing in progress…” since it’s async
Idempotency: Safe to call multiple times - Shopify prevents duplicate orders
Error Handling: Gracefully handle permission errors for free plan users
Logging: Track billing attempt ID for troubleshooting and support

Example Use Case - Customer Portal:

Scenario: Customer's card declined, they updated payment method

1. Customer sees "Payment Failed" in portal
2. Customer clicks "Update Payment Method" → adds new card
3. Customer clicks "Retry Payment Now" button
4. Frontend calls: PUT /subscription-billing-attempts/attempt-billing/789
5. Display: "Processing payment..." spinner
6. Poll endpoint every 5 seconds for status update
7. On SUCCESS: Show "Payment successful! Order #12345 created."
8. On FAILED: Show decline reason + retry instructions

Difference from Skip/Reschedule:

Attempt Billing: Immediately charges customer and creates order NOW
Skip: Postpones order to next billing cycle, no charge
Reschedule: Changes billing date without triggering immediate charge

Authentication: Requires API key authentication via X-API-Key header or api_key parameter. Additionally requires merchant account to have enableImmediatePlaceOrder permission (premium feature).

PUT

api

external

subscription-billing-attempts

attempt-billing

{id}

Retry billing for failed attempt

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

Headers

X-API-Key

string

Path Parameters

integer<int64>

required

Billing attempt ID to retry

Query Parameters

api_key

string

API Key (Deprecated - Use Header X-API-Key instead)

Response

Billing attempt successfully queued for asynchronous processing. This does NOT mean payment succeeded - billing happens in background. Poll the billing attempt status or use webhooks to check actual result.

Update order note for billing attempt

Get past orders

Retry billing for failed attempt

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