Skip to content
🔧 Admin APIs
/
/
Get membership/subscripti...

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

Send customer portal magic link via email

Request

Automatically generates and emails a secure magic link to the customer for accessing their subscription management portal. This is a convenience endpoint that combines token generation and email delivery in a single API call.

Key Features:

  • Automated Delivery: Generates magic link and sends email in one operation
  • Customer Lookup: Finds customer by email address automatically
  • Branded Emails: Uses shop's configured email templates and branding
  • Subscription Validation: Only sends if customer has active subscriptions
  • Time-Limited Links: Email contains token that expires after configured duration

Email Contents: The sent email typically includes:

  • Magic Link Button: One-click access to customer portal
  • Link URL: Full URL with embedded authentication token
  • Expiration Notice: When the link will expire (e.g., "Valid for 24 hours")
  • Shop Branding: Store logo, colors, and custom messaging
  • Help Text: Instructions on how to use the portal

Workflow:

  1. API receives customer email address
  2. System looks up customer in Shopify by email
  3. Validates customer has active subscription contracts
  4. Generates secure JWT authentication token
  5. Constructs magic link URL with token
  6. Sends branded email with magic link to customer
  7. Returns success confirmation to API caller

Email Template Customization: Email appearance and content can be customized via:

  • Shop's email notification settings in admin
  • Custom email templates for magic links
  • Localization settings for customer's language
  • Custom branding (logo, colors, footer)

Common Use Cases:

  • Customer support: send portal access link to customers over phone/chat
  • Automated workflows: trigger magic link emails based on events
  • Forgot password alternative: passwordless portal access
  • Post-purchase flows: send portal access after first order
  • Reactivation campaigns: re-engage paused/cancelled customers
  • Customer onboarding: welcome emails with portal access
  • Subscription reminders: include portal link in reminder emails

Integration Example:

GET /api/external/v2/subscription-contracts-email-magic-link?
  email=customer@example.com&
  api_key=your_api_key

This sends a magic link email to customer@example.com for portal access.

Error Handling:

  • If customer not found, returns 400 Bad Request
  • If customer has no active subscriptions, returns 400
  • If email service fails, returns 500 Internal Server Error
  • Invalid email format returns 400 Bad Request

Email Delivery Notes:

  • Emails are sent asynchronously (may take 1-5 minutes to deliver)
  • Check spam folders if customer doesn't receive email
  • Respect customer's email preferences and unsubscribe status
  • Rate limits may apply to prevent abuse

Security Considerations:

  • Only send to verified customer email addresses
  • Email contains passwordless authentication link
  • Links expire after configured duration (default: 24-72 hours)
  • Sending to wrong email grants that person subscription access
  • Consider email verification before using this endpoint

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

Query
api_keystring

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

emailstringrequired

Customer email address to send magic link to

Example: email=customer@example.com
Headers
X-API-Keystring
curl -i -X GET \
  'https://membership-admin.appstle.com/api/external/v2/subscription-contracts-email-magic-link?api_key=string&email=customer%40example.com' \
  -H 'X-API-Key: string'

Responses

Magic link email sent successfully to customer

Bodytext/plain
string

Get membership/subscription contract list

Request

Retrieves a paginated list of membership/subscription contracts with advanced filtering capabilities. This endpoint provides comprehensive access to all subscription contracts in your store with flexible query options.

Key Information Returned:

  • Contract Details: Contract ID, status, creation date, billing cycle
  • Customer Information: Customer name, email, Shopify customer ID
  • Subscription Items: Products, variants, quantities in subscription
  • Billing Information: Next billing date, billing frequency, pricing
  • Delivery Details: Shipping address, delivery method, next delivery date
  • Plan Information: Membership plan type, selling plan IDs
  • Status Tracking: Active, paused, cancelled, expired states

Filtering Capabilities:

  • Date Ranges: Filter by creation date or next billing date
  • Customer Search: Search by customer name or email
  • Status Filter: Filter by contract status (active, paused, cancelled)
  • Plan Type: Filter by membership plan type
  • Billing Frequency: Filter by billing interval (weekly, monthly, etc.)
  • Product/Variant: Find contracts containing specific products or variants
  • Order Name: Search by Shopify order name/number
  • Selling Plan: Filter by Shopify selling plan IDs
  • Special Filters: Contracts with deleted products or bounced emails

Pagination:

  • Supports standard pagination parameters (page, size, sort)
  • Returns pagination headers for total count and navigation
  • Default page size configurable via request parameters

Use Cases:

  • Export subscription data to external CRM or analytics systems
  • Build custom subscription dashboards and reports
  • Sync membership data with external platforms
  • Identify subscriptions needing attention (bounced emails, deleted products)
  • Generate subscription activity reports by date range
  • Find all subscriptions for a specific product or variant
  • Monitor subscription health and churn metrics

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

Query
api_keystring

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

fromCreatedDatestring(date-time)

Filter contracts created on or after this date

Example: fromCreatedDate=2024-01-01T00:00:00Z
toCreatedDatestring(date-time)

Filter contracts created on or before this date

Example: toCreatedDate=2024-12-31T23:59:59Z
fromNextDatestring(date-time)

Filter contracts with next billing date on or after this date

Example: fromNextDate=2024-01-01T00:00:00Z
toNextDatestring(date-time)

Filter contracts with next billing date on or before this date

Example: toNextDate=2024-12-31T23:59:59Z
subscriptionContractIdstring

Filter by specific subscription/membership contract ID

Example: subscriptionContractId=gid://shopify/SubscriptionContract/12345
customerNamestring

Filter by customer name or email (partial match)

Example: customerName=john@example.com
orderNamestring

Filter by Shopify order name

Example: orderName=#1001
statusstring

Filter by subscription status

Enum"ACTIVE""PAUSED""CANCELLED""FAILED""EXPIRED"
Example: status=ACTIVE
billingPolicyIntervalCountinteger(int32)

Filter by billing frequency count (e.g., 1 for every 1 month)

Example: billingPolicyIntervalCount=1
billingPolicyIntervalstring

Filter by billing frequency interval

Enum"DAY""WEEK""MONTH""YEAR"
Example: billingPolicyInterval=MONTH
planTypestring

Filter by plan type (PAY_AS_YOU_GO or PREPAID)

Enum"PAY_AS_YOU_GO""PREPAID"
Example: planType=PAY_AS_YOU_GO
recordTypestring

Filter by record type (CONTRACT or SELLING_PLAN_GROUP)

Example: recordType=CONTRACT
productIdinteger(int64)

Filter by Shopify product ID

Example: productId=123456789
variantIdinteger(int64)

Filter by Shopify product variant ID

Example: variantId=987654321
sellingPlanIdsstring

Filter by selling plan IDs (comma-separated for multiple)

Example: sellingPlanIds=123,456,789
havingProductsDeletedFromStoreboolean

Include only contracts with products deleted from Shopify store

Default false
emailBouncedOrFailedboolean

Include only contracts where email notifications bounced or failed

Default false
pageableobject(Pageable)required

Pagination parameters (page number and size)

Example: page=0&size=10&sort=id,desc
pageable.​pageinteger(int32)>= 0
pageable.​sizeinteger(int32)>= 1
pageable.​sortArray of strings
Headers
X-API-Keystring
curl -i -X GET \
  'https://membership-admin.appstle.com/api/external/v2/subscription-contract-details?api_key=string&fromCreatedDate=2024-01-01T00%3A00%3A00Z&toCreatedDate=2024-12-31T23%3A59%3A59Z&fromNextDate=2024-01-01T00%3A00%3A00Z&toNextDate=2024-12-31T23%3A59%3A59Z&subscriptionContractId=gid%3A%2F%2Fshopify%2FSubscriptionContract%2F12345&customerName=john%40example.com&orderName=%231001&status=ACTIVE&billingPolicyIntervalCount=1&billingPolicyInterval=MONTH&planType=PAY_AS_YOU_GO&recordType=CONTRACT&productId=123456789&variantId=987654321&sellingPlanIds=123%2C456%2C789&havingProductsDeletedFromStore=false&emailBouncedOrFailed=false&page=0&size=10&sort=id%2Cdesc' \
  -H 'X-API-Key: string'

Responses

Subscription contracts successfully retrieved with pagination headers

Bodyapplication/json
idinteger(int64)
shopstringrequired
graphSubscriptionContractIdstring
subscriptionContractIdinteger(int64)
billingPolicyIntervalstring
billingPolicyIntervalCountinteger(int32)
currencyCodestring
customerIdinteger(int64)
graphCustomerIdstring
deliveryPolicyIntervalstring
deliveryPolicyIntervalCountinteger(int32)
statusstring
graphOrderIdstring
orderIdinteger(int64)
createdAtstring(date-time)
updatedAtstring(date-time)
nextBillingDatestring(date-time)
orderAmountnumber(double)
orderNamestring
customerNamestring
customerEmailstring
subscriptionCreatedEmailSentboolean
endsAtstring(date-time)
startsAtstring(date-time)
subscriptionCreatedEmailSentStatusstring
Enum"SENT""UNSENT""FAILED""EMAIL_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_PAUSED_STATUS"
minCyclesinteger(int32)
maxCyclesinteger(int32)
customerFirstNamestring
customerLastNamestring
autoChargeboolean
importedIdstring
stopUpComingOrderEmailboolean
pausedFromActiveboolean
subscriptionCreatedSmsSentStatusstring
Enum"SENT""UNSENT""FAILED""SMS_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_PAUSED_STATUS""PHONE_NUMBER_EMPTY"
phonestring
activatedOnstring(date-time)
pausedOnstring(date-time)
cancelledOnstring(date-time)
contractDetailsJSONstring
cancellationFeedbackstring
orderNotestring
orderNoteAttributesstring
allowDeliveryPriceOverrideboolean
orderAmountUSDnumber(double)
billingDateAfterTrialstring(date-time)
trialEndDatestring(date-time)
pausedBySecurityChallengeboolean
dunningboolean
contractAmountnumber(double)
contractAmountUSDnumber(double)
upcomingSwapRulestring
emailBouncedOrFailedboolean
Response
application/json
{
  "id": 0,
  "shop": "string",
  "graphSubscriptionContractId": "string",
  "subscriptionContractId": 0,
  "billingPolicyInterval": "string",
  "billingPolicyIntervalCount": 0,
  "currencyCode": "string",
  "customerId": 0,
  "graphCustomerId": "string",
  "deliveryPolicyInterval": "string",
  "deliveryPolicyIntervalCount": 0,
  "status": "string",
  "graphOrderId": "string",
  "orderId": 0,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "nextBillingDate": "2019-08-24T14:15:22Z",
  "orderAmount": 0.1,
  "orderName": "string",
  "customerName": "string",
  "customerEmail": "string",
  "subscriptionCreatedEmailSent": true,
  "endsAt": "2019-08-24T14:15:22Z",
  "startsAt": "2019-08-24T14:15:22Z",
  "subscriptionCreatedEmailSentStatus": "SENT",
  "minCycles": 0,
  "maxCycles": 0,
  "customerFirstName": "string",
  "customerLastName": "string",
  "autoCharge": true,
  "importedId": "string",
  "stopUpComingOrderEmail": true,
  "pausedFromActive": true,
  "subscriptionCreatedSmsSentStatus": "SENT",
  "phone": "string",
  "activatedOn": "2019-08-24T14:15:22Z",
  "pausedOn": "2019-08-24T14:15:22Z",
  "cancelledOn": "2019-08-24T14:15:22Z",
  "contractDetailsJSON": "string",
  "cancellationFeedback": "string",
  "orderNote": "string",
  "orderNoteAttributes": "string",
  "allowDeliveryPriceOverride": true,
  "orderAmountUSD": 0.1,
  "billingDateAfterTrial": "2019-08-24T14:15:22Z",
  "trialEndDate": "2019-08-24T14:15:22Z",
  "pausedBySecurityChallenge": true,
  "dunning": true,
  "contractAmount": 0.1,
  "contractAmountUSD": 0.1,
  "upcomingSwapRule": "string",
  "emailBouncedOrFailed": true
}

Get pending downgrade for a subscription contract

Request

Retrieves the pending/scheduled downgrade details for a specific subscription contract. This endpoint returns information about a downgrade that has been scheduled but not yet executed.

Response Information:

  • contractId: The subscription contract ID
  • waitTillTimestamp: When the downgrade will be executed
  • oldVariantId: The current product variant ID
  • newVariantId: The target product variant ID after downgrade
  • oldPrice: Current subscription price
  • newPrice: New price after downgrade
  • sellingPlanId: The selling plan ID for the new subscription
  • sellingPlanName: Name of the selling plan

Use Cases:

  • Check if a customer has a pending downgrade scheduled
  • Display pending downgrade information in custom dashboards
  • Verify downgrade details before allowing further modifications

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

Path
contractIdinteger(int64)required

The subscription contract ID

Example: 12345
Query
api_keystring

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

Headers
X-API-Keystring
curl -i -X GET \
  'https://membership-admin.appstle.com/api/external/v2/subscription-contract-details/12345/pending-downgrade?api_key=string' \
  -H 'X-API-Key: string'

Responses

Pending downgrade found and returned successfully

Bodyapplication/json
shopstring
contractIdinteger(int64)
waitTillTimestampstring
oldLineIdstring
oldVariantIdstring
newVariantIdstring
sellingPlanIdstring
sellingPlanNamestring
oldPricenumber(double)
newPricenumber(double)
newCustomerTagstring
oldCustomerTagsstring
newOrderTagstring
eventSourcestring
retryCountinteger(int32)
customerIdinteger(int64)
executionArnstring
Response
application/json
{
  "shop": "string",
  "contractId": 0,
  "waitTillTimestamp": "string",
  "oldLineId": "string",
  "oldVariantId": "string",
  "newVariantId": "string",
  "sellingPlanId": "string",
  "sellingPlanName": "string",
  "oldPrice": 0.1,
  "newPrice": 0.1,
  "newCustomerTag": "string",
  "oldCustomerTags": "string",
  "newOrderTag": "string",
  "eventSource": "string",
  "retryCount": 0,
  "customerId": 0,
  "executionArn": "string"
}

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