transferOrderFulfillmentCreate

Registers a stock reception (fulfillment) for a transfer order at an INTERNAL fulfillment location.

Fulfillment locations of type INTERNAL are not connected to a warehouse management system. You must manually register stock receptions using this mutation to record stock movements and update received quantities on the transfer order lines.

For non-INTERNAL (external) locations, the warehouse management system handles fulfillment creation automatically. You do not need to call this mutation for those locations.

The transfer order must be in OPENED state to accept fulfillments.

Required scope: create_transfer_orders

---

Mutation

mutation TransferOrderFulfillmentCreate($input: FulfillmentInput!) {
  transferOrderFulfillmentCreate(input: $input) {
    id
    fulfillmentOrderId
    createdAt
    type
    trackingNumber
    reference
  }
}

---

Return type: FulfillmentType

Field	Description
id	Unique identifier of the fulfillment
fulfillmentOrderId	The transfer order UUID
createdAt	Timestamp when the fulfillment was created
type	Fulfillment type
trackingNumber	Optional tracking number
reference	Fulfillment reference

---

Input: FulfillmentInput

Field	Type	Required	Description
fulfillmentOrderId	String	✅	The transfer order UUID to create a fulfillment for
type	TypeEnum	✅	Fulfillment type
reference	String	✅	A reference for this fulfillment (e.g. reception note number)
trackingNumber	String	❌	Tracking number for the shipment
data	JSON	❌	Additional metadata as a JSON object
file	String	❌	File reference (e.g. reception document URL)
quantities	[FulfillmentQuantityInput!]	✅	Received quantities per line
gestures	[GestureInput!]	❌	Gesture data for the fulfillment

FulfillmentQuantityInput

Field	Type	Required	Description
sku	String	✅	SKU identifier of the received product
stockReferenceId	String	✅	Stock reference UUID
fulfillmentOrderLineNumber	String	❌	Transfer order line number
fulfillmentOrderLineId	String	❌	Transfer order line UUID
dispatchableLineNumber	String	❌	Dispatchable line number

---

Example Variables

{
  "input": {
    "fulfillmentOrderId": "550e8400-e29b-41d4-a716-446655440000",
    "type": "RECEPTION",
    "reference": "REC-2024-001",
    "trackingNumber": "1Z999AA10123456784",
    "quantities": [
      {
        "sku": "WIDGET-A-100",
        "stockReferenceId": "stock-ref-uuid-001",
        "fulfillmentOrderLineId": "line-uuid-001"
      },
      {
        "sku": "GADGET-B-200",
        "stockReferenceId": "stock-ref-uuid-002",
        "fulfillmentOrderLineId": "line-uuid-002"
      }
    ]
  }
}

---

Example Response

{
  "data": {
    "transferOrderFulfillmentCreate": {
      "id": "fulfillment-uuid-001",
      "fulfillmentOrderId": "550e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2024-02-15T14:30:00.000Z",
      "type": "RECEPTION",
      "trackingNumber": "1Z999AA10123456784",
      "reference": "REC-2024-001"
    }
  }
}

---

Code Examples

curl

curl -X POST https://api-v3.happycolis.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "query": "mutation TransferOrderFulfillmentCreate($input: FulfillmentInput!) { transferOrderFulfillmentCreate(input: $input) { id fulfillmentOrderId createdAt type trackingNumber reference } }",
    "variables": {
      "input": {
        "fulfillmentOrderId": "550e8400-e29b-41d4-a716-446655440000",
        "type": "RECEPTION",
        "reference": "REC-2024-001",
        "quantities": [
          {
            "sku": "WIDGET-A-100",
            "stockReferenceId": "stock-ref-uuid-001",
            "fulfillmentOrderLineId": "line-uuid-001"
          }
        ]
      }
    }
  }'

Node.js

const mutation = `
  mutation TransferOrderFulfillmentCreate($input: FulfillmentInput!) {
    transferOrderFulfillmentCreate(input: $input) {
      id
      fulfillmentOrderId
      createdAt
      type
      trackingNumber
      reference
    }
  }
`;

const variables = {
  input: {
    fulfillmentOrderId: '550e8400-e29b-41d4-a716-446655440000',
    type: 'RECEPTION',
    reference: 'REC-2024-001',
    trackingNumber: '1Z999AA10123456784',
    quantities: [
      {
        sku: 'WIDGET-A-100',
        stockReferenceId: 'stock-ref-uuid-001',
        fulfillmentOrderLineId: 'line-uuid-001',
      },
      {
        sku: 'GADGET-B-200',
        stockReferenceId: 'stock-ref-uuid-002',
        fulfillmentOrderLineId: 'line-uuid-002',
      },
    ],
  },
};

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.transferOrderFulfillmentCreate);

Python

import os
import requests

mutation = """
mutation TransferOrderFulfillmentCreate($input: FulfillmentInput!) {
  transferOrderFulfillmentCreate(input: $input) {
    id
    fulfillmentOrderId
    createdAt
    type
    trackingNumber
    reference
  }
}
"""

variables = {
    "input": {
        "fulfillmentOrderId": "550e8400-e29b-41d4-a716-446655440000",
        "type": "RECEPTION",
        "reference": "REC-2024-001",
        "trackingNumber": "1Z999AA10123456784",
        "quantities": [
            {
                "sku": "WIDGET-A-100",
                "stockReferenceId": "stock-ref-uuid-001",
                "fulfillmentOrderLineId": "line-uuid-001",
            },
            {
                "sku": "GADGET-B-200",
                "stockReferenceId": "stock-ref-uuid-002",
                "fulfillmentOrderLineId": "line-uuid-002",
            },
        ],
    }
}

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['transferOrderFulfillmentCreate'])

PHP

<?php
$mutation = <<<'GQL'
mutation TransferOrderFulfillmentCreate($input: FulfillmentInput!) {
  transferOrderFulfillmentCreate(input: $input) {
    id
    fulfillmentOrderId
    createdAt
    type
    trackingNumber
    reference
  }
}
GQL;

$variables = [
    'input' => [
        'fulfillmentOrderId' => '550e8400-e29b-41d4-a716-446655440000',
        'type'               => 'RECEPTION',
        'reference'          => 'REC-2024-001',
        'trackingNumber'     => '1Z999AA10123456784',
        'quantities' => [
            [
                'sku'                    => 'WIDGET-A-100',
                'stockReferenceId'       => 'stock-ref-uuid-001',
                'fulfillmentOrderLineId' => 'line-uuid-001',
            ],
            [
                'sku'                    => 'GADGET-B-200',
                'stockReferenceId'       => 'stock-ref-uuid-002',
                'fulfillmentOrderLineId' => 'line-uuid-002',
            ],
        ],
    ],
];

$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']['transferOrderFulfillmentCreate']);

Go

package main

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

func main() {
	mutation := `
		mutation TransferOrderFulfillmentCreate($input: FulfillmentInput!) {
			transferOrderFulfillmentCreate(input: $input) {
				id
				fulfillmentOrderId
				createdAt
				type
				trackingNumber
				reference
			}
		}`

	variables := map[string]any{
		"input": map[string]any{
			"fulfillmentOrderId": "550e8400-e29b-41d4-a716-446655440000",
			"type":               "RECEPTION",
			"reference":          "REC-2024-001",
			"trackingNumber":     "1Z999AA10123456784",
			"quantities": []map[string]any{
				{
					"sku":                    "WIDGET-A-100",
					"stockReferenceId":       "stock-ref-uuid-001",
					"fulfillmentOrderLineId": "line-uuid-001",
				},
				{
					"sku":                    "GADGET-B-200",
					"stockReferenceId":       "stock-ref-uuid-002",
					"fulfillmentOrderLineId": "line-uuid-002",
				},
			},
		},
	}

	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"])
}