Manage Third-Party Integrations

Learning Objectives

After completing this unit, you'll be able to:

• List five web services framework capabilities for managing third-party integrations.
  
• Explain the difference between rate limiting and circuit breaker.
  
• Explain your options when a third-party service stops responding or responds slowly.
  
• List the web services framework indicators to check when investigating poor-performing web services.
  
• List four important tips for using the web services framework.
  

Introduction

Storefronts depend on external services for payments, fraud detection, and tax calculations. When those services slow down or fail, shoppers feel it immediately. The B2C Commerce web services framework gives you structured tools to connect to third-party services, control how many calls you make, protect your storefront when services misbehave, and diagnose problems quickly without touching your code—all from Business Manager.

Five Web Services Framework Capabilities

The framework gives you five key capabilities for managing third-party integrations.

• Register services centrally. You define every integration in Business Manager under Administration | Operations | Services. Service configurations, credentials, and profiles live in one place, making it easy to audit and manage every external connection.
  
• Set connection timeouts. You configure how long B2C Commerce waits for a response before giving up. This timeout prevents a slow third-party service from holding up storefront requests indefinitely.
  
• Limit outgoing call volume. The rate limiter caps the number of calls B2C Commerce makes to a service within a time interval. This cap protects services that enforce quotas and prevents burst traffic from triggering penalties.
  
• Isolate failing services automatically. The circuit breaker monitors failed calls. When failures exceed your threshold, B2C Commerce stops calling the service and throws an error immediately, protecting the rest of your storefront from the impact.
  
• Monitor service performance. The framework collects analytics on every registered service call. Review near-real-time trends in Business Manager and investigate incidents using service logs.
  

Rate Limiting Versus Circuit Breaker

Both the rate limiter and the circuit breaker throw ServiceUnavailableException when they trip, but they protect against different problems.

The rate limiter counts outgoing calls. Before every invocation, the framework checks whether calls have reached the configured maximum within the time interval. If they have, the framework skips the call and never sends it to the external service. Use the rate limiter for any service that enforces a third-party quota or where burst traffic risks triggering throttling.

The circuit breaker counts failed calls. It monitors connection errors, HTTP 500/503 responses, and exceptions. When failures reach the configured threshold within a time window, the circuit opens. B2C Commerce stops attempting calls and throws ServiceUnavailableException immediately rather than waiting for another timeout.

HTTP 4xx responses don’t trip the circuit breaker. A 404 or 401 means the client is misconfigured, not that the remote service is down.

Read Protection Signals from the Result Object

When a protection mechanism trips, the Result object returned by Service.call() tells you exactly what happened.

Check result.status and result.errorMessage in your error-handling code to distinguish between a quota violation, a cascading failure, and a slow endpoint.

When a Third-Party Service Stops Responding or Responds Slowly

Slow or unresponsive external services are the most common cause of storefront degradation. The web services framework gives you two layers of protection.

Set a low explicit timeout. The timeout value in the service profile applies to each individual connection and read operation. The platform defaults—2 minutes for storefront requests, 15 minutes for jobs—are far too long to protect shoppers. Set an explicit timeout that matches the acceptable latency for the operation: a payment authorization warrants 2,000 ms; a background catalog import can tolerate 30,000 ms.

Turn on the circuit breaker. When a service goes down, every call blocks until it times out, which occupies storefront threads. After the circuit breaker opens, B2C Commerce throws ServiceUnavailableException immediately instead of waiting, freeing up threads for other requests. This behavior stops one failing integration from cascading into a larger issue.

To test your integration’s behavior when a service is unavailable without hitting a live endpoint, set the service mode to Mocked in Business Manager and implement a mockCall callback in your service script. This approach validates your error-handling logic safely in isolation.

Web Services Framework Indicators to Check When Investigating Poor Performance

When you receive reports of a slow or failing web service, start your investigation in Business Manager.

• Service Status dashboard: Shows near-real-time performance trends including call volume, failure rate, and response times. The dashboard stores data for up to 10 days.
  

To view the dashboard, in Business Manager, from App Launcher, select Administration | Operations | Service Status and choose the service name.

• Result object fields: In your code, inspect result.status, result.errorMessage, and result.error (the HTTP status code for HTTP services) to determine whether the problem is a timeout, a circuit breaker trip, a rate limit violation, or an application-level error.
  
• Service log files: The framework writes log files to the shared log directory under the prefix that you configured. Each service generates three log types:
  
  • head: Logs success or failure status after every call
    
  • comm: Logs request and response data (disabled by default and requires Communication Log Enabled)
    
  • Log: Logs miscellaneous messages including errors and initialization events
    

To access log files, in Business Manager, from App Launcher, elect Administration | Site Development | Log Files.

• Custom Log Settings: Because service names map directly to a logging hierarchy, you turn on debug logging for an entire integration—for example, mycartridge.http.payment—with a single setting.
  

To adjust log levels for specific services or groups of services, in Business Manager, from App Launcher, select Administration | Operations | Custom Log Settings.

Four Important Tips When Using the Web Services Framework

• Always set an explicit, low timeout in every service profile. Never rely on platform defaults. Match the timeout to the latency that your storefront can tolerate for that operation, not the maximum the service theoretically takes.
  
• Never turn off the circuit breaker. The circuit breaker is on by default, keep it that way. It's your most important safeguard against a slow or failing integration cascading into a larger storefront issue. Configure the failure threshold and interval to match the expected call rate for the service.
  
• Turn on the rate limiter for any service with a quota. If your third-party contract limits you to a certain number of API calls per interval, configure the rate limiter to match. The framework enforces the cap before you reach it, so you never accidentally exceed your quota.
  
• Use the recommended naming pattern: {cartridge}.{protocol}.{service}.{operation}. Service names become your logging hierarchy. A well-structured name like mypayment.http.payment.authorize groups all payment logs under service.mypayment.http.payment, which lets you turn logging on or off for the entire integration at once from Custom Log Settings.
  

Next Up

In this unit you learned about the architectural tradeoffs between implementing integrations client-side versus server-side and how loose coupling ensures fault tolerance. Next, learn how to use that framework for central registration, rate limiting, and circuit breaker protection.

Resources

• Salesforce Developers: Web Services