Building The Checkout

Validation

Vanilo Cloud comes with sensible defaults for checkout field validation, but you can customize them for your own needs.

To set your own configuration rules, you need to add entries to the vanilo.json configuration file.

{
  "checkout": {
    "validation": {
      "rules": {
        "phone": "required|min:10|max:25"        
      }
    }    
  }
}

The setting above will make the phone field mandatory and enforce its length to be between 10 and 25 characters.

The validation rule syntax comes from Laravel, see their documenation for more details

Fields Available for Custom Validation Rules

This is the list of the fields available for custom validation rules, along with their default values:

Field	Default Validation Rule Value
email	required|email:rfc,spoof,dns
phone	sometimes|nullable|min:4|max:22
billpayer	░░░░░░░░░░░░░░░░░░░░░░░
⮡ firstname	required|min:2|max:255
⮡ lastname	required|min:2|max:255
⮡ company_name	required_if:billpayer.is_organization,1|nullable|min:5
⮡ tax_nr	sometimes|nullable|min:5
⮡ address	░░░░░░░░░░░
⮡address	required|min:12|max:384
⮡postalcode	nullable|min:4|max:12
⮡city	nullable|min:2|max:255
payment_method_id*	sometimes|integer|exists:payment_methods,id
shipping_method_id*	sometimes|integer|exists:shipping_methods,id
shippingAddress	░░░░░░░░░░░
⮡address	required_unless_any_true:no_shipping,ship_to_billing_address
⮡postalcode	nullable|min:4|max:12
⮡city	nullable|min:2|max:255
items.*.configuration	-

^*: The optional, per-customer payment/shipping method restrictions will always be applied on top of the default/custom rules.

Configuration Sample vanilo.json:

{
  "checkout": {
    "validation": {
      "rules": {
        "phone": "required|min:10|max:25",
        "billpayer": {
          "firstname": "required|min:1|max:40",
          "lastname": "sometimes|nullable|min:1|max:30",
          "address": {
            "postalcode": "required|size:5"
          }
        },
        "shippingAddress": {
          "postalcode": "required|size:5"
        }
      }
    }    
  }
}

Bear in mind, that channel-based validation rules - if exist - will override the rules defined for the shop

Special Validation Rules

Besides the built-in Laravel validation rules, Vanilo Cloud offers several extra rules as well. Feel free to use them optionally

Required Key With Product Property

This rule can be applied to the items.*.configuration field on checkout and StoreFront API's create order request.

The name of the rule is required_key_with_product_property and has 2 mandatory input parameters:

{
  "checkout": {
    "validation": {
      "rules": {
        "items.*.configuration": "required_key_with_product_property:template_key,configuration_id"
      }
    }
  }
}

The rule above means that "if the product in the order item has a template_key property, then the customization_key must be present and not empty in the item configuration array".

This can be used to enforce configuration for order items of products that are configurable and customizable. This can be useful for customizable/configurable products where the configuration is mandatory, for example custom printed t-shirts, mugs, etc.

The rule has an optional, 3rd parameter:

{
  "checkout": {
    "validation": {
      "rules": {
        "items.*.configuration": "required_key_with_product_property:template_key,customization_key,global_job_id"
      }
    }
  }
}

The meaning of the 3rd parameter is this: "if the item product has a template_key property value, then either the customization_key or the global_job_id must be present and not empty in the item configuration array".

Shortly, the 3rd parameter defines an alternative config key that is also acceptable besides the other one.

Required Unless Any True

The name of the rule is required_unless_any_true and has one or more input parameters.

The meaning of the rule is that the given field is required unless any of parameters is true.

Example:

{
  "checkout": {
    "validation": {
      "rules": {
        "shippingAddress": {
          "address": "required_unless_any_true:no_shipping,ship_to_billing_address"
        }
      }      
    }    
  }  
}

The rule above means: The address field is required unless no_shipping or ship to billing address is true (checked).

The "is true" comparison is "truthy-style", meaning that besides true, "1", "true", "on", and "yes" values are interpreted as true, other values are considered false.