# Update order note/instructions for subscription contract

Updates the persistent order note attached to a subscription contract. This note is automatically included with EVERY future recurring order generated from this subscription, appearing in Shopify admin order details and printable packing slips.

IMPORTANT: Recurring vs One-Time Notes
- This Endpoint (Contract Note): Applies to ALL FUTURE ORDERS permanently
- Billing Attempt Note (/subscription-billing-attempts-update-order-note): Applies to ONE SPECIFIC ORDER only
- Combined Behavior: If both notes exist, they are concatenated in the Shopify order

How It Works:
1. Accepts subscription contract ID and new order note text
2. Stores note in subscription contract record
3. Every time a new order is created (monthly, weekly, etc.), note is automatically added
4. Previous contract note is replaced (not appended)
5. Empty string clears the existing note
6. Does NOT affect past orders already created

Character Limits & Validation:
- Maximum Length: 5000 characters (Shopify order note limit)
- Encoding: UTF-8 supported (emojis, international characters allowed)
- HTML: Plain text only - HTML tags display as text
- Line Breaks: Use \n for line breaks (preserved in Shopify)
- Special Characters: Automatically escaped for safety

Common Use Cases:

1. Permanent Delivery Instructions

Example: "Always leave package at back door. Do not ring doorbell (baby sleeping)."
Use Case: Customer wants same delivery instructions for all future orders
Applies To: Every monthly shipment permanently


2. Gift Subscription Messages

Example: "This is a gift subscription for Mom. Happy Birthday! Love, Sarah"
Use Case: Gift subscription with recurring message
Applies To: All orders until subscription ends or note is changed


3. Special Handling Requirements

Example: "FRAGILE - Glass bottles. Handle with care. Keep upright during shipping."
Use Case: Delicate products requiring special warehouse handling
Applies To: Every fulfillment automatically


4. Customer Preferences

Example: "Customer is allergic to peanuts. NO peanut products. Double-check packaging."
Use Case: Critical dietary restrictions or preferences
Applies To: All future orders for safety compliance


5. Internal Merchant Notes

Example: "VIP customer - priority processing. Include bonus samples."
Use Case: Internal fulfillment team instructions
Applies To: All shipments to provide consistent VIP treatment


6. Clearing Unwanted Notes

Example: orderNote="" (empty string)
Use Case: Customer moved, no longer needs "Leave at neighbor" note
Result: Future orders have no contract note (one-time notes still possible)


Where Note Appears:
- Shopify Admin: Order details page under "Notes"
- Packing Slips: Printed on warehouse packing slips (if enabled)
- Order Confirmation Emails: May appear in customer emails (theme-dependent)
- Fulfillment Apps: Visible to third-party logistics providers
- Order APIs: Accessible via Shopify Order REST/GraphQL APIs

When to Use Contract Note vs Billing Attempt Note:

| Scenario | Use Contract Note | Use Billing Attempt Note |
|----------|-------------------|-------------------------|
| Permanent delivery instructions | ✅ | ❌ |
| One-time special request | ❌ | ✅ |
| Gift message for all shipments | ✅ | ❌ |
| "Skip broccoli this week" | ❌ | ✅ |
| Allergy warnings | ✅ | ❌ |
| "Deliver to neighbor (vacation week)" | ❌ | ✅ |
| VIP customer priority | ✅ | ❌ |

Error Handling:

400 - Bad Request:
- Order note exceeds 5000 character limit
- Contract ID doesn't belong to authenticated shop
- Contract is in invalid state

404 - Contract Not Found:
- Subscription contract ID doesn't exist
- Contract was deleted
- Wrong shop (contract belongs to different store)

Integration Best Practices:
1. Display Character Counter: Show "450 / 5000 characters" in UI
2. Preview Formatting: Show how line breaks will appear
3. Confirm Permanent Changes: Warn user "This note will appear on ALL future orders"
4. Sanitize Input: Strip HTML tags, prevent injection attacks
5. Show Current Note: Pre-fill form with existing note before update

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

Endpoint: PUT /api/external/v2/subscription-contracts-update-order-note/{contractId}
Version: 0.0.1

## Path parameters:

  - `contractId` (integer, required)
    Subscription contract ID
    Example: 12345

## Query parameters:

  - `api_key` (string)
    API Key (Deprecated - Use Header X-API-Key instead)

  - `orderNote` (string, required)
    Custom order note/instructions to include with subscription orders
    Example: "Please leave at back door"

## Header parameters:

  - `X-API-Key` (string)