Skip to content
External APIs
/
/
Update order note for sub...

External APIs (0.0.1)

Comprehensive API documentation for managing subscriptions, payments, and related operations. These APIs allow you to programmatically manage subscription lifecycles, handle payments, configure products, and integrate subscription functionality into your applications.

Download OpenAPI description
external-api-swagger.json
external-api-swagger.yaml
Languages
Servers
https://subscription-admin.appstle.com

Subscription Management

Core APIs for managing the complete subscription lifecycle including creation, updates, pausing, resuming, and cancellation of subscriptions.

Operations

Update subscription delivery address and method

Request

Updates the shipping address or delivery method for a subscription contract. Supports standard shipping, local delivery, and pickup options with comprehensive address validation.

Delivery Method Types:

  • SHIPPING: Standard shipping to customer address (default)
  • LOCAL: Local delivery within specified zip codes
  • PICK_UP: Customer pickup at designated location

Key Features:

  • Zip code restrictions for customer portal access
  • Optional ShipperHQ address validation
  • Automatic phone number handling for local delivery
  • Email notifications to customers
  • Shipping price recalculation
  • Activity log tracking with old/new addresses

Zip Code Validation (Customer Portal Only): When called from customer portal:

  • Standard shipping: Validates against 'allowToSpecificZipCode' setting
  • Local delivery: Validates against 'allowToSpecificZipCodeForLocalDelivery' setting
  • External API calls bypass zip code restrictions

Address Validation:

  • If ShipperHQ is configured, addresses are validated for deliverability
  • Invalid addresses will return appropriate error messages
  • Helps prevent failed deliveries and shipping issues

Special Handling:

  • Local delivery addresses missing phone numbers are auto-populated
  • Uses customer's phone if available, otherwise defaults to placeholder
  • Handles missing address components gracefully

Post-Update Actions:

  • Sends 'SHIPPING_ADDRESS_UPDATED' email to customer
  • Creates activity log with address change details
  • Triggers asynchronous shipping price recalculation
  • May remove invalid discount codes automatically

Important Notes:

  • Province codes should use ISO 3166-2 format (e.g., 'NY' for New York)
  • Country codes should use ISO 3166-1 alpha-2 format (e.g., 'US')
  • Phone numbers should include country code for international addresses
  • Pickup locations must be pre-configured in Shopify

Authentication: Requires valid X-API-Key header

Query
contractIdinteger(int64)>= 1required

Subscription contract ID to update. Provide the numeric ID without the gid:// prefix

Example: contractId=123456789
api_keystringDeprecated

API Key (Deprecated - Use X-API-Key header instead)

Headers
X-API-Keystringrequired

API Key for authentication

Example: sk_live_1234567890abcdef
Bodyapplication/jsonrequired

New shipping address and delivery method details

address1string
address2string
citystring
firstNamestring
lastNamestring
phonestring
provincestring
zipstring
countrystring
countryCodestring
provinceCodestring
companystring
locationIdstring
methodTypestring
curl -i -X PUT \
  'https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-shipping-address?contractId=123456789&api_key=string' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: sk_live_1234567890abcdef' \
  -d '{
    "methodType": "SHIPPING",
    "firstName": "John",
    "lastName": "Doe",
    "company": "Acme Corp",
    "address1": "456 New Street",
    "address2": "Suite 200",
    "city": "Los Angeles",
    "provinceCode": "CA",
    "countryCode": "US",
    "zip": "90001",
    "phone": "+12135551234"
  }'

Responses

Shipping address successfully updated

Bodyapplication/json
get__typenamestring
idstring
createdAtobject
updatedAtobject
nextBillingDateobject
statusstring
Enum"ACTIVE""PAUSED""CANCELLED""EXPIRED""FAILED""$UNKNOWN"
deliveryPriceobject(DeliveryPrice)
lastPaymentStatusstring
Enum"SUCCEEDED""FAILED""$UNKNOWN"
billingPolicyobject(BillingPolicy)
deliveryPolicyobject(DeliveryPolicy)
linesobject(Lines)
customerPaymentMethodobject(CustomerPaymentMethod)
deliveryMethodobject(DeliveryMethod)
originOrderobject(OriginOrder)
customerobject(Customer)
discountsobject(Discounts)
notestring
customAttributesArray of objects(CustomAttribute1)
billingAttemptsobject(BillingAttempts)
Response
application/json
{
  "id": "gid://shopify/SubscriptionContract/123456789",
  "status": "ACTIVE",
  "nextBillingDate": "2024-03-01T00:00:00Z",
  "customer": {
    "id": "gid://shopify/Customer/987654321",
    "email": "customer@example.com"
  },
  "deliveryMethod": {
    "__typename": "SubscriptionDeliveryMethodShipping",
    "address": { … }
  },
  "deliveryPrice": {
    "amount": "7.99",
    "currencyCode": "USD"
  }
}

Update order note for subscription

Request

Updates the order note that will be added to all future orders generated by this subscription. Order notes help merchants track special instructions, customer preferences, or internal information about the subscription.

Key Features:

  • Note is automatically added to all future recurring orders
  • Visible in both merchant portal and customer portal
  • Appears in Shopify order details for easy reference
  • Changes apply to future orders only (existing orders unchanged) Common Use Cases:
  • Customer preferences: "No nuts - severe allergy"
  • Delivery instructions: "Leave package at side door"
  • Gift messages: "Happy Birthday from Mom!"
  • Internal notes: "VIP customer - priority handling"
  • Processing instructions: "Include sample with each order"

Important Notes:

  • Empty string clears the existing note
  • No character limit imposed by API (check Shopify limits)
  • HTML is not rendered - stored as plain text
  • Updates are logged in activity history
  • Note persists until explicitly changed

Order Generation: When Appstle creates recurring orders:

  1. Retrieves current order note from subscription
  2. Adds note to new Shopify order
  3. Note appears in order details immediately
  4. Merchants can still edit individual order notes

Authentication: Requires valid X-API-Key header

Path
contractIdinteger(int64)>= 1required

Subscription contract ID to update

Example: 123456789
Query
orderNotestringrequired

Note text to be added to all future orders. Can include special instructions, preferences, or internal notes. Pass empty string to clear existing note. HTML tags are not rendered - stored as plain text.

Examples:

Delivery Instruction

orderNote=Ring doorbell twice, leave at back door

Internal Note

orderNote=VIP Customer - Include free sample

Gift Message

orderNote=Happy Anniversary! Love, Sarah

Allergy Note

orderNote=No peanuts - severe allergy

Clear Note

api_keystringDeprecated

API Key (Deprecated - Use X-API-Key header instead)

Headers
X-API-Keystringrequired

API Key for authentication

Example: sk_live_1234567890abcdef
curl -i -X PUT \
  'https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-order-note/123456789?orderNote=string&api_key=string' \
  -H 'X-API-Key: sk_live_1234567890abcdef'

Responses

Order note successfully updated

Headers
X-Application-Contextstring

Application context with success message

Example: "appname:Subscription Updated:"
Bodyapplication/json
boolean
Response
application/json
true

Update minimum cycles for a subscription contract

Request

Updates the minimum number of billing cycles (orders) that a customer must complete before they can cancel their subscription. This creates a commitment period that helps with customer retention and business predictability.

What are Minimum Cycles? Minimum cycles represent a commitment period where:

  • Customers must complete a specified number of orders
  • Cancellation is blocked until the minimum is met
  • Often tied to special pricing or promotional offers
  • Counted from the subscription start date

Key Features:

  • Updates commitment period for existing subscriptions
  • Can increase or decrease minimum cycles
  • Setting to null removes the minimum commitment
  • Preserves all other subscription settings
  • Automatically handles invalid discount codes
  • Updates future billing queue after change

Common Use Cases:

  • Promotional Offers: '3-month minimum for 50% off'
  • Hardware Subsidies: '12-month commitment with free device'
  • Loyalty Programs: Reduce minimum after customer proves loyalty
  • Seasonal Campaigns: Temporary commitment requirements
  • Contract Adjustments: Customer service exceptions

Impact on Customers:

  • Cannot cancel via portal until minimum cycles complete
  • Pause/resume typically still allowed (check settings)
  • Shows commitment status in customer portal
  • No automatic notification sent (consider sending separately)

Cycle Counting:

  • Only successful billing attempts count toward minimum
  • Failed payments don't increment the cycle count
  • Skipped orders (if allowed) don't count
  • Current cycle = successful past orders + 1

Interaction with Max Cycles:

  • Min cycles must be less than or equal to max cycles
  • If max cycles exist, subscription auto-cancels after maximum
  • Common pattern: 3 min cycles, 12 max cycles

Best Practices:

  • Clearly communicate commitment terms upfront
  • Consider grandfathering existing customers
  • Use reasonable minimums (typically 3-12 cycles)
  • Document reason for changes in activity logs
  • Send customer notification for transparency

Important Notes:

  • Changes apply immediately to cancellation logic
  • Doesn't affect past or in-progress orders
  • Customer portal respects this setting automatically
  • Activity log tracks old and new values
  • Consider legal requirements in your jurisdiction

Authentication: Requires valid X-API-Key header

Query
contractIdinteger(int64)required

Contract ID

api_keystring

API Key (Deprecated - Use Header X-API-Key instead)

minCyclesinteger or null[ 1 .. 9999 ]

Minimum Number of Orders. The minimum number of billing cycles a customer must complete before being allowed to cancel. Set to null to remove the minimum commitment. Common values:

  • 3: Three-month commitment
  • 6: Six-month commitment
  • 12: Annual commitment
  • null: No commitment
Example: minCycles=6
Headers
X-API-Keystring
curl -i -X PUT \
  'https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-min-cycles?contractId=0&api_key=string&minCycles=6' \
  -H 'X-API-Key: string'

Responses

Minimum cycles updated successfully

Bodyapplication/json
get__typenamestring
idstring
createdAtobject
updatedAtobject
nextBillingDateobject
statusstring
Enum"ACTIVE""PAUSED""CANCELLED""EXPIRED""FAILED""$UNKNOWN"
deliveryPriceobject(DeliveryPrice)
lastPaymentStatusstring
Enum"SUCCEEDED""FAILED""$UNKNOWN"
billingPolicyobject(BillingPolicy)
deliveryPolicyobject(DeliveryPolicy)
linesobject(Lines)
customerPaymentMethodobject(CustomerPaymentMethod)
deliveryMethodobject(DeliveryMethod)
originOrderobject(OriginOrder)
customerobject(Customer)
discountsobject(Discounts)
notestring
customAttributesArray of objects(CustomAttribute1)
billingAttemptsobject(BillingAttempts)
Response
application/json
{
  "id": "gid://shopify/SubscriptionContract/123456789",
  "status": "ACTIVE",
  "nextBillingDate": "2024-04-01T00:00:00Z",
  "createdAt": "2024-01-01T00:00:00Z",
  "customer": {
    "id": "gid://shopify/Customer/987654321",
    "email": "customer@example.com",
    "displayName": "John Doe"
  },
  "billingPolicy": {
    "interval": "MONTH",
    "intervalCount": 1,
    "minCycles": 6,
    "maxCycles": null,
    "anchors": [ … ]
  },
  "deliveryPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "customerPaymentMethod": {
    "id": "gid://shopify/CustomerPaymentMethod/123456",
    "instrument": { … }
  },
  "lines": {
    "edges": [ … ]
  }
}

Subscription Payments

APIs for managing subscription payment methods, processing payments, handling payment retries, and updating billing information.

Operations

Subscription Contracts

APIs for managing subscription contracts including delivery schedules, pricing, order notes, billing cycles, and shipping addresses.

Operations

Subscription Products

APIs for managing products within subscriptions including adding, removing, updating quantities, and swapping products.

Operations

Billing & Payments

APIs for handling billing operations, payment processing, and financial transactions related to subscriptions.

Operations

Subscription Discounts

APIs for managing discounts and promotional codes applied to subscriptions.

Operations

Subscription One-Time Products

APIs for managing one-time add-on products that can be purchased alongside recurring subscription items.

Operations

Subscription Plans

APIs for managing subscription plans, pricing tiers, and plan configurations.

Operations

Build-a-Box & Bundles

APIs for managing customizable product boxes and bundles where customers can select multiple items.

Operations

Product Catalog

APIs for managing the product catalog including product information, variants, and inventory.

Operations

Operations & Settings

APIs for managing operational settings, configurations, and administrative functions.

Operations

Customer Portal

APIs powering the customer-facing portal where subscribers can manage their own subscriptions.

Operations

Customers

APIs for managing customer information, profiles, and account details.

Operations