Skip to main content
Omneya
EN
Start test system Try it
Developer docs menu

Validate an order

Check an order against all rules without creating anything, and read how the shop would resolve customer and items.

What validation does

POST /orders/validate takes the same body as POST /orders and runs the same checks with the same error codes. It creates nothing: no order, no customer, no link between your IDs and the shop’s records, no stock reservation.

Use it while you build your integration, or before you send an order you are not sure about. The key needs the scope orders.write.

Request

curl -s -X POST https://shop.example.com/api/v1/orders/validate \
  -H "Authorization: Bearer $OMNEYA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data @order.json

Each shop has its own address; replace shop.example.com. The body is the order you would send to POST /orders, for example the one in Send an order.

Response for a valid order

A valid order answers 200 OK:

{
  "data": {
    "valid": true,
    "duplicate": false,
    "order_id": null,
    "resolved": {
      "customer": { "match": "new_or_email", "customer_id": null },
      "items": [
        {
          "variation_id": 3311,
          "sku": "SKU-1001",
          "article_id": 812,
          "quantity": 2,
          "price_source": "app"
        }
      ],
      "payment_method_id": 3,
      "referrer_id": 17,
      "order_status_id": 1,
      "shipping_cost_source": "system"
    },
    "warnings": []
  }
}

resolved shows how the shop would interpret the order:

  • customer.match is existing when the customer is already known through your access or referenced by a valid customer number; customer_id then holds the shop’s customer number. It is new_or_email when the customer would be created or matched by email. Which of the two happens is decided only when the order is created, so validation does not reveal whether an email address belongs to an existing customer.
  • items shows the item each line resolves to, with its sku, the main article_id and the shop’s variation_id. price_source is app when you sent a price, system when the shop’s price would apply.
  • referrer_id is the referrer you sent, or the default referrer of your key.
  • order_status_id is the order status you sent, or the shop’s incoming order status the order would start in.
  • shipping_cost_source is app when you sent shipping costs, system when the shop would calculate them.

Duplicates

If an order with the same external_order_id already exists for your access, duplicate is true and order_id holds its ID:

{
  "data": {
    "valid": true,
    "duplicate": true,
    "order_id": 48211,
    "resolved": { "...": "..." },
    "warnings": []
  }
}

Sending this order to POST /orders would return the existing order with 200. If that order has since been deleted in the shop, validation still reports duplicate: true, while POST /orders answers 409 order_deleted.

Response for an invalid order

Errors use the same format and codes as POST /orders: 422 validation_failed with all problems per field, or 422 client_not_configured if your access is not fully set up.

{
  "error": {
    "code": "validation_failed",
    "message": "The order was not created.",
    "details": {
      "items.0.sku": [{ "code": "unknown_article", "message": "Article 'SKU-9999' is not known." }]
    }
  }
}

See Errors.

Limits of validation

Validation checks the data and resolves customer and items. It does not calculate prices, shipping method, shipping costs or totals; those are determined only when the order is created.

One check also happens only at creation: for items with unit_price_gross, the shop needs a tax rate for the delivery country. If none is configured, POST /orders answers 422 with article_tax_unresolved for that item, even though validation passed.

A passed validation is therefore a strong indication, not a guarantee. Always handle the response of POST /orders itself.