3Dsellers can write each product's vehicle compatibility (fitment) into a Shopify metafield for you. In your Shopify mapping template, map a metafield to Product Property / Vehicle Compatibility (JSON). From then on, every time 3Dsellers publishes or revises that product on Shopify, it fills the metafield with the product's Catalog Edit Vehicles list as JSON: year, make, model, trim, engine and notes for each vehicle. You no longer need to export the vehicle list to CSV and load it into Shopify yourself.
💡 Only need the vehicle list as a file? The 3Dsellers Catalog vehicle compatibility export can also run daily, weekly or monthly through the 3Dsellers API. See Can I get the vehicle list as a file on a schedule?
In this article:
What does Vehicle Compatibility (JSON) do?
Vehicle Compatibility (JSON) is a 3Dsellers Catalog product property, like Title or Brand, that you can map to a channel field in a mapping template. 3Dsellers builds its value from the product's vehicle list at the moment it publishes or revises the product, so there is nothing to fill in on the product itself.
It reads the Edit Vehicles list of the Catalog product. If more than one of your connected accounts has an Edit Vehicles list for the product, 3Dsellers merges the lists and writes each vehicle once.
If no account has an Edit Vehicles list for the product, 3Dsellers uses the vehicle list saved with the product by a Catalog vehicle compatibility CSV import, if there is one.
For a product with variations, the vehicle list comes from the parent product.
It shows in the mapping template preview, so you can check the value before you publish anything.
What do I need before I start?
A Shopify store connected to 3Dsellers.
Products in the 3Dsellers Catalog that have vehicles in Edit Vehicles, either already linked to Shopify listings or ready to publish to Shopify.
The Shopify mapping template those products use.
If you want buyers to see the list, a Shopify theme or app that reads the metafield. 3Dsellers fills the metafield; your theme decides how it is shown.
How do I map vehicle compatibility to a Shopify metafield?
You set this up once per Shopify mapping template. Every product that uses the template then sends its own vehicle list.
In 3Dsellers, go to Catalog > Products Settings > Mapping Templates and open the template your Shopify products use.
Open the Custom Metafields section.
If the metafield you want to fill is already listed (for example
vehicle_compatibility_json), go to step 5.Otherwise click Add New Metafield and create it: give it a name such as
vehicle_compatibility_json, choose the Field Type (Multi line text field or JSON, see the next section), and keep Type on Product and Namespace oncustomunless your theme expects a different namespace. The full steps for adding a metafield are in How to Use Custom Metafields for Item Specifics in Shopify & WooCommerce.In the metafield's mapping, choose Product Property, then Vehicle Compatibility (JSON). The mapping now reads Product Property / Vehicle Compatibility (JSON).
Save the template.
Check the result: in the template's Preview product... box, pick a product that has vehicles in Edit Vehicles. The metafield shows the product's vehicle list as JSON. If you changed the mapping after picking the product, click Refresh preview.
⚠️ A metafield has one mapping. If the metafield was filled from a custom attribute before, choosing Vehicle Compatibility (JSON) replaces that source. The custom attribute stays on your products, but 3Dsellers no longer sends it to this metafield.
Multi line text field or JSON: which type should I use?
Both Shopify metafield types work with Vehicle Compatibility (JSON). The difference is how much they hold and how Shopify treats the value.
Metafield type | Size limit | Good to know |
Multi line text field | 64 KB | Shopify stores the list as plain text. Fine for most lists: about 400 vehicles is roughly 57 KB. |
JSON | 128 KB | Shopify checks that the value is valid JSON and stores it as structured data. Holds about twice as many vehicles. |
If your theme or an app already reads a metafield, keep the type it already uses and map that metafield.
What does the vehicle list look like in Shopify?
3Dsellers writes a JSON array with one object per vehicle, for example:
[{"year":"2005","make":"Buick","model":"Century","trim":"Custom Sedan 4-Door","engine":"3.1L 189Cu. In. V6 GAS OHV Naturally Aspirated","notes":""},{"year":"2004","make":"Buick","model":"Century","trim":"Custom Sedan 4-Door","engine":"3.1L 189Cu. In. V6 GAS OHV Naturally Aspirated","notes":"Front only"}]
The keys
year,make,model,trimandenginecome first, andnotesis always last.Vehicles from eBay sites that use other vehicle fields get extra keys in lower case with underscores, such as
submodel,variant,body_style,type,platformorktype.Every vehicle in the list has the same keys. When a vehicle has no value for one of them, the value is an empty string (
"").A field with several values is written as one text, with the values separated by a comma and a space.
A vehicle that appears twice is written once.
When does Shopify get the vehicle list?
3Dsellers writes the metafield when it publishes a product to Shopify and every time it revises the Shopify listing. A change in Edit Vehicles therefore reaches Shopify with the next revise of the Shopify listing. If you only save the product to the Catalog, nothing is sent to Shopify yet.
Revise one product
Open the product in the Catalog.
In the product's listings, find the Shopify listing and click Revise Listing.
Check the metafield on the product in Shopify.
Revise many products
In the Catalog, tick the products you want to update.
Click Bulk Actions > Listings > Revise Product Listings.
The Update Linked Listings by Mapping Template dialog shows how many products it applies to. Unlinked listings are skipped unless you tick Revise unlinked listings.
Click Update.
⚠️ A revise sends everything the mapping template maps, not only the vehicle list, and Revise Product Listings revises every linked listing of the products you ticked. Revise one product first, check it in Shopify, and only then revise in bulk.
What happens to products with no vehicles?
⚠️ When a Catalog product has no vehicles, 3Dsellers does not send the metafield at all, so whatever is already in Shopify stays as it is. When the product does have vehicles, a revise replaces the Shopify value with the Catalog list. If you corrected a list by hand in Shopify, add those vehicles to Edit Vehicles before you revise, or the hand-made list will be overwritten.
This is deliberate: an empty Catalog list never wipes a list you keep in Shopify.
What if a product has a very long vehicle list?
Shopify limits how much a metafield can hold, so 3Dsellers keeps the vehicle list inside the limit of the metafield type: 64 KB for a Multi line text field and 128 KB for JSON. If a list is longer, 3Dsellers sends as many vehicles as fit and leaves the rest out, instead of failing the whole update. A list of about 400 vehicles is roughly 57 KB, so most lists fit either type. For very long lists, use a JSON metafield.
Can I get the vehicle list as a file on a schedule?
Yes. The 3Dsellers Catalog vehicle compatibility export gives you one row per vehicle and covers the Edit Vehicles lists of every account. Only products that have a SKU and at least one vehicle are included.
Once, by hand: in the Catalog, tick the products and choose Bulk Actions > Manage > Export Vehicle Compatibility To CSV. The steps are in Export Vehicle Compatibility to CSV for eBay Listings.
On a schedule: create an export schedule through the 3Dsellers API or MCP with the export type
node_product_catalog_compatibility. It runs daily, weekly or monthly and publishes every run to one fixed download URL that each run overwrites, so a spreadsheet or script can read the latest file without anyone logging in.
The scheduled file has these columns: SKU, CarMake, CarModel, CarVariant, CarBodyStyle, CarType, CarYear, CarEngine, KType, CarTrim and CarCompatibilityNotes. A schedule created through the API starts inactive: create it, run it once to check the file, then activate it. Scheduled exports need the Export CSV feature on your plan. The Report Center's own scheduler does not offer this export type, so use the API or MCP. The full reference is at api.3dsellers.com/docs.
⚠️ The download URL of a scheduled export is publicly readable by anyone who has the link. Treat it like the data itself and do not post it anywhere public.
What Vehicle Compatibility (JSON) will not do
It will not send a change in Edit Vehicles to Shopify until the Shopify listing is published or revised.
It will not clear a Shopify metafield when the Catalog product has no vehicles.
It will not send anything until a metafield in your mapping template is mapped to it.
It will not show the list on your storefront. Your Shopify theme or an app decides whether and how a metafield is displayed.
It will not send more than the metafield type can hold: 64 KB for a Multi line text field, 128 KB for JSON.
It will not schedule the vehicle compatibility export from the Report Center. Scheduling this export is done through the API or MCP.
Troubleshooting
The mapping preview shows the vehicle metafield empty
Vehicle Compatibility (JSON) is empty when the preview product has no vehicles. Open the product in the Catalog and check Edit Vehicles. For a variation, check the parent product, because the list comes from the parent. Then check that the metafield's mapping reads Product Property / Vehicle Compatibility (JSON), that the template is saved, and click Refresh preview.
I changed Edit Vehicles but Shopify still shows the old list
A change in Edit Vehicles is sent to Shopify only when the Shopify listing is revised, and saving the product to the Catalog alone sends nothing. Revise the Shopify listing (Revise Listing on one product, or Bulk Actions > Listings > Revise Product Listings for many) and the new list is sent.
Shopify shows fewer vehicles than Edit Vehicles
The list was longer than the metafield type can hold, so 3Dsellers sent as many vehicles as fit. A Multi line text field holds 64 KB and a JSON metafield holds 128 KB. Map the vehicle list to a JSON metafield for very long lists.
A product with no vehicles still has a vehicle list in Shopify
This is expected. When a Catalog product has no vehicles, 3Dsellers does not send the metafield, so the value already in Shopify stays. Remove it in Shopify if you no longer want it.
Publishing or revising fails with an error that names a JSON metafield
A JSON metafield only accepts valid JSON, and 3Dsellers stops with an error that names the metafield when the value is not valid JSON. Vehicle Compatibility (JSON) always produces valid JSON, so the error usually means another source, such as a custom attribute holding plain text, is mapped to that JSON metafield. Check the metafield's mapping in the template.
Buyers can't see the vehicle list on my store
3Dsellers fills the metafield, but your Shopify theme decides what is shown. Check the product's metafields in the Shopify admin. If the list is there, add the metafield to your product page with the Shopify theme editor or an app.
FAQ
Can I map the 3Dsellers Edit Vehicles list to a Shopify metafield?
Yes - in your Shopify mapping template, map the metafield to Product Property / Vehicle Compatibility (JSON). 3Dsellers then writes the product's Edit Vehicles list into that metafield as JSON every time it publishes or revises the product on Shopify.
Does 3Dsellers update the Shopify metafield as soon as I edit vehicles?
No - a change in Edit Vehicles reaches Shopify the next time 3Dsellers publishes or revises the Shopify listing. Saving the product to the Catalog alone sends nothing to Shopify.
Will 3Dsellers clear the Shopify metafield if the Catalog product has no vehicles?
No - when a Catalog product has no vehicles, 3Dsellers does not send the metafield, so the value in Shopify stays. When the product has vehicles, a revise replaces the Shopify value with the Catalog list.
Does the vehicle list sent to Shopify include compatibility notes?
Yes - every vehicle carries a notes key, always as the last key. It is an empty string when the vehicle has no note.
Which Shopify metafield type should I use for vehicle compatibility?
Use a Multi line text field or a JSON metafield. Multi line text holds up to 64 KB, which is enough for most lists (about 400 vehicles is roughly 57 KB). JSON holds up to 128 KB and Shopify validates it as JSON. If your theme already reads a metafield, keep its type.
Does revising for the vehicle list change anything else on my Shopify listing?
Yes, it can - a revise sends every field the mapping template maps, not only the vehicle list, and Revise Product Listings revises every linked listing of the products you select. Revise one product first and check it before revising in bulk.
Can I export my Catalog vehicle compatibility automatically every day?
Yes - create an export schedule with the type node_product_catalog_compatibility through the 3Dsellers API or MCP. It runs daily, weekly or monthly and overwrites one fixed download URL. The Report Center's own scheduler does not offer this export type.