|
| 1 | +--- |
| 2 | +description: Generate a new custom SCAPI endpoint (OAS 3.0 schema, api.json, script.js) in an existing cartridge. |
| 3 | +--- |
| 4 | + |
| 5 | +# scapi_custom_api_scaffold |
| 6 | + |
| 7 | +Generate a new custom SCAPI endpoint in an existing cartridge. Creates `schema.yaml` (OAS 3.0 contract), `api.json` (endpoint mapping), and `script.js` (implementation) under the cartridge's `rest-apis/<apiName>/` directory. |
| 8 | + |
| 9 | +## Overview |
| 10 | + |
| 11 | +The `scapi_custom_api_scaffold` tool scaffolds a new custom API using the B2C tooling SDK's `custom-api` scaffold. It: |
| 12 | + |
| 13 | +- Creates an OpenAPI 3.0 schema, API manifest, and script stub in your project. |
| 14 | +- Uses the first cartridge found in the project if you don't specify one. |
| 15 | +- Supports **shopper** (siteId, customer-facing) or **admin** (no siteId) API types. |
| 16 | + |
| 17 | +**No instance or OAuth required** — this tool works locally and only writes files into your project. To check registration status after deployment, use [`scapi_custom_apis_status`](./scapi-custom-apis-status). |
| 18 | + |
| 19 | +## Parameters |
| 20 | + |
| 21 | +| Parameter | Type | Required | Description | |
| 22 | +|-----------|------|----------|-------------| |
| 23 | +| `apiName` | string | Yes | API name in kebab-case (e.g. `my-products`). Must start with a lowercase letter; only letters, numbers, and hyphens. | |
| 24 | +| `cartridgeName` | string | No | Cartridge that will contain the API. Omit to use the first cartridge found under the project (working directory or `projectRoot`). | |
| 25 | +| `apiType` | `"admin"` \| `"shopper"` | No | `shopper` (siteId, customer-facing) or `admin` (no siteId). Default: `shopper`. | |
| 26 | +| `apiDescription` | string | No | Short description of the API. | |
| 27 | +| `projectRoot` | string | No | Project root for cartridge discovery. Default: MCP working directory (`--project-directory` / `SFCC_PROJECT_DIRECTORY`). | |
| 28 | +| `outputDir` | string | No | Output directory override. Default: project root (scaffold writes under cartridge path). | |
| 29 | + |
| 30 | +## Usage Examples |
| 31 | + |
| 32 | +### Create a custom API (default cartridge and type) |
| 33 | + |
| 34 | +``` |
| 35 | +Use the MCP tool to create a custom API named my-loyalty-api. |
| 36 | +``` |
| 37 | + |
| 38 | +### Create a shopper API with a description |
| 39 | + |
| 40 | +``` |
| 41 | +Use the MCP tool to scaffold a custom API named product-recommendations, type shopper, with description "Product recommendations by segment". |
| 42 | +``` |
| 43 | + |
| 44 | +### Create an admin API in a specific cartridge |
| 45 | + |
| 46 | +``` |
| 47 | +Use the MCP tool to create a custom admin API named inventory-sync in cartridge app_custom. |
| 48 | +``` |
| 49 | + |
| 50 | +## Output |
| 51 | + |
| 52 | +### Success |
| 53 | + |
| 54 | +Returns the scaffold ID, output directory, and list of created files: |
| 55 | + |
| 56 | +```json |
| 57 | +{ |
| 58 | + "scaffold": "custom-api", |
| 59 | + "outputDir": "/path/to/project", |
| 60 | + "dryRun": false, |
| 61 | + "files": [ |
| 62 | + { "path": ".../rest-apis/my-custom-api/schema.yaml", "action": "created" }, |
| 63 | + { "path": ".../rest-apis/my-custom-api/api.json", "action": "created" }, |
| 64 | + { "path": ".../rest-apis/my-custom-api/script.js", "action": "created" } |
| 65 | + ], |
| 66 | + "postInstructions": "Custom API 'my-custom-api' has been created in cartridge 'app_storefrontnext_base'. ..." |
| 67 | +} |
| 68 | +``` |
| 69 | + |
| 70 | +### Errors |
| 71 | + |
| 72 | +- **No cartridges found** — Project has no cartridge (e.g. no `.project` in a cartridge directory). Create a cartridge first (e.g. `b2c scaffold cartridge`). |
| 73 | +- **Scaffold not found** — SDK `custom-api` scaffold is missing; ensure `@salesforce/b2c-tooling-sdk` is installed. |
| 74 | +- **Parameter validation failed** — Invalid `apiName` (e.g. not kebab-case) or other parameter issue. |
| 75 | + |
| 76 | +## Next steps after scaffolding |
| 77 | + |
| 78 | +1. **Edit** `schema.yaml` to define paths, request/response schemas, and operation IDs. |
| 79 | +2. **Edit** `script.js` to implement the endpoint logic. |
| 80 | +3. **Deploy** the cartridge to your instance and **activate** the code version to register the API. |
| 81 | +4. **Verify** with [`scapi_custom_apis_status`](./scapi-custom-apis-status) that endpoints show as `active`. |
| 82 | + |
| 83 | +Shopper APIs are available at: |
| 84 | +`https://{shortCode}.api.commercecloud.salesforce.com/custom/{apiName}/v1/organizations/{organizationId}/...` and require the `siteId` query parameter and ShopperToken authentication. |
| 85 | + |
| 86 | +## Related Tools |
| 87 | + |
| 88 | +- Part of the [SCAPI](../toolsets#scapi), [PWAV3](../toolsets#pwav3), and [STOREFRONTNEXT](../toolsets#storefrontnext) toolsets |
| 89 | +- [`scapi_custom_apis_status`](./scapi-custom-apis-status) — Check custom API endpoint registration status after deployment |
| 90 | +- [`scapi_schemas_list`](./scapi-schemas-list) — List or fetch custom API schemas (use `apiFamily: "custom"`) |
| 91 | + |
| 92 | +## See Also |
| 93 | + |
| 94 | +- [SCAPI Toolset](../toolsets#scapi) — Overview of SCAPI tools |
| 95 | +- [Scaffolding Guide](../../guide/scaffolding#custom-api) — CLI and SDK scaffolding (including `b2c scaffold custom-api`) |
| 96 | +- [CLI Reference](../../cli/scaffold) — `b2c scaffold` commands |
0 commit comments