Custom SCAPI Builder
Build the api.json + schema.yaml pair that registers Custom SCAPI endpoints under /custom/.
lowercase, e.g. orders
v1, v2, v1.1…
Endpoints
Valid — files ready
{
"apiVersion": "1.0",
"apis": [
{
"id": "orders",
"version": "v1",
"description": "Custom orders endpoints",
"entrypoints": [
{
"operationId": "listOrders",
"method": "GET",
"path": "/orders",
"scopes": [
"c_listorders"
],
"cacheable": false
},
{
"operationId": "getOrder",
"method": "GET",
"path": "/orders/{id}",
"scopes": [
"c_getorder"
],
"cacheable": false
}
]
}
]
}
About Custom SCAPI Builder
Generate the api.json route registration and schema.yaml OpenAPI spec for a Custom SCAPI endpoint. Define your routes, HTTP methods, and OAuth scopes, then download both files ready to drop into your cartridge's rest-apis/directory.
Pipeline
- SCAPI Request Builder — build and test calls to your custom endpoints.
- OpenAPI Viewer — render the generated schema.yaml as interactive API documentation.
- SLAS Client Config Builder — add the custom scopes to your SLAS client.
Frequently asked
- What is Custom SCAPI?
- Custom SCAPI lets you expose your own REST endpoints on the B2C Commerce SCAPI gateway under /custom/<organization>/<api>/<version>/*. Your cartridge handles the request logic; the gateway handles OAuth authentication, rate limiting, and routing. This is the recommended pattern for headless extensibility in B2C Commerce.
- What files does a Custom SCAPI endpoint need?
- Two files per API version: rest-apis/<api>/<version>/api.json (route registration — maps HTTP method + path to an operationId and required scopes) and rest-apis/<api>/<version>/schema.yaml (OpenAPI 3.0 spec — describes request/response shapes for documentation and tooling). The cartridge also needs a controller or script that handles the request.
- Why does my endpoint return 404?
- Common causes: (1) The cartridge is not in the active code version. (2) The api.json has a syntax error — paste it into the JSON Formatter to check. (3) The API ID or version in the URL does not match api.json. (4) The cartridge was not activated after deployment. (5) The SCAPI endpoint registration takes a few minutes to propagate after a new deployment.
- What OAuth scopes should I use?
- Custom scopes must start with c_ (e.g. c_myapi_read). Define them in your SLAS client configuration and reference them in api.json. The gateway enforces that the caller's token includes the required scopes before routing the request to your cartridge.
- Can I use Custom SCAPI with Storefront Next?
- Yes. Custom SCAPI endpoints are callable from any HTTP client, including Storefront Next loaders and actions. Use the SCAPI Builder tool to construct and test the request, then copy the generated fetch/Apex code into your storefront.