# 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:
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

Endpoint: PUT /api/external/v2/subscription-billing-attempts
Version: 0.0.1

## Query parameters:

  - `api_key` (string)
    API Key (Deprecated - Use Header X-API-Key instead)

## Header parameters:

  - `X-API-Key` (string)

## Request fields (application/json):

  - `id` (integer)

  - `shop` (string, required)

  - `billingAttemptId` (string)

  - `status` (string)
    Enum: "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)

  - `contractId` (integer)

  - `attemptCount` (integer)

  - `attemptTime` (string)

  - `graphOrderId` (string)

  - `orderId` (integer)

  - `orderAmount` (number)

  - `orderName` (string)

  - `retryingNeeded` (boolean, required)

  - `transactionFailedEmailSentStatus` (string)
    Enum: "SENT", "UNSENT", "FAILED", "EMAIL_SETTINGS_DISABLED", "CUSTOMER_PAYMENT_EMPTY", "CONTRACT_CANCELLED"

  - `upcomingOrderEmailSentStatus` (string)
    Enum: "SENT", "UNSENT", "FAILED", "EMAIL_SETTINGS_DISABLED", "CUSTOMER_PAYMENT_EMPTY", "CONTRACT_CANCELLED", "STOP_FROM_CONTRACT", "CONTRACT_PAUSED"

  - `applyUsageCharge` (boolean)

  - `recurringChargeId` (integer)

  - `transactionRate` (number)

  - `usageChargeStatus` (string)
    Enum: "SUCCESS", "FAILED", "TO_BE_TRIED"

  - `transactionFailedSmsSentStatus` (string)
    Enum: "SENT", "UNSENT", "FAILED", "SMS_SETTINGS_DISABLED", "CUSTOMER_PAYMENT_EMPTY", "CONTRACT_CANCELLED", "PHONE_NUMBER_EMPTY"

  - `upcomingOrderSmsSentStatus` (string)
    Enum: "SENT", "UNSENT", "FAILED", "SMS_SETTINGS_DISABLED", "CUSTOMER_PAYMENT_EMPTY", "CONTRACT_CANCELLED", "STOP_FROM_CONTRACT", "CONTRACT_PAUSED", "PHONE_NUMBER_EMPTY"

  - `billingAttemptResponseMessage` (string)

  - `progressAttemptCount` (integer)

  - `orderNote` (string)

  - `variantList` (array)

  - `variantList.variantId` (integer)

  - `variantList.quantity` (integer)

  - `variantList.title` (string)

  - `variantList.image` (string)

  - `variantList.productTitle` (string)

  - `variantList.productId` (string)

  - `variantList.sellingPlanId` (string)

  - `orderAmountUSD` (number)

  - `securityChallengeSentStatus` (string)
    Enum: "SENT", "UNSENT", "FAILED", "EMAIL_SETTINGS_DISABLED", "CONTRACT_CANCELLED"

  - `upgradeDowngradeBilling` (boolean)

## Response 200 fields (application/json):

  - `id` (integer)

  - `shop` (string, required)

  - `billingAttemptId` (string)

  - `status` (string)
    Enum: "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)

  - `contractId` (integer)

  - `attemptCount` (integer)

  - `attemptTime` (string)

  - `graphOrderId` (string)

  - `orderId` (integer)

  - `orderAmount` (number)

  - `orderName` (string)

  - `retryingNeeded` (boolean, required)

  - `transactionFailedEmailSentStatus` (string)
    Enum: "SENT", "UNSENT", "FAILED", "EMAIL_SETTINGS_DISABLED", "CUSTOMER_PAYMENT_EMPTY", "CONTRACT_CANCELLED"

  - `upcomingOrderEmailSentStatus` (string)
    Enum: "SENT", "UNSENT", "FAILED", "EMAIL_SETTINGS_DISABLED", "CUSTOMER_PAYMENT_EMPTY", "CONTRACT_CANCELLED", "STOP_FROM_CONTRACT", "CONTRACT_PAUSED"

  - `applyUsageCharge` (boolean)

  - `recurringChargeId` (integer)

  - `transactionRate` (number)

  - `usageChargeStatus` (string)
    Enum: "SUCCESS", "FAILED", "TO_BE_TRIED"

  - `transactionFailedSmsSentStatus` (string)
    Enum: "SENT", "UNSENT", "FAILED", "SMS_SETTINGS_DISABLED", "CUSTOMER_PAYMENT_EMPTY", "CONTRACT_CANCELLED", "PHONE_NUMBER_EMPTY"

  - `upcomingOrderSmsSentStatus` (string)
    Enum: "SENT", "UNSENT", "FAILED", "SMS_SETTINGS_DISABLED", "CUSTOMER_PAYMENT_EMPTY", "CONTRACT_CANCELLED", "STOP_FROM_CONTRACT", "CONTRACT_PAUSED", "PHONE_NUMBER_EMPTY"

  - `billingAttemptResponseMessage` (string)

  - `progressAttemptCount` (integer)

  - `orderNote` (string)

  - `variantList` (array)

  - `variantList.variantId` (integer)

  - `variantList.quantity` (integer)

  - `variantList.title` (string)

  - `variantList.image` (string)

  - `variantList.productTitle` (string)

  - `variantList.productId` (string)

  - `variantList.sellingPlanId` (string)

  - `orderAmountUSD` (number)

  - `securityChallengeSentStatus` (string)
    Enum: "SENT", "UNSENT", "FAILED", "EMAIL_SETTINGS_DISABLED", "CONTRACT_CANCELLED"

  - `upgradeDowngradeBilling` (boolean)

## Response 400 fields (*/*):

  - `id` (integer)

  - `shop` (string, required)

  - `billingAttemptId` (string)

  - `status` (string)
    Enum: "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)

  - `contractId` (integer)

  - `attemptCount` (integer)

  - `attemptTime` (string)

  - `graphOrderId` (string)

  - `orderId` (integer)

  - `orderAmount` (number)

  - `orderName` (string)

  - `retryingNeeded` (boolean, required)

  - `transactionFailedEmailSentStatus` (string)
    Enum: "SENT", "UNSENT", "FAILED", "EMAIL_SETTINGS_DISABLED", "CUSTOMER_PAYMENT_EMPTY", "CONTRACT_CANCELLED"

  - `upcomingOrderEmailSentStatus` (string)
    Enum: "SENT", "UNSENT", "FAILED", "EMAIL_SETTINGS_DISABLED", "CUSTOMER_PAYMENT_EMPTY", "CONTRACT_CANCELLED", "STOP_FROM_CONTRACT", "CONTRACT_PAUSED"

  - `applyUsageCharge` (boolean)

  - `recurringChargeId` (integer)

  - `transactionRate` (number)

  - `usageChargeStatus` (string)
    Enum: "SUCCESS", "FAILED", "TO_BE_TRIED"

  - `transactionFailedSmsSentStatus` (string)
    Enum: "SENT", "UNSENT", "FAILED", "SMS_SETTINGS_DISABLED", "CUSTOMER_PAYMENT_EMPTY", "CONTRACT_CANCELLED", "PHONE_NUMBER_EMPTY"

  - `upcomingOrderSmsSentStatus` (string)
    Enum: "SENT", "UNSENT", "FAILED", "SMS_SETTINGS_DISABLED", "CUSTOMER_PAYMENT_EMPTY", "CONTRACT_CANCELLED", "STOP_FROM_CONTRACT", "CONTRACT_PAUSED", "PHONE_NUMBER_EMPTY"

  - `billingAttemptResponseMessage` (string)

  - `progressAttemptCount` (integer)

  - `orderNote` (string)

  - `variantList` (array)

  - `variantList.variantId` (integer)

  - `variantList.quantity` (integer)

  - `variantList.title` (string)

  - `variantList.image` (string)

  - `variantList.productTitle` (string)

  - `variantList.productId` (string)

  - `variantList.sellingPlanId` (string)

  - `orderAmountUSD` (number)

  - `securityChallengeSentStatus` (string)
    Enum: "SENT", "UNSENT", "FAILED", "EMAIL_SETTINGS_DISABLED", "CONTRACT_CANCELLED"

  - `upgradeDowngradeBilling` (boolean)

## Response 401 fields (*/*):

  - `id` (integer)

  - `shop` (string, required)

  - `billingAttemptId` (string)

  - `status` (string)
    Enum: "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)

  - `contractId` (integer)

  - `attemptCount` (integer)

  - `attemptTime` (string)

  - `graphOrderId` (string)

  - `orderId` (integer)

  - `orderAmount` (number)

  - `orderName` (string)

  - `retryingNeeded` (boolean, required)

  - `transactionFailedEmailSentStatus` (string)
    Enum: "SENT", "UNSENT", "FAILED", "EMAIL_SETTINGS_DISABLED", "CUSTOMER_PAYMENT_EMPTY", "CONTRACT_CANCELLED"

  - `upcomingOrderEmailSentStatus` (string)
    Enum: "SENT", "UNSENT", "FAILED", "EMAIL_SETTINGS_DISABLED", "CUSTOMER_PAYMENT_EMPTY", "CONTRACT_CANCELLED", "STOP_FROM_CONTRACT", "CONTRACT_PAUSED"

  - `applyUsageCharge` (boolean)

  - `recurringChargeId` (integer)

  - `transactionRate` (number)

  - `usageChargeStatus` (string)
    Enum: "SUCCESS", "FAILED", "TO_BE_TRIED"

  - `transactionFailedSmsSentStatus` (string)
    Enum: "SENT", "UNSENT", "FAILED", "SMS_SETTINGS_DISABLED", "CUSTOMER_PAYMENT_EMPTY", "CONTRACT_CANCELLED", "PHONE_NUMBER_EMPTY"

  - `upcomingOrderSmsSentStatus` (string)
    Enum: "SENT", "UNSENT", "FAILED", "SMS_SETTINGS_DISABLED", "CUSTOMER_PAYMENT_EMPTY", "CONTRACT_CANCELLED", "STOP_FROM_CONTRACT", "CONTRACT_PAUSED", "PHONE_NUMBER_EMPTY"

  - `billingAttemptResponseMessage` (string)

  - `progressAttemptCount` (integer)

  - `orderNote` (string)

  - `variantList` (array)

  - `variantList.variantId` (integer)

  - `variantList.quantity` (integer)

  - `variantList.title` (string)

  - `variantList.image` (string)

  - `variantList.productTitle` (string)

  - `variantList.productId` (string)

  - `variantList.sellingPlanId` (string)

  - `orderAmountUSD` (number)

  - `securityChallengeSentStatus` (string)
    Enum: "SENT", "UNSENT", "FAILED", "EMAIL_SETTINGS_DISABLED", "CONTRACT_CANCELLED"

  - `upgradeDowngradeBilling` (boolean)

## Response 404 fields (*/*):

  - `id` (integer)

  - `shop` (string, required)

  - `billingAttemptId` (string)

  - `status` (string)
    Enum: "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)

  - `contractId` (integer)

  - `attemptCount` (integer)

  - `attemptTime` (string)

  - `graphOrderId` (string)

  - `orderId` (integer)

  - `orderAmount` (number)

  - `orderName` (string)

  - `retryingNeeded` (boolean, required)

  - `transactionFailedEmailSentStatus` (string)
    Enum: "SENT", "UNSENT", "FAILED", "EMAIL_SETTINGS_DISABLED", "CUSTOMER_PAYMENT_EMPTY", "CONTRACT_CANCELLED"

  - `upcomingOrderEmailSentStatus` (string)
    Enum: "SENT", "UNSENT", "FAILED", "EMAIL_SETTINGS_DISABLED", "CUSTOMER_PAYMENT_EMPTY", "CONTRACT_CANCELLED", "STOP_FROM_CONTRACT", "CONTRACT_PAUSED"

  - `applyUsageCharge` (boolean)

  - `recurringChargeId` (integer)

  - `transactionRate` (number)

  - `usageChargeStatus` (string)
    Enum: "SUCCESS", "FAILED", "TO_BE_TRIED"

  - `transactionFailedSmsSentStatus` (string)
    Enum: "SENT", "UNSENT", "FAILED", "SMS_SETTINGS_DISABLED", "CUSTOMER_PAYMENT_EMPTY", "CONTRACT_CANCELLED", "PHONE_NUMBER_EMPTY"

  - `upcomingOrderSmsSentStatus` (string)
    Enum: "SENT", "UNSENT", "FAILED", "SMS_SETTINGS_DISABLED", "CUSTOMER_PAYMENT_EMPTY", "CONTRACT_CANCELLED", "STOP_FROM_CONTRACT", "CONTRACT_PAUSED", "PHONE_NUMBER_EMPTY"

  - `billingAttemptResponseMessage` (string)

  - `progressAttemptCount` (integer)

  - `orderNote` (string)

  - `variantList` (array)

  - `variantList.variantId` (integer)

  - `variantList.quantity` (integer)

  - `variantList.title` (string)

  - `variantList.image` (string)

  - `variantList.productTitle` (string)

  - `variantList.productId` (string)

  - `variantList.sellingPlanId` (string)

  - `orderAmountUSD` (number)

  - `securityChallengeSentStatus` (string)
    Enum: "SENT", "UNSENT", "FAILED", "EMAIL_SETTINGS_DISABLED", "CONTRACT_CANCELLED"

  - `upgradeDowngradeBilling` (boolean)