> ## 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. # 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 ## OpenAPI ````yaml /memberships/admin-api-swagger.json put /api/external/v2/subscription-contracts-update-order-note/{contractId} openapi: 3.0.1 info: description: >- Comprehensive API documentation for managing memberships, payments, and related operations. These APIs allow you to programmatically manage membership lifecycles, handle payments, configure products, and integrate membership functionality into your applications. title: Admin APIs version: 0.0.1 servers: - url: https://membership-admin.appstle.com security: [] tags: - description: >- APIs for managing Shopify delivery profiles, shipping rates, zones, and free shipping configuration for subscription memberships name: Shipping & Delivery Profiles - description: >- APIs for retrieving historical discount code usage and redemption information for membership contracts name: Customer Discount History - description: >- APIs for managing membership cancellation flow settings including retention offers, survey questions, and cancel confirmation screens name: Cancellation Flow Configuration - description: >- APIs for managing membership billing attempts, recurring orders, payment retries, order history, and order skipping name: Billing & Orders - description: >- APIs for managing one-time product additions to upcoming subscription orders, including adding, retrieving, and removing one-off items name: One-Time Add-Ons - description: >- APIs for managing membership/subscription plan groups, including creating plans, configuring discounts, billing intervals, and assigning products to plans name: Membership Plans - description: >- APIs for managing subscription product bundles, bundle configurations, item grouping, and bundle-specific discount codes name: Product Bundles - description: >- APIs for retrieving custom CSS styles applied to subscription widgets and customer portal for theme customization name: Custom CSS Styling - description: >- APIs for managing customer portal settings including UI customization, text labels, feature toggles, and branding options for the member self-service portal name: Customer Portal Configuration - description: >- APIs for managing membership/subscription contracts including creation, updates, status changes, line items, discounts, and billing operations name: Membership Contracts - description: >- APIs for managing subscription bundle configuration settings including bundle behavior, pricing rules, and display options name: Bundle Settings - description: >- APIs for managing customer payment methods, payment tokens, and payment method retrieval for subscriptions name: Customer Payment Methods - description: >- APIs for retrieving product swap/substitution options allowing members to exchange subscription items based on configured swap rules and variant groups name: Product Swap Rules - description: >- APIs for retrieving product catalog, variants, pricing, and inventory information for subscription memberships. name: Product & Inventory Data - description: >- APIs for managing shop-level membership settings, configuration, and general store information. name: Shop Settings - description: >- APIs for performing bulk/mass operations on multiple membership contracts including status updates, product replacements, and billing date changes. name: Bulk Operations paths: /api/external/v2/subscription-contracts-update-order-note/{contractId}: put: tags: - Membership Contracts summary: Update order note/instructions for subscription contract description: >- 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 operationId: updateOrderNoteV2 parameters: - description: Subscription contract ID example: 12345 in: path name: contractId required: true schema: format: int64 type: integer - description: API Key (Deprecated - Use Header X-API-Key instead) in: query name: api_key required: false schema: type: string - in: header name: X-API-Key required: false schema: type: string - description: Custom order note/instructions to include with subscription orders example: Please leave at back door in: query name: orderNote required: true schema: type: string responses: '200': content: application/json: schema: type: boolean description: >- Order note updated successfully. Returns true. Note will appear on all future recurring orders from this contract. '400': content: '*/*': schema: type: boolean description: >- Bad request - contract doesn't belong to shop, note exceeds 5000 characters, or contract in invalid state '401': content: '*/*': schema: type: boolean description: Authentication required - invalid or missing API key '404': content: '*/*': schema: type: boolean description: >- Subscription contract not found - ID doesn't exist, was deleted, or belongs to different shop ````