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 all payment methods associated with a customer directly from Shopify's payment API. This endpoint returns detailed information about stored payment instruments including credit/debit cards, digital wallets, and other payment methods that the customer can use for subscription billing.

What This Endpoint Does: Queries Shopify's GraphQL API to fetch the customer's payment methods, including active instruments and optionally revoked (expired, removed, or failed) payment methods. This provides real-time payment method data directly from Shopify's payment vault.

Payment Method Types Supported:

Credit/Debit Cards:

• Visa, Mastercard, American Express, Discover
• Card last 4 digits
• Expiry month and year
• Card brand and type
• Billing address associated with card

Digital Wallets:

• Shop Pay
• Apple Pay
• Google Pay
• PayPal (when stored)

Alternative Payment Methods:

• Bank accounts (ACH, SEPA)
• Buy Now Pay Later instruments
• Store credit

Payment Method Information Returned:

For Each Payment Method:

• Payment Instrument ID: Unique identifier (used for updates)
• Display Name: Human-readable name (e.g., "Visa ending in 4242")
• Payment Type: Card, wallet, bank account, etc.
• Status: ACTIVE, REVOKED, EXPIRED, FAILED
• Is Default: Whether this is the customer's default payment method
• Last 4 Digits: For cards and bank accounts
• Expiry Date: For cards (month/year)
• Brand: Visa, Mastercard, Amex, etc.
• Billing Address: Address associated with payment method
• Created Date: When payment method was added

Query Parameters:

allowRevokedMethod (optional, default: false):

• false: Returns only active, usable payment methods
• true: Returns both active AND revoked payment methods

Revoked Payment Methods: Include expired cards, deleted payment methods, failed instruments, and customer-removed methods. Useful for historical records and troubleshooting, but cannot be used for new billing attempts.

Use Cases:

1. Customer Portal:

• Display saved payment methods
• Allow customer to select default payment method
• Show payment method update/delete options
• Validate payment methods before subscription modification

2. Subscription Management:

• Verify customer has valid payment method before creating subscription
• Check payment method expiry before next billing
• Identify subscriptions at risk due to expiring cards
• Prompt customer to update payment if needed

3. Payment Method Updates:

• List available payment methods for customer selection
• Identify payment instrument ID for update operations
• Validate payment method before switching subscription

4. Troubleshooting & Support:

• Debug payment failures
• Verify which payment method is being used
• Check if payment method is expired or revoked
• Assist customer with payment issues

5. Analytics & Alerts:

• Track payment methods approaching expiry
• Send proactive notifications to update cards
• Analyze payment method distribution
• Identify customers with no valid payment methods

Response Structure:

Returns CustomerPaymentMethodsQuery.PaymentMethods object from Shopify GraphQL:

{
  "nodes": [
    {
      "id": "gid://shopify/CustomerPaymentMethod/abc123",
      "instrument": {
        "__typename": "CustomerCreditCard",
        "brand": "VISA",
        "lastDigits": "4242",
        "expiryMonth": 12,
        "expiryYear": 2025,
        "name": "John Doe"
      },
      "revokedAt": null,
      "revokedReason": null,
      "subscriptionContracts": [...]
    }
  ]
}

Common Scenarios:

Scenario 1: Customer with multiple cards Returns array with multiple payment method objects, each representing a stored card.

Scenario 2: Customer with no payment methods Returns empty nodes array - customer needs to add payment method.

Scenario 3: Expired card included (allowRevokedMethod=true) Returns both active cards and expired/revoked cards with revokedAt timestamp.

Important Considerations:

Data Source:

• Queries Shopify API in real-time (not Appstle database)
• Always returns current Shopify payment method state
• Subject to Shopify API rate limits

Performance:

• Response time: 300-800ms (depends on Shopify API)
• Slower than database queries
• Consider caching for non-critical displays

Security:

• Never returns full card numbers (PCI compliance)
• Returns only last 4 digits
• CVV is never stored or returned
• Payment instrument IDs are tokenized references

Privacy:

• Customer ID validated against shop
• Cannot query payment methods from other shops
• Requires appropriate API permissions

Best Practices:

1. Default to Active Only: Use allowRevokedMethod=false for payment selection UIs
2. Check Expiry Dates: Validate card expiry before using for subscriptions
3. Cache Responsibly: Cache for short periods (5-10 min) to reduce API calls
4. Handle Empty Response: Always handle case where customer has no payment methods
5. Show User-Friendly Names: Display brand and last 4 (e.g., "Visa •••• 4242")
6. Indicate Default: Highlight the default payment method clearly

Integration Examples:

Example 1: Display payment methods in customer portal

const paymentMethods = await fetch(
  `/api/external/v2/subscription-contract-details/shopify/customer/${customerId}/payment-methods`,
  { headers: { 'X-API-Key': 'your-key' } }
).then(r => r.json());

paymentMethods.nodes.forEach(pm => {
  if (pm.instrument.__typename === 'CustomerCreditCard') {
    console.log(`${pm.instrument.brand} ending in ${pm.instrument.lastDigits}`);
    if (pm.instrument.expiryYear < currentYear) {
      console.warn('Card expired!');
    }
  }
});

Example 2: Check for valid payment before creating subscription

const paymentMethods = await fetch(...);
const hasValidPayment = paymentMethods.nodes.some(pm => 
  !pm.revokedAt && pm.instrument.expiryYear >= currentYear
);

if (!hasValidPayment) {
  alert('Please add a valid payment method before subscribing');
}

Related Endpoints:

• PUT /api/external/v2/subscription-contracts-update-payment-method - Update subscription payment method
• POST /api/external/v2/associate-shopify-customer-to-external-payment-gateways - Add external payment method

Authentication: Requires valid X-API-Key header

Generates a secure, time-limited magic link that allows customers to access their subscription management portal. This endpoint supports lookup by either customer ID or email address, making it flexible for different integration scenarios.

Key Features:

• Dual Lookup: Find customer by ID or email
• Auto Customer Discovery: Automatically finds customer from email
• Secure Tokens: Encrypted tokens with 2-hour expiration
• Custom Domains: Supports shop's public domain
• Zero-Auth Access: Customers don't need passwords

Customer Lookup Logic:

Option 1: By Customer ID (Preferred)

GET /api/external/v2/manage-subscription-link?customerId=12345

• Direct lookup by Shopify customer ID
• Fastest and most reliable method
• No ambiguity

Option 2: By Email

GET /api/external/v2/manage-subscription-link?emailId=customer@example.com

• Searches for customer by email in subscription database
• Finds customer ID automatically
• If not found: Returns error

Validation Rules:

• Either customerId OR emailId must be provided
• Cannot provide both (customerId takes precedence)
• Email must match a customer with subscriptions
• Customer must belong to authenticated shop

Token Generation:

Token Contents:

• Encrypted customer ID
• Shop domain
• Generation timestamp
• Expiration time (2 hours)

Security Features:

• Cryptographically secure encryption
• Cannot be forged or modified
• Automatic expiration after 2 hours
• Single-use recommended (though not enforced)
• Tied to specific shop and customer

Generated URL Structure:

https://[shop-domain]/[manage-subscriptions-path]?token=[encrypted-token]

Example URLs:

https://mystore.com/tools/recurring/customer_portal?token=eyJhbGc...
https://shop.myshopify.com/tools/recurring/customer_portal?token=eyJhbGc...

Use Cases:

1. Email Campaigns:

• Add "Manage Subscription" button to transactional emails
• Include in billing reminder emails
• Send in order confirmation emails
• Add to marketing campaigns

2. Customer Support:

• Provide customers quick portal access
• Avoid "forgot password" issues
• Enable instant self-service
• Reduce support ticket volume

3. Post-Purchase Flows:

• Thank you page portal links
• First order welcome emails
• Onboarding email sequences
• Re-engagement campaigns

4. Account Management:

• SMS notifications with portal links
• Push notification deep links
• Customer dashboard integrations
• Third-party app integrations

Response Format:

{
  "manageSubscriptionLink": "https://mystore.com/tools/recurring/customer_portal?token=eyJhbGciOiJIUzI1NiJ9...",
  "tokenExpirationTime": "2024-03-15T14:30:00Z"
}

Response Fields:

• manageSubscriptionLink: Complete URL ready to use
• tokenExpirationTime: ISO 8601 timestamp when token expires

Integration Examples:

Email Template:

const response = await fetch(
  `/api/external/v2/manage-subscription-link?emailId=${customerEmail}`,
  { headers: { 'X-API-Key': 'your-key' } }
).then(r => r.json());

const emailHtml = `
  <p>Hi ${customerName},</p>
  <p>Manage your subscription:</p>
  <a href="${response.manageSubscriptionLink}">Manage Subscription</a>
  <p><small>Link expires ${formatDate(response.tokenExpirationTime)}</small></p>
`;

SMS Notification:

const { manageSubscriptionLink } = await getPortalLink(customerId);
const shortUrl = await shortenUrl(manageSubscriptionLink);

await sendSMS(customerPhone, 
  `Your subscription ships tomorrow! Manage it here: ${shortUrl}`
);

Important Considerations:

Token Expiration:

• Tokens expire after exactly 2 hours
• Generate new token if expired
• Don't store tokens long-term
• Best practice: Generate on-demand

Domain Selection:

• Uses shop's publicDomain if configured
• Falls back to Shopify domain (.myshopify.com)
• Respects custom domain settings
• Maintains brand consistency

Customer Lookup Errors:

• Email not found: Returns 400 error
• Invalid customer ID: Returns error
• No parameters provided: Returns 400
• Both parameters provided: Uses customerId

Security Notes:

• Tokens cannot be used across different shops
• Cannot be used for different customers
• Tampering invalidates token
• Consider rate limiting token generation

Best Practices:

1. Generate On-Demand: Create tokens when needed, not in advance
2. Use HTTPS: Always serve links over HTTPS
3. Show Expiry: Inform customers when link expires
4. URL Shortening: Use URL shorteners for SMS/print materials
5. Track Usage: Monitor which emails drive portal visits
6. Prefer Customer ID: Use customerId when available for faster lookup

Comparison with /manage-subscription-link/{customerId}:

• This endpoint: Flexible lookup (ID or email)
• Path parameter version: Customer ID only
• Both generate identical tokens
• Use this for email-based flows

Authentication: Requires valid X-API-Key header