Skip to content

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. Basket custom fields are used to capture data at the shopping cart level, while order custom fields store that data after the order is placed. This seamless transfer ensures that custom data is retained and available for fulfillment, reporting, and other workflows.

Creating Basket and Order Custom Fields#

Steps to Create Custom Fields:#

  1. Navigate to Custom Fields:
    • Go to Settings > Utilities > Custom Fields in the admin interface.
  2. Create New Fields:
    • Create a basket custom field:
      • Field: Basket
      • Code: basket_notes
      • Name: Basket Notes
      • Field Type: Text Area
    • Create a corresponding order custom field:
      • Field: Order
      • Code: order_notes
      • Name: Order Notes
      • Field Type: Text Area
  3. Save Both Fields:
    • Ensure the field codes are identical except for the entity type to enable automatic data transfer.

Capturing Custom Field Data#

Example: Capturing Order Notes During Checkout#

  1. Add a Text Area to the Checkout Page:

    On the OSEL (Shipping/Order Selection) page: 

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

  2. Write Data to the Basket Custom Field:

    On the OPAY (Payment Information) page: 

    <mvt:if expr="NOT ISNULL g.basket_notes">
     <mvt:item name="customfields" param="Write_Basket( 'basket_notes', g.basket_notes )" />
</mvt:if>

  3. Data Transfer to Order Custom Field:

When the order is placed, Miva automatically transfers the basket custom field data to the corresponding order custom field (order_notes).

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>

Note

When using the customfields functions always confirm that the customfields item is assigned to the page.

Best Practices for Basket and Order Custom Fields#

  1. Use Matching Codes:

    • Ensure the field codes for basket and order custom fields are identical (e.g., basket_notes and order_notes) to enable automatic data transfer.

  2. Validate User Input:

    • Use client-side or server-side validation to ensure data entered in custom fields is appropriate and secure.

  3. Test Data Flow:

    • Test the end-to-end process in a sandbox environment to confirm data is captured, transferred, and displayed correctly.

  4. Document Field Usage:

    • Maintain clear documentation for all basket and order custom fields, including their purposes and templates where they are used.

  5. 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#

Show a message if a custom field contains specific data: 

<mvt:item name="customfields" param="Read_Basket( 'basket_notes', l.settings:basket_notes )" />
<mvt:if expr="l.settings:basket_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#

Basket and Order Custom Fields provide a powerful way to capture and manage additional data throughout the checkout process. By leveraging these fields, you can collect customer preferences, special instructions, or other data points that enhance operational efficiency and customer satisfaction.

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