- What is an API Mapping Name
- How the API Mapping Name works
- Set Up an API Mapping Name
- Custom Mapping Names for Specific Products
- Common Use Cases
- ⚠️Important Considerations
- When to Use API Mapping Name
What is an API Mapping Name?
API Mapping Name is an alternate identifier for product attributes that allows external systems to reference attributes using different names than what appears in your Allmoxy catalog. When you set an API Mapping Name, API calls can use either the original attribute name OR the mapping name interchangeably—whichever works best for your integration.
This feature exists because some external systems have naming restrictions that Allmoxy doesn't share. For example, certain integrations can't process attribute names that start or end with underscores, or they may need attributes named differently to match their own data structure.
Most Allmoxy users will never need to touch API Mapping Name. It's a specialized tool for advanced integrations, but when you need it, it gives you the flexibility to maintain your catalog structure while accommodating external system requirements.
How the API Mapping Name Works
When an API call is made to Allmoxy, the system checks for an API Mapping Name first. If one exists, it accepts that name as valid. If the API Mapping Name field is empty, the system defaults to using the standard attribute formula name. Both names remain functional once a mapping name is set—you're not replacing the original name, you're adding an alternative.
This means your internal Allmoxy catalog can keep its existing naming conventions while accommodating external system requirements simultaneously.
Setting Up an API Mapping Name
Configuration happens in two places: at the attribute level and at the product level.
Step 1: Set the Mapping Name at the Attribute Level
Navigate to your attribute settings and locate the API Mapping Name field. Enter the alternative name that your external system needs to use. This establishes what the mapping name will be, but it doesn't automatically apply it anywhere yet.
For example, if you have an attribute called integrated_ends_ (note the trailing underscore), you might set the API Mapping Name to integrated_ends without the underscore.
Step 2: Apply the Mapping Name to Each Product
The mapping name must be explicitly enabled on every product where you want it to function. This product-level control exists because you might have multiple attributes with similar purposes on a single product, and you need granular control over which mapping names apply where.
To apply the mapping name to a product:
- Open the product that uses the attribute
- Locate the attribute in the product's attribute list
- Click Edit Override for that attribute
- Select the option to use the API Mapping Name you created (it will appear in a dropdown)
- Save the override
Once saved, API calls for that product will reference the API Mapping Name instead of the formula name.
Custom Mapping Names for Specific Products
In rare cases, you might need a product to use a completely unique mapping name that differs from both the standard attribute name and the default API Mapping Name. When editing the override, you can manually type a custom name that will apply only to that specific attribute on that specific product.
This is uncommon but useful when dealing with edge cases in your integration where standard mappings don't work for a particular product configuration.
Common Use Cases
API Mapping Name is most frequently used when integrating with design software or manufacturing systems that have rigid naming requirements. Common scenarios include:
- Naming convention conflicts: External systems that can't process underscores, special characters, or specific formatting in attribute names
- Standardized field names: Integrations that expect generic names like "width," "height," or "depth" regardless of how your catalog describes those dimensions (e.g., "cabinet_width" vs "width")
- Legacy system compatibility: Older systems that were built before flexible naming conventions became standard
⚠️Important Considerations
You must update every relevant product individually. There's no bulk-apply function for API Mapping Names. If you're setting up a new integration and need to apply mapping names across your entire catalog, plan accordingly—this is a product-by-product process.
Mapping names don't affect your internal Allmoxy interface. Your team will continue to see and use the original attribute names throughout the system. The mapping names only come into play during API communication.
The API Mapping Name field only matters if you're using Allmoxy's API. If you're not integrating with external systems via API, you can safely ignore this feature.
When to Use API Mapping Name
If you're working with a developer or integration partner and they report that certain attributes are failing or being rejected during API calls, ask them specifically which attribute names are causing issues. Often, the problem is a naming format that their system can't accept.
Once you know which attributes need alternative names, work with your API integration partner to determine what those names should be, then follow the setup process above. Your integration partner should be able to tell you exactly what naming format their system requires.