External order validation

How to validate orders via external services

Sometimes, you may need to perform custom validation on orders, as an additional step before the order placement. For example, this could be useful in case you want to support different or more complex validation rules specific to your business logic.

Triggering external validation

curl -g -X PATCH \
  'https://yourdomain.commercelayer.io/api/orders/xYZkjABcde' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "orders",
      "id": "xYZkjABcde",
      "attributes": {
        "_validate": true
      }
    }
  }'

Upon this call, Commerce Layer triggers a POST request to the specified external_validation_url endpoint, sending the order payload (including the related line items) in the request body.

To check if an external order validation has been triggered you can inspect the order's validations_count attribute and make sure it gets incremented.

Request

The request payload is a JSON:API-compliant object you can query to perform your own computation. Aside from the target resourceorder in this specific case — some relationships are also included to avoid useless API roundtrips:

  • billing_address

  • shipping_address

  • line_items.item

  • line_items

  • market

  • customer

{
  "data": {
    "id": "wBXVhKzrnq",
    "type": "orders",
    "links": { ... },
    "attributes": { ... },
    "relationships": { ... },
    "meta": { ... }
  },
  "included": [
    {
      "id": "DvlGRmhdgX",
      "type": "markets",
      "links": { ... },
      "attributes": { ... },
      "relationships": { ... },
      "meta": { ... }
    },
    {
      "id": "kdPgtRXOKL",
      "type": "line_items",
      "links": { ... },
      "attributes": { ... },
      "relationships": { ... },
      "meta": { ... }
    },
    {
      "id": "XGZwpOSrWL",
      "type": "skus",
      "links": { ... },
      "attributes": { ... },
      "relationships": { ... },
      "meta": { ... }
    }
    {
      "id": "BgnguJvXmb",
      "type": "addresses",
      "links": { ... },
      "attributes": { ... },
      "relationships": { ... },
      "meta": { ... }
    },
    {
      "id": "AlrkugwyVW",
      "type": "addresses",
      "links": { ... },
      "attributes": { ... },
      "relationships": { ... },
      "meta": { ... }
    },
    { ... }
  ]
}

In case the call to your external endpoint goes timeout, responds with an internal server error, or is blocked by the open circuit breaker, the API keeps responding with a 200 OK status code. No validation errors are attached to the order, but the validations_count value and the circuit breaker internal counter (if closed) are incremented.

Response

Your service response (or error) must match the format described in the example below.

Remember to pass the attribute-specific errors within the data object, associating them with the related order's attribute. If some error is not associated with any particular attribute use the base key (automatically filled with the error messages associated with any invalid attribute, if present).

Example

The successful response must be a JSON object, returning an empty body, meaning that the external logic running the validation has found no errors:

{
  "success": true,
  "data": {}
}

Security

When you activate external validation, a shared secret is generated at the market level. We recommend verifying the callback authenticity by signing the payload with that shared secret and comparing the result with the callback signature header.

Last updated