Hooks

Hooks are synchronous callbacks that allow you to modify order data during the checkout process. When triggered, your hook endpoint receives the current order state and returns JSON Patch operations that NCO applies to update the order.

Purpose

Hooks enable you to integrate external business logic into the checkout flow, including:

• Updating shipping options based on cart contents or delivery address
• Recalculating prices using external pricing engines
• Applying dynamic discounts or promotions from external systems
• Enriching order data with information from CRM or ERP systems
• Modifying payment options based on customer profile or order value

Unlike validations which approve or deny purchases, hooks actively modify the order data as it flows through the checkout.

How Hooks Work

Hooks are triggered at specific points in the checkout flow based on their configured scope. When a hook is invoked, NCO sends the current order state to your endpoint, and your endpoint returns JSON Patch operations describing how to modify the order.

Hook Execution Order

When multiple hooks are configured, they execute in a specific order:

1. Target hooks - Hooks targeting specific adapters
2. Scope hooks - Hooks targeting specific data scopes
3. Adapter hooks - Hooks defined by payment/shipping adapters

This ordering ensures that your custom hooks can modify data before adapter-specific logic runs.

Scopes

Hooks are configured with a scope that determines which part of the order they can modify. Available scopes include:

The scope determines both when your hook is triggered and what data it receives.

Configuring Hooks

Hooks are configured through the Configuration API. You define the scope, trigger conditions, and the endpoint to invoke.

Example: Dynamic Shipping Options

This example configures a hook that updates shipping options based on the delivery address:

PUT /api/v1/configuration/merchants/{merchant}/channels/{channel}/configurations/shipping_hook
X-Merchant: {merchant}
X-Channel: {channel}
Authorization: Bearer super-secret-and-valid-token
Host: {slug}.api-se.playground.norce.tech/checkout/configuration
Content-Type: application/json

{
  "$schema": "https://{slug}.api-se.playground.norce.tech/checkout/configuration/openapi/v1/schemas/configuration.json",
  "id": "shipping_hook",
  "active": true,
  "order": {
    "hooks": [
      {
        "description": "Update shipping options based on address",
        "reference": "shipping-options-001",
        "scope": "/shippings",
        "invoke": "https://your-shipping-service.com/api/calculate-options"
      }
    ]
  }
}

Building a Hook Endpoint

Your hook endpoint receives the current order state for the configured scope and returns JSON Patch operations to modify the order.

Request Format

NCO sends a POST request to your hook endpoint with the relevant order data:

{
  "orderId": "abc123",
  "scope": "/shippings",
  "data": {
    "shippings": [
      {
        "id": "standard",
        "name": "Standard Delivery",
        "price": 49.00
      }
    ],
    "selectedShipping": null
  },
  "context": {
    "cart": {
      "totalWeight": 2500,
      "totalValue": 599.00
    },
    "customer": {
      "address": {
        "postalCode": "12345",
        "country": "SE"
      }
    }
  }
}

Response Format

Your endpoint returns an array of JSON Patch operations (RFC 6902) that describe how to modify the order:

200 OK
Content-Type: application/json

[
  {
    "op": "add",
    "path": "/shippings/-",
    "value": {
      "id": "express",
      "name": "Express Delivery",
      "price": 99.00,
      "estimatedDelivery": "2027-01-15"
    }
  },
  {
    "op": "replace",
    "path": "/shippings/0/price",
    "value": 0.00
  },
  {
    "op": "replace",
    "path": "/shippings/0/name",
    "value": "Free Standard Delivery"
  }
]

JSON Patch Operations

The following JSON Patch operations are supported:

Example: Price Recalculation Hook

This hook recalculates item prices based on an external pricing engine:

[
  {
    "op": "replace",
    "path": "/cart/items/0/price",
    "value": 189.00
  },
  {
    "op": "add",
    "path": "/cart/items/0/priceNote",
    "value": "Member discount applied"
  },
  {
    "op": "replace",
    "path": "/cart/totals/subtotal",
    "value": 378.00
  }
]

Best Practices

When implementing hooks, consider the following:

Performance: Hooks are synchronous and block the checkout flow. Keep response times under 2 seconds to maintain a good customer experience. Consider caching frequently accessed data.

Idempotency: Your hook may be called multiple times for the same order state. Ensure your implementation produces consistent results for identical inputs.

Error Handling: If your hook encounters an error, return an appropriate HTTP error code. NCO will handle the error according to your configuration (fail the operation or continue without the hook's modifications).

Scope Boundaries: Only return patch operations that modify data within your configured scope. Operations targeting other scopes will be rejected.

Validation: Validate your JSON Patch operations before returning them. Invalid operations will cause the hook to fail.

Next Steps

• Learn about Validations for approving or denying purchases
• Explore Custom Notifications for asynchronous event handling
• Return to Extending the Checkout for an overview of all extension points