transferOrderCreate

Creates a new transfer order in DRAFT state. A transfer order represents an incoming stock replenishment from a supplier to a fulfillment location.

Required scope: create_transfer_orders

Mutation

graphql

mutation TransferOrderCreate($input: TransferOrderInput!) {
  transferOrderCreate(input: $input) {
    id
    reference
    orderNumber
    state
    externalReference
    expectedDate
    containerNumber
    containerType
    lines {
      id
      sku
      reference
      expectedQuantity
    }
    createdAt
  }
}

Input: `TransferOrderInput`

Field	Type	Required	Description
`organizationId`	String	❌	Organization UUID the transfer order belongs to
`locationId`	String	✅	Destination fulfillment location UUID
`reference`	String	✅	Internal reference for the transfer
`supplierId`	String	❌	Supplier UUID
`externalReference`	String	❌	External system reference
`containerNumber`	Int	✅	Number of containers
`containerType`	TransferOrderContainerTypeEnum	✅	`BOX`, `PALLET`, or `CONTAINER`
`expectedDate`	DateTime	✅	Expected delivery date at the warehouse
`organizationAcronym`	String	✅	Organization short code used for order number generation
`lines`	[TransferOrderLineInput!]	✅	Transfer order lines — at least one required
`shippingDate`	DateTime	❌	Date the shipment leaves the supplier
`carrier`	String	❌	Carrier name
`tracking`	String	❌	Tracking number
`comment`	String	❌	Free-text comment visible to warehouse operators
`issuedAt`	DateTime	❌	Date the transfer order was issued in your system
`emergency`	Boolean	❌	Emergency flag — prioritises reception at the warehouse

TransferOrderLineInput

Field	Type	Required	Description
`stockReferenceId`	String	❌	Stock reference UUID
`sku`	String	✅	Stock-Keeping Unit identifier
`reference`	String	✅	Product reference or label
`limitUsageDate`	String	❌	Expiry or use-by date
`batchNumber`	String	❌	Batch or lot number
`expectedQuantity`	Int	✅	Expected quantity to receive
`receivedQuantity`	Int	❌	Received quantity (typically omitted on creation)
`restockedQuantity`	Int	❌	Restocked quantity (typically omitted on creation)
`garbageQuantity`	Int	❌	Garbage or damaged quantity (typically omitted on creation)
`meta`	JSON	❌	Additional metadata as a JSON object

Example Variables

json

{
  "input": {
    "organizationId": "org-uuid-001",
    "locationId": "loc-uuid-001",
    "reference": "TO-2024-001",
    "supplierId": "supplier-uuid-001",
    "externalReference": "ERP-TRANSFER-789",
    "containerNumber": 3,
    "containerType": "BOX",
    "expectedDate": "2024-02-15T08:00:00Z",
    "organizationAcronym": "ACME",
    "shippingDate": "2024-02-12T10:00:00Z",
    "carrier": "DHL Express",
    "tracking": "1Z999AA10123456784",
    "comment": "Fragile items — handle with care",
    "emergency": false,
    "lines": [
      {
        "sku": "WIDGET-A-100",
        "reference": "Widget Alpha",
        "expectedQuantity": 500,
        "batchNumber": "BATCH-2024-01"
      },
      {
        "sku": "GADGET-B-200",
        "reference": "Gadget Beta",
        "expectedQuantity": 250,
        "limitUsageDate": "2025-06-30"
      }
    ]
  }
}

Example Response

json

{
  "data": {
    "transferOrderCreate": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "reference": "TO-2024-001",
      "orderNumber": "ACME-TO-000042",
      "state": "DRAFT",
      "externalReference": "ERP-TRANSFER-789",
      "expectedDate": "2024-02-15T08:00:00.000Z",
      "containerNumber": "3",
      "containerType": "BOX",
      "lines": [
        {
          "id": "line-uuid-001",
          "sku": "WIDGET-A-100",
          "reference": "Widget Alpha",
          "expectedQuantity": 500
        },
        {
          "id": "line-uuid-002",
          "sku": "GADGET-B-200",
          "reference": "Gadget Beta",
          "expectedQuantity": 250
        }
      ],
      "createdAt": "2024-02-10T09:00:00.000Z"
    }
  }
}

Code Examples

bash

curl -X POST https://api-v3.happycolis.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "query": "mutation TransferOrderCreate($input: TransferOrderInput!) { transferOrderCreate(input: $input) { id reference orderNumber state externalReference expectedDate containerType lines { id sku reference expectedQuantity } createdAt } }",
    "variables": {
      "input": {
        "organizationId": "org-uuid-001",
        "locationId": "loc-uuid-001",
        "reference": "TO-2024-001",
        "containerNumber": 3,
        "containerType": "BOX",
        "expectedDate": "2024-02-15T08:00:00Z",
        "organizationAcronym": "ACME",
        "lines": [
          {
            "sku": "WIDGET-A-100",
            "reference": "Widget Alpha",
            "expectedQuantity": 500,
            "batchNumber": "BATCH-2024-01"
          }
        ]
      }
    }
  }'

const mutation = `
  mutation TransferOrderCreate($input: TransferOrderInput!) {
    transferOrderCreate(input: $input) {
      id
      reference
      orderNumber
      state
      externalReference
      expectedDate
      containerType
      lines {
        id
        sku
        reference
        expectedQuantity
      }
      createdAt
    }
  }
`;

const variables = {
  input: {
    organizationId: 'org-uuid-001',
    locationId: 'loc-uuid-001',
    reference: 'TO-2024-001',
    supplierId: 'supplier-uuid-001',
    externalReference: 'ERP-TRANSFER-789',
    containerNumber: 3,
    containerType: 'BOX',
    expectedDate: '2024-02-15T08:00:00Z',
    organizationAcronym: 'ACME',
    shippingDate: '2024-02-12T10:00:00Z',
    carrier: 'DHL Express',
    tracking: '1Z999AA10123456784',
    comment: 'Fragile items — handle with care',
    emergency: false,
    lines: [
      {
        sku: 'WIDGET-A-100',
        reference: 'Widget Alpha',
        expectedQuantity: 500,
        batchNumber: 'BATCH-2024-01',
      },
      {
        sku: 'GADGET-B-200',
        reference: 'Gadget Beta',
        expectedQuantity: 250,
        limitUsageDate: '2025-06-30',
      },
    ],
  },
};

const response = await fetch('https://api-v3.happycolis.com/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.ACCESS_TOKEN}`,
  },
  body: JSON.stringify({ query: mutation, variables }),
});

const { data } = await response.json();
console.log(data.transferOrderCreate);

python

import os
import requests

mutation = """
mutation TransferOrderCreate($input: TransferOrderInput!) {
  transferOrderCreate(input: $input) {
    id
    reference
    orderNumber
    state
    externalReference
    expectedDate
    containerType
    lines {
      id
      sku
      reference
      expectedQuantity
    }
    createdAt
  }
}
"""

variables = {
    "input": {
        "organizationId": "org-uuid-001",
        "locationId": "loc-uuid-001",
        "reference": "TO-2024-001",
        "supplierId": "supplier-uuid-001",
        "externalReference": "ERP-TRANSFER-789",
        "containerNumber": 3,
        "containerType": "BOX",
        "expectedDate": "2024-02-15T08:00:00Z",
        "organizationAcronym": "ACME",
        "shippingDate": "2024-02-12T10:00:00Z",
        "carrier": "DHL Express",
        "tracking": "1Z999AA10123456784",
        "comment": "Fragile items — handle with care",
        "emergency": False,
        "lines": [
            {
                "sku": "WIDGET-A-100",
                "reference": "Widget Alpha",
                "expectedQuantity": 500,
                "batchNumber": "BATCH-2024-01",
            },
            {
                "sku": "GADGET-B-200",
                "reference": "Gadget Beta",
                "expectedQuantity": 250,
                "limitUsageDate": "2025-06-30",
            },
        ],
    }
}

response = requests.post(
    'https://api-v3.happycolis.com/graphql',
    headers={'Authorization': f'Bearer {os.environ["ACCESS_TOKEN"]}'},
    json={'query': mutation, 'variables': variables},
)

data = response.json()['data']
print(data['transferOrderCreate'])

php

<?php
$mutation = <<<'GQL'
mutation TransferOrderCreate($input: TransferOrderInput!) {
  transferOrderCreate(input: $input) {
    id
    reference
    orderNumber
    state
    externalReference
    expectedDate
    containerType
    lines {
      id
      sku
      reference
      expectedQuantity
    }
    createdAt
  }
}
GQL;

$variables = [
    'input' => [
        'organizationId'      => 'org-uuid-001',
        'locationId'          => 'loc-uuid-001',
        'reference'           => 'TO-2024-001',
        'supplierId'          => 'supplier-uuid-001',
        'externalReference'   => 'ERP-TRANSFER-789',
        'containerNumber'     => 3,
        'containerType'       => 'BOX',
        'expectedDate'        => '2024-02-15T08:00:00Z',
        'organizationAcronym' => 'ACME',
        'shippingDate'        => '2024-02-12T10:00:00Z',
        'carrier'             => 'DHL Express',
        'tracking'            => '1Z999AA10123456784',
        'comment'             => 'Fragile items — handle with care',
        'emergency'           => false,
        'lines' => [
            [
                'sku'              => 'WIDGET-A-100',
                'reference'        => 'Widget Alpha',
                'expectedQuantity' => 500,
                'batchNumber'      => 'BATCH-2024-01',
            ],
            [
                'sku'              => 'GADGET-B-200',
                'reference'        => 'Gadget Beta',
                'expectedQuantity' => 250,
                'limitUsageDate'   => '2025-06-30',
            ],
        ],
    ],
];

$ch = curl_init('https://api-v3.happycolis.com/graphql');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode(['query' => $mutation, 'variables' => $variables]),
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'Authorization: Bearer ' . getenv('ACCESS_TOKEN'),
    ],
]);

$result = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($result['data']['transferOrderCreate']);

package main

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

func main() {
	mutation := `
		mutation TransferOrderCreate($input: TransferOrderInput!) {
			transferOrderCreate(input: $input) {
				id
				reference
				orderNumber
				state
				externalReference
				expectedDate
				containerType
				lines {
					id
					sku
					reference
					expectedQuantity
				}
				createdAt
			}
		}`

	variables := map[string]any{
		"input": map[string]any{
			"organizationId":      "org-uuid-001",
			"locationId":          "loc-uuid-001",
			"reference":           "TO-2024-001",
			"supplierId":          "supplier-uuid-001",
			"externalReference":   "ERP-TRANSFER-789",
			"containerNumber":     3,
			"containerType":       "BOX",
			"expectedDate":        "2024-02-15T08:00:00Z",
			"organizationAcronym": "ACME",
			"shippingDate":        "2024-02-12T10:00:00Z",
			"carrier":             "DHL Express",
			"tracking":            "1Z999AA10123456784",
			"comment":             "Fragile items — handle with care",
			"emergency":           false,
			"lines": []map[string]any{
				{
					"sku":              "WIDGET-A-100",
					"reference":        "Widget Alpha",
					"expectedQuantity": 500,
					"batchNumber":      "BATCH-2024-01",
				},
				{
					"sku":              "GADGET-B-200",
					"reference":        "Gadget Beta",
					"expectedQuantity": 250,
					"limitUsageDate":   "2025-06-30",
				},
			},
		},
	}

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

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

	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()

	var result map[string]any
	json.NewDecoder(resp.Body).Decode(&result)
	fmt.Println(result["data"])
}

transferOrderCreate ​

Mutation ​

Input: TransferOrderInput ​

TransferOrderLineInput ​

Example Variables ​

Example Response ​