Membership Contracts

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:

Accepts subscription contract ID and new order note text
Stores note in subscription contract record
Every time a new order is created (monthly, weekly, etc.), note is automatically added
Previous contract note is replaced (not appended)
Empty string clears the existing note
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:

Display Character Counter: Show “450 / 5000 characters” in UI
Preview Formatting: Show how line breaks will appear
Confirm Permanent Changes: Warn user “This note will appear on ALL future orders”
Sanitize Input: Strip HTML tags, prevent injection attacks
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

PUT

api

external

subscription-contracts-update-order-note

{contractId}

Update order note/instructions for subscription contract

curl --request PUT \
  --url https://membership-admin.appstle.com/api/external/v2/subscription-contracts-update-order-note/{contractId}

const options = {method: 'PUT'};

fetch('https://membership-admin.appstle.com/api/external/v2/subscription-contracts-update-order-note/{contractId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const url = 'https://membership-admin.appstle.com/api/external/v2/subscription-contracts-update-order-note/{contractId}';
const options = {method: 'PUT'};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://membership-admin.appstle.com/api/external/v2/subscription-contracts-update-order-note/{contractId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://membership-admin.appstle.com/api/external/v2/subscription-contracts-update-order-note/{contractId}"

	req, _ := http.NewRequest("PUT", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://membership-admin.appstle.com/api/external/v2/subscription-contracts-update-order-note/{contractId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)

response = http.request(request)
puts response.read_body

true

true

true

true

Headers

X-API-Key

string

Path Parameters

contractId

integer<int64>

required

Subscription contract ID

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

Response

Order note updated successfully. Returns true. Note will appear on all future recurring orders from this contract.

The response is of type boolean.

Update order note/instructions for subscription contract

curl --request PUT \
  --url https://membership-admin.appstle.com/api/external/v2/subscription-contracts-update-order-note/{contractId}

const options = {method: 'PUT'};

fetch('https://membership-admin.appstle.com/api/external/v2/subscription-contracts-update-order-note/{contractId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const url = 'https://membership-admin.appstle.com/api/external/v2/subscription-contracts-update-order-note/{contractId}';
const options = {method: 'PUT'};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://membership-admin.appstle.com/api/external/v2/subscription-contracts-update-order-note/{contractId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://membership-admin.appstle.com/api/external/v2/subscription-contracts-update-order-note/{contractId}"

	req, _ := http.NewRequest("PUT", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://membership-admin.appstle.com/api/external/v2/subscription-contracts-update-order-note/{contractId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)

response = http.request(request)
puts response.read_body

true

true

true

true

Get Started

Guides

Partner Integration

Webhooks

Admin API

Customer Portal API

Update order note/instructions for subscription contract

Headers

Path Parameters

Query Parameters

Response