Transfer Orders — Overview

A TransferOrder represents a stock replenishment from a supplier to a fulfillment location. Similar to a DeliveryOrder but for incoming stock, it tracks the full lifecycle of a transfer: from declaration through warehouse reception and completion. Each transfer order contains lines describing expected SKUs and quantities, and produces fulfillment events as it progresses.

---

Transfer Order Flow

---

Transfer Order States

State	Description
DRAFT	Created but fulfillment has not been requested yet. Any fulfillment action is automatically accepted.
OPENED	Fulfillment has been requested. The transfer order is tracked via fulfillment events.
COMPLETED	All stock has been received. May be completed automatically when quantities match, or manually when discrepancies exist.

---

Important Notice

Any stock transfer to a fulfillment location not announced to HappyColis at least 48 hours before its expected delivery date may be refused or delayed by the warehouse.

---

GraphQL Types

TransferOrderType

type TransferOrderType {
  id: ID!
  reference: String
  state: TransferOrderStateEnum!
  orderNumber: String
  externalReference: String
  expectedDate: DateTime
  shippingDate: DateTime
  carrier: String
  tracking: String
  comment: String
  emergency: Boolean
  containerNumber: String
  containerType: String
  location: LocationType
  lines: [TransferOrderLineType!]!
  events: [FulfillmentEventType!]!
  fulfillments: [TransferOrderFulfillmentType!]
  createdAt: DateTime!
  updatedAt: DateTime!
}

TransferOrderLineType

type TransferOrderLineType {
  id: ID!
  sku: String!
  reference: String
  expectedQuantity: Int!
  receivedQuantity: Int
  restockedQuantity: Int
  garbageQuantity: Int
  limitUsageDate: DateTime
  batchNumber: String
  transferOrderLineNumber: String
  state: TransferOrderLineStateEnum
}

TransferOrderFulfillmentType

type TransferOrderFulfillmentType {
  id: ID!
  state: String
  createdAt: DateTime!
  issuedAt: DateTime
  updatedAt: DateTime!
  lines: [TransferOrderFulfillmentLineType!]!
}

FulfillmentEventType

type FulfillmentEventType {
  id: ID!
  type: FulfillmentEventTypeEnum!
  message: String
  date: DateTime!
}

---

Fulfillment Events

Fulfillment events are appended to the events array and provide a detailed audit trail of the transfer order lifecycle.

Event	Description
FULFILLMENT_ACCEPTED	The fulfillment was accepted by HappyColis.
FULFILLMENT_REJECTED	The fulfillment was rejected by HappyColis.
INTEGRATED	The fulfillment was accepted at the warehouse level.
INTEGRATION_ERROR	The fulfillment was rejected at the warehouse level.
FULFILLMENT_IN_PROGRESS	The fulfillment has started at the warehouse.
CANCELED	The fulfillment was cancelled.
CANCEL_REJECTED	The cancellation request was rejected.
COMPLETED	The fulfillment was completed — all stock received.
HOLDED	The fulfillment was put on hold.
RESUMED	The fulfillment was resumed from hold.

---

Operations

Mutations

Operation	Description
transferOrderCreate	Create a new transfer order in DRAFT state.
transferOrderRequestFulfillment	Submit the transfer order for fulfillment (DRAFT to OPENED).
transferOrderUpdate	Update an existing transfer order.
transferOrderHold	Pause fulfillment of an opened transfer order.
transferOrderResume	Resume a held transfer order.
transferOrderCancel	Cancel a transfer order.
transferOrderComplete	Manually mark a transfer order as completed.
transferOrderFulfillmentCreate	Register a stock reception (fulfillment) for an INTERNAL location.

---

Best Practices

1. Announce transfers 48 hours in advance. Stock transfers that arrive unannounced may be refused or delayed by the warehouse. Always create and submit your transfer order well before the expected delivery date.
2. Manual completion may be needed. When received quantities do not match expected quantities, items are missing, or additional items are received, HappyColis will not auto-complete the transfer order. Use transferOrderComplete to close it manually.
3. Use transferOrderFulfillmentCreate for INTERNAL locations. Fulfillment locations of type INTERNAL are not connected to a warehouse service. You must manually register stock receptions using this mutation to record stock movements.
4. Expect partial receptions. A single transfer order may produce multiple TransferOrderFulfillment objects. This is normal when the warehouse team processes stock in batches across different shifts.
5. Monitor fulfillment events. Track the events array or subscribe to webhooks (transfer-order/accepted, transfer-order/fulfillment-created) to react to state changes in real time.