deliveryOrderRequestFulfillment

Required scope: edit_delivery_orders

Sends a delivery order to the fulfillment location (warehouse or internal team) to begin processing. This is the primary trigger that starts the fulfillment lifecycle — it appends a FULFILLMENT_REQUESTED event to fulfillmentData.events and transitions the order to PENDING.

For WAREHOUSE-type delivery orders, the warehouse will respond asynchronously with a FULFILLMENT_ACCEPTED or FULFILLMENT_REJECTED event.

This page also covers deliveryOrderUpdate, which allows updating a delivery order's fields (e.g. delivery address, priority) before re-requesting fulfillment.

---

Mutations

deliveryOrderRequestFulfillment

mutation DeliveryOrderRequestFulfillment($id: String!) {
  deliveryOrderRequestFulfillment(id: $id) {
    id
    type
    state
    message
  }
}

deliveryOrderUpdate

mutation DeliveryOrderUpdate($input: DeliveryOrderInput!) {
  deliveryOrderUpdate(input: $input) {
    id
    type
    state
    message
  }
}

---

Arguments

deliveryOrderRequestFulfillment

Argument	Type	Required	Description
id	String!	Yes	UUID of the delivery order to send for fulfillment

deliveryOrderUpdate

Field	Type	Required	Description
id	String	Yes	UUID of the delivery order to update
locationId	String	No	New fulfillment location ID (only valid on DRAFT orders)
lines	[DeliveryOrderLineInput!]	No	Updated line quantities
priority	PriorityEnum	No	Updated priority: LOW, NORMAL, or HIGH

Return Type

Both mutations return a MutationResult object:

Field	Type	Description
id	ID!	UUID of the affected delivery order
type	String!	Always "delivery_order"
state	String!	Result state: "success" or "error"
message	String	Human-readable message describing the outcome

---

Example — Request Fulfillment

Variables

{
  "id": "do_abc123"
}

Response

{
  "data": {
    "deliveryOrderRequestFulfillment": {
      "id": "do_abc123",
      "type": "delivery_order",
      "state": "success",
      "message": "Fulfillment requested successfully."
    }
  }
}

---

Example — Update Before Re-requesting Fulfillment

Use deliveryOrderUpdate to correct a delivery order (e.g. after a FULFILLMENT_REJECTED event) before calling deliveryOrderRequestFulfillment again.

Variables

{
  "input": {
    "id": "do_abc123",
    "priority": "HIGH"
  }
}

Response

{
  "data": {
    "deliveryOrderUpdate": {
      "id": "do_abc123",
      "type": "delivery_order",
      "state": "success",
      "message": "Delivery order updated successfully."
    }
  }
}

---

Code Examples

curl

# Request fulfillment
curl -X POST https://api-v3.happycolis.com/graphql \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation DeliveryOrderRequestFulfillment($id: String!) { deliveryOrderRequestFulfillment(id: $id) { id type state message } }",
    "variables": {
      "id": "do_abc123"
    }
  }'

# Update delivery order
curl -X POST https://api-v3.happycolis.com/graphql \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation DeliveryOrderUpdate($input: DeliveryOrderInput!) { deliveryOrderUpdate(input: $input) { id type state message } }",
    "variables": {
      "input": {
        "id": "do_abc123",
        "priority": "HIGH"
      }
    }
  }'

Node.js

async function deliveryOrderRequestFulfillment(accessToken, id) {
  const response = await fetch('https://api-v3.happycolis.com/graphql', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      query: `
        mutation DeliveryOrderRequestFulfillment($id: String!) {
          deliveryOrderRequestFulfillment(id: $id) {
            id
            type
            state
            message
          }
        }
      `,
      variables: { id },
    }),
  });

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

async function deliveryOrderUpdate(accessToken, input) {
  const response = await fetch('https://api-v3.happycolis.com/graphql', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      query: `
        mutation DeliveryOrderUpdate($input: DeliveryOrderInput!) {
          deliveryOrderUpdate(input: $input) {
            id
            type
            state
            message
          }
        }
      `,
      variables: { input },
    }),
  });

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

// Request fulfillment
const result = await deliveryOrderRequestFulfillment(accessToken, 'do_abc123');

// Update then re-request
await deliveryOrderUpdate(accessToken, { id: 'do_abc123', priority: 'HIGH' });
await deliveryOrderRequestFulfillment(accessToken, 'do_abc123');

Python

import requests

def delivery_order_request_fulfillment(access_token, delivery_order_id):
    response = requests.post(
        'https://api-v3.happycolis.com/graphql',
        headers={
            'Authorization': f'Bearer {access_token}',
            'Content-Type': 'application/json',
        },
        json={
            'query': '''
                mutation DeliveryOrderRequestFulfillment($id: String!) {
                    deliveryOrderRequestFulfillment(id: $id) {
                        id
                        type
                        state
                        message
                    }
                }
            ''',
            'variables': {'id': delivery_order_id},
        },
    )
    result = response.json()
    if 'errors' in result:
        raise Exception(result['errors'][0]['message'])
    return result['data']['deliveryOrderRequestFulfillment']

def delivery_order_update(access_token, input_data):
    response = requests.post(
        'https://api-v3.happycolis.com/graphql',
        headers={
            'Authorization': f'Bearer {access_token}',
            'Content-Type': 'application/json',
        },
        json={
            'query': '''
                mutation DeliveryOrderUpdate($input: DeliveryOrderInput!) {
                    deliveryOrderUpdate(input: $input) {
                        id
                        type
                        state
                        message
                    }
                }
            ''',
            'variables': {'input': input_data},
        },
    )
    result = response.json()
    if 'errors' in result:
        raise Exception(result['errors'][0]['message'])
    return result['data']['deliveryOrderUpdate']

# Request fulfillment
result = delivery_order_request_fulfillment(access_token, 'do_abc123')

# Update then re-request
delivery_order_update(access_token, {'id': 'do_abc123', 'priority': 'HIGH'})
delivery_order_request_fulfillment(access_token, 'do_abc123')

PHP

function deliveryOrderRequestFulfillment(string $accessToken, string $id): array
{
    $client = new \GuzzleHttp\Client();

    $response = $client->post('https://api-v3.happycolis.com/graphql', [
        'headers' => [
            'Authorization' => 'Bearer ' . $accessToken,
            'Content-Type'  => 'application/json',
        ],
        'json' => [
            'query' => '
                mutation DeliveryOrderRequestFulfillment($id: String!) {
                    deliveryOrderRequestFulfillment(id: $id) {
                        id
                        type
                        state
                        message
                    }
                }
            ',
            'variables' => ['id' => $id],
        ],
    ]);

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

function deliveryOrderUpdate(string $accessToken, array $input): array
{
    $client = new \GuzzleHttp\Client();

    $response = $client->post('https://api-v3.happycolis.com/graphql', [
        'headers' => [
            'Authorization' => 'Bearer ' . $accessToken,
            'Content-Type'  => 'application/json',
        ],
        'json' => [
            'query' => '
                mutation DeliveryOrderUpdate($input: DeliveryOrderInput!) {
                    deliveryOrderUpdate(input: $input) {
                        id
                        type
                        state
                        message
                    }
                }
            ',
            'variables' => ['input' => $input],
        ],
    ]);

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

// Request fulfillment
$result = deliveryOrderRequestFulfillment($accessToken, 'do_abc123');

// Update then re-request
deliveryOrderUpdate($accessToken, ['id' => 'do_abc123', 'priority' => 'HIGH']);
deliveryOrderRequestFulfillment($accessToken, 'do_abc123');

Go

package main

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

func deliveryOrderRequestFulfillment(accessToken string, id string) (map[string]interface{}, error) {
    query := `
        mutation DeliveryOrderRequestFulfillment($id: String!) {
            deliveryOrderRequestFulfillment(id: $id) {
                id
                type
                state
                message
            }
        }
    `

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

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

type DeliveryOrderUpdateInput struct {
    ID         string  `json:"id"`
    LocationID *string `json:"locationId,omitempty"`
    Priority   *string `json:"priority,omitempty"`
}

func deliveryOrderUpdate(accessToken string, input DeliveryOrderUpdateInput) (map[string]interface{}, error) {
    query := `
        mutation DeliveryOrderUpdate($input: DeliveryOrderInput!) {
            deliveryOrderUpdate(input: $input) {
                id
                type
                state
                message
            }
        }
    `

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

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