Bulk Import and Export¶

Create, update, and download trade items, lots, and serials at scale using GTIN1's bulk import and export tools.

Permissions¶

All bulk import and export operations require authentication and organization membership.

Operation	Minimum Role
Upload and import data	Contributor
Confirm and process imports	Contributor
Cancel an import	Contributor
Export data or assets	Viewer
Download export files	Viewer

Bulk Import¶

Supported Import Types¶

Import Type	Description
Trade Items	Create or update trade items with GTIN, name, description, brand, and other fields
Lots	Create lot/batch records associated with existing trade items
Serials	Create serial number records associated with existing trade items and (optionally) lots

Uploading a File¶

Navigate to your organization dashboard and select Bulk Import.
Select the Import Type (Trade Items, Lots, or Serials).
Choose your file and click Upload.

File requirements:

File format: CSV (.csv) or Excel (.xlsx)
Maximum file size: 1 GB
Encoding: UTF-8 recommended for CSV files

Excel files

When uploading an Excel file, GTIN1 reads only the first sheet. All cell values (numbers, dates, formulas) are converted to text automatically. Make sure your data is on the first sheet of the workbook.

After uploading, GTIN1 creates an import job and begins validation automatically. You are redirected to the job status page to monitor progress.

Import Job Lifecycle¶

Every import job moves through a defined sequence of statuses:

Pending --> Validating --> Awaiting Confirmation --> Processing --> Completed
                |                    |                   |
                v                    v                   v
              Failed             Cancelled           Failed

Status	Description
Pending	Job created, waiting to start validation
Validating	GTIN1 is parsing the CSV and checking each row for errors
Awaiting Confirmation	Validation complete. Review the preview and confirm brand mappings before processing.
Processing	Records are being created or updated in the database
Completed	All rows processed. Review the results summary.
Failed	An unrecoverable error occurred during validation or processing
Cancelled	The job was cancelled by a user

Preview and Brand Mapping¶

For trade item imports, the validation step detects brand names in your CSV and attempts to match them to existing brands in your organization. Before processing begins, you review these mappings and choose how to handle each brand:

Match to existing brand: Select a brand that already exists in your organization.
Create new brand: GTIN1 creates a new brand with the specified name.

This step ensures your product catalog stays organized and avoids duplicate brand entries.

Confirming the Import¶

After reviewing the validation results and brand mappings, click Confirm to start processing. GTIN1 processes rows in the background. You can leave the page and return later to check progress.

The status page auto-refreshes to show real-time progress:

Total rows in the file
Processed rows completed so far
Progress percentage
Success count and error count

Monitoring Import Status¶

You can monitor an import job in two ways:

Status page: The import status page shows validation results, progress, brand mappings, and errors in a human-readable format.

JSON polling endpoint: For programmatic monitoring, poll the status JSON endpoint:

curl -H "Cookie: sessionid=..." \
  "https://gtin1.com/org/{org-slug}/import/{job-slug}/status.json"

Response:

{
  "status": "processing",
  "status_display": "Processing",
  "total_rows": 1500,
  "processed_rows": 742,
  "progress_percent": 49,
  "success_count": 738,
  "error_count": 4,
  "warning_count": 12,
  "is_processing": true,
  "is_complete": false,
  "result_summary": {}
}

API Import¶

The Bulk Import API lets you create and manage import jobs programmatically using bearer token authentication. All endpoints are under /api/catalog/imports.

Authentication¶

All API import endpoints require a bearer token (API key) in the Authorization header:

curl -H "Authorization: Bearer gtin1_..." \
  https://gtin1.com/api/catalog/imports/upload

Upload a File¶

Upload a CSV or Excel file to create an import job:

curlPython

curl -X POST https://gtin1.com/api/catalog/imports/upload \
  -H "Authorization: Bearer gtin1_..." \
  -F "file=@products.csv" \
  -F "import_type=trade_items"

import requests

response = requests.post(
    "https://gtin1.com/api/catalog/imports/upload",
    headers={"Authorization": "Bearer gtin1_..."},
    files={"file": open("products.csv", "rb")},
    data={"import_type": "trade_items"},
)
print(response.json())

Response (201 Created):

{
  "id": "abc123xyz789",
  "status": "pending",
  "message": "File uploaded. Validating products.csv..."
}

Import via JSON¶

Submit items directly as a JSON payload instead of uploading a file:

curlPython

curl -X POST https://gtin1.com/api/catalog/imports \
  -H "Authorization: Bearer gtin1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "import_type": "trade_items",
    "items": [
      {"gtin": "00012345678905", "brand": "Acme", "name": "Widget"},
      {"gtin": "00098765432105", "brand": "Acme", "name": "Gadget"}
    ]
  }'

import requests

response = requests.post(
    "https://gtin1.com/api/catalog/imports",
    headers={
        "Authorization": "Bearer gtin1_...",
        "Content-Type": "application/json",
    },
    json={
        "import_type": "trade_items",
        "items": [
            {"gtin": "00012345678905", "brand": "Acme", "name": "Widget"},
            {"gtin": "00098765432105", "brand": "Acme", "name": "Gadget"},
        ],
    },
)
print(response.json())

You can optionally include brand_mappings to skip the brand confirmation step:

{
  "import_type": "trade_items",
  "items": [...],
  "brand_mappings": {
    "Acme": {"matched_brand_id": 42, "create_new": false, "new_brand_name": null}
  }
}

Poll Job Status¶

Check the status of an import job:

curl https://gtin1.com/api/catalog/imports/{job_id} \
  -H "Authorization: Bearer gtin1_..."

Response:

{
  "id": "abc123xyz789",
  "import_type": "trade_items",
  "status": "processing",
  "status_display": "Processing",
  "source_filename": "products.csv",
  "total_rows": 1500,
  "processed_rows": 742,
  "progress_percent": 49,
  "success_count": 738,
  "error_count": 4,
  "warning_count": 12,
  "brand_mappings": {},
  "result_summary": {},
  "created": "2026-02-15T10:30:00Z",
  "started_at": "2026-02-15T10:30:05Z",
  "completed_at": null
}

Get Import Errors¶

Retrieve errors and warnings from an import job (paginated, 100 per page):

curl "https://gtin1.com/api/catalog/imports/{job_id}/errors?page=1" \
  -H "Authorization: Bearer gtin1_..."

Response:

{
  "count": 4,
  "items": [
    {
      "row_number": 5,
      "column_name": "gtin",
      "severity": "error",
      "error_code": "INVALID_GTIN",
      "message": "Invalid check digit",
      "raw_value": "12345"
    }
  ]
}

Confirm Brand Mappings¶

When a job is in awaiting_confirmation status, confirm brand mappings to begin processing:

curl -X POST "https://gtin1.com/api/catalog/imports/{job_id}/confirm" \
  -H "Authorization: Bearer gtin1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "brand_mappings": {
      "Acme": {"matched_brand_id": 42, "create_new": false, "new_brand_name": null},
      "NewBrand": {"matched_brand_id": null, "create_new": true, "new_brand_name": "New Brand Corp"}
    }
  }'

Cancel an Import¶

Cancel a job that is currently processing or awaiting confirmation:

curl -X POST "https://gtin1.com/api/catalog/imports/{job_id}/cancel" \
  -H "Authorization: Bearer gtin1_..."

Response (200 OK):

{
  "message": "Import cancellation requested."
}

Error Responses¶

Status Code	Meaning
`400`	Invalid request (bad import type, unsupported file format)
`401`	Missing or invalid API key
`404`	Job not found or belongs to another organization
`409`	Job is in a status that does not allow the requested action
`413`	File exceeds the 1 GB size limit
`422`	Request body validation failed

Handling Errors¶

Errors and warnings are recorded at the row level during both validation and processing. Each error includes:

Field	Description
Row number	The row in the source file (1-indexed, excluding header)
Column name	Which column caused the issue
Severity	`error` (row skipped) or `warning` (row processed with caveats)
Error code	Machine-readable code (e.g., `INVALID_GTIN`, `DUPLICATE_LOT`)
Message	Human-readable description of the issue
Raw value	The original value from the source file that caused the error

The status page displays up to 100 errors with a breakdown by error code and severity. For the complete error list, download the error report.

Downloading the Error Report¶

Click Download Errors (CSV) on the import status page to get a full error report. The CSV file contains all errors and warnings with columns:

Row, Column, Severity, Error Code, Message, Raw Value

This report is useful for fixing issues in your source file and re-importing corrected data.

Cancelling an Import¶

You can cancel a job that is currently validating, awaiting confirmation, or processing:

Navigate to the import status page.
Click Cancel Import.

Cancellation is asynchronous. Rows already processed remain in the database, but no further rows are processed.

Import History¶

View all import jobs for your organization at Bulk Import > History. The list shows each job's type, status, row counts, and timestamps, with pagination (25 jobs per page).

Bulk Export¶

Export Types¶

GTIN1 supports two categories of exports:

Data exports - download your product data in structured file formats.

Export Type	Description
Data - GTIN1 Format	Full product data in GTIN1's native format
Data - Google Shopping	Formatted for Google Merchant Center product feeds
Data - Shopify	Formatted for Shopify product CSV import

Asset exports - download generated QR codes, barcodes, or PDF sheets as files.

Export Type	Description
QR Codes	QR code images for all matching items
Barcodes	1D barcode images for all matching items
QR Codes + Barcodes	Combined export with both QR and barcode for each item
PDF Sheets (Print-Ready)	Print-ready PDF sheets with QR codes and barcodes

Export Scope¶

Choose the level of data to export:

Scope	Description
Trade Items	Export data for trade items
Lots	Export data for lots/batches
Serials	Export data for serial numbers

File Formats¶

Data exports:

Format	Extension	Description
CSV	`.csv`	Comma-separated values
TSV	`.tsv`	Tab-separated values
Excel	`.xlsx`	Microsoft Excel workbook

Asset exports:

Format	Extension	Description
SVG	`.svg`	Scalable vector graphics (delivered as ZIP)
EPS	`.eps`	Encapsulated PostScript (delivered as ZIP)
PDF	`.pdf`	PDF documents (delivered as ZIP or single PDF)

Starting an Export¶

Navigate to your organization dashboard and select Bulk Export.
Choose the Export Type and Scope.
Optionally filter by brand, trade item, date range, or lot identifier.
For asset exports, configure QR code or barcode rendering options (format, error correction, scale, colors).
Click Export to start the job.

GTIN1 processes exports in the background. You receive an email when the export is ready for download.

Export Filters¶

Narrow your export using optional filters:

Filter	Applies To	Description
Brand	All types	Export only items belonging to selected brands
Trade items	All types	Export only specific trade items
Include lots	Asset exports	Include lot-level QR codes/barcodes
Include serials	Asset exports	Include serial-level QR codes/barcodes
Date range	Asset exports	Filter by creation or modification date
Lot identifiers	Asset exports	Export only specific lots

QR and Barcode Configuration¶

For asset exports, customize the rendering:

QR code options:

Option	Default	Description
Format	SVG	`svg`, `pdf`, or `eps`
Error correction	Q (25%)	`L`, `M`, `Q`, or `H`
Scale	8	Module size
Border	4	Quiet zone width
Fill color	Black (CMYK)	Foreground color in CMYK
Background	Transparent	Background color

Barcode options:

Option	Default	Description
Format	SVG	`svg` or `eps`
Barcode type	Auto	Auto-detected from GTIN length, or specify manually
Module width	0.2 mm	Bar width
Module height	15.0 mm	Bar height
Font size	10	Human-readable text size
Quiet zone	6.5 mm	Quiet zone width
Write text	Yes	Include digits below the barcode
Guard bars	Yes	Include guard bars (EAN/UPC)

Barcode mismatch behavior - when a barcode type is incompatible with a GTIN (e.g., EAN-8 requested for a 14-digit GTIN):

Behavior	Description
Auto-fallback (default)	Automatically use a compatible barcode type
Skip	Skip incompatible items
Fail	Fail the entire export if any item is incompatible

Monitoring Export Status¶

The export status page shows real-time progress with auto-refresh. You can also poll the JSON endpoint:

curl -H "Cookie: sessionid=..." \
  "https://gtin1.com/org/{org-slug}/export/{job-slug}/status.json"

Response:

{
  "status": "processing",
  "status_display": "Processing",
  "total_items": 500,
  "processed_items": 234,
  "progress_percent": 46,
  "is_processing": true,
  "is_complete": false,
  "is_downloadable": false,
  "items_skipped": 0,
  "items_fallback": 3,
  "download_count": 0,
  "download_limit": 10,
  "remaining_downloads": 10,
  "expires_at": null,
  "file_size_bytes": 0
}

Downloading Export Files¶

Once an export completes, a download link appears on the status page. Export downloads have usage limits:

Constraint	Default
Download limit	10 downloads per export
Expiration	7 days after completion

After reaching the download limit or expiration, you need to create a new export job.

Large asset exports

Asset exports (QR codes, barcodes) are packaged as ZIP files. For large exports with thousands of items, the ZIP file may take a few minutes to generate.

Concurrent Export Limits¶

To protect system resources, GTIN1 limits the number of concurrent export jobs per organization. The default limit is 3 active jobs (pending or processing). Wait for an existing job to complete before starting another.

Export History¶

View all export jobs at Bulk Export > History, with pagination (25 jobs per page). Each entry shows the export type, scope, status, item counts, file size, download count, and timestamps.

Manifest Schema¶

For developers building automated processors for GTIN1 export files, a JSON Schema describing the export manifest format is available at:

https://gtin1.com/org/{org-slug}/export/manifest-schema/

This endpoint is public (no authentication required) and returns the schema with application/schema+json content type. The response is cached for 24 hours.

Tips for Large Imports¶

Validate before you commit: The preview step catches most issues before any data is written. Review errors carefully.
Fix and re-import: Download the error report, fix the issues in your source file, and upload a corrected version.
Start with a small sample: If importing thousands of rows, test with a small subset first to confirm your column mappings are correct.
One import type at a time: Import trade items first, then lots, then serials. Each level depends on the one above it.