Integrating Third-Party Services

Every non-trivial application integrates external services. Payments, email, authentication, maps, AI, analytics—you're not building these yourself. You're integrating APIs provided by specialists.

Categories of Integrations

Payments: Stripe, PayPal, Square handle transactions and PCI compliance.

Communication: SendGrid, Resend, Twilio send emails and SMS.

Authentication: Auth0, Clerk, Supabase provide user authentication and SSO.

Maps and Location: Google Maps, Mapbox, Geolocation services.

AI: OpenAI, Anthropic, Replicate provide AI models.

Storage: AWS S3, Cloudflare R2, Vercel Blob store files.

Analytics: Mixpanel, PostHog, Amplitude track user behavior.

CRM: HubSpot, Salesforce, Pipedrive manage customer relationships.

The Integration Risk

You depend on services you don't control. If Stripe goes down, you can't process payments. If SendGrid is unavailable, emails don't send. Your application's reliability depends on third-party uptime.

Services change. APIs are deprecated. Pricing increases. Rate limits tighten. You're at the mercy of the service provider's decisions.

Mitigate with graceful degradation: your application continues to function when integrations fail, albeit with reduced functionality. Show cached data, disable a feature, queue work for later.

Abstraction Layer Pattern

Wrap third-party integrations in your own abstraction. Instead of calling Stripe directly throughout your code, create a PaymentService that uses Stripe. This isolates Stripe-specific code to one place.

Benefits: swapping providers is straightforward (implement PaymentService with PayPal instead), testing is simpler (mock PaymentService), and code is cleaner.

Environment-Specific Configuration

Services provide sandbox/test environments. Use them for development and staging. Use production credentials only in production. Never hardcode credentials—use environment variables or secrets managers.

Error Handling for Integrations

External services fail. Network timeouts, rate limits, 5xx errors. Your code must handle failures gracefully.

Strategies: retry with exponential backoff, fall back to cached data, queue work for later processing, return a user-friendly error message.

Never expose internal integration errors to users. "Stripe returned a 500" is not a helpful error message. Translate to: "Payment processing is temporarily unavailable. Please try again later."

Cost Monitoring

Third-party API calls have costs. Stripe charges per transaction. SendGrid charges per email. OpenAI charges per token. These costs can surprise you.

Monitor usage. Set alerts when usage exceeds thresholds. Have conversations with services about your growth. Some offer volume discounts or can help optimize your usage.

Reading the Documentation

Each service has rate limits, pricing models, data retention policies, and deprecation notices. Read the docs. Know your rate limits before going to production. Know your pricing model. Understand what data the service retains and for how long.

Subscribe to their status pages and changelog. Know when they announce deprecations or changes.

The Integration Test Problem

Tests that call real external services are slow and have side effects. A test that sends a real email takes time. A test that charges a real card costs money.

Use test modes or mocking. Most services provide test API keys that simulate calls without real effects. Mock external services in unit tests. Only test integrations with real services in integration tests.

Handling API Changes

Services upgrade their APIs. Fields are renamed, deprecated, removed. Stay aware of these changes. Subscribe to webhooks about API changes. Read release notes.

Plan for migrations. When a service removes an API version, you must migrate before sunset. Test migrations on staging before deploying.