> ## Documentation Index > Fetch the complete documentation index at: https://developers.appstle.com/llms.txt > Use this file to discover all available pages before exploring further. # Get upcoming orders (top orders) > Retrieves upcoming (queued) billing attempts for a subscription contract or customer. Returns the next scheduled orders that have not yet been processed. **Query Options:** - Filter by contract ID to see upcoming orders for a specific subscription - Filter by customer ID to see all upcoming orders for a customer - Results are ordered by billing date (earliest first) **Use Cases:** - Display "Your Next Order" in customer portal - Show upcoming delivery schedule - Calculate upcoming charges - Preview next order contents **Authentication:** Requires valid X-API-Key header ## OpenAPI ````yaml /subscription/admin-api-swagger.json get /api/external/v2/subscription-billing-attempts/top-orders openapi: 3.0.1 info: description: >- Comprehensive API documentation for managing subscriptions, payments, and related operations. These APIs allow you to programmatically manage subscription lifecycles, handle payments, configure products, and integrate subscription functionality into your applications. title: Admin APIs version: 0.0.1 servers: - url: https://subscription-admin.appstle.com security: [] tags: - description: >- Core APIs for managing the complete subscription lifecycle including creation, updates, pausing, resuming, and cancellation of subscriptions. name: Subscription Management - description: >- APIs for managing subscription payment methods, processing payments, handling payment retries, and updating billing information. name: Subscription Payments - description: >- APIs for managing subscription contracts including delivery schedules, pricing, order notes, billing cycles, and shipping addresses. name: Subscription Contracts - description: >- APIs for managing products within subscriptions including adding, removing, updating quantities, and swapping products. name: Subscription Products - description: >- APIs for handling billing operations, payment processing, and financial transactions related to subscriptions. name: Billing & Payments - description: >- APIs for managing discounts and promotional codes applied to subscriptions. name: Subscription Discounts - description: >- APIs for managing one-time add-on products that can be purchased alongside recurring subscription items. name: Subscription One-Time Products - description: >- APIs for managing subscription plans, pricing tiers, and plan configurations. name: Subscription Plans - description: >- APIs for managing customizable product boxes and bundles where customers can select multiple items. name: Build-a-Box & Bundles - description: >- APIs for managing the product catalog including product information, variants, and inventory. name: Product Catalog - description: >- APIs for managing operational settings, configurations, and administrative functions. name: Operations & Settings - description: >- APIs powering the customer-facing portal where subscribers can manage their own subscriptions. name: Customer Portal - description: APIs for managing customer information, profiles, and account details. name: Customers - description: >- APIs for retrieving aggregated subscription data, customer subscription history, and account-level subscription information. name: Subscription Data - description: >- APIs for managing delivery profiles, shipping rates, free shipping configuration, and delivery method options on subscriptions. name: Delivery & Shipping - description: >- APIs for managing storefront customization including custom CSS, theme settings, label translations, and merchant-defined widget configuration. name: Customization - description: >- APIs for configuring cancellation flows, retention offers, cancellation reason management, and win-back automation. name: Customer Retention paths: /api/external/v2/subscription-billing-attempts/top-orders: get: tags: - Billing & Payments summary: Get upcoming orders (top orders) description: >- Retrieves upcoming (queued) billing attempts for a subscription contract or customer. Returns the next scheduled orders that have not yet been processed. **Query Options:** - Filter by contract ID to see upcoming orders for a specific subscription - Filter by customer ID to see all upcoming orders for a customer - Results are ordered by billing date (earliest first) **Use Cases:** - Display "Your Next Order" in customer portal - Show upcoming delivery schedule - Calculate upcoming charges - Preview next order contents **Authentication:** Requires valid X-API-Key header operationId: getTopOrdersV2 parameters: - description: API Key (Deprecated - Use Header X-API-Key instead) in: query name: api_key required: false schema: type: string - in: header name: X-API-Key required: false schema: type: string - description: Contract ID in: query name: contractId required: false schema: format: int64 type: integer - description: Customer ID in: query name: customerId required: false schema: format: int64 type: integer responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/SubscriptionBillingAttemptDTO' type: array description: Successfully retrieved upcoming orders '400': content: '*/*': schema: items: $ref: '#/components/schemas/SubscriptionBillingAttemptDTO' type: array description: Invalid contract or customer ID '401': content: '*/*': schema: items: $ref: '#/components/schemas/SubscriptionBillingAttemptDTO' type: array description: Authentication required '403': content: '*/*': schema: items: $ref: '#/components/schemas/SubscriptionBillingAttemptDTO' type: array description: Insufficient permissions components: schemas: SubscriptionBillingAttemptDTO: properties: applyUsageCharge: type: boolean attemptCount: format: int32 type: integer attemptTime: format: date-time type: string billingAttemptId: type: string billingAttemptResponseMessage: type: string billingDate: format: date-time type: string contractId: format: int64 type: integer graphOrderId: type: string id: format: int64 type: integer inventorySkippedAttemptCount: format: int32 type: integer inventorySkippedRetryingNeeded: type: boolean lastShippingUpdatedAt: format: date-time type: string orderAmount: format: double type: number orderAmountContractCurrency: format: double type: number orderAmountShopCurrency: format: double type: number orderAmountUSD: format: double type: number orderAttributes: items: $ref: '#/components/schemas/AttributeInfo' type: array orderCancelReason: enum: - CUSTOMER - DECLINED - FRAUD - INVENTORY - STAFF - OTHER - $UNKNOWN type: string orderCancelledAt: format: date-time type: string orderClosed: type: boolean orderClosedAt: format: date-time type: string orderConfirmed: type: boolean orderDisplayFinancialStatus: enum: - PENDING - AUTHORIZED - PARTIALLY_PAID - PARTIALLY_REFUNDED - VOIDED - PAID - REFUNDED - EXPIRED - $UNKNOWN type: string orderDisplayFulfillmentStatus: enum: - UNFULFILLED - PARTIALLY_FULFILLED - FULFILLED - RESTOCKED - PENDING_FULFILLMENT - OPEN - IN_PROGRESS - ON_HOLD - SCHEDULED - REQUEST_DECLINED - $UNKNOWN type: string orderId: format: int64 type: integer orderName: type: string orderNote: type: string orderProcessedAt: format: date-time type: string partialLinesSkipped: enum: - INVENTORY_MANAGEMENT - MANUAL type: string progressAttemptCount: format: int32 type: integer recurringChargeId: format: int64 type: integer retryingNeeded: type: boolean securityChallengeSentStatus: enum: - SENT - UNSENT - FAILED - EMAIL_SETTINGS_DISABLED - CONTRACT_CANCELLED type: string shop: type: string status: enum: - SUCCESS - FAILURE - REQUESTING - PROGRESS - QUEUED - SKIPPED - SOCIAL_CONNECTION_NULL - CONTRACT_CANCELLED - CONTRACT_ENDED - CONTRACT_PAUSED - AUTO_CHARGE_DISABLED - SHOPIFY_EXCEPTION - SKIPPED_DUNNING_MGMT - SKIPPED_INVENTORY_MGMT - IMMEDIATE_TRIGGERED - SECURITY_CHALLENGE - CONTRACT_PAUSED_MAX_CYCLES - REFUNDED - SKIPPED_DEMO_SHOP - SKIPPED_SHOP_INFO_NOT_FOUND - SKIPPED_BILLING_DATE_STALE - SKIPPED_DUNNING_NOT_CONFIGURED - PENDING_CONSOLIDATION type: string transactionFailedEmailSentStatus: enum: - SENT - UNSENT - FAILED - EMAIL_SETTINGS_DISABLED - CUSTOMER_PAYMENT_EMPTY - CONTRACT_CANCELLED type: string transactionFailedSmsSentStatus: enum: - SENT - UNSENT - FAILED - SMS_SETTINGS_DISABLED - CUSTOMER_PAYMENT_EMPTY - CONTRACT_CANCELLED - PHONE_NUMBER_EMPTY type: string transactionRate: format: double type: number upcomingOrderEmailSentStatus: enum: - SENT - UNSENT - FAILED - EMAIL_SETTINGS_DISABLED - CUSTOMER_PAYMENT_EMPTY - CONTRACT_CANCELLED - STOP_FROM_CONTRACT - CONTRACT_PAUSED type: string upcomingOrderSmsSentStatus: enum: - SENT - UNSENT - FAILED - SMS_SETTINGS_DISABLED - CUSTOMER_PAYMENT_EMPTY - CONTRACT_CANCELLED - STOP_FROM_CONTRACT - CONTRACT_PAUSED - PHONE_NUMBER_EMPTY type: string usageChargeStatus: enum: - SUCCESS - FAILED - TO_BE_TRIED type: string variantList: items: $ref: '#/components/schemas/VariantQuantity' type: array required: - retryingNeeded - shop type: object AttributeInfo: properties: key: type: string value: type: string type: object VariantQuantity: properties: image: type: string productId: type: string productTitle: type: string quantity: format: int32 type: integer swapId: format: int64 type: integer title: type: string variantId: format: int64 type: integer variantTitle: type: string type: object ````