# 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

Endpoint: GET /api/external/v2/associate-shopify-customer-to-external-payment-gateways
Version: 0.0.1

## Header parameters:

  - `X-API-Key` (string)

## Query parameters:

  - `paymentGateway` (string, required)
    Possible values (stripe, braintree, paypal, authorize_net)

  - `customerId` (integer)
    Id of the customer to associate payment method with

  - `email` (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 200 fields

## Response 400 fields

## Response 401 fields

## Response 404 fields

## Response 409 fields

## Response 500 fields

## Response 502 fields