# Bulk Create Catalog Variants
Create a catalog variant bulk create job to create a batch of catalog variants.
Accepts up to 100 catalog variants per request. The maximum allowed payload size is 5MB.
The maximum number of jobs in progress at one time is 500.
*Rate limits*:
Burst: `75/s`
Steady: `700/m`
**Scopes:**
`catalogs:write`
# OpenAPI definition
```json
{
"openapi": "3.0.2",
"info": {
"title": "Catalogs API",
"version": "2024-10-15",
"description": "The Klaviyo REST API. Please visit https://developers.klaviyo.com for more details.",
"contact": {
"name": "Klaviyo Developer Experience Team",
"email": "developers@klaviyo.com",
"url": "https://developers.klaviyo.com"
},
"termsOfService": "https://www.klaviyo.com/legal/api-terms",
"license": {
"name": "License",
"url": "https://www.klaviyo.com/legal"
}
},
"servers": [
{
"url": "https://a.klaviyo.com",
"description": "Production"
}
],
"paths": {
"/api/catalog-variant-bulk-create-jobs": {
"post": {
"operationId": "bulk_create_catalog_variants",
"summary": "Bulk Create Catalog Variants",
"description": "Create a catalog variant bulk create job to create a batch of catalog variants.\n\nAccepts up to 100 catalog variants per request. The maximum allowed payload size is 5MB.\nThe maximum number of jobs in progress at one time is 500.
*Rate limits*:
Burst: `75/s`
Steady: `700/m`\n\n**Scopes:**\n`catalogs:write`",
"parameters": [
{
"name": "revision",
"in": "header",
"description": "API endpoint revision (format: YYYY-MM-DD[.suffix])",
"required": true,
"schema": {
"type": "string",
"default": "2024-10-15"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/vnd.api+json": {
"schema": {
"$ref": "#/components/schemas/CatalogVariantCreateJobCreateQuery"
}
}
}
},
"responses": {
"202": {
"description": "Success",
"content": {
"application/vnd.api+json": {
"schema": {
"$ref": "#/components/schemas/PostCatalogVariantCreateJobResponse"
}
}
}
},
"4XX": {
"$ref": "#/components/responses/ClientError"
},
"5XX": {
"$ref": "#/components/responses/ServerError"
}
},
"tags": [
"Variants"
],
"x-klaviyo-operation-aliases": [
"spawn_create_variants_job",
"create_catalog_variant_bulk_create_job"
],
"x-klaviyo-pre-release": "None",
"x-klaviyo-ratelimit": {
"burst": "75/s",
"steady": "700/m"
},
"x-klaviyo-scopes": [
"catalogs:write"
],
"x-klaviyo-subtag": "Variants"
}
}
},
"components": {
"schemas": {
"CatalogItemEnum": {
"type": "string",
"enum": [
"catalog-item"
]
},
"CatalogVariantEnum": {
"type": "string",
"enum": [
"catalog-variant"
]
},
"ErrorSource": {
"type": "object",
"properties": {
"pointer": {
"description": "A pointer to the source of the error in the request payload.",
"type": "string",
"example": "/data",
"default": "/data"
}
}
},
"APIJobErrorPayload": {
"type": "object",
"properties": {
"id": {
"description": "Unique identifier for the error.",
"type": "string",
"example": "e4eebb08-b055-4a6f-bb13-c8cb69c9eb94"
},
"code": {
"description": "A code for classifying the error type.",
"type": "string",
"example": "invalid"
},
"title": {
"description": "A high-level message about the error.",
"type": "string",
"example": "Invalid input"
},
"detail": {
"description": "Specific details about the error.",
"type": "string",
"example": "The payload provided in the request is invalid."
},
"source": {
"description": "Additional information on the source of the error.",
"$ref": "#/components/schemas/ErrorSource"
}
},
"required": [
"id",
"code",
"title",
"detail",
"source"
]
},
"CatalogVariantBulkCreateJobEnum": {
"type": "string",
"enum": [
"catalog-variant-bulk-create-job"
]
},
"CatalogVariantCreateQueryResourceObject": {
"type": "object",
"properties": {
"type": {
"$ref": "#/components/schemas/CatalogVariantEnum"
},
"attributes": {
"type": "object",
"properties": {
"external_id": {
"description": "The ID of the catalog item variant in an external system.",
"type": "string",
"example": "SAMPLE-DATA-ITEM-1-VARIANT-MEDIUM"
},
"catalog_type": {
"description": "The type of catalog. Currently only \"$default\" is supported.",
"type": "string",
"example": "$default",
"default": "$default"
},
"integration_type": {
"description": "The integration type. Currently only \"$custom\" is supported.",
"type": "string",
"example": "$custom",
"default": "$custom",
"enum": [
"$custom"
]
},
"title": {
"description": "The title of the catalog item variant.",
"type": "string",
"example": "Ocean Blue Shirt (Sample) Variant Medium"
},
"description": {
"description": "A description of the catalog item variant.",
"type": "string",
"example": "Ocean blue cotton shirt with a narrow collar and buttons down the front and long sleeves. Comfortable fit and titled kaleidoscope patterns."
},
"sku": {
"description": "The SKU of the catalog item variant.",
"type": "string",
"example": "OBS-MD"
},
"inventory_policy": {
"description": "This field controls the visibility of this catalog item variant in product feeds/blocks. This field supports the following values:\n`1`: a product will not appear in dynamic product recommendation feeds and blocks if it is out of stock.\n`0` or `2`: a product can appear in dynamic product recommendation feeds and blocks regardless of inventory quantity.",
"type": "integer",
"example": 2,
"default": 0,
"enum": [
0,
1,
2
]
},
"inventory_quantity": {
"description": "The quantity of the catalog item variant currently in stock.",
"type": "number",
"example": 25
},
"price": {
"description": "This field can be used to set the price on the catalog item variant, which is what gets displayed for the item variant when included in emails. For most price-update use cases, you will also want to update the `price` on any parent items using the [Update Catalog Item Endpoint](https://developers.klaviyo.com/en/reference/update_catalog_item).",
"type": "number",
"example": 42
},
"url": {
"description": "URL pointing to the location of the catalog item variant on your website.",
"type": "string",
"example": "https://via.placeholder.com/150"
},
"image_full_url": {
"description": "URL pointing to the location of a full image of the catalog item variant.",
"type": "string",
"example": "https://via.placeholder.com/300"
},
"image_thumbnail_url": {
"description": "URL pointing to the location of an image thumbnail of the catalog item variant.",
"type": "string",
"example": "https://via.placeholder.com/150"
},
"images": {
"description": "List of URLs pointing to the locations of images of the catalog item variant.",
"type": "array",
"items": {
"type": "string"
},
"example": [
"https://via.placeholder.com/150"
]
},
"custom_metadata": {
"description": "Flat JSON blob to provide custom metadata about the catalog item variant. May not exceed 100kb.",
"type": "object",
"example": {
"Top Pick": true
}
},
"published": {
"description": "Boolean value indicating whether the catalog item variant is published.",
"type": "boolean",
"example": true,
"default": true
}
},
"required": [
"external_id",
"title",
"description",
"sku",
"inventory_quantity",
"price",
"url"
]
},
"relationships": {
"type": "object",
"properties": {
"item": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"type": {
"$ref": "#/components/schemas/CatalogItemEnum"
},
"id": {
"description": "The original catalog item ID for which this is a variant.",
"type": "string",
"example": "$custom:::$default:::SAMPLE-DATA-ITEM-1"
}
},
"required": [
"type",
"id"
]
}
}
}
}
}
},
"required": [
"type",
"attributes"
]
},
"CatalogVariantCreateJobCreateQueryResourceObject": {
"type": "object",
"properties": {
"type": {
"$ref": "#/components/schemas/CatalogVariantBulkCreateJobEnum"
},
"attributes": {
"type": "object",
"properties": {
"variants": {
"description": "Array of catalog variants to create.",
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CatalogVariantCreateQueryResourceObject"
}
}
},
"required": [
"data"
]
}
},
"required": [
"variants"
]
}
},
"required": [
"type",
"attributes"
]
},
"CatalogVariantCreateJobCreateQuery": {
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/CatalogVariantCreateJobCreateQueryResourceObject"
}
},
"required": [
"data"
]
},
"PostCatalogVariantCreateJobResponse": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"type": {
"$ref": "#/components/schemas/CatalogVariantBulkCreateJobEnum"
},
"id": {
"description": "Unique identifier for retrieving the job. Generated by Klaviyo.",
"type": "string"
},
"attributes": {
"type": "object",
"properties": {
"status": {
"description": "Status of the asynchronous job.",
"type": "string",
"example": "processing",
"enum": [
"cancelled",
"complete",
"processing",
"queued"
]
},
"created_at": {
"description": "The date and time the job was created in ISO 8601 format (YYYY-MM-DDTHH:MM:SS.mmmmmm).",
"type": "string",
"format": "date-time",
"example": "2022-11-08T00:00:00+00:00"
},
"total_count": {
"description": "The total number of operations to be processed by the job. See `completed_count` for the job's current progress.",
"type": "integer",
"example": 10
},
"completed_count": {
"description": "The total number of operations that have been completed by the job.",
"type": "integer",
"example": 9,
"default": 0
},
"failed_count": {
"description": "The total number of operations that have failed as part of the job.",
"type": "integer",
"example": 1,
"default": 0
},
"completed_at": {
"description": "Date and time the job was completed in ISO 8601 format (YYYY-MM-DDTHH:MM:SS.mmmmmm).",
"type": "string",
"format": "date-time",
"example": "2022-11-08T00:00:00+00:00"
},
"errors": {
"description": "Array of errors encountered during the processing of the job.",
"type": "array",
"items": {
"$ref": "#/components/schemas/APIJobErrorPayload"
}
},
"expires_at": {
"description": "Date and time the job expires in ISO 8601 format (YYYY-MM-DDTHH:MM:SS.mmmmmm).",
"type": "string",
"format": "date-time",
"example": "2022-11-08T00:00:00+00:00"
}
},
"required": [
"status",
"created_at",
"total_count"
]
},
"relationships": {
"type": "object",
"properties": {
"variants": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"type": {
"$ref": "#/components/schemas/CatalogVariantEnum"
},
"id": {
"description": "IDs of the created catalog variants.",
"type": "string",
"example": "$custom:::$default:::SAMPLE-DATA-ITEM-1-VARIANT-MEDIUM"
}
}
}
},
"links": {
"$ref": "#/components/schemas/RelationshipLinks"
}
}
}
}
},
"links": {
"$ref": "#/components/schemas/ObjectLinks"
}
},
"required": [
"type",
"id",
"attributes",
"links"
]
}
},
"required": [
"data"
]
},
"RelationshipLinks": {
"type": "object",
"properties": {
"self": {
"type": "string",
"format": "uri"
},
"related": {
"type": "string",
"format": "uri"
}
},
"required": [
"self",
"related"
]
},
"ObjectLinks": {
"type": "object",
"properties": {
"self": {
"type": "string",
"format": "uri"
}
},
"required": [
"self"
]
}
},
"responses": {
"ClientError": {
"description": "Client Error",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"code",
"title",
"detail"
],
"properties": {
"id": {
"type": "string"
},
"code": {
"type": "string"
},
"title": {
"type": "string"
},
"detail": {
"type": "string"
},
"source": {
"type": "object",
"properties": {
"pointer": {
"type": "string"
},
"parameter": {
"type": "string"
}
}
}
}
}
}
},
"required": [
"errors"
]
}
}
}
},
"ServerError": {
"description": "Server Error",
"content": {
"application/vnd.api+json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"code",
"title",
"detail"
],
"properties": {
"id": {
"type": "string"
},
"code": {
"type": "string"
},
"title": {
"type": "string"
},
"detail": {
"type": "string"
},
"source": {
"type": "object",
"properties": {
"pointer": {
"type": "string"
},
"parameter": {
"type": "string"
}
}
}
}
}
}
},
"required": [
"errors"
]
}
}
}
}
},
"securitySchemes": {
"Klaviyo-API-Key": {
"type": "apiKey",
"in": "header",
"name": "Authorization",
"description": "Private key authentication for /api/ endpoints is performed by setting the `Authorization` header to `Klaviyo-API-Key your-private-api-key`
For more information please visit https://developers.klaviyo.com/en/v2024-10-15/reference/api-overview#authentication",
"x-default": "Klaviyo-API-Key your-private-api-key"
}
}
},
"tags": [
{
"name": "Variants"
}
],
"security": [
{
"Klaviyo-API-Key": []
}
],
"x-readme": {
"explorer-enabled": false,
"proxy-enabled": true,
"samples-enabled": true
},
"_id": {
"buffer": {
"0": 103,
"1": 14,
"2": 199,
"3": 71,
"4": 109,
"5": 224,
"6": 147,
"7": 0,
"8": 82,
"9": 88,
"10": 175,
"11": 31
}
}
}
```