# One-Time Add-Ons

APIs for managing one-time product additions to upcoming subscription orders, including adding, retrieving, and removing one-off items

## Add one-time product to upcoming order

 - [PUT /api/external/v2/subscription-contract-one-offs-by-contractId-and-billing-attempt-id](https://developers.membership.appstle.com/admin-api-swagger/one-time-add-ons/saveoneoffbyv2.md): Adds a one-time product (one-off) to a specific upcoming billing attempt for a membership contract. The product will be included only in the specified order and will not become part of the recurring subscription.

Key Features:
- One-Time Addition: Product added to single order only
- Billing Cycle Targeting: Specify exact order to add item to
- No Subscription Impact: Doesn't change recurring items
- Instant Upsell: Add products between regular billing cycles
- Customer Flexibility: Allow members to add extras to next order
- Activity Logging: Tracks who added the item (merchant vs API)

Required Parameters:
- Contract ID: Target subscription contract
- Billing Attempt ID: Specific upcoming order to add item to
- Variant ID: Shopify product variant to add
- Variant Handle: Product handle for identification

How It Works:
1. Validates contract exists and belongs to shop
2. Checks if contract is not frozen (minimum cycles)
3. Verifies billing attempt is upcoming (not already processed)
4. Adds variant to the specified billing attempt
5. Returns updated list of all one-offs for the contract
6. Logs activity for audit trail

Use Cases:
- Customer wants to add a bonus product to next delivery
- Merchant offers limited-time add-on to existing members
- Trial/sample products added to specific orders
- Holiday specials or seasonal items
- Promotional gifts or rewards
- One-time upsells in customer portal

Business Rules:
- Item added only to specified billing attempt
- Cannot add to past or completed orders
- Contract must not be frozen/minimum cycle locked
- Duplicate items increment quantity

Authentication: Requires API key authentication via X-API-Key header or api_key parameter

## Remove one-time product from upcoming order

 - [DELETE /api/external/v2/subscription-contract-one-offs-by-contractId-and-billing-attempt-id](https://developers.membership.appstle.com/admin-api-swagger/one-time-add-ons/deleteoneoff.md): Removes a previously added one-time product (one-off) from a specific upcoming billing attempt. This allows customers or merchants to cancel add-on items before the order is processed.

Key Features:
- Flexible Cancellation: Remove add-ons before order processes
- Targeted Removal: Remove specific variant from specific order
- No Subscription Impact: Doesn't affect recurring items
- Customer Control: Let members manage their add-ons
- Activity Logging: Tracks removal for audit trail

Required Parameters:
- Contract ID: Target subscription contract
- Billing Attempt ID: Order to remove item from
- Variant ID: Product variant to remove

How It Works:
1. Validates contract exists and belongs to shop
2. Finds one-off matching contract, billing attempt, and variant
3. Deletes the one-off record
4. Returns updated list of remaining one-offs
5. Logs removal activity for audit trail

Use Cases:
- Customer changes mind about add-on product
- Remove out-of-stock items from upcoming orders
- Cancel promotional items no longer available
- Customer wants to reduce order total
- Merchant corrects mistakenly added items
- Manage add-ons in customer portal

Business Rules:
- Can only remove from upcoming (unprocessed) orders
- Must match exact contract, billing attempt, and variant
- Returns remaining one-offs after deletion
- Cannot remove from past/completed orders

Authentication: Requires API key authentication via X-API-Key header or api_key parameter

## Get one-time add-ons for a membership contract

 - [GET /api/external/v2/subscription-contract-one-offs-by-contractId](https://developers.membership.appstle.com/admin-api-swagger/one-time-add-ons/getoneoffsforsubscriptioncontractv2.md): Retrieves all one-time product additions scheduled for upcoming orders of a specific membership contract. One-offs are products added to a single billing cycle without affecting the recurring subscription items.

Key Information Returned:
- One-Off Items: List of products added to upcoming orders
- Product Details: Variant ID, handle, title, price, image
- Billing Association: Which billing attempt the item is added to
- Quantity: Number of units for the one-time add-on
- Status: Active, pending, or fulfilled one-offs
- Created Date: When the one-off was added

One-Off Item Data:
- Contract ID: Parent subscription contract
- Billing Attempt ID: Specific order the item will be added to
- Variant Info: Product variant being added
- Pricing: One-time price for the add-on
- Fulfillment Status: Whether item has been shipped

Use Cases:
- Display scheduled one-time add-ons in customer portal
- Show customers which extra items are in next order
- Sync one-off data with external order management systems
- Generate custom order previews for customers
- Build upsell dashboards showing add-on purchases
- Track one-time product revenue per contract

Authentication: Requires API key authentication via X-API-Key header or api_key parameter