@salesforce/b2c-cli 2.3.1 → 2.4.0

package/content/guidance/b2c/b2c-hooks/references/OCAPI-SCAPI-HOOKS.md

@@ -0,0 +1,403 @@
+# OCAPI/SCAPI Hooks Reference
+
+OCAPI and SCAPI share the same hooks. Registering a hook for OCAPI also applies to SCAPI endpoints.
+
+## Prerequisites
+
+Enable hooks in Business Manager:
+**Administration > Global Preferences > Feature Switches > Enable Salesforce Commerce Cloud API hook execution**
+
+## Hook Naming Convention
+
+```
+dw.ocapi.shop.<resource>.<sub-resource>.<hookType><METHOD>
+```
+
+Hook types: `before<METHOD>`, `after<METHOD>`, `modify<METHOD>Response`, `validate<Resource>`
+
+## Complete Hook Reference
+
+### Authentication
+
+| Hook | Signature |
+|------|-----------|
+| `dw.ocapi.shop.auth.beforePOST` | `beforePOST(authHeader: String, authType: EnumValue): Status` |
+| `dw.ocapi.shop.auth.afterPOST` | `afterPOST(customer: Customer, authType: EnumValue): Status` |
+| `dw.ocapi.shop.auth.modifyPOSTResponse` | `modifyPOSTResponse(customer: Customer, response, authType): Status` |
+
+### Basket
+
+| Hook | Signature |
+|------|-----------|
+| `dw.ocapi.shop.basket.beforeGET` | `beforeGET(basketId: String): Status` |
+| `dw.ocapi.shop.basket.beforePATCH` | `beforePATCH(basket: Basket, input): Status` |
+| `dw.ocapi.shop.basket.beforePOST_v2` | `beforePOST(basket: Basket): Status` |
+| `dw.ocapi.shop.basket.beforeDELETE` | `beforeDELETE(basket: Basket): Status` |
+| `dw.ocapi.shop.basket.afterPOST` | `afterPOST(basket: Basket): Status` |
+| `dw.ocapi.shop.basket.afterPATCH` | `afterPATCH(basket: Basket, input): Status` |
+| `dw.ocapi.shop.basket.afterDELETE` | `afterDELETE(basketId: String): Status` |
+| `dw.ocapi.shop.basket.modifyGETResponse` | `modifyGETResponse(basket: Basket, response): Status` |
+| `dw.ocapi.shop.basket.modifyPATCHResponse` | `modifyPATCHResponse(basket: Basket, response): Status` |
+| `dw.ocapi.shop.basket.modifyPOSTResponse` | `modifyPOSTResponse(basket: Basket, response): Status` |
+| `dw.ocapi.shop.basket.validateBasket` | `validateBasket(response, duringSubmit: boolean): Status` |
+| `dw.ocapi.baskets.actions.afterMerge` | `afterMerge(basket: Basket): Status` |
+| `dw.ocapi.baskets.actions.afterTransfer` | `afterTransfer(basket: Basket): Status` |
+
+### Basket Billing Address
+
+| Hook | Signature |
+|------|-----------|
+| `dw.ocapi.shop.basket.billing_address.beforePUT` | `beforePUT(basket: Basket, address): Status` |
+| `dw.ocapi.shop.basket.billing_address.afterPUT` | `afterPUT(basket: Basket, address): Status` |
+| `dw.ocapi.shop.basket.billing_address.modifyPUTResponse` | `modifyPUTResponse(basket: Basket, response, address): Status` |
+
+### Basket Customer
+
+| Hook | Signature |
+|------|-----------|
+| `dw.ocapi.shop.basket.customer.beforePUT` | `beforePUT(basket: Basket, customerInfo): Status` |
+| `dw.ocapi.shop.basket.customer.afterPUT` | `afterPUT(basket: Basket, customerInfo): Status` |
+| `dw.ocapi.shop.basket.customer.modifyPUTResponse` | `modifyPUTResponse(basket: Basket, response, customerInfo): Status` |
+
+### Basket Coupon
+
+| Hook | Signature |
+|------|-----------|
+| `dw.ocapi.shop.basket.coupon.beforePOST` | `beforePOST(basket: Basket, couponItem): Status` |
+| `dw.ocapi.shop.basket.coupon.beforeDELETE` | `beforeDELETE(basket: Basket, couponItemId: String): Status` |
+| `dw.ocapi.shop.basket.coupon.afterPOST` | `afterPOST(basket: Basket, couponItem): Status` |
+| `dw.ocapi.shop.basket.coupon.afterDELETE` | `afterDELETE(basket: Basket, couponItemId: String): Status` |
+| `dw.ocapi.shop.basket.coupon.modifyPOSTResponse` | `modifyPOSTResponse(basket: Basket, response, coupon): Status` |
+| `dw.ocapi.shop.basket.coupon.modifyDELETEResponse` | `modifyDELETEResponse(basket: Basket, response, couponItemId): Status` |
+
+### Basket Items
+
+| Hook | Signature |
+|------|-----------|
+| `dw.ocapi.shop.basket.items.beforePOST` | `beforePOST(basket: Basket, items): Status` |
+| `dw.ocapi.shop.basket.items.afterPOST` | `afterPOST(basket: Basket, items): Status` |
+| `dw.ocapi.shop.basket.items.modifyPOSTResponse` | `modifyPOSTResponse(basket: Basket, response, items): Status` |
+| `dw.ocapi.shop.basket.item.beforePATCH` | `beforePATCH(basket: Basket, item): Status` |
+| `dw.ocapi.shop.basket.item.beforeDELETE` | `beforeDELETE(basket: Basket, itemId: String): Status` |
+| `dw.ocapi.shop.basket.item.afterPATCH` | `afterPATCH(basket: Basket, item): Status` |
+| `dw.ocapi.shop.basket.item.afterDELETE` | `afterDELETE(basket: Basket, itemId: String): Status` |
+| `dw.ocapi.shop.basket.item.modifyPATCHResponse` | `modifyPATCHResponse(basket: Basket, response, itemId): Status` |
+| `dw.ocapi.shop.basket.item.modifyDELETEResponse` | `modifyDELETEResponse(basket: Basket, response, itemId): Status` |
+
+### Basket Gift Certificate Item
+
+| Hook | Signature |
+|------|-----------|
+| `dw.ocapi.shop.basket.gift_certificate_item.beforePOST` | `beforePOST(basket: Basket, item): Status` |
+| `dw.ocapi.shop.basket.gift_certificate_item.beforePATCH` | `beforePATCH(basket: Basket, itemId: String, item): Status` |
+| `dw.ocapi.shop.basket.gift_certificate_item.beforeDELETE` | `beforeDELETE(basket: Basket, itemId: String): Status` |
+| `dw.ocapi.shop.basket.gift_certificate_item.afterPOST` | `afterPOST(basket: Basket, item): Status` |
+| `dw.ocapi.shop.basket.gift_certificate_item.afterPATCH` | `afterPATCH(basket: Basket, itemId: String, item): Status` |
+| `dw.ocapi.shop.basket.gift_certificate_item.afterDELETE` | `afterDELETE(basket: Basket, itemId: String): Status` |
+| `dw.ocapi.shop.basket.gift_certificate_item.modifyPOSTResponse` | `modifyPOSTResponse(basket: Basket, response, item): Status` |
+| `dw.ocapi.shop.basket.gift_certificate_item.modifyPATCHResponse` | `modifyPATCHResponse(basket: Basket, response, itemId): Status` |
+| `dw.ocapi.shop.basket.gift_certificate_item.modifyDELETEResponse` | `modifyDELETEResponse(basket: Basket, response, itemId): Status` |
+
+### Basket Payment Instrument
+
+| Hook | Signature |
+|------|-----------|
+| `dw.ocapi.shop.basket.payment_instrument.beforePOST` | `beforePOST(basket: Basket, instrument): Status` |
+| `dw.ocapi.shop.basket.payment_instrument.beforePATCH` | `beforePATCH(basket: Basket, instrument, newInstrument): Status` |
+| `dw.ocapi.shop.basket.payment_instrument.beforeDELETE` | `beforeDELETE(basket: Basket, instrument): Status` |
+| `dw.ocapi.shop.basket.payment_instrument.afterPOST` | `afterPOST(basket: Basket, instrument): Status` |
+| `dw.ocapi.shop.basket.payment_instrument.afterPATCH` | `afterPATCH(basket: Basket, instrument, request): Status` |
+| `dw.ocapi.shop.basket.payment_instrument.afterDELETE` | `afterDELETE(basket: Basket): Status` |
+| `dw.ocapi.shop.basket.payment_instrument.modifyPOSTResponse` | `modifyPOSTResponse(basket: Basket, response, request): Status` |
+| `dw.ocapi.shop.basket.payment_instrument.modifyPATCHResponse` | `modifyPATCHResponse(basket: Basket, response, instrumentId): Status` |
+| `dw.ocapi.shop.basket.payment_instrument.modifyDELETEResponse` | `modifyDELETEResponse(basket: Basket, response, instrumentId): Status` |
+
+### Basket Payment Methods
+
+| Hook | Signature |
+|------|-----------|
+| `dw.ocapi.shop.basket.payment_methods.beforeGET` | `beforeGET(basketId: String): Status` |
+| `dw.ocapi.shop.basket.payment_methods.afterGET` | `afterGET(basket: Basket, paymentMethods): Status` |
+| `dw.ocapi.shop.basket.payment_methods.modifyGETResponse_v2` | `modifyGETResponse(basket: Basket, response): Status` |
+
+### Basket Shipment
+
+| Hook | Signature |
+|------|-----------|
+| `dw.ocapi.shop.basket.shipment.beforePOST` | `beforePOST(basket: Basket, shipment): Status` |
+| `dw.ocapi.shop.basket.shipment.beforePATCH` | `beforePATCH(basket: Basket, shipment: Shipment, shipmentInfo): Status` |
+| `dw.ocapi.shop.basket.shipment.beforeDELETE` | `beforeDELETE(basket: Basket, shipment: Shipment): Status` |
+| `dw.ocapi.shop.basket.shipment.afterPOST` | `afterPOST(basket: Basket, shipment): Status` |
+| `dw.ocapi.shop.basket.shipment.afterPATCH` | `afterPATCH(basket: Basket, shipment: Shipment, shipmentInfo): Status` |
+| `dw.ocapi.shop.basket.shipment.afterDELETE` | `afterDELETE(basket: Basket, shipmentId: String): Status` |
+| `dw.ocapi.shop.basket.shipment.modifyPOSTResponse` | `modifyPOSTResponse(basket: Basket, response, shipment): Status` |
+| `dw.ocapi.shop.basket.shipment.modifyPATCHResponse` | `modifyPATCHResponse(basket: Basket, response, shipmentId): Status` |
+| `dw.ocapi.shop.basket.shipment.modifyDELETEResponse` | `modifyDELETEResponse(basket: Basket, response, shipmentId): Status` |
+
+### Basket Shipment Shipping Address
+
+| Hook | Signature |
+|------|-----------|
+| `dw.ocapi.shop.basket.shipment.shipping_address.beforePUT` | `beforePUT(basket: Basket, shipment: Shipment, address): Status` |
+| `dw.ocapi.shop.basket.shipment.shipping_address.afterPUT` | `afterPUT(basket: Basket, shipment: Shipment, address): Status` |
+| `dw.ocapi.shop.basket.shipment.shipping_address.modifyPUTResponse` | `modifyPUTResponse(basket: Basket, response, address): Status` |
+
+### Basket Shipment Shipping Method
+
+| Hook | Signature |
+|------|-----------|
+| `dw.ocapi.shop.basket.shipment.shipping_method.beforePUT` | `beforePUT(basket: Basket, shipment: Shipment, method): Status` |
+| `dw.ocapi.shop.basket.shipment.shipping_method.afterPUT` | `afterPUT(basket: Basket, shipment: Shipment, method): Status` |
+| `dw.ocapi.shop.basket.shipment.shipping_method.modifyPUTResponse` | `modifyPUTResponse(basket: Basket, response, method): Status` |
+
+### Basket Shipments Shipping Methods
+
+| Hook | Signature |
+|------|-----------|
+| `dw.ocapi.shop.basket.shipments.shipping_methods.beforeGET` | `beforeGET(basketId: String, shipmentId: String): Status` |
+| `dw.ocapi.shop.basket.shipments.shipping_methods.modifyGETResponse_v2` | `modifyGETResponse(basket: Basket, response): Status` |
+
+### Category
+
+| Hook | Signature |
+|------|-----------|
+| `dw.ocapi.shop.category.beforeGET` | `beforeGET(categoryId: String): Status` |
+| `dw.ocapi.shop.category.modifyGETResponse` | `modifyGETResponse(category: Category, response): Status` |
+
+### Customer
+
+| Hook | Signature |
+|------|-----------|
+| `dw.ocapi.shop.customer.beforeGET` | `beforeGET(customerId: String): Status` |
+| `dw.ocapi.shop.customer.beforePOST` | `beforePOST(customerInput): Status` |
+| `dw.ocapi.shop.customer.beforePATCH` | `beforePATCH(customer: Customer, customerInput): Status` |
+| `dw.ocapi.shop.customer.afterPOST` | `afterPOST(customer: Customer, customerInput): Status` |
+| `dw.ocapi.shop.customer.afterPATCH` | `afterPATCH(customer: Customer, customerInput): Status` |
+| `dw.ocapi.shop.customer.modifyGETResponse` | `modifyGETResponse(customer: Customer, response): Status` |
+| `dw.ocapi.shop.customer.modifyPOSTResponse` | `modifyPOSTResponse(customer: Customer, response): Status` |
+| `dw.ocapi.shop.customer.modifyPATCHResponse` | `modifyPATCHResponse(customer: Customer, response): Status` |
+
+### Customer Auth
+
+| Hook | Signature |
+|------|-----------|
+| `dw.ocapi.shop.customer.auth.beforePOST` | `beforePOST(authHeader: String, authType: EnumValue): Status` |
+| `dw.ocapi.shop.customer.auth.afterPOST` | `afterPOST(customer: Customer, authType: EnumValue): Status` |
+| `dw.ocapi.shop.customer.auth.modifyPOSTResponse` | `modifyPOSTResponse(customer: Customer, response, authType): Status` |
+
+### Customer Address
+
+| Hook | Signature |
+|------|-----------|
+| `dw.ocapi.shop.customer.addresses.beforeGET` | `beforeGET(customerId: String): Status` |
+| `dw.ocapi.shop.customer.addresses.beforePOST` | `beforePOST(customer: Customer, address): Status` |
+| `dw.ocapi.shop.customer.addresses.afterPOST` | `afterPOST(customer: Customer, address): Status` |
+| `dw.ocapi.shop.customer.addresses.modifyGETResponse` | `modifyGETResponse(customer: Customer, response): Status` |
+| `dw.ocapi.shop.customer.address.beforeGET` | `beforeGET(customerId: String, addressName: String): Status` |
+| `dw.ocapi.shop.customer.address.beforePATCH` | `beforePATCH(customer: Customer, address, addressInput): Status` |
+| `dw.ocapi.shop.customer.address.beforeDELETE` | `beforeDELETE(customer: Customer, address): Status` |
+| `dw.ocapi.shop.customer.address.afterPATCH` | `afterPATCH(customer: Customer, address, addressInput): Status` |
+| `dw.ocapi.shop.customer.address.afterDELETE` | `afterDELETE(customer: Customer, addressName: String): Status` |
+| `dw.ocapi.shop.customer.address.modifyGETResponse` | `modifyGETResponse(customer: Customer, response): Status` |
+| `dw.ocapi.shop.customer.address.modifyPOSTResponse` | `modifyPOSTResponse(customer: Customer, response, address): Status` |
+| `dw.ocapi.shop.customer.address.modifyPATCHResponse` | `modifyPATCHResponse(customer: Customer, response, addressName): Status` |
+
+### Customer Baskets
+
+| Hook | Signature |
+|------|-----------|
+| `dw.ocapi.shop.customer.baskets.beforeGET` | `beforeGET(customerId: String): Status` |
+| `dw.ocapi.shop.customer.baskets.modifyGETResponse_v2` | `modifyGETResponse(customer: Customer, response): Status` |
+
+### Customer Orders
+
+| Hook | Signature |
+|------|-----------|
+| `dw.ocapi.shop.customer.orders.beforeGET` | `beforeGET(customerId: String): Status` |
+| `dw.ocapi.shop.customer.orders.modifyGETResponse_v2` | `modifyGETResponse(customer: Customer, response): Status` |
+
+### Customer Password
+
+| Hook | Signature |
+|------|-----------|
+| `dw.ocapi.shop.customer.password.beforePUT` | `beforePUT(customer: Customer, passwordInput): Status` |
+| `dw.ocapi.shop.customer.password.afterPUT_v2` | `afterPUT(customer: Customer, passwordInput): Status` |
+| `dw.ocapi.shop.customer.password_reset.beforePOST` | `beforePOST(email: String): Status` |
+| `dw.ocapi.shop.customer.password_reset.afterPOST` | `afterPOST(email: String): Status` |
+
+### Customer Payment Instrument
+
+| Hook | Signature |
+|------|-----------|
+| `dw.ocapi.shop.customer.payment_instruments.beforeGET` | `beforeGET(customerId: String): Status` |
+| `dw.ocapi.shop.customer.payment_instruments.modifyGETResponse_v2` | `modifyGETResponse(customer: Customer, response): Status` |
+| `dw.ocapi.shop.customer.payment_instrument.beforeGET` | `beforeGET(customerId: String, instrumentId: String): Status` |
+| `dw.ocapi.shop.customer.payment_instrument.beforePOST` | `beforePOST(customer: Customer, instrument): Status` |
+| `dw.ocapi.shop.customer.payment_instrument.beforeDELETE` | `beforeDELETE(customer: Customer, instrument): Status` |
+| `dw.ocapi.shop.customer.payment_instrument.afterPOST` | `afterPOST(customer: Customer, instrument): Status` |
+| `dw.ocapi.shop.customer.payment_instrument.afterDELETE` | `afterDELETE(customer: Customer, instrumentId: String): Status` |
+| `dw.ocapi.shop.customer.payment_instrument.modifyGETResponse` | `modifyGETResponse(customer: Customer, response): Status` |
+| `dw.ocapi.shop.customer.payment_instrument.modifyPOSTResponse` | `modifyPOSTResponse(customer: Customer, response, instrument): Status` |
+
+### Customer Product Lists
+
+| Hook | Signature |
+|------|-----------|
+| `dw.ocapi.shop.customer.product_lists.beforeGET` | `beforeGET(customerId: String): Status` |
+| `dw.ocapi.shop.customer.product_lists.beforePOST` | `beforePOST(customer: Customer, productList): Status` |
+| `dw.ocapi.shop.customer.product_lists.afterPOST` | `afterPOST(customer: Customer, productList): Status` |
+| `dw.ocapi.shop.customer.product_lists.modifyGETResponse_v3` | `modifyGETResponse(customer: Customer, response): Status` |
+| `dw.ocapi.shop.customer.product_list.beforeGET` | `beforeGET(customerId: String, listId: String): Status` |
+| `dw.ocapi.shop.customer.product_list.beforePATCH` | `beforePATCH(customer: Customer, productList, listInput): Status` |
+| `dw.ocapi.shop.customer.product_list.beforeDELETE` | `beforeDELETE(customer: Customer, productList): Status` |
+| `dw.ocapi.shop.customer.product_list.afterPATCH` | `afterPATCH(customer: Customer, productList, listInput): Status` |
+| `dw.ocapi.shop.customer.product_list.afterDELETE` | `afterDELETE(customer: Customer, listId: String): Status` |
+| `dw.ocapi.shop.customer.product_list.modifyGETResponse` | `modifyGETResponse(customer: Customer, response): Status` |
+| `dw.ocapi.shop.customer.product_list.modifyPOSTResponse` | `modifyPOSTResponse(customer: Customer, response, productList): Status` |
+| `dw.ocapi.shop.customer.product_list.modifyPATCHResponse` | `modifyPATCHResponse(customer: Customer, response, listId): Status` |
+
+### Customer Product List Items
+
+| Hook | Signature |
+|------|-----------|
+| `dw.ocapi.shop.customer.product_list.items.beforeGET` | `beforeGET(customerId: String, listId: String): Status` |
+| `dw.ocapi.shop.customer.product_list.items.beforePOST` | `beforePOST(customer: Customer, productList, item): Status` |
+| `dw.ocapi.shop.customer.product_list.items.afterPOST` | `afterPOST(customer: Customer, productList, item): Status` |
+| `dw.ocapi.shop.customer.product_list.items.modifyGETResponse_v2` | `modifyGETResponse(customer: Customer, response): Status` |
+| `dw.ocapi.shop.customer.product_list.item.beforeGET` | `beforeGET(customerId: String, listId: String, itemId: String): Status` |
+| `dw.ocapi.shop.customer.product_list.item.beforePATCH` | `beforePATCH(customer: Customer, productList, item, itemInput): Status` |
+| `dw.ocapi.shop.customer.product_list.item.beforeDELETE` | `beforeDELETE(customer: Customer, productList, item): Status` |
+| `dw.ocapi.shop.customer.product_list.item.afterPATCH` | `afterPATCH(customer: Customer, productList, item, itemInput): Status` |
+| `dw.ocapi.shop.customer.product_list.item.afterDELETE` | `afterDELETE(customer: Customer, productList, itemId: String): Status` |
+| `dw.ocapi.shop.customer.product_list.item.modifyGETResponse` | `modifyGETResponse(customer: Customer, response): Status` |
+| `dw.ocapi.shop.customer.product_list.item.modifyPOSTResponse` | `modifyPOSTResponse(customer: Customer, response, item): Status` |
+| `dw.ocapi.shop.customer.product_list.item.modifyPATCHResponse` | `modifyPATCHResponse(customer: Customer, response, itemId): Status` |
+
+### Gift Certificate
+
+| Hook | Signature |
+|------|-----------|
+| `dw.ocapi.shop.gift_certificate.beforePOST` | `beforePOST(giftCertificateCode: String): Status` |
+| `dw.ocapi.shop.gift_certificate.modifyPOSTResponse` | `modifyPOSTResponse(giftCertificate, response): Status` |
+
+### Order
+
+| Hook | Signature |
+|------|-----------|
+| `dw.ocapi.shop.order.beforeGET` | `beforeGET(orderId: String): Status` |
+| `dw.ocapi.shop.order.beforePOST` | `beforePOST(basket: Basket): Status` |
+| `dw.ocapi.shop.order.afterPOST` | `afterPOST(order: Order): Status` |
+| `dw.ocapi.shop.order.modifyGETResponse` | `modifyGETResponse(order: Order, response): Status` |
+| `dw.ocapi.shop.order.modifyPOSTResponse` | `modifyPOSTResponse(order: Order, response): Status` |
+| `dw.ocapi.shop.order.validateOrder` | `validateOrder(response, duringPlace: boolean): Status` |
+
+> **Prefer the order payment-instrument authorization lifecycle.** SCAPI creates the order in
+> `CREATED` status. Follow it with an order payment-instrument `PATCH`, which invokes
+> `dw.order.payment.authorizeCreditCard` or `dw.order.payment.authorize`. The default order-PI
+> `afterPATCH` implementation places the order after authorized coverage reaches the order total.
+> Use `order.afterPOST` placement as the single-phase Commerce transaction alternative described in
+> [SKILL.md](../SKILL.md#alternative-authorize-and-place-in-orderafterpost).
+
+### Order Payment Instrument
+
+| Hook | Signature |
+|------|-----------|
+| `dw.ocapi.shop.order.payment_instrument.beforePOST` | `beforePOST(order: Order, instrument): Status` |
+| `dw.ocapi.shop.order.payment_instrument.beforePATCH` | `beforePATCH(order: Order, instrument, newInstrument): Status` |
+| `dw.ocapi.shop.order.payment_instrument.beforeDELETE` | `beforeDELETE(order: Order, instrument): Status` |
+| `dw.ocapi.shop.order.payment_instrument.afterPOST` | `afterPOST(order: Order, instrument: OrderPaymentInstrumentRequest, successfullyAuthorized: boolean): Status` |
+| `dw.ocapi.shop.order.payment_instrument.afterPATCH` | `afterPATCH(order: Order, instrument: OrderPaymentInstrument, newInstrument: OrderPaymentInstrumentRequest, successfullyAuthorized: boolean): Status` |
+| `dw.ocapi.shop.order.payment_instrument.afterDELETE` | `afterDELETE(order: Order, instrumentId: String): Status` |
+| `dw.ocapi.shop.order.payment_instrument.modifyPOSTResponse` | `modifyPOSTResponse(order: Order, response, request): Status` |
+| `dw.ocapi.shop.order.payment_instrument.modifyPATCHResponse` | `modifyPATCHResponse(order: Order, response, instrumentId): Status` |
+| `dw.ocapi.shop.order.payment_instrument.modifyDELETEResponse` | `modifyDELETEResponse(order: Order, response, instrumentId): Status` |
+
+The order PI `POST` and `PATCH` authorize the affected instrument before calling their `after*`
+hook. `successfullyAuthorized` reports whether the selected `dw.order.payment.authorize*` hook
+succeeded. A non-null return ends hook execution; return `undefined` on success when the platform's
+default coverage-based placement implementation must still run. For `CREDIT_CARD`, supply
+payment-card data. A customer payment-instrument ID causes Commerce to copy the customer's PI for
+authorization; otherwise the authorization details come from the request. Request amount and card
+security code remain available to `authorizeCreditCard` in either case.
+
+### Order Payment Methods
+
+| Hook | Signature |
+|------|-----------|
+| `dw.ocapi.shop.order.payment_methods.beforeGET` | `beforeGET(orderId: String): Status` |
+| `dw.ocapi.shop.order.payment_methods.modifyGETResponse_v2` | `modifyGETResponse(order: Order, response): Status` |
+
+### Product
+
+| Hook | Signature |
+|------|-----------|
+| `dw.ocapi.shop.product.beforeGET` | `beforeGET(productId: String): Status` |
+| `dw.ocapi.shop.product.modifyGETResponse` | `modifyGETResponse(product: Product, response): Status` |
+
+### Product Search
+
+| Hook | Signature |
+|------|-----------|
+| `dw.ocapi.shop.product_search.beforeGET` | `beforeGET(searchRequest): Status` |
+| `dw.ocapi.shop.product_search.modifyGETResponse` | `modifyGETResponse(searchResult, response): Status` |
+
+### Promotion
+
+| Hook | Signature |
+|------|-----------|
+| `dw.ocapi.shop.promotion.beforeGET` | `beforeGET(promotionId: String): Status` |
+| `dw.ocapi.shop.promotion.modifyGETResponse` | `modifyGETResponse(promotion: Promotion, response): Status` |
+| `dw.ocapi.shop.promotions.beforeGET` | `beforeGET(promotionIds: String): Status` |
+| `dw.ocapi.shop.promotions.modifyGETResponse` | `modifyGETResponse(promotions, response): Status` |
+
+### Search Suggestion
+
+| Hook | Signature |
+|------|-----------|
+| `dw.ocapi.shop.search_suggestion.beforeGET` | `beforeGET(query: String): Status` |
+| `dw.ocapi.shop.search_suggestion.modifyGETResponse` | `modifyGETResponse(suggestions, response): Status` |
+
+### Store
+
+| Hook | Signature |
+|------|-----------|
+| `dw.ocapi.shop.store.beforeGET` | `beforeGET(storeId: String): Status` |
+| `dw.ocapi.shop.store.modifyGETResponse` | `modifyGETResponse(store: Store, response): Status` |
+| `dw.ocapi.shop.stores.beforeGET` | `beforeGET(storeIds: String): Status` |
+| `dw.ocapi.shop.stores.modifyGETResponse` | `modifyGETResponse(stores, response): Status` |
+
+## Common Patterns
+
+### Validation (return error to reject request)
+
+```javascript
+exports.beforePUT = function(basket, address) {
+    if (!isValidZipCode(address.postalCode)) {
+        var status = new Status(Status.ERROR);
+        status.addDetail('field', 'postalCode');
+        status.addDetail('message', 'Invalid postal code');
+        return status;
+    }
+    return new Status(Status.OK);
+};
+```
+
+### Modify Response (add custom properties)
+
+```javascript
+exports.modifyGETResponse = function(product, response) {
+    response.c_customField = 'value';
+    response.c_extendedInfo = { source: 'hook' };
+};
+```
+
+### Custom Properties
+
+Add `c_` prefixed properties in modifyResponse hooks. Supported types: String, Integer, Double, Boolean, Date, Set of Strings.
+
+## Notes
+
+- All hooks return `dw.system.Status` - return `Status.OK` to continue, `Status.ERROR` to reject
+- Hooks with `_v2` or `_v3` suffix are newer versions with updated signatures
+- Response objects in `modify*Response` hooks can be modified in place
+- Custom query parameters with `c_` prefix are accessible via `request.httpParameterMap`

package/content/guidance/b2c/b2c-hooks/references/ORDER-HOOK-LIFECYCLE.md

@@ -0,0 +1,169 @@
+# Shopper Order Payment Lifecycle (SCAPI/OCAPI)
+
+## Recommended Lifecycle
+
+Use the documented Shopper Orders payment-instrument authorization seam:
+
+```text
+POST /orders
+  |
+  v
+beforePOST(basket) -> platform creates and commits order in CREATED -> afterPOST(order)
+  |
+  v
+PATCH /orders/{orderNo}/payment-instruments/{paymentInstrumentId}
+  |
+  +-> order.payment_instrument.beforePATCH(order, persistentPI, requestPI)
+  +-> platform updates/resolves the payment instrument
+  +-> dw.order.payment.authorizeCreditCard or dw.order.payment.authorize
+  +-> order.payment_instrument.afterPATCH(..., successfullyAuthorized)
+  +-> default afterPATCH places when authorized coverage >= order total
+  +-> order.payment_instrument.modifyPATCHResponse(...)
+  |
+  v
+NEW = placed; CREATED = not yet placed
+```
+
+Do not perform a slow gateway call in `order.afterPOST` by default. Let order creation commit first,
+then authorize through the order-PI endpoint. This keeps a durable order number available when the
+gateway declines, times out, or returns an indeterminate result.
+
+## Hook Responsibilities
+
+| Phase | Responsibility |
+|-------|----------------|
+| `order.beforePOST` | Validate the basket at the final server-owned boundary before order creation |
+| `order.afterPOST` | Add fast order metadata only; do not authorize/place in the recommended flow |
+| `order.payment_instrument.beforePATCH` | Reject untrusted method, amount, processor, ownership, and token-provenance input before the gateway call |
+| `dw.order.payment.authorizeCreditCard` | Authorize credit cards and persist the payment transaction result |
+| `dw.order.payment.authorize` | Authorize non-card instruments and persist the payment transaction result |
+| `order.payment_instrument.afterPATCH` | Use `successfullyAuthorized`, perform final persistent-state checks, and return no value on success |
+| Platform default `afterPATCH` | Place a still-`CREATED` order when authorized payment coverage equals or exceeds the total |
+| `order.payment_instrument.modifyPATCHResponse` | Shape the response or perform post-placement reporting; determine success from persisted order status |
+
+The `afterPATCH` signature is:
+
+```javascript
+afterPATCH(order, paymentInstrument, newPaymentInstrument, successfullyAuthorized)
+```
+
+- `paymentInstrument` is the updated persistent order PI.
+- `newPaymentInstrument` is request data and remains untrusted.
+- `successfullyAuthorized` is the payment-hook result reduced to a boolean.
+- A non-null `Status` ends hook execution. Return `undefined` after successful validation so the
+  platform placement implementation still runs.
+
+Use `request.custom` to retain a richer authorization outcome within the request when the boolean is
+insufficient. For example, distinguish a deterministic decline from a gateway timeout or manual
+review. Do not add object metadata solely as inter-hook transport.
+
+## Payment-Instrument Resolution
+
+The order-PI endpoint invokes:
+
+- Require an applicable payment method; include payment-card data when the method is `CREDIT_CARD`.
+- `dw.order.payment.authorizeCreditCard` when the request includes payment-card data or the PI has a
+  credit-card type.
+- `dw.order.payment.authorize` otherwise.
+
+For a saved payment method, pass the documented customer payment-instrument ID (named
+`customer_payment_instrument_id` in the OCAPI documentation; generated SCAPI clients can expose a
+camel-case property). Commerce resolves the reference from the order customer's instruments and
+copies that customer PI for authorization; an unknown ID throws. Request amount and card security
+code are still propagated to `authorizeCreditCard`.
+
+Without that reference, the payment hook input is populated from request data such as payment-card
+or bank-account information. Do not assume this `paymentDetails` argument is the same object instance
+as the persistent PI attached to `order`. Resolve the persistent instrument when the integration
+stored token or approval state on it. Treat reusable payment tokens and all `c_*` request properties
+as untrusted input; possession of a client-supplied token does not prove wallet ownership.
+
+## Success and Failure Handling
+
+After the final required payment-instrument request:
+
+- Treat `NEW` as placement success.
+- Treat `CREATED` as not placed. During a multi-instrument flow this is expected until total
+  authorized coverage is sufficient.
+- On a deterministic authorization failure, call the Shopper Orders fail action with
+  `reopenBasket=true` to persist the failed order and restore the basket.
+- On timeout or indeterminate provider state, preserve the `CREATED` order for reconciliation. Do not
+  automatically retry or reopen the basket when doing so could duplicate an authorization.
+
+Current Shopper Orders v1 failure request:
+
+```http
+POST /checkout/shopper-orders/v1/organizations/{organizationId}/orders/{orderNo}/actions/fail?siteId={siteId}&reopenBasket=true
+Authorization: Bearer {shopperToken}
+Content-Type: application/json
+
+{
+  "reasonCode": "payment_auth_failure"
+}
+```
+
+Supported payment-oriented reason codes are `payment_auth_failure`, `payment_confirm_failure`, and
+`payment_capture_failure`. Confirm the current schema before generating version-specific code.
+
+## Alternative: Complete Checkout in `order.afterPOST`
+
+Choose this option when checkout should create, authorize, and perform the Commerce-side
+place-or-fail transition in one server-side phase, or when a processor cannot participate in the
+order-PI authorization lifecycle. It reduces storefront orchestration and makes `order.afterPOST`
+own the complete `CREATED -> NEW/FAILED` transition. The external gateway operation is not rolled
+back with the Commerce transaction.
+
+Important transaction rules:
+
+- `order.afterPOST` runs inside the order-creation transaction. Do not wrap `OrderMgr.placeOrder`,
+  `OrderMgr.failOrder`, or PI mutations in another `Transaction.wrap`.
+- `Status.ERROR` rolls back the complete order creation; no order record survives.
+- Returning success after `OrderMgr.failOrder` commits a queryable failed order but does not produce
+  an HTTP error by itself.
+- Manually verify every payment instrument and total authorized coverage before placement.
+
+These rollback semantics were empirically verified on sandbox zzpq-019 on 2026-06-24: an
+`afterPOST` `Status.ERROR` returned HTTP 400 and left no searchable order.
+
+### Two-Hook Variant
+
+If this flow must both persist a failed order and return an HTTP error, split the behavior:
+
+```javascript
+var OrderMgr = require('dw/order/OrderMgr');
+var Status = require('dw/system/Status');
+
+exports.afterPOST = function (order) {
+    var result = authorizePayment(order);
+    if (result.declined) {
+        OrderMgr.failOrder(order, false);
+        request.custom.paymentDecline = {
+            code: result.code,
+            message: result.message
+        };
+        return new Status(Status.OK); // commit the FAILED order
+    }
+
+    var placeStatus = OrderMgr.placeOrder(order);
+    if (placeStatus.error) {
+        return new Status(Status.ERROR, 'PLACE_FAILED');
+    }
+};
+
+exports.modifyPOSTResponse = function () {
+    var decline = request.custom.paymentDecline;
+    if (decline) {
+        return new Status(Status.ERROR, decline.code, decline.message);
+    }
+};
+```
+
+This remains a valid single-phase checkout option. Prefer the separate order-PI authorization plus
+Shopper Orders fail action when durable intermediate state, shorter order creation, payment-extension
+alignment, or explicit recovery control matters more than atomic one-request orchestration.
+
+## Cross-References
+
+- [B2C Hooks](../SKILL.md#headless-order-payment-use-the-order-pi-authorization-seam) — primary implementation guidance
+- `b2c-ordering` skill — order statuses and Shopper Orders failure handling
+- [OCAPI/SCAPI Hooks reference](./OCAPI-SCAPI-HOOKS.md) — hook signature list