Skip to content
/Subscription Payments

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

Subscription Payments

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

Operations

Send payment method update email to customer

Request

Triggers Shopify to send an email to the subscription customer with a secure link to update their payment method. This endpoint initiates Shopify's native payment update flow without requiring direct payment handling.

Key Features:

  • Sends official Shopify payment update email to customer
  • Customer receives secure link to Shopify-hosted payment update page
  • No PCI compliance required - Shopify handles all payment data
  • Supports all Shopify-supported payment methods
  • Automatically updates subscription after customer completes the process

Process Flow:

  1. API call triggers email send request to Shopify
  2. Shopify sends branded email to customer's registered email
  3. Customer clicks secure link in email
  4. Customer authenticates on Shopify-hosted page
  5. Customer adds/updates payment method
  6. Subscription automatically uses new payment method

Email Details:

  • Sent from Shopify's email servers
  • Uses store's configured sender email
  • Subject line typically: "Update your payment method"
  • Contains secure, time-limited link
  • Shopify-branded with store information

Use Cases:

  • Failed payment recovery
  • Expiring credit card updates
  • Customer-requested payment changes
  • Proactive payment method maintenance

Important Notes:

  • Customer must have valid email address
  • Email cannot be customized (Shopify template)
  • Link expiration time set by Shopify
  • Multiple emails can be sent if needed
  • No webhook for completion - poll contract for updates

Rate Limiting:

  • Subject to Shopify's email sending limits
  • Recommended: Wait 24 hours between sends to same customer
  • Excessive sends may be blocked by Shopify

Authentication: Requires valid X-API-Key header

Query
contractIdinteger(int64)>= 1required

Subscription contract ID for payment method update. Must be a valid contract ID that belongs to the authenticated shop.

Example: contractId=123456789
api_keystringDeprecated

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

Headers
X-API-Keystringrequired

API Key for authentication

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

Responses

Payment update email sent successfully

Bodyapplication/json
Response
application/json
{
  "message": "Payment method update email sent successfully"
}

Update subscription payment method

Request

Updates the payment method for an existing subscription contract to use a different existing payment method. The new payment method must already be associated with the customer in Shopify.

Important Notes:

  • The payment method must already exist in the customer's Shopify payment methods
  • Only valid, non-revoked payment methods can be used
  • The update is processed through Shopify's subscription draft system
  • Payment method details are cached locally after successful update

Process Flow:

  1. Validates subscription contract exists
  2. Creates a draft update in Shopify
  3. Updates the draft with new payment method
  4. Commits the draft to apply changes
  5. Caches payment instrument details locally
  6. Records activity log entry

Authentication: Requires valid X-API-Key header

Query
contractIdinteger(int64)>= 1required

Subscription contract ID to update payment method for. Must be a valid contract ID that belongs to the authenticated shop.

Example: contractId=123456789
paymentMethodIdstring^gid://shopify/CustomerPaymentMethod/[a-zA-Z0...required

ID of the existing customer payment method to use. Must be a valid Shopify GraphQL payment method ID in the format 'gid://shopify/CustomerPaymentMethod/{id}'. The payment method must:

  • Already exist in the customer's Shopify account
  • Be in a valid state (not expired or revoked)
  • Be authorized for subscription use

You can retrieve available payment methods using the customer payment methods endpoint.

Example: paymentMethodId=gid://shopify/CustomerPaymentMethod/cdb2bbe581599b20439ebf636a380b8b
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-existing-payment-method?contractId=123456789&paymentMethodId=gid%3A%2F%2Fshopify%2FCustomerPaymentMethod%2Fcdb2bbe581599b20439ebf636a380b8b' \
  -H 'X-API-Key: sk_live_1234567890abcdef'

Responses

Payment method updated successfully

Bodyapplication/json
Response
application/json
{
  "message": "Payment method updated successfully"
}

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