At various places throughout the app you may encounter a warning or error code. These codes are formatted like ABC001. This document provides more context on the error codes as well as tips to resolve them.

These codes will appear when you upload a spreadsheet to be imported with the app.

There was an error opening the file you uploaded. Please try again and contact us if the problem persists.

You can upload a ZIP file with multiple CSV files to have them processed at once. However in this case the app did not detect any CSV files in the zip file you uploaded.

If you want to process multiple Excel sheets at the same time you can combine them into a single Excel workbook and upload that.

We couldn't determine if your file was CSV, Excel, or a valid ZIP. Please upload either a CSV file, an Excel workbook with the .xlsx extension, or a ZIP file containing CSV files so our system can process it.

Our system tried to read your file but did not detect any sheets with the required structure. Ensure your file includes sheets that match one of our supported object types (for example, a valid Products or Orders sheet) and try again.

Your spreadsheet contains columns that Altera does not recognize and these columns will be ignored when you import data through the app.

The most common cause of this is trying to import data that does not match the Altera/Matrixify format. To fix this, make sure your spreadsheet matches the format in our documentation ( Product Fields for example).

The file you uploaded appears to be a product export from Shopify's admin in Shopify's native format. Altera requires product files to be in the Altera/Matrixify format instead. See our Product Fields documentation for the correct format.

You can convert your file to the Altera format by going to the 'Transform data' section of app in the left menu. Note that even if you convert a Shopify product export to the Altera/Matrixify format, some data may not come through.

If you're trying to copy products from one Shopify store to another, the best approach is to:

This ensures all product data is captured and transferred correctly.

Some columns can appear multiple times in a spreadsheet but others cannot. Make sure that you don't have any columns with duplicate names besides Tags and Image Src.

The ID column should either be empty, contain a number like 8106245782738, or contain a GraphQL identifier like gid://shopify/Products/8106245782738. If it doesn't it may cause problems with the import. If your ID is a number, make sure it is a whole number, like 8106245782738, and not formatted as a decimal number like 8106245782738.0.

Excel has a character limit of 32,767 characters per cell. When metafields with exactly this character count are detected, they will be ignored during import to prevent data corruption in Shopify. This typically happens when Excel has truncated longer text values. For large metafield values, consider using CSV files for importing the values.

It looks like you are trying to upload an export of your WooCommerce products to Altera. Please try uploading the file again in the Altera/Matrixify format instead.

You are using the DELETE command in your import. Please note that deleting items is permanent and cannot be undone. The deletion will also process any hidden rows in your spreadsheet, so make sure to review your data carefully before proceeding.

You are using the REPLACE command in your import. When replacing items, the existing item will be completely deleted and recreated with the new data. This means all existing data not included in your import will be lost. The replacement will also process any hidden rows in your spreadsheet, so make sure to review your data carefully before proceeding.

ZIP files uploaded for import should not contain subdirectories. All CSV files should be placed at the root level of the ZIP file. Please restructure your ZIP file to place all CSV files in the root directory without any subdirectories.

The ZIP file you uploaded contains files that are not CSV files. ZIP files for import should only contain CSV files (plus any system files like .DS_Store which are automatically ignored). Please remove any non-CSV files from your ZIP file and try again.

The value provided cannot be converted to true/false. Boolean columns in your spreadsheet must contain recognized true or false values.

Accepted true values:

Accepted false values:

Values are case-insensitive, so TRUE, True, FALSE, and False are also valid. Make sure all values in boolean columns match one of these accepted formats.

The file you uploaded appears to be an order export from Shopify's admin in Shopify's native format. Altera requires order files to be in the Altera/Matrixify format instead, which contains more data than Shopify's native export.

You can convert the file in the 'Transform data' section of the app. Note that even if you convert a Shopify order export to the Altera/Matrixify format, not all order data will come through. Shopify's native order export is missing many fields that are required for a complete order import. For example:

If you're trying to copy orders from one Shopify store to another, the best approach is to:

This ensures all order data is captured and transferred correctly.

The system could not find a file analysis for the uploaded file. This typically occurs when trying to process a file that hasn't been analyzed yet. The file analysis should be triggered automatically when a file is uploaded.

If you continue to see this error, please contact support.

The file analysis completed successfully, but no analysis data was found. This is an unexpected error that indicates a problem with the analysis process.

Please try re-uploading your file. If the problem persists, contact support.

The system was unable to analyze your file due to an error. This could be caused by:

Try re-uploading your file. If the error persists, verify that your file is a valid CSV, Excel (.xlsx), or ZIP file. Contact support if you need further assistance.

The file analysis took too long to complete and timed out. This can happen with very large files or during periods of high system load.

Please try again in a few moments. If the problem persists with the same file, consider:

The Command column contains a value we don't recognize. Valid commands are:

Check your Command column for typos (e.g., "CREATE" instead of "NEW") and update them to one of the supported commands above. You can also leave the Command column blank to use the default MERGE behavior.

Error codes related to data formatting and validation that can occur across different object types (orders, customers, products, etc.).

The phone number provided in your import is not in a valid format that Shopify accepts. Shopify is fairly strict about phone numbers and may reject numbers that are accepted in other platforms.

To ensure the phone number is accepted we recommend the following:

For US phone numbers specifically, Shopify rejects the area code 555 and all area codes starting with 1 as those are not real phone numbers.

Excel formatting tip: When entering phone numbers that start with a plus sign (like +16308545555), Excel may interpret them incorrectly or apply unwanted formatting. To prevent this, prefix the phone number with a single quote character (e.g., '+16308545555). The quote tells Excel to treat the value as text, and it won't be visible when the file is processed.

The province/state code provided in your import is not valid for the specified country. Shopify uses ISO 3166 standard province codes, and each country has its own set of valid province codes.

How to fix this:

Common examples:

If you're importing addresses for a country that doesn't require province codes, simply leave the province column empty rather than trying to provide a value.

The country code provided in your import is not valid. Shopify uses ISO 3166-1 alpha-2 standard country codes, which are two-letter codes that represent countries.

How to fix this:

Common examples:

Common mistakes:

The email address provided in your import is not in a valid format. Shopify validates email addresses to ensure they follow proper email formatting standards.

How to fix this:

Common examples of valid emails:

The value provided is not a valid number or cannot be converted to a number. This error occurs when numeric fields contain text, special characters, or formatting that cannot be interpreted as a valid numeric value.

This error applies to various numeric fields across different import types including:

How to fix this:

Common examples:

Invalid values:

Valid values:

Excel formatting tip: Sometimes Excel may modify email addresses, especially if they contain special characters. Use single quotes to force text formatting: '[email protected]

These codes indicate that a row was skipped during import based on the command used and whether the item exists in Shopify. Skipped rows are not errors - they are expected behavior when using NEW, UPDATE, or DELETE commands with items that don't match the command's requirements.

You used the NEW command to create an item, but an item with the same identifier already exists in your Shopify store. The row was skipped to prevent creating duplicates.

Why this happens: The NEW command is designed to only create items that don't already exist. When it finds a matching item, it skips the row rather than failing.

How to resolve:

You used the UPDATE command to update an item, but no matching item was found in your Shopify store. The row was skipped because there's nothing to update.

Why this happens: The UPDATE command is designed to only update items that already exist. When it can't find a matching item, it skips the row rather than failing.

How to resolve:

You used the DELETE command to delete an item, but no matching item was found in your Shopify store. The row was skipped because there's nothing to delete.

Why this happens: The DELETE command is designed to only delete items that exist. When it can't find a matching item (perhaps because it was already deleted), it skips the row rather than failing.

How to resolve:

When importing a ZIP file containing multiple CSV files, the system could not find a CSV file matching the expected sheet name. This typically occurs when the ZIP file structure doesn't match what was detected during file analysis.

How to resolve:

The file format is not supported for this operation. Altera supports Excel (.xlsx), CSV, and ZIP files containing CSV files.

How to resolve:

Error and warning codes that occur when dealing with smart and manual collections

The collection that already exists in Shopify is a smart collection, but the import is trying to treat it as a manual collection. Shopify does not allow you to convert a smart collection to a manual collection. You can replace the collection however by setting the 'Command' column to REPLACE.

The collection that already exists in Shopify is a manual collection, but the import is trying to treat it as a smart collection. Shopify does not allow you to convert a manual collection to a smart collection. You can replace the collection however by setting the 'Command' column to REPLACE.

When creating a smart collection rule based on a metafield, the system could not find the corresponding metafield definition. Make sure that the metafield definition exists in your Shopify store, and has the 'Smart collection' enabled, before creating a smart collection rule that references it.

The metafield condition column format is invalid. When creating a smart collection rule based on a metafield, the column must follow the correct format:

For example: Metafield: custom.size or Variant Metafield: custom.color

Make sure your metafield condition includes the namespace and key separated by a period (.).

For more information about smart collection rule formats, see the Smart Collection Fields documentation.

Error and warning codes that occur when dealing with discount imports and operations.

The Shopify API rejected the discount data and refused to save it. This typically occurs when the discount configuration violates Shopify's business rules or contains invalid data that passed initial validation but failed at the API level.

The discount type specified in your import is not valid. The 'Type' column must be one of: 'Amount off Products', 'Amount off Order', 'Free Shipping', 'Buy X Get Y', or empty.

The discount method specified in your import is not valid. The 'Method' column must be either 'Code', 'Automatic', or empty.

The system attempted to create a discount with a type that is not supported by the discount creation API. This is an internal error that should be reported if encountered.

The date format provided for a discount field (such as start date or end date) is invalid. Expected format is YYYY-MM-DD HH:MM:SS or YYYY-MM-DD.

The usage limit value provided for the discount is not a valid number. Usage limits must be whole numbers (integers) indicating how many times the discount can be used.

The discount with the specified ID could not be found in your Shopify store. This may occur when trying to update or delete a discount that doesn't exist.

The system tried to delete a discount with a type that is not supported by the deletion API. This is an internal error that should be reported if encountered.

The system failed to add multiple codes to an existing discount. This typically happens when trying to add duplicate codes or codes that violate Shopify's validation rules.

The 'uses per order limit' value provided for the discount is not a valid number. This field must be a whole number (integer) indicating how many times the discount can be applied within a single order.

The customer segment specified in your discount cannot be found in your Shopify store. Make sure the segment name matches exactly and that the segment exists in your store.

The customer with the specified email address cannot be found in your Shopify store. Make sure the email address is correct and that the customer exists in your store.

The system could not determine the discount type from the provided data. This is an internal error that should be reported if encountered.

The system attempted to update a discount with a type that is not supported by the discount update API. This is an internal error that should be reported if encountered.

Importing discounts is still in beta. Please test with 1 or 2 discounts first to ensure everything works as expected before importing larger datasets.

The discount type was not specified in the import data. Make sure your import includes the discount type information or that existing discounts have their type properly identified.

The discount value must be a valid number. This error occurs when the 'Value' column contains text or other non-numeric values that cannot be converted to numbers. For percentage discounts, use a numeric value (e.g., 10.00 for 10% off). For fixed amount discounts, use the monetary value without currency symbols (e.g., 25.00 for $25 off). Ensure all values in the 'Value' column are either empty or contain only numeric values.

Numbers should use a period (not comma) for decimal separation and should not include thousands separators. For example, use 1234.66 instead of 1,234.66 or 1234,66.

When you specify a 'Minimum Value' for a discount, you must also set the 'Minimum Requirement' column to either 'Amount' or 'Quantity'. This tells Shopify whether the minimum requirement is based on:

Make sure that every row with a 'Minimum Value' also has a corresponding 'Minimum Requirement' set to one of these valid values. Empty or invalid values in the 'Minimum Requirement' column will cause the discount import to fail.

When you specify a 'Minimum Requirement' for a discount (either 'Amount' or 'Quantity'), you must also provide a corresponding value in the 'Minimum Value' column. This value determines the threshold that customers must meet to qualify for the discount.

For example:

Make sure that every row with a 'Minimum Requirement' set to 'Amount' or 'Quantity' also has a valid numeric value in the 'Minimum Value' column. Empty values will cause the discount import to fail.

This error occurs when trying to configure subscription-related discount fields on a store that doesn't have a subscription app installed. Shopify only allows subscription discount settings when the store has a subscription management app active.

The fields that require a subscription app are:

How to fix this:

If you don't need subscription functionality for your discounts, simply remove these columns from your spreadsheet and the import will proceed successfully.

Error and warning codes for importing and exporting files.

In some situations stores that are on a Shopify Trial are not able to upload files through the API. This is related to the store's subscription to Shopify, it has nothing to do with being on a paid or free plan with Altera. If your files fail to upload you will need to either switch to a paid Shopify plan or reach out to Shopify support for more help. In some situations this also applies to uploading images when you create new products.

Alt text is required when updating existing files. The UPDATE command requires you to provide the 'Alt' column with a value to update the file's alt text. If you want to replace the file entirely rather than just updating its metadata, use the REPLACE command instead.

The system failed to download and stage the media file for upload to Shopify. This error occurs when importing VIDEO or 3D model files (MODEL_3D) that need to be staged before uploading to Shopify's servers.

Media types are automatically detected from file extensions when not explicitly specified:

Common reasons for this error include:

How to fix this:

Note: IMAGE and EXTERNAL_VIDEO media types do not require staging and are uploaded directly.

Codes related to creating and managing import or export jobs.

In order to provide a reliable service to all users you may have a limit to the number of jobs you can run at the same time. You can either cancel another job or wait for it to finish before starting a new job.

You have reached the maximum number of scheduled jobs allowed by your plan. To create a new scheduled job, you'll need to either disable an existing scheduled job or upgrade your plan for a higher scheduled job limit.

Your export has reached the maximum number of rows allowed by your current plan. The export was completed up to this limit, but additional data could not be included in the file.

To export more data, you can:

The exported file will contain a message indicating where the row limit was reached.

The single CSV export format only supports exporting one object type at a time. To export multiple object types, use the ZIP format (matrixify_zip) instead, which creates separate CSV files for each object type in a single archive.

Error and warning codes for importing and exporting menus.

When you import menus you need to have menu item columns like "Menu Item: Resource Type" and "Menu Item: Title". To get these columns in an export, make sure that you select the 'General' and 'Menu items' groups when configuring which fields to export.

The Shopify API rejected the menu data and refused to save it. This typically occurs when the menu configuration violates Shopify's business rules or contains invalid data that passed initial validation but failed at the API level.

The 'Menu Item: Title' column contains empty values. When importing menus, every menu item must have a title. Check your spreadsheet and ensure that all rows with menu items have a title specified in the 'Menu Item: Title' column. Empty titles will prevent the menu items from being created properly in Shopify.

The menu title is required when creating a new menu. Make sure your import includes the 'Title' column with a valid menu name for each menu you want to create. Empty or missing titles will prevent the menu from being created in Shopify.

A circular reference has been detected in your menu structure. This occurs when a menu item is configured to be its own parent or ancestor, creating an infinite loop in the menu hierarchy.

Common scenarios that cause this error:

How to fix this:

Example of problematic data:

To resolve this, ensure your menu hierarchy flows in one direction without any item becoming its own ancestor.

A menu item has the same value for both 'Menu Item: ID' and 'Menu Item: Parent ID', which creates a direct self-reference. A menu item cannot be its own parent in the menu hierarchy.

This is a specific case of a circular reference where a menu item directly references itself as its parent, rather than indirectly through other menu items.

How to fix this:

Example of problematic data:

Corrected data:

or

Error and warning codes for importing and exporting metafield definitions.

The metafield definition could not be deleted. This may be because the metafield definition was already removed.

Certain namespaces like shopify and shopify--discovery--product_search_boost are protected namespaces that belong to Shopify proper. Third-party apps are not allowed to update these metafield definitions through the API. This often occurs when trying to import metafield definitions for Shopify Product Category Metafields. Unfortunately at this time those still need to be created manually within the Shopify admin.

Required columns are missing from your metafield definition import. For metafield definitions to import correctly, your spreadsheet must include both 'Type: Name' and 'Namespace' columns. These fields are necessary for Shopify to properly create the metafield definitions.

The column for specifying the metafield type should be named 'Type: Name', not just 'Type'. Please rename this column in your spreadsheet before importing.

Error and warning codes related to metafield values during imports.

The value provided for a metafield could not be saved to Shopify because it doesn't match the expected format or validation rules for that metafield. This commonly happens when:

To resolve this issue, check that the metafield value conforms to the requirements of its definition in your Shopify store. You may need to view the metafield definition in Shopify admin to verify the expected type and format.

Error and warning codes related to metafield operations and conversions.

Shopify stores rich text metafields not as HTML but in a custom JSON format. When you import HTML content into a rich text metafield, Altera attempts to convert it to Shopify's rich text JSON format for you. However, if the HTML is invalid or contains elements that cannot be converted, the conversion may fail.

Common causes:

How to fix this:

Error and warning codes that occur when dealing with metaobject definition imports and operations.

You are trying to create a metaobject definition that belongs to a standard Shopify namespace. Standard Shopify metaobject definitions (like those with system-reserved type names) cannot be created through the API as they are managed by Shopify itself. Only custom metaobject definitions can be created through imports.

You are trying to update a metaobject definition that belongs to a standard Shopify namespace. Standard Shopify metaobject definitions (like those with system-reserved type names) cannot be modified through the API as they are managed by Shopify itself. Only custom metaobject definitions can be updated through imports.

The metaobject definition you are trying to delete cannot be found in your Shopify store. This may be because it was already deleted or because the identifier (ID or type) provided in your import is incorrect.

The 'Type' column is required for metaobject definition imports and cannot be empty. This column specifies the type identifier for the metaobject definition, which is used to identify and create the definition in Shopify. Make sure your import file includes the 'Type' column with valid type names for all metaobject definitions.

You are trying to create or modify a metaobject definition that belongs to a standard Shopify namespace (typically starting with "shopify--"). These are system-managed metaobject definitions that cannot be created or modified through the API. Only custom metaobject definitions can be imported. Please remove any standard Shopify metaobject definitions from your import file.

Error and warning codes that occur when dealing with metaobject imports and operations.

The metaobject definition type is required for metaobject imports and cannot be empty. This column specifies which metaobject definition the imported data should use. Make sure your import file includes the 'Definition: Type' column with valid metaobject definition types for all rows containing metaobject data.

The metaobject definition with the specified type could not be found in your Shopify store. This typically occurs when the metaobject definition doesn't exist or the type name is incorrect. Verify that the metaobject definition exists in your store and that the type name matches exactly.

Error and warning codes that occur when dealing with catalog imports and operations.

The Shopify API rejected the catalog data and refused to save it during an update operation. This typically occurs when the catalog configuration violates Shopify's business rules or contains invalid data that passed initial validation but failed at the API level.

The market specified in your catalog import cannot be found in your Shopify store. Make sure the market handle matches exactly and that the market exists in your store. Check that the market is properly configured and active.

The company location specified in your catalog import cannot be found in your Shopify store. Make sure the company location name matches exactly and that the location exists in your store. Verify that the company location is properly set up in your B2B configuration.

The system failed to create a price list for the catalog. This typically happens when there are issues with the price list configuration or when Shopify's API rejects the price list data. Check your price list settings including currency, name, and any parent adjustment configurations.

You cannot change the publication ID of an existing catalog during an update operation. The publication ID is set when the catalog is created and cannot be modified afterward. If you need to change the publication association, you may need to replace the catalog entirely using the REPLACE command.

The Shopify API rejected the catalog data and refused to create the catalog. This typically occurs when the catalog configuration violates Shopify's business rules or contains invalid data that passed initial validation but failed at the API level during creation.

After creating a catalog, the system could not find the associated price list that should have been created. This is an internal error that indicates an issue with the catalog creation process. Please try again or contact support if the problem persists.

The 'Type' and 'Type Values' fields are required when creating a catalog. These fields determine the context of the catalog (such as which markets or company locations it applies to). Make sure your import includes both the catalog type (e.g., "Market" or "Company Location") and the corresponding values (e.g., market handles or location names).

Catalogs for sales channels/apps cannot be created through the API. Only catalogs for markets and company locations are supported. If you need to create catalogs for apps or sales channels, you'll need to do this manually through the Shopify admin interface.

Error and warning codes that occur when dealing with customer imports and operations.

You are trying to set a specific Store Credit Amount with an expiration date, but the customer already has a non-zero store credit balance.

When using the 'Store Credit: Amount' column, the system creates a transaction for the difference between the current balance and the target amount. If you provide an expiration date, it would only apply to this adjustment transaction, not the entire balance. This would result in different parts of the balance having different expiration dates, which is not the intended behavior when setting a total amount.

To resolve this, you can:

The date format provided for the store credit balance expiry date is invalid. The 'Store Credit: Expires At' column contains a value that cannot be parsed as a valid date/time.

The date should be in a standard format that can be recognized, such as:

Make sure all values in the 'Store Credit: Expires At' column are either empty or contain properly formatted date/time values.

The expiry date provided for the store credit balance is not in the future. The 'Store Credit: Expires At' column contains a date/time that is in the past or is the current date/time.

Store credit expiry dates must be set to a future date to be valid. Check that the date you're providing is after the current date and time.

How to fix this:

Store credit columns detected in your customer import. These operations affect real money and customer account balances. Please double-check your data carefully before importing, as incorrect values could result in financial discrepancies or customer billing issues.

Error and warning codes that occur when dealing with company imports and operations.

The system failed to create a new company due to an error from the Shopify API. This typically occurs when the company data violates Shopify's business rules or contains invalid information. Check the detailed error message for specific issues with your company data, such as missing required fields or invalid values.

The system failed to update an existing company due to an error from the Shopify API. This typically occurs when the updated company data violates Shopify's business rules or contains invalid information. Check the detailed error message for specific issues with your company data.

The system failed to delete a company due to an error from the Shopify API. This may occur if the company has associated data that prevents deletion or if there are business rule violations. Check the detailed error message for specific information about why the deletion failed.

The Shopify API rejected the company data and refused to save it during an update operation. This typically occurs when the company configuration violates Shopify's business rules or contains invalid data that passed initial validation but failed at the API level.

The system failed to create a new company location due to an error from the Shopify API. This typically occurs when the location data violates Shopify's business rules or contains invalid information. Check the detailed error message for specific issues with your location data.

The system failed to update an existing company location due to an error from the Shopify API. This typically occurs when the updated location data violates Shopify's business rules or contains invalid information. Check the detailed error message for specific issues with your location data.

The system failed to delete a company location due to an error from the Shopify API. This may occur if the location has associated data that prevents deletion or if there are business rule violations. Check the detailed error message for specific information about why the deletion failed.

The system failed to assign an address to a company location due to an error from the Shopify API. This typically occurs when the address data is invalid or incomplete. Ensure that required address fields like address1 and countryCode are provided and valid.

The system failed to update tax settings for a company location due to an error from the Shopify API. This typically occurs when the tax configuration is invalid or conflicts with existing settings. Check the detailed error message for specific issues with your tax settings.

The system failed to create a new company contact due to an error from the Shopify API. This typically occurs when the contact data violates Shopify's business rules, the customer already exists, or required information is missing. Check the detailed error message for specific issues.

The system failed to delete a company contact due to an error from the Shopify API. This may occur if the contact has associated data that prevents deletion or if there are business rule violations. Check the detailed error message for specific information about why the deletion failed.

The system failed to assign roles to customers at a company location due to an error from the Shopify API. This typically occurs when the role assignment data is invalid, the customer or role doesn't exist, or there are business rule violations. Check the detailed error message for specific issues.

The system failed to revoke roles from customers at a company location due to an error from the Shopify API. This typically occurs when the role assignment doesn't exist or there are business rule violations. Check the detailed error message for specific information about why the revocation failed.

The system failed to assign a catalog to company locations due to an error from the Shopify API. This typically occurs when the catalog or location doesn't exist, or when there are business rule violations preventing the assignment. Check the detailed error message for specific information about the failure.

The system failed to remove a catalog from company locations due to an error from the Shopify API. This typically occurs when the catalog assignment doesn't exist or there are business rule violations preventing the removal. Check the detailed error message for specific information about the failure.

A company name is required when creating a new company. This error occurs when attempting to create a new company record without providing a value in the 'Name' column. The company name is a mandatory field in Shopify and must be specified for all new company records.

How to fix this:

The 'Location: Tax Exemptions' column contains invalid tax exemption values. This column must either be blank or contain a comma-separated list of valid tax exemption codes that Shopify recognizes.

Valid tax exemption codes include exemptions for specific regions and purposes, such as:

For a complete list of all valid tax exemption values, see the Shopify TaxExemption enum documentation.

How to fix this:

Example of valid data:

When updating a company, if you try to identify a location by name and multiple locations exist with the same name, this error occurs. Location names are not unique in Shopify's B2B system, so when multiple locations share the same name, the system cannot determine which one to update.

How to fix this:

Example:

Instead of:

Use:

This error occurs when using the UPDATE command for a company location that doesn't exist. The UPDATE command requires the location to already exist in the company before it can be updated.

How to fix this:

Example of valid data:

This error occurs when trying to assign a customer as a contact to a company, but the customer is already associated with a different company. Shopify does not allow a customer to be a contact for multiple companies simultaneously.

How to fix this:

These codes are related to uploading blog posts (articles) and blogs.

The image for a blog post needs to be a complete URL that starts with http:// or https://.

Shopify needs to associate all blog posts with a blog on your store. If you are unsure of what to set this to, just add the 'Blog: Handle' column to your spreadsheet with the values 'blog' in each row.

Shopify blog posts only support one featured image, but you can include additional images in the body HTML of your post. This warning is raised if there's commas or pipe characters in the Image Src column because those are often used to separate different URLs.

Shopify does not accept blog post dates before January 1, 1970 (the Unix epoch). If you have blog posts with dates before this, you'll need to update them to a valid date range. This limitation is due to how Shopify handles date storage internally.

The published date is more than 10 years in the future, which might indicate a data entry error. While Shopify may accept future dates, having dates too far in the future could cause unexpected behavior or indicate that the year was entered incorrectly (e.g., typing 2224 instead of 2024).

The 'Published At' column contains a value that cannot be parsed as a valid date/time. The date should be in a standard format that can be recognized, such as:

Make sure all values in the 'Published At' column are either empty (for drafts) or contain properly formatted date/time values.

A 'Body HTML' value is exactly 32,676 characters long, which indicates that Excel has truncated the content. Excel has a cell character limit of 32,767 characters, and when content exceeds this limit, it gets cut off.

To avoid data loss, export your original data in CSV format instead of Excel. CSV files do not have the same character limitations as Excel cells, so your full Body HTML content will be preserved.

These codes occur when trying to figure out which kind of Shopify object you are importing or exporting (e.g., products, orders etc..)

When trying to export objects, the provided object type wasn't recognized. Ensure you're using a valid object type (e.g., products or orders).

Sheet analysis didn't find a matching type for the label. Double-check your sheet configurations or labels before importing.

You tried to import using an object slug that isn't supported. Confirm it's a valid import type (e.g., products, customers).

A metafield reference value didn't start with gid://shopify/, so it couldn't be processed. Check that all reference handles match the expected gid://shopify/ format.

Error and warning codes that occur when dealing with draft order imports and operations.

We're still working on importing draft orders. Please email us if you need more information about when this feature will be available or if you have specific requirements for draft order imports.

The draft order you are trying to delete cannot be found in your Shopify store. This may be because it was already deleted or because the identifier (ID or name) provided in your import is incorrect.

The Shopify API rejected the draft order data and refused to save it during a creation operation. This typically occurs when the draft order configuration violates Shopify's business rules or contains invalid data that passed initial validation but failed at the API level.

You are trying to update a draft order that has already been completed (converted to a real order). Completed draft orders are locked and only their tags can be modified. Other changes require creating a new draft order.

The Shopify API rejected the draft order data and refused to update it. This typically occurs when the updated draft order configuration violates Shopify's business rules or contains invalid data that passed initial validation but failed at the API level.

The email address provided for the draft order is not in a valid format. Email addresses must follow the standard email format (e.g., [email protected]). Please check the email field and ensure it contains a properly formatted email address.

The date format provided for the 'Reserve Inventory Until' field is invalid. Expected format is YYYY-MM-DD HH:MM:SS or YYYY-MM-DD. Please ensure your date values match one of these formats.

Error and warning codes that occur when dealing with orders

Order sheets work best with either a Name or ID column for grouping. When neither column is present, the system will fall back to using "Top Row" column markers for grouping, or group all rows into a single order if no Top Row column exists.

Required columns, such as the Line: Type column are missing from the source file.

The Line: Type column must be one of these values:

Importing orders will trigger Shopify Admin staff notifications for each order unless they are disabled. Shopify does not provide a way for apps to detect if notifications are already turned off.

To disable order notifications, open up the Shopify admin and go to Settings > Notifications > Staff notifications and turn them off before importing large batches of orders.

Additionally, importing orders may trigger other applications that are configured to process new orders on Shopify. We recommend testing with 1-2 orders before importing large batches of orders.

Editing existing orders is not currently supported through the application. You may need to delete the existing order and create a new one with your desired changes.

This error occurs when processing a refund with insufficient line item data. When processing refunds, make sure to include all required line item information to properly associate the refund with the correct items.

Shopify limits new orders to 5 per minute on trial and development stores. If your store is on a trial or development plan, order imports will run more slowly due to this limitation. To increase the import speed, consider upgrading to a paid Shopify plan.

The date/time columns in your order import ('Processed At', 'Transaction: Processed At', 'Fulfillment: Processed At') must contain valid date/time values or be left blank. This error occurs when these columns contain text or other values that cannot be parsed as valid dates. Use standard date formats like 2024-01-15, 2024-01-15 14:30:00, or Jan 15, 2024 2:30 PM. Ensure all values in these columns are either empty or contain properly formatted date/time values.

When importing orders with fixed date payment terms, the 'Payment Terms: Due At' column must be provided and cannot be empty. This error occurs when you have specified a payment terms template that requires a fixed due date, but the corresponding 'Payment Terms: Due At' column is missing or empty. Ensure that for fixed date payment terms, you include the 'Payment Terms: Due At' column with a valid date/time value specifying when the payment is due.

More than one existing order matches the criteria provided in your import (ID or Name). Each row in your import must uniquely identify a single order. Check that your Order ID or Name values are unique and don't match multiple existing orders in your store.

You can only update a single fulfillment per order when the Fulfillment ID is not specified. If you need to update multiple fulfillments for the same order, you must provide the specific Fulfillment ID for each fulfillment you want to update.

When importing orders, if you provide any shipping or billing address information, you must provide all required address fields. This error occurs when some address fields are filled but others are missing.

Required shipping address fields:

Required billing address fields:

How to fix this:

Shopify does not allow editing orders that were placed in a currency different from your store's base currency. You can only add line items to orders that were placed in your store currency.

To resolve this:

Note: Shopify doesn't allow adding Line Items to an Archived Order – the app will automatically unarchive the order, add the line items, and then re-archive it if it was originally archived.

When using the Line: Command column with the MERGE value to add line items to an order, you must include at least one line item row in your spreadsheet.

To resolve this:

Error and warning codes that occur when dealing with product data

Products with multiple variants need to have the Option1 Value column set to identify the different variants.

The product status field must be empty or one of the following: ACTIVE, ARCHIVED or DRAFT.

The spreadsheet it identifying products by title but more than one product with that title exists in Shopify. A product title needs to be unique when using it to update a product. If you have multiple products with the same title you can either use the ID or Handle column to identify the product you want to update.

The Variant Weight column should just contain a number. If you want to set the unit of the weight you can set that separately in the Variant Weight Unit column.

When importing reference metafields the values need to be in the GID format like gid://shopify/Metaobject/123456789 or ["gid://shopify/Metaobject/123456789"] if it's a list of references. We are working on adding support for looking up references by handle. Please contact us if you feel this feature should be prioritized.

When including an 'Option1 Name' column in your product import, you must also include the corresponding 'Option1 Value' column. Option names define the type of variant (like "Size" or "Color"), while option values define the specific variants (like "Small" or "Red").

For each product with an 'Option1 Name' defined, you must provide a corresponding value in the 'Option1 Value' column. Empty option values will cause errors when creating variants in Shopify. Ensure all products with option names have corresponding option values set.

When updating variant data, you must include at least one column that identifies which variant to update, such as 'Variant ID', 'Variant SKU', or 'Variant Barcode' if the product has more than one variant. Without an identification column, the system cannot determine which variant should receive the updates. Add one of these columns to your import file to resolve this issue.

The product's title is required in each row of your import file. This is necessary for the system to properly group variants belonging to the same product. Make sure every row in your import file has a product title, even when importing multiple variants of the same product.

The price columns ('Variant Price', 'Variant Compare At Price', 'Variant Cost') should contain only plain numbers with a period (not comma) for decimal separation and no currency symbols. For example, use 19.99 instead of $19.99 or 19,99. This ensures that prices are correctly interpreted by Shopify when imported.

The meta description field (Metafield: description_tag [single_line_text_field]) should not contain newline characters. Newlines in meta descriptions can cause issues with SEO and may not display correctly in search engine results. Altera will attempt to remove any newline characters from this field during import, but it's best to ensure your source data does not include them.

The meta description field (Metafield: description_tag [single_line_text_field]) should not contain HTML elements. HTML in meta descriptions is typically stripped by search engines and may cause unexpected display issues in search results. Using plain text in meta descriptions is recommended for better SEO outcomes and proper display across all platforms. Please remove HTML elements like <div> or <p> tags from your meta descriptions.

When setting a compare-at price for a specific market, you must also set the regular price for that same market. Shopify requires that any market with a compare-at price must also have a regular price defined. Update your spreadsheet to include the regular price for any markets where you've specified a compare-at price.

The meta description field (Metafield: description_tag [single_line_text_field]) exceeds Shopify's recommended maximum length of 160 characters. While longer descriptions will be imported, search engines typically truncate meta descriptions to around 155-160 characters. For optimal SEO performance, keep your meta descriptions concise and within the recommended length to ensure they display properly in search results.

The meta title field (Metafield: title_tag [single_line_text_field]) exceeds Shopify's recommended maximum length of 70 characters. While longer titles will be imported, search engines typically display only the first 50-60 characters of meta titles in search results. For optimal SEO performance, keep your meta titles concise and within the recommended length to ensure they display properly in search results.

A title is required to create a new product. This error occurs when trying to create a product without providing a title field. This may also happen when trying to update products by SKU where the SKU doesn't exist on the store. In such cases, the system tries to create a new product but fails because there's no title provided in the import data.

If you are creating new products, ensure that each product row in your import file includes a 'Title' column with the product's name. If you are updating existing products by SKU you can ignore this error if you know that not all SKUs in your import file exist on the store.

The unit price data in the 'Variant Unit Price' column is not in the correct format. Unit price must be either blank or a valid JSON object with the following structure:

The valid units are: CL, CM, FLOZ, FT, FT2, G, GAL, IN, ITEM, KG, L, LB, M, M2, M3, MG, ML, MM, OZ, PT, QT.

Both quantityValue and referenceValue must be numeric. The quantityValue can be a decimal number, but referenceValue must be a whole number (though 2.0 is acceptable and will be converted to 2).

The 'Image Command' column contains an invalid value. This column specifies how images should be handled when importing products and must contain either 'MERGE', 'REPLACE', 'NEW', 'DELETE', or 'IGNORE' (case insensitive).

Make sure all values in the 'Image Command' column are either empty or one of the valid commands. Any other values will cause the import to fail.

The column contains values in Excel's scientific notation format (like 8.0335E+12 or 1.23E-05). This typically happens when:

How to fix this:

Prevention: Always format SKU and Barcode columns as "Text" in Excel before entering data, especially for UPC codes, EAN codes, or other long numeric identifiers that should be treated as text rather than numbers.

You are trying to set inventory levels for a product variant at a location where the inventory item is not stocked. Before you can update inventory quantities, the product variant must first be stocked at that location.

If you are trying to set inventory using the Variant Inventory Qty column, the app will try to stock the variant at the oldest active location on your store. (It is not possible to see the default location for a store through the API.) If you want to stock the variant at a specific location, you can use the Inventory Available: [Location Name] column to set the inventory quantity.

You are trying to set inventory quantities for a product variant that has inventory tracking disabled. In Shopify, you cannot set inventory levels for variants that are not being tracked.

There are several ways to fix this:

The Harmonized System (HS) code provided is invalid. HS codes are used to classify goods for customs purposes.

If you are seeing this error, check that your HS codes:

You can search for valid HS codes on the UK's Integrated Online Tariff website.

Error codes that appear when downloading files from remote sources (HTTP, FTP, Google Drive, etc.) and managing remote connections

The URL scheme is not supported. Currently supported schemes are HTTP, HTTPS, and FTP.

The URL format is invalid for the specified source type. Make sure you've entered a valid URL.

The file was not found at the specified URL. Please check that the URL is correct and the file exists.

Authentication is required or you have insufficient permissions to access the file. Check if the file requires login or specific permissions.

An HTTP error occurred when trying to download the file. This could be due to server problems or invalid requests.

The downloaded file is empty (zero bytes). Please check the source file.

Failed to connect to the server. Check your internet connection and verify the URL is correct.

The connection timed out while trying to download the file. This could be due to a slow connection or server issues.

The file download failed due to a general request error. Check the detailed error message for more information.

An unexpected error occurred during the HTTP download. Check the logs for more details.

Failed to connect to the FTP server. Check that the server address is correct and the server is running.

Authentication failed for the FTP server. Verify your username and password.

Unable to access the file on the FTP server. The file may not exist or you might not have permission to access it.

An error occurred during the FTP file transfer. Check your connection and try again.

The downloaded FTP file is empty (zero bytes). Please check the source file.

A general FTP error occurred. Check the detailed error message for more information.

An unexpected error occurred during the FTP download. Check the logs for more details.

The remote connection you are trying to use cannot be found. This may be because it was deleted or because the identifier provided is incorrect. Please verify that the remote connection exists and that you have access to it.

No hostname was provided for the FTP server connection. When configuring an FTP connection, the hostname (server address) is required. Please check your remote connection settings and ensure that the 'Host' field is filled in with a valid FTP server address.

The local file specified for upload cannot be found on the system. This typically occurs when trying to upload a file to an FTP server, but the source file path is incorrect or the file has been deleted or moved. Please verify that the file exists at the specified location before attempting to upload it.

Unable to upload the file to the FTP server due to permission issues. This error occurs when you lack write permissions to the target directory on the FTP server. Verify that:

Contact your FTP server administrator if you need additional permissions for the upload location.

An error occurred during the FTP file upload process. This could be due to various reasons such as:

Check the detailed error message for more information about what went wrong during the upload process.

An unexpected error occurred during the FTP upload process. This is a general error code for unexpected issues that occur when uploading files to an FTP server. Check the logs for more details about the specific error that occurred.

Failed to create a required subdirectory on the FTP server during file upload. This error occurs when:

Common causes:

How to fix this:

An unexpected error occurred during the remote file upload process. This is a general error code for unexpected issues that occur when uploading files to any remote connection type (HTTP, FTP, SFTP, etc.). Check the error message and logs for more details about the specific error that occurred.

An unexpected error occurred during the remote file download process. This is a general error code for unexpected issues that occur when downloading files from any remote connection type (HTTP, FTP, SFTP, etc.). Check the error message and logs for more details about the specific error that occurred.

The upload transfer is missing the local file path in its metadata. This typically occurs when attempting to upload a file to a remote server, but the system cannot find the path to the local file that should be uploaded. Check that the transfer was configured correctly with the required metadata including the local file path.

The upload transfer is missing the remote destination path. This error occurs when attempting to upload a file to a remote server (FTP, SFTP, etc.), but the system doesn't know where on the remote server to place the file. The remote file path specifies the destination location and filename on the remote server.

How to fix this:

No files were found matching the specified wildcard pattern on the FTP server. This error occurs when attempting to download a file using a wildcard pattern (e.g., export_*.csv), but no files on the server match the pattern.

How to fix this:

Failed to connect to the SFTP server. Check that the server address is correct and the server is running.

Authentication failed for the SFTP server. Verify your username, password or key file.

Unable to access the file on the SFTP server. The file may not exist or you might not have permission to access it.

An error occurred during the SFTP file transfer. Check your connection and try again.

The downloaded SFTP file is empty (zero bytes). Please check the source file.

The downloaded file is in a format that is not supported for importing. Please check our documentation for supported file formats.

The remote file exceeds the maximum allowed file size. Please try with a smaller file or contact support for assistance.

Rate limit exceeded when accessing the remote file. Please try again later or with a different source.

You have reached your plan's limit for the number of remote connections you can create.

How to fix this:

You cannot delete this remote connection because it is being used by one or more active repeating jobs. Before deleting the connection, you must first either:

To find which jobs are using this connection, go to the Jobs page and look for scheduled jobs that reference this connection.

An unhandled error occurred during the remote file download process. This is a general error code for unexpected issues.

These codes occur when the app is writing your output to a spreadsheet

You attempted to export using a data type the system doesn't recognize. Please try to reconfigure the job and run it again.

The export format is not recognized. Currently Altera only supports CSV and Excel files in the Altera/Matrixify format.

These codes occur when interacting with the Shopify API.

Shopify imposes a daily limit on the number of product variants that can be created through the API. This error occurs when you've reached that limit for the current day.

When you encounter this error:

This is a Shopify platform limitation and cannot be bypassed through the application.

An error was returned from the Shopify API that was not related to internal server issues or product modification conflicts. This could be due to various reasons such as invalid data, API limitations, or other Shopify-specific constraints. The exact error message from Shopify will be provided with this code to help diagnose the specific issue.

This error occurs when waiting for files to reach a terminal status (READY or FAILED) but the operation times out before all files complete processing. This can happen when:

If you encounter this error, you can try:

These codes appear when Shopify rejects an operation due to validation issues or business rule violations.

This error occurs when Shopify rejects the data you're trying to submit because it doesn't meet their requirements. Unlike technical API errors, these are usually related to the actual content of your data.

Common reasons for this error include:

The error message accompanying this code will provide specific details about what went wrong, which should help you correct your data before trying again.

Error codes related to API key permissions and access control.

This error occurs when the API key being used does not have the necessary permissions to perform the requested operation. Each API key can be configured with specific permissions that control which types of jobs (imports or exports) and which object types (products, orders, customers, etc.) it can access.

Common reasons for this error include:

How to fix this: