Skip to content
🔧 Admin APIs
/
/
Get raw subscription cont...

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

Get detailed customer subscription information

Request

Retrieves comprehensive details for all subscription contracts associated with a specific customer. This endpoint returns complete subscription contract data including products, pricing, billing schedule, and status.

Key Information Returned:

  • Contract Details: Contract ID, status (active, paused, cancelled), creation date
  • Products: Line items with product names, variants, quantities, and prices
  • Billing Information: Next billing date, billing frequency, payment method
  • Delivery Details: Shipping address, delivery method, delivery frequency
  • Pricing: Subtotal, discounts applied, total amount per cycle
  • Membership Plan: Associated subscription plan name and details
  • Order History: Past billing attempts and fulfillment records

Subscription Contract Details Include:

  • Contract ID: Unique identifier for the subscription
  • Customer ID: Shopify customer ID associated with the contract
  • Status: ACTIVE, PAUSED, CANCELLED, EXPIRED
  • Billing Cycle: Number of completed billing cycles
  • Next Billing Date: When the next payment will be charged
  • Delivery Date: When the next order will be shipped
  • Products: All line items in the subscription with pricing
  • Discount Codes: Applied discount codes and their values
  • Custom Attributes: Any custom metadata or tags

Common Use Cases:

  • Display full subscription list in customer account dashboard
  • Retrieve all contract details for customer support inquiries
  • Build custom customer portal with subscription management
  • Sync subscription data to external CRM or analytics systems
  • Generate customer subscription reports and analytics
  • Validate customer's active subscriptions before offering upgrades
  • Show subscription history and upcoming deliveries

Response Format: Returns a List of SubscriptionContractDetailsDTO objects, one per active/paused contract. If customer has no subscriptions, returns an empty list.

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

Path
customerIdinteger(int64)required

Shopify customer ID

Example: 6789012345
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-customers-detail/valid/6789012345?api_key=string' \
  -H 'X-API-Key: string'

Responses

Customer subscription details successfully retrieved (may be empty list if no subscriptions)

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 raw subscription contract details from Shopify

Request

Retrieves the complete subscription contract data directly from Shopify's GraphQL API. This returns the full, unmodified Shopify contract object with all nested data.

Key Features:

  • Raw Shopify Data: Direct response from Shopify API, not transformed
  • Complete Contract: All contract fields, line items, billing details
  • Real-Time Data: Fetches current state from Shopify (not cached)
  • Nested Objects: Includes customer, addresses, discounts, line items

Returned Contract Data:

  • Contract ID & Status: Shopify global ID, status (ACTIVE/PAUSED/CANCELLED/EXPIRED)
  • Customer Info: Customer object with name, email, addresses
  • Line Items: Products/variants in subscription with quantities, prices
  • Billing Details: Next billing date, billing policy (frequency, interval)
  • Delivery Details: Delivery policy, shipping address, method
  • Pricing: Line prices, discounts, currency code
  • Dates: Created at, updated at, next billing date
  • Custom Attributes: Any custom data attached to the contract
  • Discounts: Applied discount codes with amounts

Common Use Cases:

  • Full Contract Display: Show all contract details in admin/portal
  • Debugging: Inspect raw Shopify contract structure
  • Data Export: Get complete contract for reporting/analytics
  • Integration Development: Understand Shopify's contract schema
  • Audit Trail: Capture complete contract state at a point in time

Differences from other endpoints:

  • This returns Shopify's raw contract object
  • /api/external/v2/subscription-contract-details returns transformed DTO
  • This includes more nested Shopify-specific fields

Parameters:

  • contractId (required, path): The subscription contract ID (numeric)

Response: Returns complete Shopify SubscriptionContract GraphQL object

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

Path
contractIdinteger(int64)required

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-contracts/contract-external/12345?api_key=string' \
  -H 'X-API-Key: string'

Responses

Subscription contract retrieved successfully from Shopify

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": [ … ]
  }
}

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

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