Submitting Ordered Item Additional Fields from Templates

If you want to submit ordered item additional fields and values using the methods in this support article, you must ensure the field has been created in the Ordered Items Fields UI.

Validation

Please note the following validation is imposed on Ordered Item Additional Fields weather submitted via templates or duplicated from the associated product field.

• A maximum of 10 ordered item additional fields for each ordered item submitted in this way
• Each ordered item additional field value is limited to a maximum of 150 characters.

Validation Failure Behaviour

If you submit an order with Additional Fields, any that fail validation, including if submitting more than the maximum threshold of 10 will be logged to the Error Log. You will be able to see the error and the submitted value. By default the order will still be created. If you want order creation to fail if any additional fields fail validation then you may update the setting Store -> Settings -> Aurora -> Order -> Ordered Item Additional Field
validation failure to "Fail Order".

📘

You should consider setting the "Ordered Item Additional Field
validation failure" mode to "Fail Order" on test sites so that issues with this functionality don't go undiscovered.

Submitting Ordered Item Additional Fields as Key Value Pairs

To submit an Ordered Item Additional Field as a Key Value Pair you can update the templates to include this data at the time of submission.

Checkout

To submit the ordered item additional fields in a standard checkout flow, simply submit a hidden field for each basket item in the form with the name ordered_items_additional_fields[BASKET_ID][ADDITIONAL_FIELD_NAME] and the value being the value to store. This could be done by looping over the $mini_basket to get access to each items Basket ID, and the underlying Product record. An example follows:

{foreach from=$mini_basket item=basket_item}
  <input name="ordered_items_additional_fields[{$basket_item.id}][my_field_1]" type="hidden" value="my_value_1">
  <input name="ordered_items_additional_fields[{$basket_item.id}][my_field_2]" type="hidden" value="my_value_2">
{/foreach}

Non-checkout Flows

When creating a checkout through the Ajax endpoint /checkout/setup-submit you can submit a data key ordered_items_additional_fields with an object mapping Basket IDs to an object representing the key-value pairs for each Ordered Item Additional Field. An example follows, please be sure to view both the Smarty and JavaScript files in the following example:

let submitData = {
  // ... Data for the setup-submit endpoint
};

// Merge in the order fields hidden inputs defined in the template.
$.extend(submitData, $('.order-fields input').serializeForm())
    
$.ajax({
  url: "/checkout/setup-submit?checkout_type=proxy-adyen",
  type: "POST",
  data: submitData,
});

<div class="order-fields">
  {foreach from=$minibasket item=basket_item}
    <input name="ordered_items_additional_fields[{$basket_item.id}][my_field_1]" type="hidden" value="my_value_1">
    <input name="ordered_items_additional_fields[{$basket_item.id}][my_field_2]" type="hidden" value="my_value_2">
  {/foreach}
</div>

The above example is an abstract example of how this works in general. For a working example of this in the AuroraDemo template files please refer to the following:

• example.com/basket/adyen-order-fields.tpl.html - This template file sets up the hidden fields which are serialised by the aapc.js component. This template file is included by the example.com/basket/index.tpl.html template file.
• example.com/_js/aapc.js - aapc.js component. Look at the $.aapc.setupSubmit function which serialises the fields from the following JQuery selector #adyen-order-fields input, which matches the div containing the hidden fields in the adyen-order-fields.tpl.html file.

PDP Flows

The PDP solution to this is similar to the Non-Checkout flows detailed above, however, since only a single item is purchased and the Basket ID is not known at the time the template is rendered, it is acceptable to submit the ordered_item_additional_fields not grouped by Basket ID. An example follows, please be sure to view both the Smarty and JavaScript files in the following example:

let submitData = {
  // ... Data for the setup-submit endpoint
};

// Merge in the order fields hidden inputs defined in the template.
$.extend(submitData, $('.order-fields input').serializeForm())

$.ajax({
  url: "/checkout/setup-submit?checkout_type=proxy-adyen",
  type: "POST",
  data: submitData,
});

<div class="order-fields">
  <input name="ordered_items_additional_fields[my_field_1]" type="hidden" value="my_value_1">
  <input name="ordered_items_additional_fields[my_field_2]" type="hidden" value="my_value_2">
</div>

An example of this is available in the following AuroraDemo template files:

• example.com/products/adyen-order-fields.tpl.html - This template file sets up the hidden fields which are serialised by the aapc.js component. This template file is included by the example.com/products/details.tpl.html template file. Please note that the fields are not being grouped by any Basket ID in this file as opposed to the implementation in the Non-Checkout flows example above.
• example.com/_js/aapc.js - aapc.js component. Look at the $.aapc.setupSubmit function which serialises the fields from the following JQuery selector #adyen-order-fields input, which matches the div containing the hidden fields in the adyen-order-fields.tpl.html file.

Duplicating Product Fields to Ordered Items

Product Fields are related internally to Products within Aurora. If you define an Aurora Product Field and wish to write the value of the field to the Ordered Item record at the time of the order you can submit the field names along with your checkout data.

Variation/Attribute Fields

If a product variation/attribute has the same field name as the product, it will override the field value saved to the Ordered Item additional field. This can be useful where you want a general field value at the product level, but you wish to override that value at the variation/attribute level.

Checkout

To submit the field names to copy to the order in a standard checkout flow, simply submit a hidden field in the form with the name duplicate_product_fields_to_ordered_items[] and the value being the clean field name for the product field.

<input name="duplicate_product_fields_to_ordered_items[]" type="hidden" value="my_field">

Non-Checkout Flows

When creating a checkout through the Ajax endpoint /checkout/setup-submit you can submit a data key duplicate_product_fields_to_ordered_items with an array of field names. An example follows, please be sure to view both the Smarty and JavaScript files in the following example:

let submitData = {
  // ... Data for the setup-submit endpoint
};

// Merge in the order fields hidden inputs defined in the template.
$.extend(submitData, $('.order-fields input').serializeForm())

$.ajax({
  url: "/checkout/setup-submit?checkout_type=proxy-adyen",
  type: "POST",
  data: submitData,
});

<div class="order-fields">
  <input name="duplicate_product_fields_to_ordered_items[]" type="hidden" value="my_field_1">
  <input name="duplicate_product_fields_to_ordered_items[]" type="hidden" value="my_field_2">
</div>