> ## Documentation Index > Fetch the complete documentation index at: https://docs.omnicommerce.sg/llms.txt > Use this file to discover all available pages before exploring further. # Bulk Import Products from JSON or CSV > Queue a bulk product import for the authenticated organization. ### Input options - Upload a CSV (2 MiB) or JSON products file (8 MiB) using `multipart/form-data`. - Send JSON with a `products` array of 1–1,000 flat product objects (8 MiB request maximum). - Send JSON with inline `csvText`. - Send JSON referencing a stored `documentId`. ### Asynchronous result The API creates import rows, then queues draft creation and AI Review through Inngest. Completed import jobs expose `reviewBatchIds`, `reviewUrls`, and `reviewWarnings`; generated changes require Review approval. Poll the returned `bulk_...` job with `GET /api/v1/jobs/{jobId}`. Cancel an in-flight import with `POST /api/v1/jobs/{jobId}/cancel`. ## OpenAPI ````yaml /openapi.json post /api/v1/products/bulk-import openapi: 3.1.0 info: title: OmniCommerce API version: 1.0.0 license: name: Proprietary url: https://omnicommerce.sg/terms description: >- OmniCommerce API surface for agents and developer integrations. Includes public endpoints (merchant discovery, product search, compare, catalog, ACO retrieval) and authenticated endpoints (product management via API key Bearer tokens). servers: - url: https://omnicommerce.sg description: Production - url: http://localhost:3000 description: Local development security: [] tags: - name: agentic-checkout description: Merchant-fulfilled agentic checkout x-group: Agentic Checkout - name: aops description: Agent operating procedures x-group: AOPs - name: commerce description: Root commerce discovery x-group: Commerce - name: developer-platform description: Authenticated developer platform APIs x-group: Developer Platform - name: looks description: AI-styled product looks x-group: Looks - name: oauth description: OAuth token endpoints x-group: OAuth - name: orders description: Workspace and agentic orders x-group: Orders - name: organizations description: Organization management x-group: Organizations - name: price-books description: Marketplace list-price markup rules x-group: Price Books - name: products description: Product CRUD, bulk import, and publish x-group: Products - name: promotions description: Central promotions and marketplace sync x-group: Promotions - name: public-agent description: Public agent discovery and catalog APIs x-group: Public Agent - name: returns description: returns x-group: Returns - name: settlements description: settlements x-group: Settlements - name: ucp description: Universal Commerce Protocol x-group: UCP paths: /api/v1/products/bulk-import: post: tags: - products summary: Bulk Import Products from JSON or CSV description: >- Queue a bulk product import for the authenticated organization. ### Input options - Upload a CSV (2 MiB) or JSON products file (8 MiB) using `multipart/form-data`. - Send JSON with a `products` array of 1–1,000 flat product objects (8 MiB request maximum). - Send JSON with inline `csvText`. - Send JSON referencing a stored `documentId`. ### Asynchronous result The API creates import rows, then queues draft creation and AI Review through Inngest. Completed import jobs expose `reviewBatchIds`, `reviewUrls`, and `reviewWarnings`; generated changes require Review approval. Poll the returned `bulk_...` job with `GET /api/v1/jobs/{jobId}`. Cancel an in-flight import with `POST /api/v1/jobs/{jobId}/cancel`. operationId: post_v1_products_bulk_import requestBody: required: true content: multipart/form-data: schema: type: object required: - file - targetMarketplaces - targetCountries properties: file: type: string format: binary description: >- CSV file or JSON array containing product rows. JSON object files may wrap the array as `products`. organizationId: type: string description: >- Optional for API-key requests; required for session-authenticated requests across multiple organizations. fileName: type: string description: >- Optional display name override. Defaults to the uploaded file name. targetMarketplaces: oneOf: - type: string description: Comma-separated marketplace list, e.g. `shopee,lazada`. - type: array items: type: string enum: - shopee - lazada - tiktok - shopify - zalora - amazon - ebay targetCountries: oneOf: - type: string description: Comma-separated country list, e.g. `sg,my`. - type: array items: type: string fieldMapping: type: string description: >- JSON object mapping CSV headers to import fields, e.g. `{"sku":"SKU","title":"Product Name"}`. marketplaceStoreSelections: type: string description: JSON object mapping marketplace keys to connected store IDs. selectedRowIndexes: type: string description: JSON array of zero-based CSV row indexes to import. lane: type: string enum: - standard - enterprise dedupPolicy: type: string enum: - keep_first - keep_last - merge_fields_prefer_non_empty - fail_job autoApproveThreshold: oneOf: - type: number - type: string description: >- Optional confidence threshold between 0 and 1, or the string `null`. spendCeilingUsd: oneOf: - type: number - type: string model: type: string description: Optional enrichment model override. imageAnnotationTemplateId: type: string format: uuid imageAnnotationGalleryTemplateId: type: string format: uuid imageAnnotationScope: type: string enum: - primary - all_gallery workflow: type: string description: >- JSON object with enrichment workflow options such as `sourceImagesAutomatically`, `enableRichDescription`, and `autoAssignMarketplaceTaxonomy`. application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: products: minItems: 1 maxItems: 1000 type: array items: type: object properties: sku: type: string minLength: 1 maxLength: 200 title: type: string maxLength: 400 gtin: type: string maxLength: 100 brand: type: string maxLength: 160 description: type: string maxLength: 10000 price: type: number minimum: 0 currency: type: string pattern: ^[A-Za-z]{3}$ compareAtPrice: type: number minimum: 0 salePrice: type: number minimum: 0 costPerItem: type: number minimum: 0 inventory: type: integer minimum: 0 maximum: 9007199254740991 images: maxItems: 30 type: array items: type: string format: uri maxLength: 2048 category: type: string maxLength: 255 categoryName: type: string maxLength: 500 weight: type: number minimum: 0 dimensions: type: object properties: length: type: number minimum: 0 width: type: number minimum: 0 height: type: number minimum: 0 required: - length - width - height additionalProperties: false required: - sku additionalProperties: false organizationId: type: string minLength: 1 maxLength: 120 csvText: type: string documentId: type: string minLength: 1 maxLength: 255 fileName: type: string maxLength: 500 selectedRowIndexes: type: array items: type: integer minimum: 0 maximum: 9007199254740991 lane: type: string enum: - standard - enterprise targetMarketplaces: minItems: 1 type: array items: type: string enum: - shopee - lazada - tiktok - shopify - whatsapp - zalora - amazon - ebay targetCountries: minItems: 1 type: array items: type: string minLength: 1 maxLength: 80 fieldMapping: type: object propertyNames: type: string additionalProperties: type: string dedupPolicy: type: string enum: - keep_first - keep_last - merge_fields_prefer_non_empty - fail_job autoApproveThreshold: anyOf: - type: number minimum: 0 maximum: 1 - type: 'null' spendCeilingUsd: anyOf: - type: number minimum: 0 - type: 'null' marketplaceStoreSelections: type: object propertyNames: type: string additionalProperties: type: string model: type: string minLength: 1 maxLength: 120 imageAnnotationTemplateId: anyOf: - type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ - type: 'null' imageAnnotationGalleryTemplateId: anyOf: - type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ - type: 'null' imageAnnotationScope: type: string enum: - primary - all_gallery workflow: type: object properties: enableRichDescription: type: boolean sourceImagesAutomatically: type: boolean autoAssignMarketplaceTaxonomy: type: boolean enableBackgroundRemoval: type: boolean enableMannequinRemoval: type: boolean skipImageTagging: type: boolean skipZeroInventoryProducts: type: boolean excludedImageTags: anyOf: - type: string maxLength: 2000 - maxItems: 50 type: array items: type: string minLength: 1 maxLength: 120 enabledBuiltInImageTags: maxItems: 100 type: array items: type: string minLength: 1 maxLength: 120 customImageTags: maxItems: 20 type: array items: type: object properties: name: type: string minLength: 1 maxLength: 120 description: type: string minLength: 1 maxLength: 280 required: - name - description enrich: type: boolean disableAcoGeneration: type: boolean skipEnrichment: type: boolean skipBackgroundRemoval: type: boolean additionalProperties: false required: - targetMarketplaces - targetCountries oneOf: - required: - products - required: - csvText - required: - documentId example: products: - sku: SKU-1 title: Sample product price: 19.9 costPerItem: 10 inventory: 20 images: - https://cdn.example.com/sku-1.jpg targetMarketplaces: - shopee targetCountries: - sg workflow: enableRichDescription: true autoAssignMarketplaceTaxonomy: true responses: '202': description: Bulk import workflow accepted content: application/json: schema: type: object properties: ok: type: boolean apiVersion: type: string default: developer_v1 operationId: type: string status: type: string jobId: type: string description: Bulk import job ID with `bulk_` prefix. warnings: type: array items: type: string recommendations: type: array items: type: string links: type: object additionalProperties: type: string data: type: object properties: rowCount: type: integer fileName: type: string targetMarketplaces: type: array items: type: string targetCountries: type: array items: type: string fieldMapping: type: object counts: type: object '400': description: Bad Request - Invalid products, CSV, or payload '401': description: Unauthorized - Invalid or missing Bearer token '403': description: Forbidden - Token not authorized for this organization '413': description: Payload Too Large - JSON request or file upload exceeds limit '500': description: Internal Server Error security: - bearerAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: >- Bearer API key for server-to-server access. Session auth is also supported in first-party UI flows. ````