Billing & Orders

Update subscription billing attempt

Updates billing attempt details for a subscription contract. Billing attempts represent individual charge attempts for recurring subscription orders.

Key Information Updated:

Billing Date: Next scheduled billing/charge date
Status: Success, failed, pending, or scheduled
Error Messages: Failure reasons for declined payments
Retry Count: Number of retry attempts made
Order ID: Associated Shopify order if billing succeeded
Amount: Billing amount charged or attempted

Billing Attempt Lifecycle:

Scheduled: Billing attempt is queued for future processing
Pending: Charge is being processed by payment gateway
Success: Payment captured, order created
Failed: Payment declined or error occurred
Retrying: Automatic retry scheduled after failure

Common Use Cases:

Reschedule failed billing attempts to a new date
Update billing date to align with customer preferences
Mark manual payment reconciliation in external systems
Sync billing status with external payment processors
Trigger retry logic for failed payment attempts
Update billing metadata for reporting and analytics

Important Notes:

Changing billing date will affect the subscription’s billing cycle
Only pending or failed attempts can typically be modified
Successfully billed attempts are immutable in most cases

Authentication: Requires API key authentication via X-API-Key header or api_key parameter

PUT

api

external

subscription-billing-attempts

Update subscription billing attempt

curl --request PUT \
  --url https://membership-admin.appstle.com/api/external/v2/subscription-billing-attempts \
  --header 'Content-Type: application/json' \
  --data '
{
  "retryingNeeded": true,
  "shop": "my-store.myshopify.com"
}
'

import requests

url = "https://membership-admin.appstle.com/api/external/v2/subscription-billing-attempts"

payload = {
    "retryingNeeded": True,
    "shop": "my-store.myshopify.com"
}
headers = {"Content-Type": "application/json"}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({retryingNeeded: true, shop: 'my-store.myshopify.com'})
};

fetch('https://membership-admin.appstle.com/api/external/v2/subscription-billing-attempts', 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';
const options = {
  method: 'PUT',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({retryingNeeded: true, shop: 'my-store.myshopify.com'})
};

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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'retryingNeeded' => true,
    'shop' => 'my-store.myshopify.com'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://membership-admin.appstle.com/api/external/v2/subscription-billing-attempts"

	payload := strings.NewReader("{\n  \"retryingNeeded\": true,\n  \"shop\": \"my-store.myshopify.com\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Content-Type", "application/json")

	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")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"retryingNeeded\": true,\n  \"shop\": \"my-store.myshopify.com\"\n}"

response = http.request(request)
puts response.read_body

{
  "retryingNeeded": true,
  "shop": "my-store.myshopify.com",
  "applyUsageCharge": true,
  "attemptCount": 1,
  "attemptTime": "2023-11-07T05:31:56Z",
  "billingAttemptId": "<string>",
  "billingAttemptResponseMessage": "<string>",
  "billingDate": "2023-11-07T05:31:56Z",
  "contractId": 67890,
  "graphOrderId": "<string>",
  "id": 12345,
  "orderAmount": 29.99,
  "orderAmountUSD": 123,
  "orderId": 123,
  "orderName": "#1001",
  "orderNote": "<string>",
  "progressAttemptCount": 123,
  "recurringChargeId": 123,
  "transactionRate": 123,
  "upgradeDowngradeBilling": true,
  "variantList": [
    {
      "image": "<string>",
      "productId": "<string>",
      "productTitle": "<string>",
      "quantity": 123,
      "sellingPlanId": "<string>",
      "title": "<string>",
      "variantId": 123
    }
  ]
}

{
  "retryingNeeded": true,
  "shop": "my-store.myshopify.com",
  "applyUsageCharge": true,
  "attemptCount": 1,
  "attemptTime": "2023-11-07T05:31:56Z",
  "billingAttemptId": "<string>",
  "billingAttemptResponseMessage": "<string>",
  "billingDate": "2023-11-07T05:31:56Z",
  "contractId": 67890,
  "graphOrderId": "<string>",
  "id": 12345,
  "orderAmount": 29.99,
  "orderAmountUSD": 123,
  "orderId": 123,
  "orderName": "#1001",
  "orderNote": "<string>",
  "progressAttemptCount": 123,
  "recurringChargeId": 123,
  "transactionRate": 123,
  "upgradeDowngradeBilling": true,
  "variantList": [
    {
      "image": "<string>",
      "productId": "<string>",
      "productTitle": "<string>",
      "quantity": 123,
      "sellingPlanId": "<string>",
      "title": "<string>",
      "variantId": 123
    }
  ]
}

{
  "retryingNeeded": true,
  "shop": "my-store.myshopify.com",
  "applyUsageCharge": true,
  "attemptCount": 1,
  "attemptTime": "2023-11-07T05:31:56Z",
  "billingAttemptId": "<string>",
  "billingAttemptResponseMessage": "<string>",
  "billingDate": "2023-11-07T05:31:56Z",
  "contractId": 67890,
  "graphOrderId": "<string>",
  "id": 12345,
  "orderAmount": 29.99,
  "orderAmountUSD": 123,
  "orderId": 123,
  "orderName": "#1001",
  "orderNote": "<string>",
  "progressAttemptCount": 123,
  "recurringChargeId": 123,
  "transactionRate": 123,
  "upgradeDowngradeBilling": true,
  "variantList": [
    {
      "image": "<string>",
      "productId": "<string>",
      "productTitle": "<string>",
      "quantity": 123,
      "sellingPlanId": "<string>",
      "title": "<string>",
      "variantId": 123
    }
  ]
}

{
  "retryingNeeded": true,
  "shop": "my-store.myshopify.com",
  "applyUsageCharge": true,
  "attemptCount": 1,
  "attemptTime": "2023-11-07T05:31:56Z",
  "billingAttemptId": "<string>",
  "billingAttemptResponseMessage": "<string>",
  "billingDate": "2023-11-07T05:31:56Z",
  "contractId": 67890,
  "graphOrderId": "<string>",
  "id": 12345,
  "orderAmount": 29.99,
  "orderAmountUSD": 123,
  "orderId": 123,
  "orderName": "#1001",
  "orderNote": "<string>",
  "progressAttemptCount": 123,
  "recurringChargeId": 123,
  "transactionRate": 123,
  "upgradeDowngradeBilling": true,
  "variantList": [
    {
      "image": "<string>",
      "productId": "<string>",
      "productTitle": "<string>",
      "quantity": 123,
      "sellingPlanId": "<string>",
      "title": "<string>",
      "variantId": 123
    }
  ]
}

Headers

X-API-Key

string

Query Parameters

api_key

string

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

Body

application/json

Updated billing attempt details including billing date, status, and metadata

retryingNeeded

boolean

required

shop

string

required

Shop domain identifier

Example:

"my-store.myshopify.com"

applyUsageCharge

boolean

attemptCount

integer<int32>

Number of billing retry attempts

Example:

1

attemptTime

string<date-time>

billingAttemptId

string

Shopify billing attempt ID

billingAttemptResponseMessage

string

billingDate

string<date-time>

Scheduled billing date for this attempt

contractId

integer<int64>

Associated subscription contract ID

Example:

67890

graphOrderId

string

integer<int64>

Unique identifier of the billing attempt record

Example:

12345

orderAmount

number<double>

Total order amount

Example:

29.99

orderAmountUSD

number<double>

orderId

integer<int64>

Shopify order ID if billing was successful

orderName

string

Shopify order name/number

Example:

"#1001"

orderNote

string

Order note or special instructions

progressAttemptCount

integer<int32>

recurringChargeId

integer<int64>

securityChallengeSentStatus

enum<string>

Available options:

SENT,

UNSENT,

FAILED,

EMAIL_SETTINGS_DISABLED,

CONTRACT_CANCELLED

status

enum<string>

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,

SKIPPED_DUNNING_MGMT,

SECURITY_CHALLENGE,

SHOPIFY_EXCEPTION

transactionFailedEmailSentStatus

enum<string>

Available options:

SENT,

UNSENT,

FAILED,

EMAIL_SETTINGS_DISABLED,

CUSTOMER_PAYMENT_EMPTY,

CONTRACT_CANCELLED

transactionFailedSmsSentStatus

enum<string>

Available options:

SENT,

UNSENT,

FAILED,

SMS_SETTINGS_DISABLED,

CUSTOMER_PAYMENT_EMPTY,

CONTRACT_CANCELLED,

PHONE_NUMBER_EMPTY

transactionRate

number<double>

upcomingOrderEmailSentStatus

enum<string>

Available options:

SENT,

UNSENT,

FAILED,

EMAIL_SETTINGS_DISABLED,

CUSTOMER_PAYMENT_EMPTY,

CONTRACT_CANCELLED,

STOP_FROM_CONTRACT,

CONTRACT_PAUSED

upcomingOrderSmsSentStatus

enum<string>

Available options:

SENT,

UNSENT,

FAILED,

SMS_SETTINGS_DISABLED,

CUSTOMER_PAYMENT_EMPTY,

CONTRACT_CANCELLED,

STOP_FROM_CONTRACT,

CONTRACT_PAUSED,

PHONE_NUMBER_EMPTY

upgradeDowngradeBilling

boolean

usageChargeStatus

enum<string>

Available options:

SUCCESS,

FAILED,

TO_BE_TRIED

variantList

object[]

Show child attributes

Response

Billing attempt successfully updated

retryingNeeded

boolean

required

shop

string

required

Shop domain identifier

Example:

"my-store.myshopify.com"

applyUsageCharge

boolean

attemptCount

integer<int32>

Number of billing retry attempts

Example:

1

attemptTime

string<date-time>

billingAttemptId

string

Shopify billing attempt ID

billingAttemptResponseMessage

string

billingDate

string<date-time>

Scheduled billing date for this attempt

contractId

integer<int64>

Associated subscription contract ID

Example:

67890

graphOrderId

string

integer<int64>

Unique identifier of the billing attempt record

Example:

12345

orderAmount

number<double>

Total order amount

Example:

29.99

orderAmountUSD

number<double>

orderId

integer<int64>

Shopify order ID if billing was successful

orderName

string

Shopify order name/number

Example:

"#1001"

orderNote

string

Order note or special instructions

progressAttemptCount

integer<int32>

recurringChargeId

integer<int64>

securityChallengeSentStatus

enum<string>

Available options:

SENT,

UNSENT,

FAILED,

EMAIL_SETTINGS_DISABLED,

CONTRACT_CANCELLED

status

enum<string>

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,

SKIPPED_DUNNING_MGMT,

SECURITY_CHALLENGE,

SHOPIFY_EXCEPTION

transactionFailedEmailSentStatus

enum<string>

Available options:

SENT,

UNSENT,

FAILED,

EMAIL_SETTINGS_DISABLED,

CUSTOMER_PAYMENT_EMPTY,

CONTRACT_CANCELLED

transactionFailedSmsSentStatus

enum<string>

Available options:

SENT,

UNSENT,

FAILED,

SMS_SETTINGS_DISABLED,

CUSTOMER_PAYMENT_EMPTY,

CONTRACT_CANCELLED,

PHONE_NUMBER_EMPTY

transactionRate

number<double>

upcomingOrderEmailSentStatus

enum<string>

Available options:

SENT,

UNSENT,

FAILED,

EMAIL_SETTINGS_DISABLED,

CUSTOMER_PAYMENT_EMPTY,

CONTRACT_CANCELLED,

STOP_FROM_CONTRACT,

CONTRACT_PAUSED

upcomingOrderSmsSentStatus

enum<string>

Available options:

SENT,

UNSENT,

FAILED,

SMS_SETTINGS_DISABLED,

CUSTOMER_PAYMENT_EMPTY,

CONTRACT_CANCELLED,

STOP_FROM_CONTRACT,

CONTRACT_PAUSED,

PHONE_NUMBER_EMPTY

upgradeDowngradeBilling

boolean

usageChargeStatus

enum<string>

Available options:

SUCCESS,

FAILED,

TO_BE_TRIED

variantList

object[]

Show child attributes

Get product swap options for subscription items

Update order note for billing attempt

Update subscription billing attempt

curl --request PUT \
  --url https://membership-admin.appstle.com/api/external/v2/subscription-billing-attempts \
  --header 'Content-Type: application/json' \
  --data '
{
  "retryingNeeded": true,
  "shop": "my-store.myshopify.com"
}
'

import requests

url = "https://membership-admin.appstle.com/api/external/v2/subscription-billing-attempts"

payload = {
    "retryingNeeded": True,
    "shop": "my-store.myshopify.com"
}
headers = {"Content-Type": "application/json"}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({retryingNeeded: true, shop: 'my-store.myshopify.com'})
};

fetch('https://membership-admin.appstle.com/api/external/v2/subscription-billing-attempts', 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';
const options = {
  method: 'PUT',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({retryingNeeded: true, shop: 'my-store.myshopify.com'})
};

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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'retryingNeeded' => true,
    'shop' => 'my-store.myshopify.com'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://membership-admin.appstle.com/api/external/v2/subscription-billing-attempts"

	payload := strings.NewReader("{\n  \"retryingNeeded\": true,\n  \"shop\": \"my-store.myshopify.com\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Content-Type", "application/json")

	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")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"retryingNeeded\": true,\n  \"shop\": \"my-store.myshopify.com\"\n}"

response = http.request(request)
puts response.read_body

{
  "retryingNeeded": true,
  "shop": "my-store.myshopify.com",
  "applyUsageCharge": true,
  "attemptCount": 1,
  "attemptTime": "2023-11-07T05:31:56Z",
  "billingAttemptId": "<string>",
  "billingAttemptResponseMessage": "<string>",
  "billingDate": "2023-11-07T05:31:56Z",
  "contractId": 67890,
  "graphOrderId": "<string>",
  "id": 12345,
  "orderAmount": 29.99,
  "orderAmountUSD": 123,
  "orderId": 123,
  "orderName": "#1001",
  "orderNote": "<string>",
  "progressAttemptCount": 123,
  "recurringChargeId": 123,
  "transactionRate": 123,
  "upgradeDowngradeBilling": true,
  "variantList": [
    {
      "image": "<string>",
      "productId": "<string>",
      "productTitle": "<string>",
      "quantity": 123,
      "sellingPlanId": "<string>",
      "title": "<string>",
      "variantId": 123
    }
  ]
}

{
  "retryingNeeded": true,
  "shop": "my-store.myshopify.com",
  "applyUsageCharge": true,
  "attemptCount": 1,
  "attemptTime": "2023-11-07T05:31:56Z",
  "billingAttemptId": "<string>",
  "billingAttemptResponseMessage": "<string>",
  "billingDate": "2023-11-07T05:31:56Z",
  "contractId": 67890,
  "graphOrderId": "<string>",
  "id": 12345,
  "orderAmount": 29.99,
  "orderAmountUSD": 123,
  "orderId": 123,
  "orderName": "#1001",
  "orderNote": "<string>",
  "progressAttemptCount": 123,
  "recurringChargeId": 123,
  "transactionRate": 123,
  "upgradeDowngradeBilling": true,
  "variantList": [
    {
      "image": "<string>",
      "productId": "<string>",
      "productTitle": "<string>",
      "quantity": 123,
      "sellingPlanId": "<string>",
      "title": "<string>",
      "variantId": 123
    }
  ]
}

{
  "retryingNeeded": true,
  "shop": "my-store.myshopify.com",
  "applyUsageCharge": true,
  "attemptCount": 1,
  "attemptTime": "2023-11-07T05:31:56Z",
  "billingAttemptId": "<string>",
  "billingAttemptResponseMessage": "<string>",
  "billingDate": "2023-11-07T05:31:56Z",
  "contractId": 67890,
  "graphOrderId": "<string>",
  "id": 12345,
  "orderAmount": 29.99,
  "orderAmountUSD": 123,
  "orderId": 123,
  "orderName": "#1001",
  "orderNote": "<string>",
  "progressAttemptCount": 123,
  "recurringChargeId": 123,
  "transactionRate": 123,
  "upgradeDowngradeBilling": true,
  "variantList": [
    {
      "image": "<string>",
      "productId": "<string>",
      "productTitle": "<string>",
      "quantity": 123,
      "sellingPlanId": "<string>",
      "title": "<string>",
      "variantId": 123
    }
  ]
}

{
  "retryingNeeded": true,
  "shop": "my-store.myshopify.com",
  "applyUsageCharge": true,
  "attemptCount": 1,
  "attemptTime": "2023-11-07T05:31:56Z",
  "billingAttemptId": "<string>",
  "billingAttemptResponseMessage": "<string>",
  "billingDate": "2023-11-07T05:31:56Z",
  "contractId": 67890,
  "graphOrderId": "<string>",
  "id": 12345,
  "orderAmount": 29.99,
  "orderAmountUSD": 123,
  "orderId": 123,
  "orderName": "#1001",
  "orderNote": "<string>",
  "progressAttemptCount": 123,
  "recurringChargeId": 123,
  "transactionRate": 123,
  "upgradeDowngradeBilling": true,
  "variantList": [
    {
      "image": "<string>",
      "productId": "<string>",
      "productTitle": "<string>",
      "quantity": 123,
      "sellingPlanId": "<string>",
      "title": "<string>",
      "variantId": 123
    }
  ]
}