Item User Fields

Overview

Item User Fields allow you to add custom fields to specific products in your store. Unlike Item Attributes (which apply to categories), Item User Fields are product-specific and allow you to collect additional information that customers must provide when purchasing that particular item.

Purpose

• Custom Product Information: Collect product-specific information from customers during checkout
• Personalization: Enable customers to provide personalized details for specific products
• Gift Messages: Collect gift messages or special instructions for specific items
• Customization Options: Gather customization details for made-to-order products
• Configuration Data: Collect technical specifications or setup preferences for complex products
• Validation: Ensure customers provide required information before completing purchase

Accessing Item User Fields

Navigate to: System Settings > Item User Fields from the sidebar

List View

The list displays all custom fields configured for specific products across your store.

Table Columns

Item

• Shows: Product name that this custom field belongs to
• Format: Product name (e.g., "Samsung Galaxy S24", "Google Pixel 8")
• Clickable: Links to the product details page
• Sortable: Yes
• Searchable: Yes
• Purpose: Quickly identify which product has which custom fields

Field Name

• Shows: Technical identifier for the field
• Format: Lowercase with underscores (e.g., "processor", "ram_size", "storage_capacity")
• Purpose: Internal reference name used by the system
• Requirements:
• Must start with a letter or underscore
• Can contain letters, numbers, and underscores only
• No spaces or special characters
• Automatically converted to lowercase with underscores
• Searchable: Yes

Field Label

• Shows: The display name shown to customers
• Format: Human-readable text (e.g., "المعالج" for processor in Arabic)
• Translatable: Yes - can be different in each language
• Purpose: What customers see when providing information
• Clickable: Yes - opens edit form
• Searchable: Yes

Field Type

• Shows: Type of input field displayed to customers
• Format: Color-coded badge
• Values:
• Text (Gray badge): Single-line text input
• Number (Orange/Warning badge): Numeric input only
• Select List (Green/Success badge): Dropdown selection
• Date (Blue/Info badge): Date picker
• Time (Purple/Primary badge): Time picker
• Sortable: Yes
• Filter Available: Yes

Required

• Shows: Whether customers must fill this field
• Format: Checkmark icon (✓) if required, empty if optional
• Interactive: Click to toggle required/optional status
• Quick Toggle: No confirmation needed - immediate update
• Purpose: Control which fields are mandatory for purchase

Created At

• Shows: When the field was created
• Format: Date and time
• Sortable: Yes
• Visibility: Hidden by default (toggle via column selector)

Updated At

• Shows: Last modification date and time
• Format: Date and time
• Sortable: Yes
• Visibility: Hidden by default (toggle via column selector)

Search Functionality

Use the search box to find fields by:

• Product name
• Field name
• Field label

Filters

Field Type Filter

Filter by input type:

• Text: Show only text input fields
• Number: Show only numeric fields
• Select List: Show only dropdown fields
• Date: Show only date picker fields
• Time: Show only time picker fields
• Clear: Show all field types

Required Filter

Filter by requirement status:

• Required: Show only mandatory fields
• Optional: Show only non-mandatory fields
• All: Show both required and optional fields

Row Actions

Edit

• Function: Opens edit form to modify field settings
• Available: For all fields
• Can Modify: All field properties

Delete

• Function: Permanently removes the custom field
• Impact:
• Customers will no longer see this field
• Previously collected data is not deleted
• Cannot be undone
• Use Case: Remove fields no longer needed

Bulk Actions

Select multiple fields using checkboxes:

Delete

• Function: Remove multiple custom fields at once
• Warning: Requires confirmation
• Impact: Same as individual delete
• Use Case: Clean up obsolete fields for discontinued products

Export

• Function: Export field data to Excel/CSV
• Exported Data: All visible columns
• Use Case: Backup configuration, documentation, analysis

Creating Item User Fields

Click "New Item User Field" button in the top-right corner.

Form Fields

Item Required

• Type: Searchable dropdown
• Purpose: Select which product this field belongs to
• Validation: Required - you cannot create a field without selecting a product
• Searchable: Yes - type to search through all products
• Display: Shows product name
• Note: Each product can have multiple custom fields

Example:

• Product: "Custom T-Shirt"
• You can add fields for: size, color, print_text, print_position

Field Name Required

• Type: Text input
• Purpose: Internal identifier for the field
• Validation:
• Required
• Maximum 100 characters
• Must match pattern: letters, numbers, underscores only
• Must start with letter or underscore
• Auto-Format: Automatically converts to lowercase and replaces invalid characters with underscores
• Helper Text: "Only letters, numbers, and underscores. Must start with a letter or underscore."
• Placeholder: "e.g. custom_field_1, user_note"

Examples:

• Good: delivery_date, engraving_text, color_preference
• Bad (will be converted): Delivery Date → delivery_date
• Bad (will be converted): Gift Message! → gift_message_

Best Practices:

• Use descriptive names
• Use underscores for spaces
• Keep it short but meaningful
• Follow consistent naming convention

Field Label Required

• Type: Text input
• Purpose: Display name shown to customers
• Validation:
• Required
• Maximum 100 characters
• Translatable: Yes - can be different in Arabic and English
• Format: Can include any characters, spaces, special characters

Examples:

• English: "Delivery Date", "Engraving Text", "Gift Message"
• Arabic: "تاريخ التسليم", "نص النقش", "رسالة الهدية"

Best Practices:

• Be clear and specific
• Use customer-friendly language
• Keep it concise
• Provide context if needed

Field Type Required

• Type: Dropdown selection
• Purpose: Determines what input control customers see
• Default: Text
• Options:

Text

• Input: Single-line text box
• Use Cases:
• Names
• Short messages
• Email addresses
• Phone numbers
• Short instructions
• Validation: None by default (any text accepted)
• Example: "Recipient Name", "Gift Message"

Number

• Input: Numeric input field
• Use Cases:
• Quantities
• Measurements
• Age
• Weight
• Dimensions
• Validation: Only numbers allowed
• Example: "Shirt Size (numeric)", "Package Weight"

Select List

• Input: Dropdown menu
• Requires: "Select Options" field (appears when this type is selected)
• Use Cases:
• Predefined choices
• Color options
• Size selections
• Configuration options
• Validation: Must select from available options
• Example: "T-Shirt Size" (S, M, L, XL, XXL)

Date

• Input: Date picker calendar
• Use Cases:
• Delivery date preference
• Event date
• Birth date
• Anniversary date
• Format: Depends on locale setting
• Example: "Preferred Delivery Date"

Time

• Input: Time picker
• Use Cases:
• Delivery time preference
• Event time
• Appointment time
• Format: 12-hour or 24-hour depending on locale
• Example: "Preferred Delivery Time"

Select Options

• Type: Multi-line text area
• Visibility: Only appears when Field Type is "Select List"
• Purpose: Define the options available in the dropdown
• Format: One option per line
• Helper Text: "Enter each option on a new line"

Example:

Small
Medium
Large
X-Large
XX-Large

Best Practices:

• One option per line
• Keep options concise
• List in logical order (e.g., size order, alphabetical)
• Avoid duplicate options
• Use clear, unambiguous names

Required

• Type: Toggle switch (On/Off)
• Default: Off (optional)
• Purpose: Make the field mandatory for purchase
• Impact:
• ON: Customers cannot add item to cart without filling this field
• OFF: Field is optional - customers can leave it blank
• Best Practice: Only make fields required if absolutely necessary

Create Actions

Create

• Function: Saves the custom field and returns to list view
• Validation: All required fields must be filled
• Shortcut: Press Enter after filling form

Create & Create Another

• Function: Saves the custom field and opens a blank form
• Use Case: When adding multiple fields to the same or different products
• Efficiency: Avoids returning to list view between creations

Cancel

• Function: Discards changes and returns to list view
• Warning: No confirmation - changes are lost immediately

Use Cases and Examples

Example 1: T-Shirt Customization Shop

Product: "Custom Printed T-Shirt"

Custom Fields:

1. Field Name: shirt_size
2. Label: "T-Shirt Size"
3. Type: Select List
4. Options: S, M, L, XL, XXL, XXXL

5. Required: Yes

6. Field Name: shirt_color

7. Label: "T-Shirt Color"
8. Type: Select List
9. Options: White, Black, Navy, Red, Gray

10. Required: Yes

11. Field Name: print_text

12. Label: "Text to Print"
13. Type: Text

14. Required: Yes

15. Field Name: print_position

16. Label: "Print Position"
17. Type: Select List
18. Options: Front Center, Back Center, Front Left, Front Right
19. Required: Yes

Result: Customers must specify size, color, text, and position before purchasing.

Example 2: Gift Product

Product: "Premium Gift Box"

Custom Fields:

1. Field Name: recipient_name
2. Label: "Recipient Name"
3. Type: Text

4. Required: Yes

5. Field Name: gift_message

6. Label: "Gift Message"
7. Type: Text

8. Required: No

9. Field Name: delivery_date

10. Label: "Preferred Delivery Date"
11. Type: Date

12. Required: No

13. Field Name: delivery_time

14. Label: "Preferred Delivery Time"
15. Type: Time
16. Required: No

Result: Customers can personalize gifts with recipient details and delivery preferences.

Example 3: Electronics Configuration

Product: "Custom Gaming PC"

Custom Fields:

1. Field Name: processor
2. Label: "Processor"
3. Type: Select List
4. Options: Intel i5, Intel i7, Intel i9, AMD Ryzen 5, AMD Ryzen 7, AMD Ryzen 9

5. Required: Yes

6. Field Name: ram_size

7. Label: "RAM Size (GB)"
8. Type: Select List
9. Options: 8, 16, 32, 64

10. Required: Yes

11. Field Name: storage_type

12. Label: "Storage Type"
13. Type: Select List
14. Options: SSD 256GB, SSD 512GB, SSD 1TB, SSD 2TB

15. Required: Yes

16. Field Name: additional_notes

17. Label: "Additional Configuration Notes"
18. Type: Text
19. Required: No

Result: Customers can configure their PC build with specific components.

Example 4: Event Tickets

Product: "Conference Ticket"

Custom Fields:

1. Field Name: attendee_name
2. Label: "Attendee Full Name"
3. Type: Text

4. Required: Yes

5. Field Name: attendee_email

6. Label: "Attendee Email"
7. Type: Text

8. Required: Yes

9. Field Name: dietary_requirements

10. Label: "Dietary Requirements"
11. Type: Select List
12. Options: None, Vegetarian, Vegan, Halal, Gluten-Free, Other

13. Required: No

14. Field Name: tshirt_size

15. Label: "Conference T-Shirt Size"
16. Type: Select List
17. Options: S, M, L, XL, XXL
18. Required: Yes

Result: Collect attendee information for badges, meals, and merchandise.

Best Practices

Field Design

1. Minimize Required Fields: Only make fields required if absolutely necessary
2. Clear Labels: Use simple, customer-friendly language
3. Logical Order: Create fields in the order customers should fill them
4. Appropriate Types: Choose the right field type for the data:
5. Use Select List when options are limited
6. Use Text for free-form input
7. Use Number when values must be numeric
8. Use Date/Time for temporal data

Naming Conventions

1. Field Names: Use lowercase with underscores (e.g., delivery_date, not DeliveryDate)
2. Consistency: Use similar naming patterns across all fields
3. Descriptive: Names should indicate the field's purpose
4. Avoid Abbreviations: Use full words when possible

Select List Options

1. Comprehensive: Include all likely options
2. Logical Order: Sort logically (size order, alphabetical, popularity)
3. Avoid Overlap: Each option should be distinct
4. Include "Other": For categories where you can't list everything

User Experience

1. Help Text: Use field labels to explain what information is needed
2. Examples: Provide examples in field labels or help text
3. Validation: Use appropriate field types to enforce data format
4. Testing: Test the checkout process to ensure fields work correctly

Maintenance

1. Regular Review: Periodically review and remove unused fields
2. Update Options: Keep Select List options current
3. Monitor Usage: Track which fields are commonly left blank (may need adjustment)
4. Documentation: Keep internal notes on why certain fields exist

Integration with Checkout Process

How It Works

1. Product Page: Custom fields appear on the product detail page
2. Add to Cart: Customers must fill required fields before adding to cart
3. Cart Display: Field values show in cart item details
4. Checkout: Information is submitted with the order
5. Order Details: Field values appear in order details for fulfillment

Customer Experience

• Fields appear below product description
• Required fields show asterisk (*)
• Empty required fields prevent adding to cart
• Validation messages appear for invalid input
• Field values show in cart summary

Vendor/Admin View

• Field values appear in order items
• Can be viewed when processing orders
• Exported with order data
• Available in order reports

Limitations and Considerations

Field-Level Limitations

1. One Product Per Field: Each custom field belongs to exactly one product
2. Cannot Edit Field Name: Field names cannot be changed after creation (must delete and recreate)
3. No File Uploads: Cannot use Item User Fields for file uploads (images, documents)
4. No Multi-Select: Select Lists allow only single selection, not multiple

Performance Considerations

1. Number of Fields: While there's no hard limit, keep fields to 5-10 per product for best UX
2. Long Select Lists: Very long dropdown lists can be hard to use - consider categories instead
3. Required Fields: Too many required fields may discourage purchases

Use Case Limitations

Not Suitable For:

• File uploads (logos, designs, images)
• Complex multi-step configuration
• Real-time pricing based on selections
• Cross-product dependencies

Better Alternatives For:

• Category-wide attributes: Use Item Attributes (Section 36) instead
• Inventory variants: Use Item Variations (Section 15) instead
• File uploads: Consider custom development or third-party plugins
• Complex configuration: Consider custom form integration

Troubleshooting

Field Not Appearing on Product Page

Possible Causes:

• Field was just created - may need cache clear
• Product page template doesn't support custom fields
• Field is associated with wrong product

Solutions:

1. Verify the field is assigned to the correct product
2. Clear browser cache
3. Check product page in frontend
4. Contact support if issue persists

Customers Can Add to Cart Without Filling Required Field

Possible Causes:

• Required toggle is off
• Validation not working properly
• Custom theme override

Solutions:

1. Edit the field and ensure Required toggle is ON
2. Test in incognito/private browser window
3. Check with different products
4. Contact support if validation fails

Select List Options Not Appearing

Possible Causes:

• Options not saved properly
• Each option must be on a new line
• Empty options in list

Solutions:

1. Edit the field
2. Check "Select Options" field
3. Ensure each option is on a separate line
4. Remove any blank lines
5. Save and test again

Wrong Field Type Selected

Problem: Field was created with wrong type (e.g., Text instead of Select List)

Solution:

1. Cannot change field type after creation
2. Must delete the field
3. Create new field with correct type
4. Use same field name and label for consistency

Field Values Not Showing in Orders

Possible Causes:

• Field was created after order was placed
• Field values weren't submitted properly
• Order system not configured to capture field data

Solutions:

1. Check order details page thoroughly
2. Verify field exists and is active
3. Test with new order
4. Contact support if data is missing

Frequently Asked Questions

Can I add the same field to multiple products?

No, each custom field is specific to one product. However, you can create fields with the same name and configuration for different products. Use "Create & Create Another" to quickly create similar fields for multiple products.

What's the difference between Item User Fields and Item Attributes?

Item User Fields:

• Product-specific
• Customer fills during purchase
• For collecting custom information
• Examples: gift message, engraving text

Item Attributes (Section 36):

• Category-wide specifications
• Set by admin, not customer
• For filtering and product specs
• Examples: screen size, color, brand

What's the difference between Item User Fields and Item Variations?

Item User Fields:

• Custom information from customers
• No inventory tracking per option
• No price difference per option
• Examples: personalization text, delivery preferences

Item Variations (Section 15):

• Predefined product variants
• Separate inventory per variant
• Different prices per variant
• Examples: size/color combinations with different SKUs

Can customers upload files through Item User Fields?

No, Item User Fields do not support file uploads. If you need customers to upload images, logos, or documents, you'll need custom development or a third-party plugin.

Do custom field values affect product price?

No, Item User Fields are for information collection only and do not affect the product price. If you need different prices for different options, use Item Variations (Section 15) instead.

Can I make some options in a Select List cost more?

No, Item User Fields cannot have different prices per option. For price variations, use Item Variations (Section 15).

What happens to old field values if I delete a field?

• The field is removed from the product page
• New customers won't see the field
• Previously collected data in old orders remains intact
• Historical orders still show the field values

Can I change a field from optional to required?

Yes, you can toggle the Required status at any time:

• In the list view: Click the checkmark icon
• In the edit form: Toggle the Required switch

This only affects new orders going forward.

How many custom fields can I add to one product?

There's no hard limit, but for best user experience:

• Keep it under 5-7 fields if possible
• Only make 2-3 fields required
• Too many fields can discourage purchases

Can I set default values for fields?

Currently, you cannot set default values. All fields start empty, and customers must fill them in.

Can I validate field values (e.g., email format)?

Basic validation is provided by field type (e.g., Number type only accepts numbers). For complex validation (email format, phone format), custom development would be required.

Do custom fields work with the mobile app?

Yes, custom fields should appear in the mobile app on product pages, assuming the app supports this feature. Test thoroughly on mobile before going live.

Related Sections

• Products - Add custom fields to products
• Categories - Product category management
• Category User Fields - Custom fields for categories