stockReferenceUpdatePhysicalStock

Required scope: edit_stock_references

Increments or decrements a stock quantity by a delta value. Three variants of this mutation exist — one for each quantity type:

Mutation	Quantity affected
stockReferenceUpdatePhysicalStock	physicalQuantity
stockReferenceUpdateUsableStock	usableQuantity
stockReferenceUpdateReservedStock	reservedQuantity

All three mutations accept the same StockMovementInput input type and follow the same semantics. Use a positive delta to increment and a negative delta to decrement.

For inventory reconciliation (setting an absolute value), use stockReferenceAdjustInventoryLevel instead.

---

Mutations

mutation StockReferenceUpdatePhysicalStock($input: StockMovementInput!) {
  stockReferenceUpdatePhysicalStock(input: $input) {
    id
    physicalQuantity
    usableQuantity
  }
}

mutation StockReferenceUpdateUsableStock($input: StockMovementInput!) {
  stockReferenceUpdateUsableStock(input: $input) {
    id
    usableQuantity
  }
}

mutation StockReferenceUpdateReservedStock($input: StockMovementInput!) {
  stockReferenceUpdateReservedStock(input: $input) {
    id
    reservedQuantity
  }
}

Input

StockMovementInput

Field	Type	Required	Description
id	String	Yes	Stock reference UUID
delta	Int	Yes	Quantity change — positive to add, negative to subtract
nature	StockMovementNatureEnum	Yes	Business reason for the movement — see below
message	String	No	Free-text audit message for the movement log
date	DateTime	No	Movement date (defaults to current timestamp if omitted)

---

Stock Movement Natures

Nature	Description
ORDER	Movement related to order fulfillment (e.g., picking for a delivery order)
RETURN	Product return received from a customer
RECEPTION	Stock reception, typically from a transfer order or supplier delivery
WAREHOUSE_INVENTORY	Inventory count adjustment or reconciliation
LOSS	Stock loss due to damage, theft, or expiry

---

Variables

Increment physical stock (reception)

{
  "input": {
    "id": "sr_abc123",
    "delta": 50,
    "nature": "RECEPTION",
    "message": "Received 50 units from supplier PO-2024-0089",
    "date": "2024-01-15T10:00:00Z"
  }
}

Decrement physical stock (loss)

{
  "input": {
    "id": "sr_abc123",
    "delta": -3,
    "nature": "LOSS",
    "message": "3 units damaged during handling"
  }
}

Response

{
  "data": {
    "stockReferenceUpdatePhysicalStock": {
      "id": "sr_abc123",
      "physicalQuantity": 197,
      "usableQuantity": 187
    }
  }
}

---

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 StockReferenceUpdatePhysicalStock($input: StockMovementInput!) { stockReferenceUpdatePhysicalStock(input: $input) { id physicalQuantity usableQuantity } }",
    "variables": {
      "input": {
        "id": "sr_abc123",
        "delta": 50,
        "nature": "RECEPTION",
        "message": "Received 50 units from supplier PO-2024-0089",
        "date": "2024-01-15T10:00:00Z"
      }
    }
  }'

Node.js

async function updatePhysicalStock(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 StockReferenceUpdatePhysicalStock($input: StockMovementInput!) {
          stockReferenceUpdatePhysicalStock(input: $input) {
            id
            physicalQuantity
            usableQuantity
          }
        }
      `,
      variables: { input },
    }),
  });

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

// Reception: add 50 units
const result = await updatePhysicalStock(accessToken, {
  id: 'sr_abc123',
  delta: 50,
  nature: 'RECEPTION',
  message: 'Received 50 units from supplier PO-2024-0089',
  date: '2024-01-15T10:00:00Z',
});

// Loss: remove 3 units
const loss = await updatePhysicalStock(accessToken, {
  id: 'sr_abc123',
  delta: -3,
  nature: 'LOSS',
  message: '3 units damaged during handling',
});

Python

import requests

def update_physical_stock(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 StockReferenceUpdatePhysicalStock($input: StockMovementInput!) {
                    stockReferenceUpdatePhysicalStock(input: $input) {
                        id
                        physicalQuantity
                        usableQuantity
                    }
                }
            ''',
            'variables': {'input': input_data},
        },
    )
    result = response.json()
    if 'errors' in result:
        raise Exception(result['errors'][0]['message'])
    return result['data']['stockReferenceUpdatePhysicalStock']

# Reception: add 50 units
result = update_physical_stock(access_token, {
    'id': 'sr_abc123',
    'delta': 50,
    'nature': 'RECEPTION',
    'message': 'Received 50 units from supplier PO-2024-0089',
    'date': '2024-01-15T10:00:00Z',
})

# Loss: remove 3 units
loss = update_physical_stock(access_token, {
    'id': 'sr_abc123',
    'delta': -3,
    'nature': 'LOSS',
    'message': '3 units damaged during handling',
})

PHP

function updatePhysicalStock(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 StockReferenceUpdatePhysicalStock($input: StockMovementInput!) {
                    stockReferenceUpdatePhysicalStock(input: $input) {
                        id
                        physicalQuantity
                        usableQuantity
                    }
                }
            ',
            'variables' => ['input' => $input],
        ],
    ]);

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

// Reception: add 50 units
$result = updatePhysicalStock($accessToken, [
    'id'      => 'sr_abc123',
    'delta'   => 50,
    'nature'  => 'RECEPTION',
    'message' => 'Received 50 units from supplier PO-2024-0089',
    'date'    => '2024-01-15T10:00:00Z',
]);

// Loss: remove 3 units
$loss = updatePhysicalStock($accessToken, [
    'id'      => 'sr_abc123',
    'delta'   => -3,
    'nature'  => 'LOSS',
    'message' => '3 units damaged during handling',
]);

Go

package main

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

type StockMovementInput struct {
    ID      string  `json:"id"`
    Delta   int     `json:"delta"`
    Nature  string  `json:"nature"`
    Message *string `json:"message,omitempty"`
    Date    *string `json:"date,omitempty"`
}

func updatePhysicalStock(accessToken string, input StockMovementInput) (map[string]interface{}, error) {
    query := `
        mutation StockReferenceUpdatePhysicalStock($input: StockMovementInput!) {
            stockReferenceUpdatePhysicalStock(input: $input) {
                id
                physicalQuantity
                usableQuantity
            }
        }
    `

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