How do you design SFCC API integrations with OCAPI and SCAPI?

Long Answer

On Salesforce Commerce Cloud (SFCC), robust integrations balance the platform’s strengths with external OMS, ERP, and payment providers. My strategy aligns surface area, reliability, and security across SCAPI, OCAPI, web services, and hooks, while enforcing idempotency, rate limits, and consistent error handling with solid secure credential management.

1) Surface choice: SCAPI vs OCAPI

Use SCAPI for shopper traffic where scale, cacheability, and modern semantics matter (carts, checkout, pricing, inventory). SCAPI is optimized for storefront consumption and benefits from the platform’s performance envelope. Use OCAPI for administrative and data operations (feeds, catalog, price books, customer and order exports). OCAPI Data/Admin suits jobs, integrations, and Business Manager tools. When a capability exists in both, favor SCAPI for web and headless storefronts, and OCAPI for scheduled or operational tasks.

2) Service abstraction and hooks

Wrap all external calls with the SFCC Service Framework and expose integration seams through hooks. Hooks allow pre and post processing of basket, order, and payment flows without forking core pipelines. Each service definition includes timeouts, connection pools, logging, circuit breakers, and retry rules. I keep mapping logic in dedicated modules, converting SFCC objects to provider DTOs and back. This separation makes swapping an OMS, ERP, or PSP a configuration and mapping exercise rather than a rewrite.

3) Idempotency as a first class requirement

Payments and order creation must be idempotent. I generate idempotency keys per basket submission or per provider transaction and store them with a small dedup record (order no, hash, expiry). For PSPs that accept keys, I forward the key and validate repeated responses. For providers without native support, I implement a dedupe store keyed by request signature and guard against replays caused by network retries, shopper double-clicks, or webhook retries. For asynchronous callbacks and webhooks, I verify signatures, enforce nonce windows, and use idempotency on the receiver with atomic upserts.

4) Rate limits and backpressure

I centralize rate limit controls in the service layer. Each integration uses token buckets or leaky buckets with adaptive backoff and jitter. I introduce queues for bursty feeds and order exports, splitting work into batches with concurrency caps. When partners throttle, the service honors Retry-After or equivalent hints and publishes health metrics. For storefront calls, I enforce strict time budgets and degrade gracefully (for example, fall back to cached inventory) instead of blocking the page.

5) Error handling and observability

Errors follow a typed contract: retryable (timeouts, 429, 5xx), non-retryable (4xx validation), and unknown. Retries use exponential backoff with caps; dead-letter queues capture poison messages. I enrich logs with correlation IDs (request ID, basket ID, order no, idempotency key) and emit metrics for success rate, latency, and throttle events. Webhook handlers return 2xx only after durable persistence. All failures surface as actionable events in Business Manager with links to traces.

6) Secure credential management

I never hardcode secrets. I store API keys, client secrets, and certificates in SFCC service credentials with encryption, scoped permissions, and rotation schedules. Mutual TLS for sensitive providers lives in the service profile. For multi-tenant rollouts, I isolate credentials per site and brand. I audit access, rotate keys on a calendar, and prefer short-lived tokens with OAuth where available.

7) Schema negotiation and tolerant readers

Provider schemas evolve. I keep tolerant readers in integration code, ignoring unknown fields and defaulting missing optional ones. I version mapping modules and introduce feature flags to roll out new fields. For OCAPI and SCAPI responses consumed by clients, I prefer additive changes and document deprecations with timelines.

8) Rollout and rollback plans

Risky changes ship behind feature flags and canary cohorts (for example, one brand, one country). I support shadow mode where requests are duplicated to the new integration and responses compared out of band. Rollback is instant by flipping the flag and draining queues. For data migrations, I follow expand-and-contract: dual-write metadata, backfill, cut reads, then remove legacy paths.

9) Jobs, feeds, and resilience

For bulk imports and exports, I use OCAPI Admin or job endpoints with resumable markers and checksum validation. I chunk large payloads, compress where supported, and schedule windows that respect partner quotas. Each job is idempotent with content hashes to skip duplicates, and failures restart from the last good checkpoint.

This pattern—SCAPI for shopper flows, OCAPI for operations, services plus hooks for seams, strict idempotency, respectful rate limits, robust error handling, and strong secure credential management—keeps SFCC integrations fast, safe, and maintainable.

‍

Table

‍

Common Mistakes

• Using OCAPI for high-traffic storefront interactions instead of SCAPI, creating latency and scaling pain.
  
• Skipping idempotency so payment retries or shopper double-submits create duplicate orders.
  
• Ignoring rate limits and flooding partners without adaptive backoff or queues.
  
• Treating all errors as retryable and amplifying incidents; no DLQ or typed policies.
  
• Hardcoding secrets rather than using encrypted service credentials with rotation.
  
• Accepting webhooks without signature verification or replay protection.
  
• Tight coupling of SFCC objects to provider payloads, making schema changes brittle.
  
• Shipping changes without feature flags, canaries, or rollback, causing prolonged outages.
  
  

Sample Answers

Junior:
“I use SCAPI for carts and checkout and OCAPI for jobs and admin tasks. I define services with timeouts and retries, store credentials in encrypted service settings, and add an idempotency key to order creation so retries are safe.”

Mid:
“I wrap OMS and PSP calls in the Service Framework and expose hooks around basket and order flows. I enforce idempotency with keys and a dedupe record, respect rate limits with token buckets and backoff, and classify errors to decide retries. Webhooks are signed and replay-safe.”

Senior:
“I split surfaces: SCAPI for shopper paths, OCAPI for operational feeds. Integrations are modular with mapping layers, queues, and DLQs. I standardize idempotency, throttle with adaptive policies, and keep secrets in rotating service credentials and mTLS. Rollouts use flags, canaries, and shadow traffic with instant rollback. Tolerant readers and versioned mappings absorb provider schema changes.”

‍

Evaluation Criteria

Strong answers differentiate SCAPI vs OCAPI usage, employ the SFCC Service Framework and hooks, and mandate idempotency for orders and payments. They handle rate limits with adaptive backoff and queues, define typed error handling with DLQs, and practice secure credential management via encrypted services, rotation, and mTLS or OAuth. They describe webhook verification and replay defense, tolerant readers for schema drift, and controlled rollout with flags, canaries, and rollback. Red flags include using OCAPI for shopper flows, missing idempotency, hardcoded secrets, and no plan for throttling or rollback.

‍

Preparation Tips

• Build a sample checkout using SCAPI and add an idempotency key per submit; verify safe retries.
  
• Create a service profile for a PSP with timeouts, retries, and token bucket throttling; simulate 429 and observe backoff.
  
• Implement hooks to enrich basket and map order payloads to an OMS DTO module.
  
• Store credentials in service settings, enable mTLS or OAuth, and rotate in a sandbox.
  
• Add webhook handlers with signature verification, nonce windows, and idempotent upserts.
  
• Create OCAPI jobs for catalog or price feeds with chunking and resumable markers.
  
• Instrument correlation IDs and metrics for latency, success, and throttle events; send to logs and dashboards.
  
• Ship behind a feature flag, canary on one site, and rehearse rollback.
  
  

Real-world Context

A retailer moved cart and checkout integrations from OCAPI to SCAPI, cutting p95 by thirty percent and improving cache hit rates. An enterprise brand implemented idempotency keys and dedupe storage for its PSP; duplicate charge incidents dropped to zero despite network retries. A marketplace added token bucket throttling and queues before OMS exports; partner 429s vanished and throughput stabilized. Another merchant rotated secrets through encrypted service credentials and enabled mTLS; audit findings cleared and incident blast radius shrank. Webhooks with signature verification and nonce windows eliminated replay bugs during provider outages.

‍

Key Takeaways

• Use SCAPI for shopper flows and OCAPI for operational and administrative tasks.
  
• Encapsulate external providers with the Service Framework and hooks plus mapping layers.
  
• Enforce idempotency for orders, payments, and webhooks; dedupe and verify.
  
• Respect rate limits with throttling, backoff, and queues; classify errors with DLQs.
  
• Practice strong secure credential management with encrypted services, rotation, and mTLS or OAuth.
  
• Roll out with flags, canaries, and shadow traffic; keep instant rollback ready.
  
  

Practice Exercise

Scenario:
You must integrate SFCC with an OMS, an ERP pricing feed, and a payment provider. Traffic spikes during promotions, partners rate limit, and occasional timeouts trigger duplicate orders.

Tasks:

1. Choose SCAPI for cart and payment steps, OCAPI Admin for catalog and price feeds.
   
2. Define three Service Framework profiles with timeouts, retries, and token bucket throttling; add correlation IDs to all calls.
   
3. Implement checkout hooks that build OMS and PSP DTOs and attach an idempotency key per submit. Store a dedupe record with order number, checksum, and expiry.
   
4. Add webhook handlers for payment events with signature verification, timestamp windows, and idempotent upserts; return 2xx only after durable persistence.
   
5. Create an OCAPI job to import price feeds in chunks; resume from markers on failure and validate with checksums.
   
6. Store API keys and certificates in encrypted service credentials; enable mTLS or OAuth and schedule rotation.
   
7. Instrument metrics for success rate, latency, throttles, retries, and dedup hits; surface dashboards in BM.
   
8. Roll out under a feature flag to one site and market; shadow traffic for one day; then canary to ten percent. Prepare a one-click rollback.
   
   

Deliverable:
A working integration blueprint and code snippets that demonstrate SFCC API integration patterns with OCAPI vs SCAPI, reliable idempotency, controlled rate limits, robust error handling, and secure credential management across OMS, ERP, and payment providers.