Locations — Overview

Locations represent warehouses or fulfillment centers where your products are stored and orders are fulfilled. Each location can operate independently (INTERNAL) or be connected to a third-party fulfillment service (WAREHOUSE).

---

GraphQL Types

LocationType

The root type for a location.

type LocationType {
  id: ID!
  name: String!
  title: String
  description: String
  locationType: LocationTypeEnum!
  active: Boolean!
  socialReason: String
  address: String
  addressComplement: String
  zipCode: String
  city: String
  country: String
  phone: String
  email: String
  fulfillmentConfig: LocationFulfillmentConfig
  integration: FulfillmentServiceIntegration
  organization: OrganizationType
}

Field	Type	Description
id	ID!	Unique identifier
name	String!	Unique slug name (e.g. paris-warehouse)
title	String	Human-readable display name
description	String	Free-text description
locationType	LocationTypeEnum!	INTERNAL or WAREHOUSE — see below
active	Boolean!	Whether the location is currently active
socialReason	String	Legal company name
address	String	Street address
addressComplement	String	Address line 2
zipCode	String	Zip or postal code
city	String	City
country	String	ISO 3166-1 alpha-2 country code (e.g. FR)
phone	String	Contact phone number
email	String	Contact email address
fulfillmentConfig	LocationFulfillmentConfig	Country and policy configuration — see below
integration	FulfillmentServiceIntegration	Connected fulfillment service — see below
organization	OrganizationType	Parent organization

---

LocationTypeEnum

Controls how stock and fulfillment are managed for the location.

Value	Description
INTERNAL	Virtual locations for stock managed by HappyColis in your own warehouse. You can manually or automatically manage stock.
WAREHOUSE	Physical locations connected to a FulfillmentService. This is the main type when you have a contractual relationship with HappyColis.
EXTERNAL	Virtual locations representing stock managed outside HappyColis. Stock movements are not allowed on these locations.

TIP

Your variants must be associated to a location (via a StockReference) before you can assign DeliveryOrders to that location.

---

LocationFulfillmentConfig

Per-location configuration that controls which orders the location can fulfill.

type LocationFulfillmentConfig {
  allowedCountries: [String!]
  excludedCountries: [String!]
  preparationDelay: Int
  inventoryPolicy: InventoryPolicyEnum
}

Field	Type	Description
allowedCountries	[String!]	ISO country codes this location is allowed to ship to. Empty means no restriction.
excludedCountries	[String!]	ISO country codes this location must never ship to. Takes priority over allowedCountries.
preparationDelay	Int	Default number of business days needed to prepare an order before handing off to a carrier.
inventoryPolicy	InventoryPolicyEnum	Controls behavior when stock is insufficient. DENY rejects the order; CONTINUE allows overselling.

---

FulfillmentServiceIntegration

Represents the connection between a location and a fulfillment service.

type FulfillmentServiceIntegration {
  id: ID!
  state: IntegrationStateEnum!
  fulfillmentService: FulfillmentServiceType
}

Field	Type	Description
id	ID!	Unique identifier for the integration record
state	IntegrationStateEnum!	Current lifecycle state — see below
fulfillmentService	FulfillmentServiceType	The connected fulfillment service

Integration States

State	Description
PENDING	Integration request sent to the fulfillment service; awaiting activation confirmation.
ACTIVE	Integration is active and operational. The fulfillment service is processing orders for this location.
ERROR	The integration encountered a connectivity or configuration error. Check the fulfillment service dashboard.
INACTIVE	Integration has been manually deactivated or the fulfillment service is unavailable.

---

Operations

Queries

Operation	Scope	Description
location	view_locations	Retrieve a location by ID or by name

Mutations

Operation	Scope	Description
locationCreate	create_locations	Create a new location
locationUpdate	edit_locations	Update location fields or fulfillment config
locationActivate	edit_locations	Set a location as active
locationDeactivate	edit_locations	Set a location as inactive
locationConnectToFulfillmentService	edit_locations	Connect or disconnect a fulfillment service

---

Best Practices

1. Use unique, slug-friendly names. The name field is a unique code that cannot be changed after creation. Keep it lowercase and hyphenated (e.g. lyon-warehouse-2). The title and description fields are used for display.
2. Configure country restrictions early. Set allowedCountries and excludedCountries before routing orders to the location.
3. Set preparationDelay accurately. This value affects expected delivery date calculations shown to customers.
4. Test integrations in staging. Always validate a fulfillment service connection in a non-production organization before going live.
5. Drain before deactivating. Transfer pending stock and open orders to another location before calling locationDeactivate.