Skip to content
/Membership Contracts

External (0.0.1)

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

Shipping & Delivery Profiles

APIs for managing Shopify delivery profiles, shipping rates, zones, and free shipping configuration for subscription memberships

Operations

Customer Discount History

APIs for retrieving historical discount code usage and redemption information for membership contracts

Operations

Cancellation Flow Configuration

APIs for managing membership cancellation flow settings including retention offers, survey questions, and cancel confirmation screens

Operations

Billing & Orders

APIs for managing membership billing attempts, recurring orders, payment retries, order history, and order skipping

Operations

One-Time Add-Ons

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

Operations

Membership Plans

APIs for managing membership/subscription plan groups, including creating plans, configuring discounts, billing intervals, and assigning products to plans

Operations

Product Bundles

APIs for managing subscription product bundles, bundle configurations, item grouping, and bundle-specific discount codes

Operations

Custom CSS Styling

APIs for retrieving custom CSS styles applied to subscription widgets and customer portal for theme customization

Operations

Customer Portal Configuration

APIs for managing customer portal settings including UI customization, text labels, feature toggles, and branding options for the member self-service portal

Operations

Membership Contracts

APIs for managing membership/subscription contracts including creation, updates, status changes, line items, discounts, and billing operations

Operations

Update subscription contract status (pause/resume/activate)

Request

Changes the status of a subscription contract. This allows pausing, resuming, or activating subscriptions to control billing and delivery.

Key Features:

  • Pause Subscriptions: Temporarily stop billing and deliveries
  • Resume Subscriptions: Reactivate paused subscriptions
  • Activate Subscriptions: Start inactive subscriptions
  • Activity Logging: All status changes are logged for audit trail
  • Customer Restrictions: Includes minimum cycle checks when called from customer portal

Status Values:

  • ACTIVE: Subscription is active and billing/delivering normally
  • PAUSED: Subscription is temporarily paused (no billing, no deliveries)
  • CANCELLED: Subscription is cancelled (use DELETE endpoint instead)

Pause vs. Cancel:

  • Pause: Temporary hold, customer can resume anytime
  • Cancel: Permanent termination, requires creating new subscription to restart

Common Use Cases:

  • Vacation Hold: Customer going on vacation, pause deliveries temporarily
  • Financial Pause: Customer needs temporary break from payments
  • Product Surplus: Customer has too much product, pause until they use it
  • Seasonal Pause: Pause subscriptions during off-season (e.g., lawn care in winter)
  • Resume After Pause: Customer ready to restart after temporary hold
  • Reactivate Failed: Reactivate subscription after payment method updated

Pause Behavior:

  • Billing Paused: No charges while paused
  • Deliveries Paused: No orders created while paused
  • Next Billing Date: Preserved or recalculated on resume (merchant setting)
  • Unlimited Duration: Pauses can be indefinite unless merchant sets limits

Resume Behavior:

  • Immediate Reactivation: Subscription becomes active immediately
  • Next Billing Date: Calculated based on pause duration settings
  • Deliveries Resume: Next delivery scheduled according to interval

Customer Portal Restrictions: When called from customer portal (vs. merchant API):

  • Minimum Cycles: Cannot pause/cancel until minimum billing cycles met
  • Freeze Period: Updates may be frozen until minimum requirements satisfied
  • Retention Rules: Special retention discounts may be offered on cancellation

Important Notes:

  • Customer Communication: Consider sending email notifications on status changes
  • Billing Cycles Not Lost: Paused cycles don't count toward minimums
  • No Pro-rata: No refunds or credits when pausing mid-cycle

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

Query
contractIdinteger(int64)required

Subscription contract ID

Example: contractId=12345
statusstringrequired

New subscription status

Enum"ACTIVE""PAUSED"
Example: status=PAUSED
api_keystring

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

Headers
X-API-Keystring
curl -i -X PUT \
  'https://membership-admin.appstle.com/api/external/v2/subscription-contracts-update-status?contractId=12345&status=PAUSED&api_key=string' \
  -H 'X-API-Key: string'

Responses

Subscription status successfully updated (no content returned)

Response
No content

Update shipping address for subscription contract

Request

Changes the delivery shipping address for a subscription contract. This allows customers to update where their subscription orders are delivered.

Key Features:

  • Full Address Update: Change complete shipping address in one call
  • Address Validation: System validates address format and country codes
  • Immediate Effect: New address applies to the next delivery
  • Activity Logging: All address changes are logged for audit trail
  • International Support: Supports addresses in all countries

Required Address Fields:

  • firstName: Recipient's first name
  • lastName: Recipient's last name
  • address1: Street address line 1
  • city: City name
  • countryCode: ISO 3166-1 alpha-2 country code (e.g., US, CA, GB)
  • zip: Postal/ZIP code

Optional Address Fields:

  • address2: Apartment, suite, unit number
  • company: Company name (for business addresses)
  • phone: Contact phone number
  • provinceCode: State/province code (e.g., CA, NY, ON)

Common Use Cases:

  • Customer Moved: Update address after relocation
  • Temporary Address: Ship to vacation home or temporary location
  • Gift Recipient: Change recipient for gift subscriptions
  • Correct Typos: Fix address errors from initial signup
  • Business to Home: Switch between business and residential addresses
  • Seasonal Address: Update for snowbird/seasonal residents

Country and Province Codes:

  • countryCode: Use ISO 3166-1 alpha-2 codes
    • Examples: US (United States), CA (Canada), GB (United Kingdom), AU (Australia)
  • provinceCode: Use ISO 3166-2 subdivision codes
    • US Examples: CA (California), NY (New York), TX (Texas)
    • Canada Examples: ON (Ontario), BC (British Columbia), QC (Quebec)

Address Validation:

  • Format Validation: System checks required fields are present
  • Country Validation: Verifies country code is valid
  • Province Validation: Checks province code matches country
  • Postal Code: Validates postal code format for country

Important Notes:

  • Shipping Rate Recalculation: New address may have different shipping costs
  • Delivery Method: System automatically selects appropriate delivery method
  • Next Order Only: Only affects future orders, not orders already placed
  • Address Book: Consider updating customer's default address separately
  • PO Boxes: Some delivery methods may not support PO Box addresses

Shipping Cost Impact:

  • Changing address may change shipping costs for future deliveries
  • International addresses typically have higher shipping costs
  • Remote/rural areas may have additional delivery fees
  • Consider notifying customer of cost changes

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

Query
contractIdinteger(int64)required

Subscription contract ID

Example: contractId=12345
api_keystring

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

Headers
X-API-Keystring
Bodyapplication/jsonrequired

New shipping address details

address1string
address2string
citystring
firstNamestring
lastNamestring
phonestring
provincestring
zipstring
countrystring
countryCodestring
provinceCodestring
companystring
curl -i -X PUT \
  'https://membership-admin.appstle.com/api/external/v2/subscription-contracts-update-shipping-address?contractId=12345&api_key=string' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: string' \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "address1": "123 Main Street",
    "address2": "Apt 4B",
    "city": "San Francisco",
    "provinceCode": "CA",
    "countryCode": "US",
    "zip": "94102",
    "phone": "+1-415-555-0123",
    "company": "Acme Corp"
  }'

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
{
  "get__typename": "string",
  "id": "string",
  "createdAt": {},
  "updatedAt": {},
  "nextBillingDate": {},
  "status": "ACTIVE",
  "deliveryPrice": {
    "get__typename": "string",
    "amount": {},
    "currencyCode": "USD"
  },
  "lastPaymentStatus": "SUCCEEDED",
  "billingPolicy": {
    "get__typename": "string",
    "interval": "DAY",
    "intervalCount": 0,
    "anchors": [ … ],
    "maxCycles": 0,
    "minCycles": 0
  },
  "deliveryPolicy": {
    "get__typename": "string",
    "interval": "DAY",
    "intervalCount": 0,
    "anchors": [ … ]
  },
  "lines": {
    "get__typename": "string",
    "nodes": [ … ],
    "pageInfo": { … }
  },
  "customerPaymentMethod": {
    "get__typename": "string",
    "id": "string",
    "instrument": { … },
    "revokedAt": {},
    "revokedReason": "AUTHORIZE_NET_GATEWAY_NOT_ENABLED"
  },
  "deliveryMethod": {
    "get__typename": "string",
    "id": "string",
    "methodType": "SHIPPING",
    "serviceCode": "string",
    "minDeliveryDateTime": {},
    "maxDeliveryDateTime": {},
    "additionalInformation": { … },
    "brandedPromise": { … }
  },
  "originOrder": {
    "get__typename": "string",
    "id": "string",
    "name": "string",
    "fulfillmentOrders": { … }
  },
  "customer": {
    "get__typename": "string",
    "id": "string",
    "email": "string",
    "displayName": "string",
    "firstName": "string",
    "lastName": "string",
    "phone": "string"
  },
  "discounts": {
    "get__typename": "string",
    "nodes": [ … ],
    "pageInfo": { … }
  },
  "note": "string",
  "customAttributes": [
    { … }
  ],
  "billingAttempts": {
    "get__typename": "string",
    "nodes": [ … ]
  }
}

Update subscription payment method

Request

Updates the payment method for a subscription contract by refreshing payment instrument from Shopify customer. This endpoint syncs the subscription's payment method with the customer's default payment method in Shopify.

Payment Method Update Process:

  • Fetch Latest Payment: Retrieves customer's current default payment method from Shopify
  • Update Contract: Associates new payment method with subscription contract
  • Validate Payment: Ensures payment method is valid and active
  • Sync Changes: Updates payment instrument in subscription billing system

Key Features:

  • Automatic Sync: Pulls latest payment method from Shopify customer record
  • Payment Validation: Verifies new payment method is usable for billing
  • Contract Update: Updates Shopify subscription contract with new payment
  • Failed Billing Recovery: Useful for updating payment after billing failures

Use Cases:

  • Customer updates credit card and wants to apply to existing subscription
  • Recover from failed billing by allowing payment method update
  • Sync payment methods in customer portal workflows
  • Update expired or invalid payment methods
  • Switch between multiple saved payment methods
  • Integration with custom payment update flows

Important Notes:

  • Customer must have a default payment method in Shopify
  • Payment method must be valid and not expired
  • Updates are reflected immediately for future billing
  • Does not retry failed billing attempts automatically

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

Query
contractIdinteger(int64)required

Subscription contract ID to update payment method for

Example: contractId=123456789
api_keystring

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

Headers
X-API-Keystring
curl -i -X PUT \
  'https://membership-admin.appstle.com/api/external/v2/subscription-contracts-update-payment-method?contractId=123456789&api_key=string' \
  -H 'X-API-Key: string'

Responses

Payment method successfully updated for subscription

Bundle Settings

APIs for managing subscription bundle configuration settings including bundle behavior, pricing rules, and display options

Operations

Customer Payment Methods

APIs for managing customer payment methods, payment tokens, and payment method retrieval for subscriptions

Operations

Product Swap Rules

APIs for retrieving product swap/substitution options allowing members to exchange subscription items based on configured swap rules and variant groups

Operations

Subscription Contract Management

Operations

Subscription Billing

Operations

Billing Attempts

Operations