Get one-time products for next upcoming order

Retrieves one-time products that will be included in the next scheduled order for a subscription contract. This endpoint specifically returns products associated with the earliest queued billing attempt, making it ideal for showing customers what additional items will be in their next delivery.

Full behavior, validation rules, and side effects

Key Differences from /subscription-contract-one-offs-by-contractId:

• Returns ONLY products for the next upcoming order (not all future orders)
• Finds the earliest QUEUED billing attempt by date
• Returns empty array if no queued billing attempts exist
• Useful for “Your Next Order” previews in customer portals

Use Cases:

• Display a preview of the next order including one-time add-ons
• Calculate the total cost of the upcoming delivery
• Show customers their next delivery date with associated one-time items
• Allow last-minute modifications before order processing

Business Logic:

1. Searches for billing attempts with status = QUEUED
2. Selects the one with the earliest billing date
3. Returns all one-time products for that specific billing attempt
4. Returns empty array if no queued orders exist (e.g., subscription paused/cancelled)

Authentication: Requires valid X-API-Key header that identifies the shop

GET /api/external/v2/upcoming-subscription-contract-one-offs-by-contractId

Get one-time products for next upcoming order

cURL

curl --request GET \
  --url https://subscription-admin.appstle.com/api/external/v2/upcoming-subscription-contract-one-offs-by-contractId \
  --header 'X-API-Key: <x-api-key>'

200

Next Order Has Multiple One-Time Products

[
  {
    "id": 12345,
    "shop": "example-store.myshopify.com",
    "subscriptionContractId": 98765,
    "billingAttemptId": 54321,
    "variantId": 42549172011164,
    "variantHandle": "premium-coffee-blend-500g",
    "quantity": 2,
    "price": 19.99
  },
  {
    "id": 12346,
    "shop": "example-store.myshopify.com",
    "subscriptionContractId": 98765,
    "billingAttemptId": 54321,
    "variantId": 42549172011165,
    "variantHandle": "coffee-filters-pack-100",
    "quantity": 1,
    "price": 8.99
  }
]

Headers

X-API-Key · string · required

API Key for authentication. This key identifies your shop and must be included in the X-API-Key header.

Query Parameters

api_key · string

API Key (Deprecated - Use X-API-Key header instead)

contractId · integer<int64> · required

The unique identifier of the subscription contract to retrieve upcoming one-time products for Must be a valid contract ID that belongs to the authenticated shop

Required range: x >= 1

Response

200

application/json

Successfully retrieved one-time products for the next order

shop · string · required

The Shopify store domain that owns this subscription

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]*\.myshopify\.com$

Example:

"example-store.myshopify.com"

id · integer<int64> · read-only

Unique identifier of the one-time product record

Example:

12345

billingAttemptId · integer<int64>

The billing attempt ID this one-time product is associated with. This determines which upcoming order will include this product.

Required range: x >= 1

Example:

54321

subscriptionContractId · integer<int64>

The subscription contract ID this one-time product belongs to

Required range: x >= 1

Example:

98765

variantId · integer<int64>

The Shopify product variant ID for this one-time product

Required range: x >= 1

Example:

42549172011164

variantHandle · string

The handle/slug of the product variant for URL-friendly identification

Pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$

Example:

"premium-coffee-blend-500g"

quantity · integer<int32>

The quantity of this product to include in the order

Required range: 1 <= x <= 999

Example:

2

price · number<double>

The price per unit of this product in the shop's base currency. This may include any applicable discounts.

Required range: 0 <= x <= 999999.99

Example:

19.99