Metadata Management

Metadata Management lets you attach custom key-value pairs to accounts, products, and orders. Use metadata to store extra information, track custom data, or integrate with external systems without changing your database structure.

Quick Start

Add metadata by selecting the type (Account, Product, or Order), entering the key-value pair, and specifying which records to apply it to. Search by owner using o:OrderID or p:SKU formats.

Why Use Metadata?

Flexible Data Storage

Store custom information without modifying your database tables or product structure.

Integration Support

Pass custom data to shipping carriers, marketplaces, or third-party systems.

Custom Business Rules

Track special handling requirements, customer preferences, or internal notes.

Historical Tracking

Keep metadata changes visible with timestamps and account associations.

Accessing Metadata Management

Navigate to Metadata from the main menu or visit /attributes.php directly.

The interface displays all metadata entries with:

• ID: Unique metadata record identifier
• Date: When the metadata was created or updated
• Type: Whether metadata applies to Company, Product, Order, or Order Item
• Account: The account that owns this metadata
• Owner: The specific record (SKU, Order ID, etc.)
• Key: The metadata field name
• Value: The metadata field value

How to Add Metadata

1. Click “Add Metadata”

   Opens the metadata creation form.

2. Select Metadata Type

   Choose from:

   • Account: Apply to entire accounts/companies
   • Product: Apply to specific SKUs
   • Order: Apply to specific orders

3. Specify Owner Records (for Product/Order)

   • For Product: Enter SKU list (comma-separated)
   • For Order: Enter Shipping numbers (comma-separated)
   • System validates that records exist before saving

4. Select Account(s)

   Choose which account(s) this metadata applies to. For account-level metadata, this is the target account. For product/order metadata, this is the owning account.

5. Enter Key and Value

   • Metadata: The field name (e.g., special_handling, gift_message, external_id)
   • Value: The field value (e.g., fragile, Happy Birthday!, 12345)

6. Click “Save changes”

   System validates SKUs/Orders and shows success message. Any invalid SKUs/Orders are listed separately.

Managing Metadata

Edit Metadata

1. Click the ⋮ (three dots) next to any metadata entry
2. Select Edit
3. Update the account, key, or value
4. Click Save

Note

System-generated attributes like _international_settings_ cannot be manually edited or added.

Delete Metadata

Single Delete:

1. Click the ⋮ (three dots) next to the metadata entry
2. Select Delete
3. Confirm deletion

Bulk Delete:

1. Check the boxes next to multiple metadata entries
2. Click Actions > Delete
3. Confirm deletion

Search and Filter

Use column search boxes to find specific metadata:

• ID: Enter exact metadata ID
• Date: Filter by creation/update date
• Type: Select Company, Product, Order, or Order Item
• Account: Select specific account
• Owner: Search by record using format:
  • o:OrderID - Search orders (e.g., o:12345)
  • p:SKU - Search products (e.g., p:ABC-123)
• Key: Search by metadata field name
• Value: Search by metadata value

Time Filters (top-right buttons):

• Today: Show metadata from today
• This Week: Show metadata from current week (default)
• Last Week: Show previous week’s metadata
• Monthly: Select specific month/year

Press Enter after typing to apply search filters.

Export Options

Export metadata records using the toolbar buttons:

• Copy: Copy to clipboard
• PDF: Generate PDF report with formatted columns
• CSV: Export comma-separated values
• Excel: Export spreadsheet with metadata records

Exports include: ID, Type, Account, Owner, Key, and Value columns.

Common Metadata Examples

Shipping Instructions

Key: special_handling
Value: fragile, signature_required, no_weekend_delivery
Applied to: Orders or Products

Gift Messages

Key: gift_message
Value: Customer’s gift message text
Applied to: Orders

External IDs

Key: external_id, marketplace_id
Value: External system’s reference number
Applied to: Orders or Products

Custom Classifications

Key: priority, customer_type, handling_code
Value: Custom business classifications
Applied to: Accounts, Products, or Orders

💡 Best Practices

Use Consistent Key Names

Standardize metadata keys across your system (e.g., always use gift_message not giftMessage or gift-message).

Validate Before Saving

When adding product/order metadata, verify SKUs and Order IDs exist to avoid failed saves.

Document Your Keys

Keep a reference list of metadata keys and their purposes for your team.

Clean Up Old Data

Periodically review and remove outdated metadata to keep the system clean.

Metadata in Orders and Products

Metadata can be set when creating or importing orders/products:

• CSV Upload: Include metadata columns in your upload files
• API Integration: Pass metadata in API calls as key-value pairs
• Manual Entry: Use the Metadata Management interface

When orders or products are processed, their metadata is available for:

• Custom business logic
• Shipping label generation
• Packing slip information
• Integration with external systems

Troubleshooting

”All SKUs are invalid”

Problem: When adding product metadata, all SKUs failed validation.

Solutions:

• Verify SKUs exist in your catalog
• Check for typos or extra spaces
• Ensure SKUs belong to the selected account
• Use exact SKU format (case-sensitive)

“All ship numbers are invalid”

Problem: When adding order metadata, all Order IDs failed validation.

Solutions:

• Verify orders exist in the system
• Use Order ID (numeric), not Order Number
• Check that orders belong to the selected account

Search Results Not Showing

Problem: Metadata exists but doesn’t appear in search.

Solutions:

• Check time filter (default is “This Week”)
• Switch to “Monthly” and select earlier dates
• Clear all column filters and try again
• Verify the metadata’s creation date

Cannot Edit System Metadata

Problem: Error when trying to edit certain metadata keys.

Explanation: Metadata keys starting with underscore (_) are system-generated and protected from manual editing. These are used internally by ShipEdge for features like international settings.

Related Features

• Product Catalog: Add metadata to products for custom tracking
• Order Management: View and edit order-level metadata
• API Documentation: Pass metadata through API endpoints

Next Steps: Product Management | Creating Products