variantCreate

Required scope: create_products

Create a new variant within an existing product. Each variant must have a SKU that is unique within the organization. Variants start in DRAFT status by default.

---

Mutation

mutation VariantCreate($input: VariantInput!) {
  variantCreate(input: $input) {
    id
    sku
    title
    status
    model
  }
}

Input — VariantInput

Field	Type	Required	Description
organizationId	String	✅	Organization UUID
productId	String	✅	Parent product ID
sku	String	✅	Unique SKU within the organization
title	String	❌	Variant label (e.g. "Small / Blue")
status	ProductStatusEnum	❌	Initial status — defaults to DRAFT
model	ProductModelEnum	❌	Variant model — defaults to PRODUCT
weight	Float	❌	Weight value
weightUnit	WeightUnitEnum	❌	G, KG, LB, or OZ
height	Float	❌	Height
width	Float	❌	Width
length	Float	❌	Length
distanceUnit	DistanceUnitEnum	❌	CM or IN
barcode	String	❌	EAN or UPC barcode
originCountry	String	❌	ISO 3166-1 alpha-2 country code (e.g. FR)
hsCode	String	❌	HS tariff code for customs

---

Example

Variables

{
  "input": {
    "organizationId": "org_123",
    "productId": "prod_456",
    "sku": "TSHIRT-S-BLUE",
    "title": "Small / Blue",
    "status": "DRAFT",
    "model": "PRODUCT",
    "weight": 200,
    "weightUnit": "G",
    "barcode": "3760123456789",
    "originCountry": "FR",
    "hsCode": "6109100010"
  }
}

Response

{
  "data": {
    "variantCreate": {
      "id": "var_001",
      "sku": "TSHIRT-S-BLUE",
      "title": "Small / Blue",
      "status": "DRAFT",
      "model": "PRODUCT"
    }
  }
}

---

Code Examples

curl

curl -X POST https://api-v3.happycolis.com/graphql \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation VariantCreate($input: VariantInput!) { variantCreate(input: $input) { id sku title status model } }",
    "variables": {
      "input": {
        "organizationId": "org_123",
        "productId": "prod_456",
        "sku": "TSHIRT-S-BLUE",
        "title": "Small / Blue",
        "status": "DRAFT",
        "model": "PRODUCT",
        "weight": 200,
        "weightUnit": "G",
        "barcode": "3760123456789",
        "originCountry": "FR",
        "hsCode": "6109100010"
      }
    }
  }'

Node.js

async function createVariant(accessToken, variantData) {
  const response = await fetch('https://api-v3.happycolis.com/graphql', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      query: `
        mutation VariantCreate($input: VariantInput!) {
          variantCreate(input: $input) {
            id
            sku
            title
            status
            model
          }
        }
      `,
      variables: { input: variantData },
    }),
  });

  const { data, errors } = await response.json();
  if (errors) throw new Error(errors[0].message);
  return data.variantCreate;
}

// Usage
const variant = await createVariant(accessToken, {
  organizationId: 'org_123',
  productId: 'prod_456',
  sku: 'TSHIRT-S-BLUE',
  title: 'Small / Blue',
  status: 'DRAFT',
  model: 'PRODUCT',
  weight: 200,
  weightUnit: 'G',
  barcode: '3760123456789',
  originCountry: 'FR',
  hsCode: '6109100010',
});

Python

import requests

def create_variant(access_token, variant_data):
    response = requests.post(
        'https://api-v3.happycolis.com/graphql',
        headers={
            'Authorization': f'Bearer {access_token}',
            'Content-Type': 'application/json',
        },
        json={
            'query': '''
                mutation VariantCreate($input: VariantInput!) {
                    variantCreate(input: $input) {
                        id
                        sku
                        title
                        status
                        model
                    }
                }
            ''',
            'variables': {'input': variant_data},
        },
    )
    result = response.json()
    if 'errors' in result:
        raise Exception(result['errors'][0]['message'])
    return result['data']['variantCreate']

# Usage
variant = create_variant(access_token, {
    'organizationId': 'org_123',
    'productId': 'prod_456',
    'sku': 'TSHIRT-S-BLUE',
    'title': 'Small / Blue',
    'status': 'DRAFT',
    'model': 'PRODUCT',
    'weight': 200,
    'weightUnit': 'G',
    'barcode': '3760123456789',
    'originCountry': 'FR',
    'hsCode': '6109100010',
})

PHP

function createVariant(string $accessToken, array $variantData): array
{
    $client = new \GuzzleHttp\Client();

    $response = $client->post('https://api-v3.happycolis.com/graphql', [
        'headers' => [
            'Authorization' => 'Bearer ' . $accessToken,
            'Content-Type'  => 'application/json',
        ],
        'json' => [
            'query' => '
                mutation VariantCreate($input: VariantInput!) {
                    variantCreate(input: $input) {
                        id
                        sku
                        title
                        status
                        model
                    }
                }
            ',
            'variables' => ['input' => $variantData],
        ],
    ]);

    $result = json_decode($response->getBody()->getContents(), true);
    if (isset($result['errors'])) {
        throw new \Exception($result['errors'][0]['message']);
    }
    return $result['data']['variantCreate'];
}

// Usage
$variant = createVariant($accessToken, [
    'organizationId' => 'org_123',
    'productId'      => 'prod_456',
    'sku'            => 'TSHIRT-S-BLUE',
    'title'          => 'Small / Blue',
    'status'         => 'DRAFT',
    'model'          => 'PRODUCT',
    'weight'         => 200,
    'weightUnit'     => 'G',
    'barcode'        => '3760123456789',
    'originCountry'  => 'FR',
    'hsCode'         => '6109100010',
]);

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

type VariantInput struct {
    OrganizationID string   `json:"organizationId"`
    ProductID      string   `json:"productId"`
    SKU            string   `json:"sku"`
    Title          string   `json:"title,omitempty"`
    Status         string   `json:"status,omitempty"`
    Model          string   `json:"model,omitempty"`
    Weight         *float64 `json:"weight,omitempty"`
    WeightUnit     string   `json:"weightUnit,omitempty"`
    Height         *float64 `json:"height,omitempty"`
    Width          *float64 `json:"width,omitempty"`
    Length         *float64 `json:"length,omitempty"`
    DistanceUnit   string   `json:"distanceUnit,omitempty"`
    Barcode        string   `json:"barcode,omitempty"`
    OriginCountry  string   `json:"originCountry,omitempty"`
    HsCode         string   `json:"hsCode,omitempty"`
}

func createVariant(accessToken string, input VariantInput) (map[string]interface{}, error) {
    query := `
        mutation VariantCreate($input: VariantInput!) {
            variantCreate(input: $input) {
                id
                sku
                title
                status
                model
            }
        }
    `

    body, _ := json.Marshal(map[string]interface{}{
        "query":     query,
        "variables": map[string]interface{}{"input": input},
    })

    req, _ := http.NewRequest("POST", "https://api-v3.happycolis.com/graphql", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer "+accessToken)
    req.Header.Set("Content-Type", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)

    if errs, ok := result["errors"]; ok {
        return nil, fmt.Errorf("graphql error: %v", errs)
    }
    data := result["data"].(map[string]interface{})
    return data["variantCreate"].(map[string]interface{}), nil
}