Update subscription billing attempt

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

Full behavior, validation rules, and side effects

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:

1. Scheduled: Billing attempt is queued for future processing
2. Pending: Charge is being processed by payment gateway
3. Success: Payment captured, order created
4. Failed: Payment declined or error occurred
5. 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/v2/subscription-billing-attempts

Update subscription billing attempt

cURL

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

200

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

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

shop · string · required

Shop domain identifier

Example:

"my-store.myshopify.com"

retryingNeeded · boolean · required

id · integer<int64>

Unique identifier of the billing attempt record

Example:

12345

billingAttemptId · string

Shopify billing attempt ID

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

billingDate · string<date-time>

Scheduled billing date for this attempt

contractId · integer<int64>

Associated subscription contract ID

Example:

67890

attemptCount · integer<int32>

Number of billing retry attempts

Example:

1

attemptTime · string<date-time>

graphOrderId · string

orderId · integer<int64>

Shopify order ID if billing was successful

orderAmount · number<double>

Total order amount

Example:

29.99

orderName · string

Shopify order name/number

Example:

"#1001"

transactionFailedEmailSentStatus · enum<string>

Available options: SENT, UNSENT, FAILED, EMAIL_SETTINGS_DISABLED, CUSTOMER_PAYMENT_EMPTY, CONTRACT_CANCELLED

upcomingOrderEmailSentStatus · enum<string>

Available options: SENT, UNSENT, FAILED, EMAIL_SETTINGS_DISABLED, CUSTOMER_PAYMENT_EMPTY, CONTRACT_CANCELLED, STOP_FROM_CONTRACT, CONTRACT_PAUSED

applyUsageCharge · boolean

recurringChargeId · integer<int64>

transactionRate · number<double>

usageChargeStatus · enum<string>

Available options: SUCCESS, FAILED, TO_BE_TRIED

transactionFailedSmsSentStatus · enum<string>

Available options: SENT, UNSENT, FAILED, SMS_SETTINGS_DISABLED, CUSTOMER_PAYMENT_EMPTY, CONTRACT_CANCELLED, PHONE_NUMBER_EMPTY

upcomingOrderSmsSentStatus · enum<string>

Available options: SENT, UNSENT, FAILED, SMS_SETTINGS_DISABLED, CUSTOMER_PAYMENT_EMPTY, CONTRACT_CANCELLED, STOP_FROM_CONTRACT, CONTRACT_PAUSED, PHONE_NUMBER_EMPTY

billingAttemptResponseMessage · string

progressAttemptCount · integer<int32>

orderNote · string

Order note or special instructions

variantList · object[]

Show child attributes

orderAmountUSD · number<double>

securityChallengeSentStatus · enum<string>

Available options: SENT, UNSENT, FAILED, EMAIL_SETTINGS_DISABLED, CONTRACT_CANCELLED

upgradeDowngradeBilling · boolean

Response

200

application/json

Billing attempt successfully updated

shop · string · required

Shop domain identifier

Example:

"my-store.myshopify.com"

retryingNeeded · boolean · required

id · integer<int64>

Unique identifier of the billing attempt record

Example:

12345

billingAttemptId · string

Shopify billing attempt ID

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

billingDate · string<date-time>

Scheduled billing date for this attempt

contractId · integer<int64>

Associated subscription contract ID

Example:

67890

attemptCount · integer<int32>

Number of billing retry attempts

Example:

1

attemptTime · string<date-time>

graphOrderId · string

orderId · integer<int64>

Shopify order ID if billing was successful

orderAmount · number<double>

Total order amount

Example:

29.99

orderName · string

Shopify order name/number

Example:

"#1001"

transactionFailedEmailSentStatus · enum<string>

Available options: SENT, UNSENT, FAILED, EMAIL_SETTINGS_DISABLED, CUSTOMER_PAYMENT_EMPTY, CONTRACT_CANCELLED

upcomingOrderEmailSentStatus · enum<string>

Available options: SENT, UNSENT, FAILED, EMAIL_SETTINGS_DISABLED, CUSTOMER_PAYMENT_EMPTY, CONTRACT_CANCELLED, STOP_FROM_CONTRACT, CONTRACT_PAUSED

applyUsageCharge · boolean

recurringChargeId · integer<int64>

transactionRate · number<double>

usageChargeStatus · enum<string>

Available options: SUCCESS, FAILED, TO_BE_TRIED

transactionFailedSmsSentStatus · enum<string>

Available options: SENT, UNSENT, FAILED, SMS_SETTINGS_DISABLED, CUSTOMER_PAYMENT_EMPTY, CONTRACT_CANCELLED, PHONE_NUMBER_EMPTY

upcomingOrderSmsSentStatus · enum<string>

Available options: SENT, UNSENT, FAILED, SMS_SETTINGS_DISABLED, CUSTOMER_PAYMENT_EMPTY, CONTRACT_CANCELLED, STOP_FROM_CONTRACT, CONTRACT_PAUSED, PHONE_NUMBER_EMPTY

billingAttemptResponseMessage · string

progressAttemptCount · integer<int32>

orderNote · string

Order note or special instructions

variantList · object[]

Show child attributes

orderAmountUSD · number<double>

securityChallengeSentStatus · enum<string>

Available options: SENT, UNSENT, FAILED, EMAIL_SETTINGS_DISABLED, CONTRACT_CANCELLED

upgradeDowngradeBilling · boolean