stockReferenceCreate

Required scope: create_stock_references

Creates a stock reference linking a product variant (by SKU) to a location. The combination of sku + locationId must be unique within the organization.

• Stock references at INTERNAL locations are created with status VALID and are immediately available for fulfillment.
• Stock references at WAREHOUSE locations are created with status DRAFT and require a stockReferenceRequestFulfillment call to become active.

---

Mutation

mutation StockReferenceCreate($input: StockReferenceCreateInput!) {
  stockReferenceCreate(input: $input) {
    id
    sku
    reference
    status
    physicalQuantity
    usableQuantity
    reservedQuantity
    location { id name }
    productVariant { id sku }
  }
}

Input

StockReferenceCreateInput

Field	Type	Required	Description
sku	String	Yes	The variant SKU to link to the location
locationId	String	Yes	The location UUID where stock will be held
physicalQuantity	Int	No	Initial physical quantity (default: 0)
usableQuantity	Int	No	Initial usable quantity (default: 0)
model	ProductModelEnum	No	PRODUCT or BUNDLE (default: PRODUCT)
reference	String	No	Optional custom warehouse reference code

---

Variables

{
  "input": {
    "sku": "TSHIRT-S-BLUE",
    "locationId": "loc_123",
    "physicalQuantity": 100,
    "usableQuantity": 100,
    "model": "PRODUCT"
  }
}

Response

{
  "data": {
    "stockReferenceCreate": {
      "id": "sr_abc123",
      "sku": "TSHIRT-S-BLUE",
      "reference": null,
      "status": "VALID",
      "physicalQuantity": 100,
      "usableQuantity": 100,
      "reservedQuantity": 0,
      "location": {
        "id": "loc_123",
        "name": "paris-warehouse"
      },
      "productVariant": {
        "id": "var_456",
        "sku": "TSHIRT-S-BLUE"
      }
    }
  }
}

---

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 StockReferenceCreate($input: StockReferenceCreateInput!) { stockReferenceCreate(input: $input) { id sku reference status physicalQuantity usableQuantity reservedQuantity location { id name } productVariant { id sku } } }",
    "variables": {
      "input": {
        "sku": "TSHIRT-S-BLUE",
        "locationId": "loc_123",
        "physicalQuantity": 100,
        "usableQuantity": 100,
        "model": "PRODUCT"
      }
    }
  }'

Node.js

async function stockReferenceCreate(accessToken, input) {
  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 StockReferenceCreate($input: StockReferenceCreateInput!) {
          stockReferenceCreate(input: $input) {
            id
            sku
            reference
            status
            physicalQuantity
            usableQuantity
            reservedQuantity
            location { id name }
            productVariant { id sku }
          }
        }
      `,
      variables: { input },
    }),
  });

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

const stockRef = await stockReferenceCreate(accessToken, {
  sku: 'TSHIRT-S-BLUE',
  locationId: 'loc_123',
  physicalQuantity: 100,
  usableQuantity: 100,
  model: 'PRODUCT',
});

Python

import requests

def stock_reference_create(access_token, input_data):
    response = requests.post(
        'https://api-v3.happycolis.com/graphql',
        headers={
            'Authorization': f'Bearer {access_token}',
            'Content-Type': 'application/json',
        },
        json={
            'query': '''
                mutation StockReferenceCreate($input: StockReferenceCreateInput!) {
                    stockReferenceCreate(input: $input) {
                        id
                        sku
                        reference
                        status
                        physicalQuantity
                        usableQuantity
                        reservedQuantity
                        location { id name }
                        productVariant { id sku }
                    }
                }
            ''',
            'variables': {'input': input_data},
        },
    )
    result = response.json()
    if 'errors' in result:
        raise Exception(result['errors'][0]['message'])
    return result['data']['stockReferenceCreate']

stock_ref = stock_reference_create(access_token, {
    'sku': 'TSHIRT-S-BLUE',
    'locationId': 'loc_123',
    'physicalQuantity': 100,
    'usableQuantity': 100,
    'model': 'PRODUCT',
})

PHP

function stockReferenceCreate(string $accessToken, array $input): 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 StockReferenceCreate($input: StockReferenceCreateInput!) {
                    stockReferenceCreate(input: $input) {
                        id
                        sku
                        reference
                        status
                        physicalQuantity
                        usableQuantity
                        reservedQuantity
                        location { id name }
                        productVariant { id sku }
                    }
                }
            ',
            'variables' => ['input' => $input],
        ],
    ]);

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

$stockRef = stockReferenceCreate($accessToken, [
    'sku'              => 'TSHIRT-S-BLUE',
    'locationId'       => 'loc_123',
    'physicalQuantity' => 100,
    'usableQuantity'   => 100,
    'model'            => 'PRODUCT',
]);

Go

package main

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

type StockReferenceCreateInput struct {
    SKU              string  `json:"sku"`
    LocationID       string  `json:"locationId"`
    PhysicalQuantity *int    `json:"physicalQuantity,omitempty"`
    UsableQuantity   *int    `json:"usableQuantity,omitempty"`
    Model            *string `json:"model,omitempty"`
    Reference        *string `json:"reference,omitempty"`
}

func stockReferenceCreate(accessToken string, input StockReferenceCreateInput) (map[string]interface{}, error) {
    query := `
        mutation StockReferenceCreate($input: StockReferenceCreateInput!) {
            stockReferenceCreate(input: $input) {
                id
                sku
                reference
                status
                physicalQuantity
                usableQuantity
                reservedQuantity
                location { id name }
                productVariant { id sku }
            }
        }
    `

    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["stockReferenceCreate"].(map[string]interface{}), nil
}