stockReference

Required scope: view_stock_references

Retrieve a single stock reference by its UUID, by SKU + location, or by warehouse reference + location. Exactly one lookup argument must be provided.

---

Query

query GetStockReference(
  $id: String
  $bySku: StockReferenceBySkuInput
  $byReference: StockReferenceByReferenceInput
) {
  stockReference(id: $id, bySku: $bySku, byReference: $byReference) {
    id
    sku
    reference
    status
    model
    physicalQuantity
    usableQuantity
    reservedQuantity
    location { id name }
    productVariant { id sku }
    storageProfile { id name }
  }
}

Arguments

Argument	Type	Description
id	String	Stock reference UUID. Mutually exclusive with bySku and byReference.
bySku	StockReferenceBySkuInput	Look up by SKU and location. Mutually exclusive with id and byReference.
byReference	StockReferenceByReferenceInput	Look up by warehouse reference code and location. Mutually exclusive with id and bySku.

StockReferenceBySkuInput

input StockReferenceBySkuInput {
  sku: String!
  locationId: String!
}

Field	Type	Required	Description
sku	String	Yes	The variant SKU
locationId	String	Yes	The location UUID

StockReferenceByReferenceInput

input StockReferenceByReferenceInput {
  reference: String!
  locationId: String!
}

Field	Type	Required	Description
reference	String	Yes	The custom warehouse reference code
locationId	String	Yes	The location UUID

---

Example — Lookup by ID

Variables

{
  "id": "sr_abc123"
}

Response

{
  "data": {
    "stockReference": {
      "id": "sr_abc123",
      "sku": "TSHIRT-S-BLUE",
      "reference": "WH-REF-0042",
      "status": "VALID",
      "model": "PRODUCT",
      "physicalQuantity": 150,
      "usableQuantity": 140,
      "reservedQuantity": 10,
      "location": {
        "id": "loc_123",
        "name": "paris-warehouse"
      },
      "productVariant": {
        "id": "var_456",
        "sku": "TSHIRT-S-BLUE"
      },
      "storageProfile": {
        "id": "sp_789",
        "name": "Standard"
      }
    }
  }
}

---

Example — Lookup by SKU

Variables

{
  "bySku": {
    "sku": "TSHIRT-S-BLUE",
    "locationId": "loc_123"
  }
}

---

Example — Lookup by Reference

Variables

{
  "byReference": {
    "reference": "WH-REF-0042",
    "locationId": "loc_123"
  }
}

---

Code Examples

curl

curl -X POST https://api-v3.happycolis.com/graphql \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query GetStockReference($id: String, $bySku: StockReferenceBySkuInput, $byReference: StockReferenceByReferenceInput) { stockReference(id: $id, bySku: $bySku, byReference: $byReference) { id sku reference status model physicalQuantity usableQuantity reservedQuantity location { id name } productVariant { id sku } storageProfile { id name } } }",
    "variables": {
      "id": "sr_abc123"
    }
  }'

Node.js

async function getStockReference(accessToken, { id, bySku, byReference }) {
  const response = await fetch('https://api-v3.happycolis.com/graphql', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      query: `
        query GetStockReference(
          $id: String
          $bySku: StockReferenceBySkuInput
          $byReference: StockReferenceByReferenceInput
        ) {
          stockReference(id: $id, bySku: $bySku, byReference: $byReference) {
            id
            sku
            reference
            status
            model
            physicalQuantity
            usableQuantity
            reservedQuantity
            location { id name }
            productVariant { id sku }
            storageProfile { id name }
          }
        }
      `,
      variables: { id, bySku, byReference },
    }),
  });

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

// Lookup by ID
const sr = await getStockReference(accessToken, { id: 'sr_abc123' });

// Lookup by SKU + location
const srBySku = await getStockReference(accessToken, {
  bySku: { sku: 'TSHIRT-S-BLUE', locationId: 'loc_123' },
});

Python

import requests

def get_stock_reference(access_token, id=None, by_sku=None, by_reference=None):
    response = requests.post(
        'https://api-v3.happycolis.com/graphql',
        headers={
            'Authorization': f'Bearer {access_token}',
            'Content-Type': 'application/json',
        },
        json={
            'query': '''
                query GetStockReference(
                    $id: String
                    $bySku: StockReferenceBySkuInput
                    $byReference: StockReferenceByReferenceInput
                ) {
                    stockReference(id: $id, bySku: $bySku, byReference: $byReference) {
                        id
                        sku
                        reference
                        status
                        model
                        physicalQuantity
                        usableQuantity
                        reservedQuantity
                        location { id name }
                        productVariant { id sku }
                        storageProfile { id name }
                    }
                }
            ''',
            'variables': {'id': id, 'bySku': by_sku, 'byReference': by_reference},
        },
    )
    result = response.json()
    if 'errors' in result:
        raise Exception(result['errors'][0]['message'])
    return result['data']['stockReference']

# Lookup by ID
sr = get_stock_reference(access_token, id='sr_abc123')

# Lookup by SKU + location
sr = get_stock_reference(
    access_token,
    by_sku={'sku': 'TSHIRT-S-BLUE', 'locationId': 'loc_123'},
)

PHP

function getStockReference(
    string $accessToken,
    ?string $id = null,
    ?array $bySku = null,
    ?array $byReference = null
): array {
    $client = new \GuzzleHttp\Client();

    $response = $client->post('https://api-v3.happycolis.com/graphql', [
        'headers' => [
            'Authorization' => 'Bearer ' . $accessToken,
            'Content-Type'  => 'application/json',
        ],
        'json' => [
            'query' => '
                query GetStockReference(
                    $id: String
                    $bySku: StockReferenceBySkuInput
                    $byReference: StockReferenceByReferenceInput
                ) {
                    stockReference(id: $id, bySku: $bySku, byReference: $byReference) {
                        id
                        sku
                        reference
                        status
                        model
                        physicalQuantity
                        usableQuantity
                        reservedQuantity
                        location { id name }
                        productVariant { id sku }
                        storageProfile { id name }
                    }
                }
            ',
            'variables' => [
                'id'          => $id,
                'bySku'       => $bySku,
                'byReference' => $byReference,
            ],
        ],
    ]);

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

// Lookup by ID
$sr = getStockReference($accessToken, id: 'sr_abc123');

// Lookup by SKU + location
$sr = getStockReference($accessToken, bySku: [
    'sku'        => 'TSHIRT-S-BLUE',
    'locationId' => 'loc_123',
]);

Go

package main

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

type StockReferenceBySkuInput struct {
    SKU        string `json:"sku"`
    LocationID string `json:"locationId"`
}

type StockReferenceByReferenceInput struct {
    Reference  string `json:"reference"`
    LocationID string `json:"locationId"`
}

type StockReferenceVariables struct {
    ID          *string                         `json:"id,omitempty"`
    BySku       *StockReferenceBySkuInput       `json:"bySku,omitempty"`
    ByReference *StockReferenceByReferenceInput `json:"byReference,omitempty"`
}

func getStockReference(accessToken string, vars StockReferenceVariables) (map[string]interface{}, error) {
    query := `
        query GetStockReference(
            $id: String
            $bySku: StockReferenceBySkuInput
            $byReference: StockReferenceByReferenceInput
        ) {
            stockReference(id: $id, bySku: $bySku, byReference: $byReference) {
                id
                sku
                reference
                status
                model
                physicalQuantity
                usableQuantity
                reservedQuantity
                location { id name }
                productVariant { id sku }
                storageProfile { id name }
            }
        }
    `

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

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