> ## Documentation Index > Fetch the complete documentation index at: https://developers.appstle.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. **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 ## OpenAPI ````yaml /subscription/admin-api-swagger.json get /api/external/v2/associate-shopify-customer-to-external-payment-gateways openapi: 3.0.1 info: description: >- 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. title: Admin APIs version: 0.0.1 servers: - url: https://subscription-admin.appstle.com security: [] tags: - description: >- Core APIs for managing the complete subscription lifecycle including creation, updates, pausing, resuming, and cancellation of subscriptions. name: Subscription Management - description: >- APIs for managing subscription payment methods, processing payments, handling payment retries, and updating billing information. name: Subscription Payments - description: >- APIs for managing subscription contracts including delivery schedules, pricing, order notes, billing cycles, and shipping addresses. name: Subscription Contracts - description: >- APIs for managing products within subscriptions including adding, removing, updating quantities, and swapping products. name: Subscription Products - description: >- APIs for handling billing operations, payment processing, and financial transactions related to subscriptions. name: Billing & Payments - description: >- APIs for managing discounts and promotional codes applied to subscriptions. name: Subscription Discounts - description: >- APIs for managing one-time add-on products that can be purchased alongside recurring subscription items. name: Subscription One-Time Products - description: >- APIs for managing subscription plans, pricing tiers, and plan configurations. name: Subscription Plans - description: >- APIs for managing customizable product boxes and bundles where customers can select multiple items. name: Build-a-Box & Bundles - description: >- APIs for managing the product catalog including product information, variants, and inventory. name: Product Catalog - description: >- APIs for managing operational settings, configurations, and administrative functions. name: Operations & Settings - description: >- APIs powering the customer-facing portal where subscribers can manage their own subscriptions. name: Customer Portal - description: APIs for managing customer information, profiles, and account details. name: Customers - description: >- APIs for retrieving aggregated subscription data, customer subscription history, and account-level subscription information. name: Subscription Data - description: >- APIs for managing delivery profiles, shipping rates, free shipping configuration, and delivery method options on subscriptions. name: Delivery & Shipping - description: >- APIs for managing storefront customization including custom CSS, theme settings, label translations, and merchant-defined widget configuration. name: Customization - description: >- APIs for configuring cancellation flows, retention offers, cancellation reason management, and win-back automation. name: Customer Retention paths: /api/external/v2/associate-shopify-customer-to-external-payment-gateways: get: tags: - Subscription Contracts - Billing & Payments summary: Associate external payment gateway customer with Shopify customer description: >- 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 operationId: associateShopifyCustomerToExternalPaymentGateways parameters: - in: header name: X-API-Key required: false schema: type: string - description: Possible values (stripe, braintree, paypal, authorize_net) in: query name: paymentGateway required: true schema: type: string - description: Id of the customer to associate payment method with in: query name: customerId required: false schema: format: int64 type: integer - description: Email of the customer to associate payment method with in: query name: email required: false schema: type: string - description: Id of customer in external payment gateway, not required for Paypal in: query name: customerProfileId required: false schema: type: string - description: Card Id or payment profile Id in external payment gateway in: query name: paymentProfileId required: true schema: type: string responses: '200': content: application/json: examples: Successful Stripe association: description: Successful Stripe association value: data: customerPaymentMethodRemoteUserInfoCreate: customerPaymentMethod: id: gid://shopify/CustomerPaymentMethod/abc123 instrument: __typename: CustomerCreditCard brand: VISA lastDigits: '4242' userErrors: [] description: >- Successfully associated external payment gateway customer with Shopify customer. Returns Shopify GraphQL raw response. '400': content: application/json: examples: Invalid payment gateway: description: Invalid payment gateway value: detail: >- Invalid payment gateway: invalid_gateway. Supported: stripe, braintree, paypal, authorize_net status: 400 title: Invalid payment gateway type: https://example.com/errors/bad-request Missing customer identifier: description: Missing customer identifier value: detail: CustomerId or email is required status: 400 title: Missing required parameter type: https://example.com/errors/bad-request Missing customerProfileId for Stripe: description: Missing customerProfileId for Stripe value: detail: customerProfileId is required for stripe customers status: 400 title: Missing required parameter type: https://example.com/errors/bad-request description: >- Bad request - Invalid parameters, missing required fields, or invalid payment gateway '401': content: application/json: example: detail: Valid X-API-Key header is required status: 401 title: Authentication required type: https://example.com/errors/unauthorized description: Authentication required '404': content: application/json: example: detail: No customer found with ID 12345 in Shopify status: 404 title: Customer not found type: https://example.com/errors/not-found description: Customer not found (when using customerId) '409': content: application/json: example: detail: >- More than one customer found for: customer@example.com. Please provide specific customerId instead. status: 409 title: Multiple customers found type: https://example.com/errors/conflict description: Conflict - Multiple customers found with provided email '500': content: application/json: example: detail: 'Error in creating customer id with email: customer@example.com' status: 500 title: Association failed type: https://example.com/errors/internal-error description: >- Internal error - Failed to associate payment method or Shopify API error '502': content: application/json: example: detail: Failed to communicate with external payment gateway status: 502 title: Payment gateway error type: https://example.com/errors/bad-gateway description: Bad gateway - External payment gateway or Shopify API error ````