This article provides a comprehensive guide on importing orders efficiently using a CSV file. Streamline your order management by importing orders in bulk, eliminating the need for manual entry.
Preparing Your CSV File for Import
Before initiating the import process, ensure your CSV file is correctly structured. Download the CSV template to guarantee accurate data formatting. Each row in the CSV file should represent a single line item, allowing orders to span multiple rows. Utilize the "orderReferenceId" column to link line items to their corresponding orders.
For each row, include essential order details:
Order Reference ID
Shipping Details
Item Details
URLs for Each Print Area
For a detailed explanation of the required fields in the CSV file, refer to the "Create order" page in our API documentation. This comprehensive resource provides valuable insights into structuring your import data effectively: Create order.
Importing Orders: A Step-by-Step Guide
Follow these steps to import your orders seamlessly:
Access your Orders page and click the "Import" button.
Choose the designated store for your imported orders. These orders will be marked as placed from the selected store. You have the flexibility to import them as manual orders as well.
Upload the CSV file containing the orders you want to import. You can also download a fresh CSV template from this page.
Double-check that you've selected the correct destination store and import file. Once everything is in order, click "Import" to begin the import process.
You'll receive a notification confirming the initiation of the import process.
Once the import process is finished, we'll send you an email notification. This email will provide a summary of the import, including:
The total number of orders in the import file.
The number of orders successfully imported.
The number of orders that failed to import.
Additionally, the email will include a CSV file containing detailed import results. This file will have three columns:
orderReferenceId
result (indicating "success" or "failure" for each order)
errors (providing specific reasons for any import failures)
Understanding Required Parameters for CSV File for Import
Below, you'll find a detailed breakdown of the necessary parameters and their corresponding documentation references to help you complete the spreadsheet accurately.
This method is mainly used by those testing the platform before integrating with our APIs or submitting ad hoc orders.
General Order Information
orderReferenceId – Displays the order number in the Gelato dashboard. Example:
G-250202201217.customerReferenceId – Internal customer ID reference.
orderType – Can be set as
draft, but defaults toorder.shipmentMethodUid – Specifies the shipping method:
normal,standard, orexpress.currency – Currency used for payment.
retailShippingPriceInclVat, retailCurrency, item.retailPriceInclVat – Used in analytics and various areas of the platform, including customs forms.
Shipping Address Details
These parameters correspond to standard checkout address fields:
shippingAddress.firstName
shippingAddress.lastName
shippingAddress.addressLine1
shippingAddress.addressLine2
shippingAddress.city
shippingAddress.postCode
shippingAddress.state
shippingAddress.country
shippingAddress.email
shippingAddress.phone
shippingAddress.companyName
Tax and Compliance Details
shippingAddress.federalTaxId – The Federal Tax identification number of the recipient. Used to provide CPF/CNPJ for a Brazilian recipient. Mandatory for Brazil. To supply CNPJ instead of CPF, set
isBusinesstotrue.shippingAddress.stateTaxId – The State Tax identification number of the recipient. Used to provide IE for a Brazilian recipient. Mandatory for Brazil if the recipient is a company. To supply this field, set
isBusinesstotrue.shippingAddress.registrationState – The code number for a U.S. state or the equivalent for other countries, defining the state where the recipient company is registered. Mandatory for Brazil if the recipient is a company. To supply this field, set
isBusinesstotrue.
Product Information
item.itemReferenceId – Corresponds to
Item Reference IDin the order. For eCommerce platform orders, this is assigned automatically. For manual orders, it must be defined.item.productUid – Follow our guide on product UIDs and how to map products to Gelato’s standards.
item.storeProductVariantId – Provide the variant ID from the store URL, e.g.,
https://dashboard.gelato.com/stores/e92a3ee9-e494-41bf-a031-ca80e2fa3558/products/edit/04076663-f5a3-4701-af66-be932c676697.item.quantity – Specifies the number of units ordered.
item.pageCount – Required for multipage products (e.g., brochures).
Embroidery-Specific Parameters
For embroidery designs, additional parameters are required. Refer to the Embroidery Guide for full details.
item.adjustProductUidByFileTypes
item.file1.id, item.file1.type, item.file1.url, item.file1.threadColors, item.file1.fitMethod, item.file1.fillMethod
item.file2.id, item.file2.type, item.file2.url, item.file2.threadColors, item.file2.fitMethod, item.file2.fillMethod
Since CSV-based order submission requires continuous spreadsheet management and preparation of print-ready files, we recommend leveraging more streamlined fulfillment options via API integration. This approach optimizes efficiency and reduces manual effort. For more details, refer to our Gelato API Documentation.