External APIs (0.0.1)

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Retrieves paginated list of past (processed) billing attempts for a subscription contract or customer. Includes successful orders, failed attempts, and skipped orders.

Filter Options:

• By contract ID: Get order history for specific subscription
• By customer ID: Get all orders across all customer subscriptions
• Pagination: Control page size and page number

Order Information:

• Billing attempt status (SUCCESS, FAILED, SKIPPED)
• Shopify order ID for successful attempts
• Billing date and processing date
• Order total and line items
• Error messages for failed attempts

Authentication: Requires valid X-API-Key header

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

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