Add Customer Product

Create a new customer product with variant options and metadata. Customer products define the structure and configuration options that customers can order.

POST /product/v1/customer-product

Request Format

The request body must be a JSON object containing the customer product configuration:

{
  "name": "Premium Cotton T-Shirt",
  "customerIds": ["customer-123", "customer-456"],
  "productModelId": "model-tshirt-001",
  "variantOptions": [
    {
      "id": "size",
      "name": "Size",
      "attributesMapping": [
        {
          "partModelId": "fabric",
          "attributeIds": ["attr-size-small", "attr-size-medium", "attr-size-large"]
        }
      ]
    },
    {
      "id": "color",
      "name": "Color",
      "attributesMapping": [
        {
          "partModelId": "fabric",
          "attributeIds": ["attr-color-red", "attr-color-blue", "attr-color-green"]
        }
      ]
    }
  ],
  "partQuantities": [
    {
      "partModelId": "fabric-cotton-premium",
      "quantity": 2
    }
  ]
}

Example curl request

curl --location --request POST 'https://connect.gelatoapis.com/product/v1/customer-product' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-api-key' \
--data-raw '{
  "name": "Premium Cotton T-Shirt",
  "customerIds": ["customer-123", "customer-456"],
  "productModelId": "model-tshirt-001",
  "variantOptions": [
    {
      "id": "size",
      "name": "Size",
      "attributesMapping": [
        {
          "partModelId": "fabric",
          "attributeIds": ["attr-size-small", "attr-size-medium", "attr-size-large"]
        }
      ]
    },
    {
      "id": "color",
      "name": "Color",
      "attributesMapping": [
        {
          "partModelId": "fabric",
          "attributeIds": ["attr-color-red", "attr-color-blue", "attr-color-green"]
        }
      ]
    }
  ],
  "partQuantities": [
    {
      "partModelId": "fabric-cotton-premium",
      "quantity": 2
    }
  ]
}'

Request Parameters

Parameter	Type	Required	Description
name	string	Required	Name for the customer product
customerIds	array[string]	Required	Array of customer IDs that can order this product. Use ["*"] to allow all customers
productModelId	string	Required	Product model this customer product is based on
variantOptions	array[object]	Required	Array of variant option definitions (size, color, etc.)
partQuantities	array[object]	Optional	Custom part quantities to override defaults in multi-part product models

Variant Option Object

Parameter	Type	Required	Description
id	string	Required	Unique identifier for the variant option
name	string	Required	Display name for the variant option
attributesMapping	array[object]	Required	Mappings between variant option and product/part model attributes

Part Quantity Object

Parameter	Type	Required	Description
partModelId	string	Required	Part model identifier
quantity	integer	Required	Custom quantity (must be >= 0)

Response Format

Returns the created customer product with server-generated fields:

{
  "id": "cp-550e8400-e29b-41d4-a716-446655440001",
  "name": "Premium Cotton T-Shirt",
  "customerIds": ["customer-123", "customer-456"],
  "productModelId": "model-tshirt-001",
  "variantOptions": [
    {
      "id": "size",
      "name": "Size",
      "attributesMapping": [
        {
          "partModelId": "fabric",
          "attributeIds": ["attr-size-small", "attr-size-medium", "attr-size-large"]
        }
      ]
    },
    {
      "id": "color",
      "name": "Color",
      "attributesMapping": [
        {
          "partModelId": "fabric",
          "attributeIds": ["attr-color-red", "attr-color-blue", "attr-color-green"]
        }
      ]
    }
  ],
  "partQuantities": [
    {
      "partModelId": "fabric-cotton-premium",
      "quantity": 2
    }
  ],
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Common Use Cases

Create Framed Poster Product:

curl --location --request POST 'https://connect.gelatoapis.com/product/v1/customer-product' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-api-key' \
--data-raw '{
  "name": "Premium Framed Poster",
  "customerIds": ["customer-123"],
  "productModelId": "model-framed-poster-001",
  "variantOptions": [
    {
      "id": "size",
      "name": "Size",
      "attributesMapping": [
        {
          "partModelId": "frame",
          "attributeIds": ["attr-width", "attr-height"]
        },
        {
          "partModelId": "poster-print-paper-premium",
          "attributeIds": ["attr-width", "attr-height"]
        }
      ]
    },
    {
      "id": "frame-color",
      "name": "Frame Color",
      "attributesMapping": [
        {
          "partModelId": "frame",
          "attributeIds": ["attr-color"]
        }
      ]
    }
  ]
}'

Create Eco-Friendly Tote Bag:

curl --location --request POST 'https://connect.gelatoapis.com/product/v1/customer-product' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-api-key' \
--data-raw '{
  "name": "Eco-Friendly Tote Bag",
  "customerIds": ["*"],
  "productModelId": "model-tote-bag-eco",
  "variantOptions": [
    {
      "id": "material",
      "name": "Material Type",
      "attributesMapping": [
        {
          "partModelId": "bag-fabric",
          "attributeIds": ["attr-cotton-organic", "attr-hemp", "attr-bamboo"]
        }
      ]
    }
  ],
  "partQuantities": [
    {
      "partModelId": "fabric-organic-cotton",
      "quantity": 1
    },
    {
      "partModelId": "handle-cotton-rope",
      "quantity": 2
    }
  ]
}'