location

Required scope: view_locations

Retrieve a single location by its ID or by its organization-scoped name.

---

Query

query GetLocation($id: String, $byName: LocationByNameInput) {
  location(id: $id, byName: $byName) {
    id
    name
    title
    description
    locationType
    active
    fulfillmentConfig {
      allowedCountries
      excludedCountries
      preparationDelay
      inventoryPolicy
    }
    integration {
      id
      state
      fulfillmentService {
        id
        name
      }
    }
  }
}

Arguments

Argument	Type	Description
id	String	Location UUID. Mutually exclusive with byName.
byName	LocationByNameInput	Look up by organization and name slug. Mutually exclusive with id.

LocationByNameInput

input LocationByNameInput {
  organizationId: String!
  name: String!
}

Field	Type	Required	Description
organizationId	String	Yes	The organization UUID that owns the location
name	String	Yes	The unique slug name of the location

---

Example — Lookup by ID

Variables

{
  "id": "loc_123"
}

Response

{
  "data": {
    "location": {
      "id": "loc_123",
      "name": "paris-warehouse",
      "title": "Paris Warehouse",
      "description": "Main warehouse in Paris",
      "locationType": "INTERNAL",
      "active": true,
      "fulfillmentConfig": {
        "allowedCountries": ["FR", "BE"],
        "excludedCountries": [],
        "preparationDelay": 1,
        "inventoryPolicy": "DENY"
      },
      "integration": null
    }
  }
}

---

Example — Lookup by Name

Variables

{
  "byName": {
    "organizationId": "org_123",
    "name": "paris-warehouse"
  }
}

---

Code Examples

curl

curl -X POST https://api-v3.happycolis.com/graphql \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query GetLocation($id: String, $byName: LocationByNameInput) { location(id: $id, byName: $byName) { id name title description locationType active fulfillmentConfig { allowedCountries excludedCountries preparationDelay inventoryPolicy } integration { id state fulfillmentService { id name } } } }",
    "variables": {
      "id": "loc_123"
    }
  }'

Node.js

async function getLocation(accessToken, { id, byName }) {
  const response = await fetch('https://api-v3.happycolis.com/graphql', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      query: `
        query GetLocation($id: String, $byName: LocationByNameInput) {
          location(id: $id, byName: $byName) {
            id
            name
            title
            description
            locationType
            active
            fulfillmentConfig {
              allowedCountries
              excludedCountries
              preparationDelay
              inventoryPolicy
            }
            integration {
              id
              state
              fulfillmentService {
                id
                name
              }
            }
          }
        }
      `,
      variables: { id, byName },
    }),
  });

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

// Lookup by ID
const location = await getLocation(accessToken, { id: 'loc_123' });

// Lookup by name
const locationByName = await getLocation(accessToken, {
  byName: { organizationId: 'org_123', name: 'paris-warehouse' },
});

Python

import requests

def get_location(access_token, id=None, by_name=None):
    response = requests.post(
        'https://api-v3.happycolis.com/graphql',
        headers={
            'Authorization': f'Bearer {access_token}',
            'Content-Type': 'application/json',
        },
        json={
            'query': '''
                query GetLocation($id: String, $byName: LocationByNameInput) {
                    location(id: $id, byName: $byName) {
                        id
                        name
                        title
                        description
                        locationType
                        active
                        fulfillmentConfig {
                            allowedCountries
                            excludedCountries
                            preparationDelay
                            inventoryPolicy
                        }
                        integration {
                            id
                            state
                            fulfillmentService {
                                id
                                name
                            }
                        }
                    }
                }
            ''',
            'variables': {'id': id, 'byName': by_name},
        },
    )
    result = response.json()
    if 'errors' in result:
        raise Exception(result['errors'][0]['message'])
    return result['data']['location']

# Lookup by ID
location = get_location(access_token, id='loc_123')

# Lookup by name
location = get_location(access_token, by_name={
    'organizationId': 'org_123',
    'name': 'paris-warehouse',
})

PHP

function getLocation(string $accessToken, ?string $id = null, ?array $byName = null): array
{
    $client = new \GuzzleHttp\Client();

    $response = $client->post('https://api-v3.happycolis.com/graphql', [
        'headers' => [
            'Authorization' => 'Bearer ' . $accessToken,
            'Content-Type'  => 'application/json',
        ],
        'json' => [
            'query' => '
                query GetLocation($id: String, $byName: LocationByNameInput) {
                    location(id: $id, byName: $byName) {
                        id
                        name
                        title
                        description
                        locationType
                        active
                        fulfillmentConfig {
                            allowedCountries
                            excludedCountries
                            preparationDelay
                            inventoryPolicy
                        }
                        integration {
                            id
                            state
                            fulfillmentService {
                                id
                                name
                            }
                        }
                    }
                }
            ',
            'variables' => ['id' => $id, 'byName' => $byName],
        ],
    ]);

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

// Lookup by ID
$location = getLocation($accessToken, id: 'loc_123');

// Lookup by name
$location = getLocation($accessToken, byName: [
    'organizationId' => 'org_123',
    'name'           => 'paris-warehouse',
]);

Go

package main

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

type LocationVariables struct {
    ID     *string                `json:"id,omitempty"`
    ByName *LocationByNameInput   `json:"byName,omitempty"`
}

type LocationByNameInput struct {
    OrganizationID string `json:"organizationId"`
    Name           string `json:"name"`
}

func getLocation(accessToken string, vars LocationVariables) (map[string]interface{}, error) {
    query := `
        query GetLocation($id: String, $byName: LocationByNameInput) {
            location(id: $id, byName: $byName) {
                id
                name
                title
                description
                locationType
                active
                fulfillmentConfig {
                    allowedCountries
                    excludedCountries
                    preparationDelay
                    inventoryPolicy
                }
                integration {
                    id
                    state
                    fulfillmentService {
                        id
                        name
                    }
                }
            }
        }
    `

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

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