b2c-hooks_skill

Overview

This skill documents how to implement and register hooks in B2C Commerce using HookMgr and hooks.json. It covers OCAPI/SCAPI hooks, system hooks (calculate, payment, order), and creating custom extension points. The goal is to help developers extend API behavior and core processing without breaking system implementations.

How this skill works

Hooks are registered in a cartridge hooks.json and implemented as scripts that export functions matching hook method names (e.g., afterPOST, calculate). Use dw.system.HookMgr.hasHook and .callHook to detect and invoke hooks programmatically. OCAPI/SCAPI hooks run around API methods (before/after/modifyResponse), while system hooks handle core logic like order calculation or payment flows. Custom hooks always execute all implementations regardless of return values.

When to use it

• Extend or customize an existing OCAPI/SCAPI API resource (validation, response enrichment).
• Override or augment core processing like basket/order calculations, shipping, or tax.
• Integrate payment providers via authorize/capture/refund extension points.
• Expose cross-cutting logic as custom extension points for reuse across cartridges.
• Pass transient data between before/after/modifyResponse hook stages (request.custom).

Best practices

• Register hooks in package.json pointing to hooks.json and keep implementations in a hooks/ folder.
• Do not return any value from OCAPI/SCAPI hooks unless you intentionally want to skip the system implementation.
• Return Status.ERROR only to stop processing and rollback; avoid returning Status.OK because it skips system logic.
• Use request.custom to share data between hooks in the same request and check request.isSCAPI() when needed.
• Keep hooks small and performant; avoid long external calls in before hooks or transactions in calculate hooks.
• Use c_ prefixed custom properties when modifying API responses to avoid collisions.

Example use cases

• Validate address payload in beforePUT and return Status.ERROR for invalid addresses.
• Call an external payment gateway in afterPOST and surface result via modifyPOSTResponse using request.custom.
• Implement a custom order number generator via dw.order.createOrderNo.
• Override shipping calculation by registering dw.order.calculateShipping to call a carrier API.
• Add product metadata to SCAPI product response with a remote include in modifyGETResponse.