> ## 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 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. **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 ## OpenAPI ````yaml /subscription/admin-api-swagger.json get /api/external/v2/upcoming-subscription-contract-one-offs-by-contractId 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/upcoming-subscription-contract-one-offs-by-contractId: get: tags: - Subscription One-Time Products summary: Get one-time products for next upcoming order description: >- 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. **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 operationId: getOneOffForContractNextOrderExternal parameters: - deprecated: true description: API Key (Deprecated - Use X-API-Key header instead) example: sk_live_1234567890abcdef in: query name: api_key required: false schema: type: string - description: >- API Key for authentication. This key identifies your shop and must be included in the X-API-Key header. example: sk_live_1234567890abcdef in: header name: X-API-Key required: true schema: type: string - description: >- The unique identifier of the subscription contract to retrieve upcoming one-time products for example: 98765 in: query name: contractId required: true schema: description: Must be a valid contract ID that belongs to the authenticated shop format: int64 minimum: 1 type: integer responses: '200': content: application/json: examples: Next Order Has Multiple One-Time Products: description: >- The next order (billing attempt 54321) has two one-time products added value: - billingAttemptId: 54321 id: 12345 price: 19.99 quantity: 2 shop: example-store.myshopify.com subscriptionContractId: 98765 variantHandle: premium-coffee-blend-500g variantId: 42549172011164 - billingAttemptId: 54321 id: 12346 price: 8.99 quantity: 1 shop: example-store.myshopify.com subscriptionContractId: 98765 variantHandle: coffee-filters-pack-100 variantId: 42549172011165 Next Order Has No One-Time Products: description: The next order exists but has no one-time products added value: [] No Upcoming Orders: description: >- No queued billing attempts exist - subscription may be paused, cancelled, or all orders processed value: [] Single One-Time Product: description: Customer added a limited edition item to their next delivery value: - billingAttemptId: 54323 id: 12347 price: 24.99 quantity: 1 shop: example-store.myshopify.com subscriptionContractId: 98765 variantHandle: limited-edition-seasonal-blend variantId: 42549172011166 schema: items: $ref: '#/components/schemas/SubscriptionContractOneOffDTO' type: array description: Successfully retrieved one-time products for the next order '400': content: application/json: examples: Invalid Contract ID Format: description: Invalid Contract ID Format value: detail: >- Failed to convert value of type 'java.lang.String' to required type 'java.lang.Long'; For input string: 'invalid' instance: >- /api/external/v2/upcoming-subscription-contract-one-offs-by-contractId status: 400 title: Bad Request type: https://example.com/probs/bad-request Missing Contract ID: description: Missing Contract ID value: detail: >- Required request parameter 'contractId' for method parameter type Long is not present instance: >- /api/external/v2/upcoming-subscription-contract-one-offs-by-contractId status: 400 title: Bad Request type: https://example.com/probs/bad-request schema: $ref: '#/components/schemas/Problem' description: Invalid request parameters '401': content: application/json: example: detail: Full authentication is required to access this resource instance: >- /api/external/v2/upcoming-subscription-contract-one-offs-by-contractId status: 401 title: Unauthorized type: https://example.com/probs/unauthorized schema: $ref: '#/components/schemas/Problem' description: Authentication required - missing or invalid API key '403': content: application/json: example: detail: >- Access is denied - contract does not belong to authenticated shop instance: >- /api/external/v2/upcoming-subscription-contract-one-offs-by-contractId status: 403 title: Forbidden type: https://example.com/probs/forbidden schema: $ref: '#/components/schemas/Problem' description: Forbidden - API key doesn't have permission to access this contract components: schemas: SubscriptionContractOneOffDTO: description: >- Represents a one-time product added to a subscription contract for a specific billing attempt properties: billingAttemptId: description: >- The billing attempt ID this one-time product is associated with. This determines which upcoming order will include this product. example: 54321 format: int64 minimum: 1 type: integer id: description: Unique identifier of the one-time product record example: 12345 format: int64 readOnly: true type: integer price: description: >- The price per unit of this product in the shop's base currency. This may include any applicable discounts. example: 19.99 format: double maximum: 999999.99 minimum: 0 type: number quantity: description: The quantity of this product to include in the order example: 2 format: int32 maximum: 999 minimum: 1 type: integer shop: description: The Shopify store domain that owns this subscription example: example-store.myshopify.com pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]*\.myshopify\.com$ type: string subscriptionContractId: description: The subscription contract ID this one-time product belongs to example: 98765 format: int64 minimum: 1 type: integer variantHandle: description: >- The handle/slug of the product variant for URL-friendly identification example: premium-coffee-blend-500g pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$ type: string variantId: description: The Shopify product variant ID for this one-time product example: 42549172011164 format: int64 minimum: 1 type: integer required: - shop type: object Problem: properties: detail: type: string instance: format: uri type: string parameters: additionalProperties: type: object type: object status: $ref: '#/components/schemas/StatusType' title: type: string type: format: uri type: string type: object StatusType: properties: reasonPhrase: type: string statusCode: format: int32 type: integer type: object ````