Subscription Contracts

Associate external payment gateway customer with Shopify customer

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.

Full behavior, validation rules, and side effects

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:

Customer Lookup:
- If customerId provided: Use directly
- If email provided: Search for existing Shopify customer
- If email not found: Create new Shopify customer
Validation:
- Validate payment gateway name
- Check required parameters for selected gateway
- Verify customer belongs to authenticated shop
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
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:

Test First: Test with sandbox/test gateway credentials before production
Verify Gateway Active: Ensure external gateway is properly configured in Shopify
Use Customer ID: Prefer customerId over email to avoid ambiguity
Handle Errors: Implement robust error handling for gateway failures
Validate Externally: Verify payment profiles exist in external gateway before associating
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

GET

api

external

associate-shopify-customer-to-external-payment-gateways

Associate external payment gateway customer with Shopify customer

curl --request GET \
  --url https://subscription-admin.appstle.com/api/external/v2/associate-shopify-customer-to-external-payment-gateways

{
  "data": {
    "customerPaymentMethodRemoteUserInfoCreate": {
      "customerPaymentMethod": {
        "id": "gid://shopify/CustomerPaymentMethod/abc123",
        "instrument": {
          "__typename": "CustomerCreditCard",
          "brand": "VISA",
          "lastDigits": "4242"
        }
      },
      "userErrors": []
    }
  }
}

Headers

X-API-Key

string

Query Parameters

paymentGateway

string

required

Possible values (stripe, braintree, paypal, authorize_net)

customerId

integer<int64>

Id of the customer to associate payment method with

string

Email of the customer to associate payment method with

customerProfileId

string

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

paymentProfileId

string

required

Card Id or payment profile Id in external payment gateway

Response

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

Retrieve raw Shopify GraphQL response for a subscription contract

Cancel a subscription contract

Associate external payment gateway customer with Shopify customer

curl --request GET \
  --url https://subscription-admin.appstle.com/api/external/v2/associate-shopify-customer-to-external-payment-gateways

{
  "data": {
    "customerPaymentMethodRemoteUserInfoCreate": {
      "customerPaymentMethod": {
        "id": "gid://shopify/CustomerPaymentMethod/abc123",
        "instrument": {
          "__typename": "CustomerCreditCard",
          "brand": "VISA",
          "lastDigits": "4242"
        }
      },
      "userErrors": []
    }
  }
}

Get Started

Guides

Partner Integration

Webhooks

Admin API

Storefront API

Resources

Associate external payment gateway customer with Shopify customer

Headers

Query Parameters

Response

Get Started

Guides

Partner Integration

Webhooks

Admin API

Storefront API

Resources

Documentation Index

Headers

Query Parameters

Response