Validations

Validations are external checks that verify whether an order can proceed to completion. They allow you to integrate with external systems to validate business rules, inventory availability, pricing accuracy, and other conditions before a purchase is finalized.

Purpose

Validations serve as gatekeepers in the checkout flow, enabling you to:

• Verify stock availability in external inventory systems
• Check real-time pricing against external pricing engines
• Perform fraud detection and risk assessment
• Validate customer credit limits or account status
• Enforce business rules such as minimum order values or restricted products
• Verify delivery addresses against shipping provider requirements

Unlike hooks which modify order data, validations return a pass/fail result and can prevent an order from proceeding if conditions are not met.

How Validations Work

Validations are triggered explicitly by calling the validate endpoint on an order. This gives you control over when validation occurs in your checkout flow.

Triggering Validation

To validate an order, make a POST request to the validate endpoint:

POST /api/v0/checkout/orders/{orderId}/validate
X-Merchant: {merchant}
X-Channel: {channel}
Authorization: Bearer {token}
Host: {slug}.api-se.playground.norce.tech/checkout/order

Validation Response

When all validations pass, the endpoint returns a successful response and the order can proceed to payment completion.

When one or more validations fail, the endpoint returns an HTTP 400 response with aggregated error details from all failing validators:

400 Bad Request
Content-Type: application/json

{
  "errors": [
    {
      "code": "STOCK_UNAVAILABLE",
      "message": "Product SKU-12345 is out of stock",
      "source": "inventory-validator"
    },
    {
      "code": "PRICE_CHANGED",
      "message": "Price for SKU-67890 has changed since cart was created",
      "source": "pricing-validator"
    }
  ]
}

The aggregated errors allow your frontend to display all validation issues to the customer at once, rather than requiring multiple validation attempts.

Configuring Validations

Validations are configured through the Configuration API, similar to other NCO extensions. You define which external endpoints should be called during validation and what conditions trigger them.

Example: Stock Availability Validator

This example configures a validation that checks stock availability with an external inventory system:

PUT /api/v1/configuration/merchants/{merchant}/channels/{channel}/configurations/stock_validation
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": "stock_validation",
  "active": true,
  "order": {
    "validations": [
      {
        "description": "Verify stock availability before purchase",
        "reference": "stock-check-001",
        "invoke": "https://your-inventory-system.com/api/validate-stock"
      }
    ]
  }
}

Building a Validation Endpoint

Your validation endpoint receives the current order state and must return a response indicating whether validation passed or failed.

Request Format

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

{
  "orderId": "abc123",
  "cart": {
    "items": [
      {
        "sku": "SKU-12345",
        "quantity": 2,
        "price": 199.00
      }
    ]
  },
  "customer": {
    "email": "customer@example.com"
  }
}

Response Format

Your endpoint should return HTTP 200 for successful validation:

200 OK

For failed validation, return HTTP 400 with error details:

400 Bad Request
Content-Type: application/json

{
  "code": "STOCK_UNAVAILABLE",
  "message": "Insufficient stock for SKU-12345. Only 1 available."
}

Best Practices

When implementing validations, consider the following:

Performance: Validations are synchronous and block the checkout flow. Keep your validation endpoints fast (under 2 seconds) to maintain a good customer experience.

Error Messages: Provide clear, customer-friendly error messages that explain what went wrong and how to resolve the issue.

Idempotency: Validation endpoints may be called multiple times for the same order. Ensure your implementation handles repeated calls gracefully.

Graceful Degradation: Consider how your checkout should behave if a validation service is unavailable. You may want to implement timeouts and fallback behavior.

Next Steps

• Learn about Hooks for modifying order data during checkout
• Explore Custom Notifications for asynchronous event handling
• Return to Extending the Checkout for an overview of all extension points