Basket and Order Custom Fields#

Basket and Order Custom Fields in Miva Merchant allow you to store and manage additional data during the checkout process. Order custom fields are created in the admin and persist after an order is placed. Basket fields are not created in the admin — instead, values are written to them at runtime using Write_Basket with the same field code as the corresponding order custom field. Upon checkout, any runtime basket field whose code matches an order custom field will automatically transfer its value to that order custom field.

Creating Order Custom Fields#

Basket fields do not exist as admin-configured entities — only order custom fields are created in the admin. The basket field is written at runtime using Write_Basket with a code that matches the order custom field. On checkout, Miva automatically transfers any basket field value whose code matches an order custom field to that order custom field.

Steps to Create an Order Custom Field:#

Navigate to Custom Fields:
- Go to Settings > Utilities > Custom Fields in the admin interface.
Create the Order Custom Field:
- Field: Order
- Code: order_notes
- Name: Order Notes
- Field Type: Text Area
Save the Field.

Capturing Custom Field Data#

Example: Capturing Order Notes During Checkout#

Add a Text Area to the Checkout Page:

On the OSEL (Shipping/Order Selection) page:

<label for="order_notes">Special Instructions:</label>
<textarea name="order_notes" id="order_notes"></textarea>

Write the Value to the Basket at Runtime:

The input name matches the order custom field code (order_notes). Use Write_Basket with that same code on the OPAY (Payment Information) page:
```
<mvt:if expr="NOT ISNULL g.order_notes">
     <mvt:item name="customfields" param="Write_Basket( 'order_notes', g.order_notes )" />
</mvt:if>
```
!!! note The customfields item must be assigned to the page it is used on via that page’s Items list in the admin. This applies to every page where a customfields function call appears.
Data Transfer to Order Custom Field:

When the order is placed, Miva automatically transfers any runtime basket field whose code matches an order custom field. Because Write_Basket was called with order_notes — the same code as the order custom field — the value is transferred automatically.

Displaying Custom Field Data#

Displaying Order Notes on the Invoice#

On the INVC (Invoice) page:

<mvt:item name="customfields" param="Read_Order( l.settings:order:id, 'order_notes', l.settings:order_notes )" />
<p>Special Instructions: &mvt:order_notes;</p>

Best Practices for Basket and Order Custom Fields#

Use Matching Codes:
- The code passed to Write_Basket at runtime must exactly match the order custom field code defined in the admin. This is what triggers the automatic value transfer on checkout.
Validate User Input:
- Use client-side or server-side validation to ensure data entered in custom fields is appropriate and secure.
Test Data Flow:
- Test the end-to-end process in a sandbox environment to confirm data is captured, transferred, and displayed correctly.
Document Field Usage:
- Maintain clear documentation for all basket and order custom fields, including their purposes and templates where they are used.
Use Debugging Tools:
- Leverage the Debug() function to troubleshoot issues with reading or writing custom field data.

Advanced Techniques#

Using Conditional Logic for Basket Fields#

Read back a value written to the basket at runtime and act on it:

<mvt:item name="customfields" param="Read_Basket( 'order_notes', l.settings:order_notes )" />
<mvt:if expr="l.settings:order_notes EQ 'Gift'">
    <p>You have added a gift note to this order.</p>
</mvt:if>

Exporting Custom Fields via the JSON API#

The Miva JSON API allows you to retrieve custom field data dynamically for various entities such as products, orders, and baskets. To include custom fields in the response, you must specify the customfields parameter in the request.

Retrieving Custom Product Fields#

For example, to retrieve custom fields for products, use the ProductList_Load_Query function. Ensure you include the CustomField_Values:* on demand column to fetch associated custom fields. Request Body:

{
    "Store_code": "beta",
    "Function": "ProductList_Load_Query",
    "Count": 1,
    "Offset": 0,
    "Filter": [
        {
            "name": "ondemandcolumns",
            "value": ["CustomField_Values:*",]
        }
    ]
}

Response Example:

{
  "data": [
    {
      "id": 1001,
      "code": "PRODUCT123",
      "name": "Sample Product",
      "price": "29.99",
      "CustomField_Values": {
          "cmp-mv-prodctgy-meta": {
               "keywords": "",
               "description": ""
          },
          "cmp-cssui-pchdft": {
               "header": "",
               "footer": ""
          },
          "customfields": {
               "product_material": "Wood",
               "product_color": "Red"
          }
      }      
    }
  ]
}

Summary#

Order custom fields — created in the admin — provide a persistent way to capture additional data on every order. By writing matching values to the basket at runtime with Write_Basket, that data flows automatically into the order on checkout, making it available for fulfillment, reporting, and other workflows.

Ready to explore more? Learn about Debugging Custom Fields → and how to resolve custom field-related issues.