orcaqubits/sf-b2c-ocapi

OCAPI -- Open Commerce API (Maintenance-Only)

MAINTENANCE-ONLY NOTICE

OCAPI is in maintenance-only mode. Salesforce is not adding new features and has positioned SCAPI as the successor for all new storefront development. OCAPI receives only critical security patches and bug fixes. It has NOT been formally deprecated with a sunset date.

Use this skill ONLY for: maintaining legacy integrations, planning OCAPI-to-SCAPI migration, or debugging production OCAPI issues.

Do NOT build new features against OCAPI. Use the sf-b2c-scapi skill for all new work.

Before Writing Code

Fetch live documentation BEFORE writing any code.

1. Web-search site:developer.salesforce.com OCAPI reference B2C Commerce for latest reference docs
2. Web-search site:developer.salesforce.com SCAPI migration OCAPI for migration guides
3. Web-search Salesforce B2C Commerce OCAPI maintenance mode 2026 for deprecation timeline updates
4. WebFetch: developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-ocapi-overview.html
5. Confirm OCAPI version support on your instance via Business Manager > Administration > Site Development > Open Commerce API Settings

Conceptual Architecture

Shop API vs Data API

| Aspect | Shop API | Data API | |--------|----------|----------| | Purpose | Storefront operations (browse, cart, checkout) | Admin/integration operations (catalog, config, batch) | | Audience | Shoppers / frontend apps | Admins / ERP / PIM integrations | | Site scope | Site-specific (/s/{site_id}/dw/shop/) | Global (/s/-/dw/data/) | | Auth | Client ID header or customer JWT | JWT bearer token from Account Manager | | Typical consumers | PWA, mobile apps, kiosks | ERP connectors, OMS, back-office tools |

Authentication Types Overview

| Auth Type | API | Use Case | |-----------|-----|----------| | Client ID header (x-dw-client-id) | Shop API | Anonymous browsing | | Customer JWT (via /customers/auth) | Shop API | Registered customer sessions | | OAuth JWT (Account Manager) | Data API | Server-to-server integrations | | BM User Grant | Data API | Operations requiring BM user context |

Access control is configured via JSON in Business Manager, granting each client specific resources and methods.

Pagination

OCAPI uses offset-based pagination with count (page size) and start (offset) parameters. Responses include total, hits, next, and previous fields.

| Parameter | Default | Description | |-----------|---------|-------------| | count | 25 | Results per page (max varies, typically 200) | | start | 0 | Zero-based offset |

Use the expand parameter to include related data (images, prices, variations) in a single request, reducing round-trips. Use select to request only needed fields, reducing payload size.

Versioning

OCAPI requires an explicit version in the URL path (e.g., v24.5). Each B2C Commerce release may introduce a new version. Pin your version and do not upgrade unless required for a security patch.

Key Differences: OCAPI vs SCAPI

| Aspect | OCAPI | SCAPI | |--------|-------|-------| | Auth | Client ID header + Basic auth | SLAS (OAuth 2.1 with PKCE) | | Naming | snake_case fields | camelCase fields | | Versioning | Frequent version bumps (v24.5) | Stable (v1) | | SDK | No official SDK | Commerce SDK (Node.js/TypeScript) | | CDN | Separate CDN config | eCDN built-in | | Search | POST with JSON body | GET with query params | | Status | Maintenance-only | Active development |

Migration Guidance (OCAPI to SCAPI)

Migration should be incremental, not big-bang:

1. Migrate authentication first -- move to SLAS, which unblocks all SCAPI calls
2. Replace endpoints one at a time -- run OCAPI and SCAPI in parallel during transition
3. Build a field-name mapping layer -- snake_case to camelCase for downstream consumers
4. Adopt the Commerce SDK -- handles auth token management and provides TypeScript types
5. Migrate search last -- product search has the most complex integration (refinements, sorting, custom attributes)
6. Update error handling -- SCAPI error responses differ from OCAPI fault documents

Fault Handling

OCAPI returns faults in a standard envelope with _type: "fault" and a nested fault object containing type and message. Common fault types:

| Fault Type | HTTP Status | |------------|-------------| | InvalidParameterException | 400 | | AuthenticationFailedException | 401 | | AuthorizationFailedException | 403 | | NotFoundException | 404 | | RateLimitExceededException | 429 |

Best Practices

Legacy Maintenance

• Minimize changes to working OCAPI integrations; focus effort on migration planning
• Pin your OCAPI version -- avoid unnecessary version bumps
• Monitor Salesforce release notes quarterly for deprecation timeline updates
• Document every OCAPI endpoint your system calls (frequency, criticality) to prepare for migration

Security

• Rotate client credentials on a schedule
• Never expose Data API credentials or SLAS secrets in frontend code
• Restrict OCAPI resource access to minimum required endpoints/methods in BM config
• Audit OCAPI access logs for unexpected usage patterns

Performance

• Cache product/category responses (5-15 min for products, 1 hour for categories)
• Use expand to fetch related data in one call instead of multiple requests
• Implement exponential backoff on 429 responses
• Avoid deep pagination -- use refinements to narrow result sets

Fetch the latest OCAPI reference docs, SCAPI migration guide, and Salesforce release notes for exact endpoint schemas, version availability, and deprecation timelines before implementing.