# Get upcoming orders

Retrieves upcoming/scheduled billing attempts for shop, contract, or customer. Returns future orders that haven't been processed yet.

Query Options:
- No params: All upcoming orders for shop
- contractId: Upcoming orders for specific contract
- customerId: Upcoming orders for specific customer

Use Cases:
- Display next delivery dates in portal
- Show upcoming charges
- Allow order modifications before processing

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

Endpoint: GET /api/external/v2/subscription-billing-attempts/top-orders
Version: 0.0.1

## Query parameters:

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

  - `contractId` (integer)
    Filter by subscription contract ID
    Example: 123456

  - `customerId` (integer)
    Filter by customer ID
    Example: 789012

## Header parameters:

  - `X-API-Key` (string)

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