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.

Full behavior, validation rules, and side effects

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

GET /subscriptions/cp/api/subscription-billing-attempts/top-orders

Get upcoming orders (top orders)

cURL

curl --request GET \
  --url https://www.myshop.com/apps/subscriptions/cp/api/subscription-billing-attempts/top-orders

200

[
  {
    "shop": "<string>",
    "retryingNeeded": true,
    "id": 123,
    "billingAttemptId": "<string>",
    "billingDate": "2023-11-07T05:31:56Z",
    "contractId": 123,
    "attemptCount": 123,
    "attemptTime": "2023-11-07T05:31:56Z",
    "graphOrderId": "<string>",
    "orderId": 123,
    "orderAmount": 123,
    "orderName": "<string>",
    "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>",
        "variantTitle": "<string>",
        "swapId": 123
      }
    ],
    "orderAmountUSD": 123,
    "orderCancelledAt": "2023-11-07T05:31:56Z",
    "orderClosed": true,
    "orderClosedAt": "2023-11-07T05:31:56Z",
    "orderConfirmed": true,
    "orderProcessedAt": "2023-11-07T05:31:56Z",
    "lastShippingUpdatedAt": "2023-11-07T05:31:56Z",
    "inventorySkippedAttemptCount": 123,
    "inventorySkippedRetryingNeeded": true,
    "orderAttributes": [
      {
        "key": "<string>",
        "value": "<string>"
      }
    ],
    "orderAmountShopCurrency": 123,
    "orderAmountContractCurrency": 123
  }
]

Query Parameters

contractId · integer<int64>

Response

200

application/json

Successfully retrieved upcoming orders

shop · string · required

retryingNeeded · boolean · required

id · integer<int64>

billingAttemptId · string

status · enum<string>

Available options: 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

billingDate · string<date-time>

contractId · integer<int64>

attemptCount · integer<int32>

attemptTime · string<date-time>

graphOrderId · string

orderId · integer<int64>

orderAmount · number<double>

orderName · string

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

variantList · object[]

Show child attributes

securityChallengeSentStatus · enum<string>

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

orderAmountUSD · number<double>

orderCancelReason · enum<string>

Available options: CUSTOMER, DECLINED, FRAUD, INVENTORY, STAFF, OTHER, $UNKNOWN

orderCancelledAt · string<date-time>

orderClosed · boolean

orderClosedAt · string<date-time>

orderConfirmed · boolean

orderDisplayFinancialStatus · enum<string>

Available options: PENDING, AUTHORIZED, PARTIALLY_PAID, PARTIALLY_REFUNDED, VOIDED, PAID, REFUNDED, EXPIRED, $UNKNOWN

orderDisplayFulfillmentStatus · enum<string>

Available options: UNFULFILLED, PARTIALLY_FULFILLED, FULFILLED, RESTOCKED, PENDING_FULFILLMENT, OPEN, IN_PROGRESS, ON_HOLD, SCHEDULED, REQUEST_DECLINED, $UNKNOWN

orderProcessedAt · string<date-time>

lastShippingUpdatedAt · string<date-time>

inventorySkippedAttemptCount · integer<int32>

inventorySkippedRetryingNeeded · boolean

orderAttributes · object[]

Show child attributes

partialLinesSkipped · enum<string>

Available options: INVENTORY_MANAGEMENT, MANUAL

orderAmountShopCurrency · number<double>

orderAmountContractCurrency · number<double>