> ## Documentation Index > Fetch the complete documentation index at: https://docs.polinate.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create an item and its variants > Create a parent item and its variants in one request. Idempotent via Idempotency-Key. ## OpenAPI ````yaml openapi.json post /api/v1/items openapi: 3.0.3 info: title: Polinate External API version: 1.0.0 description: >- External API for partners and services. Authentication via X-Business-Id and X-API-Key headers. Credentials location: In the Polinate app, navigate to Business Settings → Integrations to find your Business ID and API Key. servers: - url: https://integrations.polinate.ai description: Production security: [] tags: - name: Items description: >- Manage items and item variants. Auth: X-Business-Id and X-API-Key (see Business Settings → Integrations). - name: Buyers description: >- Create buyers and related contacts/locations. Auth: X-Business-Id and X-API-Key (see Business Settings → Integrations). - name: Pricing description: >- Create price lists and entries. Auth: X-Business-Id and X-API-Key (see Business Settings → Integrations). - name: Invoices description: >- List and update invoices. Auth: X-Business-Id and X-API-Key (see Business Settings → Integrations). - name: Orders description: >- Order ingestion. Auth: X-Business-Id and X-API-Key (see Business Settings → Integrations). paths: /api/v1/items: post: tags: - Items summary: Create an item and its variants description: >- Create a parent item and its variants in one request. Idempotent via Idempotency-Key. operationId: createItem parameters: - schema: type: string description: >- Business identifier for external auth. Find in Polinate app → Business Settings → Integrations. example: '{{businessId}}' required: true name: X-Business-Id in: header - schema: type: string description: >- Per-business API key for external auth. Find in Polinate app → Business Settings → Integrations. example: '{{apiKey}}' required: true name: X-API-Key in: header - schema: type: string description: Idempotency key for POST operations example: '{{idempotencyKey}}' required: false name: Idempotency-Key in: header requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ItemCreateRequest' examples: Minimal: summary: Minimal required fields value: item: name: Widget handle: widget-1 type: OTHER status: ACTIVE variants: - variantName: Default currency: AUD price: 12.34 cost: 8.5 Full: summary: All supported fields with multiple variants value: item: name: Widget Deluxe handle: widget-deluxe-2000 type: OTHER status: ACTIVE description: A premium multi-purpose widget imgUrl: https://cdn.example.com/widget-deluxe.png customType: HARDWARE brand: Acme vendorName: Acme Manufacturing properties: colorOptions: - red - blue variants: - variantName: Default sku: WID-DEL-DEF barcode: '1234567890123' currency: AUD price: 19.99 cost: 10 weight: 0.5 length: 10 width: 5 height: 3 - variantName: Large sku: WID-DEL-L barcode: '1234567890124' currency: AUD price: 24.99 cost: 13 responses: '200': description: Created - Returns item ID and variant IDs in submission order content: application/json: schema: $ref: '#/components/schemas/ItemCreateResponse' example: success: true id: itm_123 variantIds: - var_abc - var_def '400': description: Invalid payload content: application/json: schema: $ref: '#/components/schemas/StandardError' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/StandardError' '429': description: Rate limited headers: Retry-After: schema: type: string description: Seconds to wait before retrying content: application/json: schema: $ref: '#/components/schemas/StandardError' components: schemas: ItemCreateRequest: type: object properties: item: type: object properties: name: type: string handle: type: string description: Unique across all items description: type: string imgUrl: type: string format: uri customType: type: string brand: type: string vendorName: type: string type: type: string enum: - BEVERAGE - VEGETABLE - FRUIT - MEAT - DAIRY - CLEANING - CONDIMENT - DRY_GOOD - FROZEN_FOOD - BAKERY - POULTRY - DISPOSABLE - SEAFOOD - OTHER status: type: string enum: - ACTIVE - DRAFT - ARCHIVED - DELETED properties: type: object properties: {} required: - name - handle - type - status additionalProperties: false variants: type: array items: type: object properties: variantName: type: string description: Unique per item sku: type: string barcode: type: string upc: type: string isDefault: type: boolean currency: type: string enum: - USD - EUR - GBP - CAD - AUD - NZD - CHF - JPY - CNY - INR - BRL - MXN - ARS - COP - PHP price: type: number cost: type: number weight: type: number length: type: number width: type: number height: type: number unitOfMeasure: type: string leadTime: type: number reorderPoint: type: number reorderQuantity: type: number inStockQuantity: type: number onOrderQuantity: type: number countryOfOrigin: type: string hsCode: type: string eccn: type: string customsDeclarationInfo: type: string sequence: type: number properties: type: object properties: {} required: - variantName - currency - price - cost additionalProperties: false minItems: 1 required: - item - variants ItemCreateResponse: type: object properties: success: type: boolean id: type: string description: The created item ID variantIds: type: array items: type: string description: Array of created variant IDs in the same order as the request required: - success - id - variantIds StandardError: type: object properties: errorCode: type: string message: type: string fieldErrors: type: object additionalProperties: type: string required: - errorCode - message ````