Skip to content
External APIs
/
/
Associate external paymen...

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

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

Get past orders report with detailed filtering

Request

Retrieves a detailed report of past billing attempts with advanced filtering options. This endpoint provides comprehensive data for analytics, troubleshooting, and reporting purposes.

Filter Options:

  • By status: SUCCESS, FAILED, SKIPPED
  • By date range: Filter by billing date range
  • By attempt count: Filter by number of retry attempts
  • By contract status: Filter by subscription contract status
  • By contract ID: Get report for specific subscription

Response Includes:

  • Detailed billing attempt information
  • Shopify exception details for failed attempts (optional)
  • Retry attempt count
  • Processing timestamps
  • Order totals and line items

Authentication: Requires valid X-API-Key header

Query
api_keystring

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

contractIdinteger(int64)

Filter by contract Id

statusstringrequired

Filter by status

Enum"SUCCESS""FAILURE""REQUESTING""PROGRESS""QUEUED""SKIPPED""SOCIAL_CONNECTION_NULL""CONTRACT_CANCELLED""CONTRACT_ENDED""CONTRACT_PAUSED"
includeShopifyExceptionboolean

Include Shopify Exception in case of Failure

Default false
fromDaystring(date-time)

Filter date range from

toDaystring(date-time)

Filter by date range to

attemptCountinteger(int32)

Filter by retry attempts

contractStatusstring

Filter by Contract Status

pageableobject(Pageable)required

Pagination parameters (page number and size)

Example: page=0&size=5&sort=id,desc
pageable.​pageinteger(int32)>= 0
pageable.​sizeinteger(int32)>= 1
pageable.​sortArray of strings
Headers
X-API-Keystring
curl -i -X GET \
  'https://subscription-admin.appstle.com/api/external/v2/subscription-billing-attempts/past-orders/report?api_key=string&contractId=0&status=SUCCESS&includeShopifyException=false&fromDay=2019-08-24T14%3A15%3A22Z&toDay=2019-08-24T14%3A15%3A22Z&attemptCount=0&contractStatus=string&page=0&size=5&sort=id%2Cdesc' \
  -H 'X-API-Key: string'

Responses

Successfully retrieved report

Body*/*Array [
subscriptionBillingAttemptobject(SubscriptionBillingAttempt)
subscriptionContractDetailsobject(SubscriptionContractDetails)
]

Associate external payment gateway customer with Shopify customer

Request

Links a customer's payment profile from an external payment gateway (Stripe, Braintree, PayPal, Authorize.Net) to their Shopify customer account. This enables Shopify subscription billing to charge payment methods stored in external gateways, which is essential for migrating existing subscriptions or integrating with legacy payment systems.

What This Endpoint Does: Creates a connection between a Shopify customer and their corresponding customer profile in an external payment gateway. This allows Shopify's subscription system to send billing requests to the external gateway using the stored payment credentials, effectively enabling subscriptions to bill through payment methods managed outside of Shopify.

Supported Payment Gateways:

1. Stripe (paymentGateway=stripe):

  • Requires: customerProfileId (Stripe customer ID, e.g., cus_xxxxx)
  • Requires: paymentProfileId (Stripe payment method ID, e.g., pm_xxxxx or card ID)
  • Links Shopify customer to Stripe customer and stored card/payment method

2. Braintree (paymentGateway=braintree):

  • Requires: customerProfileId (Braintree customer ID)
  • Requires: paymentProfileId (Braintree payment method token)
  • Supports credit cards and PayPal accounts stored in Braintree vault

3. PayPal (paymentGateway=paypal):

  • Requires: paymentProfileId (PayPal billing agreement ID)
  • Optional: customerProfileId (not required for PayPal)
  • Links Shopify customer to PayPal billing agreement

4. Authorize.Net (paymentGateway=authorize_net):

  • Requires: customerProfileId (Authorize.Net customer profile ID)
  • Requires: paymentProfileId (Authorize.Net payment profile ID)
  • Links to Customer Information Manager (CIM) profiles

Request Parameters:

Required Parameters:

  • paymentGateway (string): Gateway name - stripe, braintree, paypal, or authorize_net
  • paymentProfileId (string): Payment method/card ID in the external gateway
  • customerId OR email (one required): Shopify customer identifier

Optional Parameters:

  • customerProfileId (string): Customer ID in external gateway (required for Stripe, Braintree, Authorize.Net; optional for PayPal)

Customer Identification:

By Customer ID (recommended):

  • Provide Shopify customerId if known
  • Fastest and most reliable method
  • Avoids ambiguity with duplicate emails

By Email:

  • Provide customer email if customer ID unknown
  • System looks up Shopify customer by email
  • If exactly one match: Uses that customer
  • If multiple matches: Returns error (ambiguous)
  • If no matches: Creates new Shopify customer with that email

Use Cases:

1. Subscription Migration:

  • Migrating subscriptions from legacy platform to Shopify
  • Preserving existing payment methods during migration
  • Avoiding customer disruption by not requiring payment re-entry
  • Maintaining payment history and customer profiles

2. Payment Gateway Integration:

  • Using external payment processor for compliance reasons
  • Leveraging existing payment gateway relationships
  • Maintaining payment data in external PCI-compliant vault
  • Integrating with enterprise payment infrastructure

3. Multi-Platform Sync:

  • Syncing payment methods from other sales channels
  • Centralizing payment methods across platforms
  • Enabling subscriptions for existing customer base

4. Custom Checkout Flows:

  • Building custom subscription checkout with external gateway
  • Collecting payment via external gateway, then linking to Shopify
  • Supporting payment methods not natively available in Shopify

Process Flow:

  1. Customer Lookup:

    • If customerId provided: Use directly
    • If email provided: Search for existing Shopify customer
    • If email not found: Create new Shopify customer

  2. Validation:

    • Validate payment gateway name
    • Check required parameters for selected gateway
    • Verify customer belongs to authenticated shop

  3. Gateway Association:

    • Call Shopify GraphQL mutation for gateway-specific association
    • Link customer profile ID and payment profile ID
    • Store association in Shopify's payment instrument vault

  4. Response:

    • Return Shopify's raw GraphQL response
    • Response includes payment instrument ID for future use
    • Contains success/error details from Shopify API

Example Requests:

Stripe Example:

GET /api/external/v2/associate-shopify-customer-to-external-payment-gateways?
  paymentGateway=stripe&
  customerId=12345&
  customerProfileId=cus_ABC123&
  paymentProfileId=pm_XYZ789

Braintree with Email:

GET /api/external/v2/associate-shopify-customer-to-external-payment-gateways?
  paymentGateway=braintree&
  email=customer@example.com&
  customerProfileId=bt_customer_123&
  paymentProfileId=bt_card_token_456

PayPal Example:

GET /api/external/v2/associate-shopify-customer-to-external-payment-gateways?
  paymentGateway=paypal&
  customerId=12345&
  paymentProfileId=B-12345BILLING67890

Important Considerations:

Gateway Setup:

  • External payment gateway must be installed and configured in Shopify
  • Gateway must be activated for subscription billing
  • Appropriate credentials and API keys must be configured

Data Validation:

  • Payment profile IDs are not validated against external gateway
  • Invalid IDs will be accepted but will fail during actual billing
  • Test associations before migrating production subscriptions

Customer Creation:

  • If customer doesn't exist and email provided, new customer is created
  • Created customers have minimal information (just email initially)
  • Consider adding additional customer details after creation

Security:

  • This endpoint does NOT store or handle actual payment credentials
  • Only references/tokens to external gateway profiles are used
  • Payment data remains in external gateway's PCI-compliant vault
  • Shopify never receives sensitive card data

Best Practices:

  1. Test First: Test with sandbox/test gateway credentials before production
  2. Verify Gateway Active: Ensure external gateway is properly configured in Shopify
  3. Use Customer ID: Prefer customerId over email to avoid ambiguity
  4. Handle Errors: Implement robust error handling for gateway failures
  5. Validate Externally: Verify payment profiles exist in external gateway before associating
  6. Document IDs: Keep mapping of Shopify customer IDs to external gateway IDs

Migration Workflow Example:

For each legacy subscription:
1. Get customer email and Stripe customer ID from legacy system
2. Call this endpoint to link Shopify customer to Stripe customer
3. Create subscription contract in Shopify using returned payment instrument
4. Verify subscription created successfully
5. Mark legacy subscription as migrated
6. Test billing with external gateway

Troubleshooting:

"More than one customer found for email":

  • Multiple Shopify customers exist with same email
  • Solution: Use specific customerId instead of email

"Invalid payment gateway":

  • Gateway name misspelled or unsupported
  • Solution: Use exact values: stripe, braintree, paypal, authorize_net

"customerProfileId required":

  • Missing required parameter for Stripe/Braintree/Authorize.Net
  • Solution: Provide customer ID from external gateway

Response Format: Returns Shopify's raw GraphQL mutation response containing payment instrument details and success/error information.

Related Endpoints:

  • GET /api/external/v2/subscription-contract-details/shopify/customer/{customerId}/payment-methods - Verify association successful
  • PUT /api/external/v2/subscription-contracts-update-payment-method - Use associated payment for subscription

Authentication: Requires valid X-API-Key header

Query
paymentGatewaystringrequired

Possible values (stripe, braintree, paypal, authorize_net)

customerIdinteger(int64)

Id of the customer to associate payment method with

emailstring

Email of the customer to associate payment method with

customerProfileIdstring

Id of customer in external payment gateway, not required for Paypal

paymentProfileIdstringrequired

Card Id or payment profile Id in external payment gateway

Headers
X-API-Keystring
curl -i -X GET \
  'https://subscription-admin.appstle.com/api/external/v2/associate-shopify-customer-to-external-payment-gateways?paymentGateway=string&customerId=0&email=string&customerProfileId=string&paymentProfileId=string' \
  -H 'X-API-Key: string'

Responses

Successfully associated external payment gateway customer with Shopify customer. Returns Shopify GraphQL raw response.

Bodyapplication/json
Response
application/json
{
  "data": {
    "customerPaymentMethodRemoteUserInfoCreate": { … }
  }
}

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