Skip to main content
How to import orders via a CSV file?

Learn how to efficiently import orders in bulk using a CSV file and streamline order management

Updated this week

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:

  1. Access your Orders page and click the "Import" button.

  2. 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.

  3. Upload the CSV file containing the orders you want to import. You can also download a fresh CSV template from this page.

  4. 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.

  5. You'll receive a notification confirming the initiation of the import process.

  6. 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 to order.

  • shipmentMethodUid – Specifies the shipping method: normal, standard, or express.

  • 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 isBusiness to true.

  • 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 isBusiness to true.

  • 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 isBusiness to true.

Product Information

  • item.itemReferenceId – Corresponds to Item Reference ID in 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.

Did this answer your question?