# Add one-time product to subscription order

Adds a one-time product (add-on) to a specific subscription order. The product will be included only in the specified billing attempt and will not recur in future orders. This endpoint is idempotent - attempting to add the same product to the same billing attempt will return success without creating duplicates.

Important Behaviors:
- If the specified billingAttemptId is not valid or not QUEUED, the system will automatically add the product to the next upcoming order
- The system prevents duplicate products (same variantId) in the same billing attempt
- Products are automatically removed after the associated order is processed
- Activity logs are created for audit trails

Validation Rules:
- Contract must belong to the authenticated shop
- Contract must not be frozen (minimum cycles restriction)
- At least one QUEUED billing attempt must exist
- Variant must be a valid Shopify product variant

Use Cases:
- Allow customers to add special items to their next delivery
- Enable upselling opportunities in customer portals
- Programmatically add promotional or seasonal items
- Implement "try before you subscribe" features

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

Endpoint: PUT /api/external/v2/subscription-contract-one-offs-by-contractId-and-billing-attempt-id
Version: 0.0.1

## Header parameters:

  - `X-API-Key` (string, required)
    API Key for authentication. This key identifies your shop and must be included in the X-API-Key header.
    Example: "sk_live_1234567890abcdef"

## Query parameters:

  - `contractId` (integer, required)
    The unique identifier of the subscription contract
    Example: 98765

  - `billingAttemptId` (integer, required)
    The billing attempt ID to add the product to. If invalid or not QUEUED, the system will automatically use the next upcoming order.
    Example: 54321

  - `variantId` (integer, required)
    The Shopify product variant ID to add as a one-time purchase
    Example: 42549172011164

  - `variantHandle` (string, required)
    The handle/slug of the product variant for URL-friendly identification
    Example: "premium-coffee-blend-500g"

  - `quantity` (integer)
    The quantity of the product to add. Defaults to 1 if not specified.
    Example: 2

  - `api_key` (string)
    API Key (Deprecated - Use X-API-Key header instead)
    Example: "sk_live_1234567890abcdef"

## Response 200 fields (application/json):

  - `id` (integer)
    Unique identifier of the one-time product record
    Example: 12345

  - `shop` (string, required)
    The Shopify store domain that owns this subscription
    Example: "example-store.myshopify.com"

  - `billingAttemptId` (integer)
    The billing attempt ID this one-time product is associated with. This determines which upcoming order will include this product.
    Example: 54321

  - `subscriptionContractId` (integer)
    The subscription contract ID this one-time product belongs to
    Example: 98765

  - `variantId` (integer)
    The Shopify product variant ID for this one-time product
    Example: 42549172011164

  - `variantHandle` (string)
    The handle/slug of the product variant for URL-friendly identification
    Example: "premium-coffee-blend-500g"

  - `quantity` (integer)
    The quantity of this product to include in the order
    Example: 2

  - `price` (number)
    The price per unit of this product in the shop's base currency. This may include any applicable discounts.
    Example: 19.99

## Response 401 fields (application/json):

  - `instance` (string)

  - `type` (string)

  - `parameters` (object)

  - `status` (object)

  - `status.statusCode` (integer)

  - `status.reasonPhrase` (string)

  - `detail` (string)

  - `title` (string)

## Response 403 fields (application/json):

  - `instance` (string)

  - `type` (string)

  - `parameters` (object)

  - `status` (object)

  - `status.statusCode` (integer)

  - `status.reasonPhrase` (string)

  - `detail` (string)

  - `title` (string)


## Response 400 fields