stockReferenceArchive

Required scope: edit_stock_references

Irreversible operation

Archiving a stock reference is permanent. Archived references cannot be restored. All quantity counters are frozen and the reference is excluded from fulfillment routing. Ensure all pending delivery orders associated with this reference are resolved before archiving.

This page also covers stockReferenceRequestFulfillment, which is required to activate a stock reference at a WAREHOUSE location.

---

stockReferenceArchive

Permanently archives a stock reference, setting its status to ARCHIVED. No further stock movements or fulfillment routing will occur for this reference.

Mutation

mutation StockReferenceArchive($id: String!) {
  stockReferenceArchive(id: $id) {
    id
    status
  }
}

Arguments

Argument	Type	Required	Description
id	String	Yes	Stock reference UUID to archive

Variables

{
  "id": "sr_abc123"
}

Response

{
  "data": {
    "stockReferenceArchive": {
      "id": "sr_abc123",
      "status": "ARCHIVED"
    }
  }
}

---

stockReferenceRequestFulfillment

Required scope: edit_stock_references

Activates a stock reference that was created at a WAREHOUSE location. Stock references at warehouse locations start in DRAFT status and are not visible to the order routing engine until this mutation is called. It notifies the connected fulfillment service and transitions the status from DRAFT to VALID.

This mutation returns a scalar Boolean (true on success).

Mutation

mutation StockReferenceRequestFulfillment($id: String!) {
  stockReferenceRequestFulfillment(id: $id)
}

Arguments

Argument	Type	Required	Description
id	String	Yes	Stock reference UUID (must be in DRAFT status at a WAREHOUSE location)

Variables

{
  "id": "sr_abc123"
}

Response

{
  "data": {
    "stockReferenceRequestFulfillment": true
  }
}

After a successful call, the stock reference transitions to VALID and becomes eligible for delivery order routing.

---

Code Examples

stockReferenceArchive

curl

curl -X POST https://api-v3.happycolis.com/graphql \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation StockReferenceArchive($id: String!) { stockReferenceArchive(id: $id) { id status } }",
    "variables": {
      "id": "sr_abc123"
    }
  }'

Node.js

async function stockReferenceArchive(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 StockReferenceArchive($id: String!) {
          stockReferenceArchive(id: $id) {
            id
            status
          }
        }
      `,
      variables: { id },
    }),
  });

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

const archived = await stockReferenceArchive(accessToken, 'sr_abc123');
console.log(archived.status); // "ARCHIVED"

Python

import requests

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

archived = stock_reference_archive(access_token, 'sr_abc123')
print(archived['status'])  # "ARCHIVED"

PHP

function stockReferenceArchive(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 StockReferenceArchive($id: String!) {
                    stockReferenceArchive(id: $id) {
                        id
                        status
                    }
                }
            ',
            'variables' => ['id' => $id],
        ],
    ]);

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

$archived = stockReferenceArchive($accessToken, 'sr_abc123');
echo $archived['status']; // "ARCHIVED"

Go

package main

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

func stockReferenceArchive(accessToken string, id string) (map[string]interface{}, error) {
    query := `
        mutation StockReferenceArchive($id: String!) {
            stockReferenceArchive(id: $id) {
                id
                status
            }
        }
    `

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

---

stockReferenceRequestFulfillment

curl

curl -X POST https://api-v3.happycolis.com/graphql \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation StockReferenceRequestFulfillment($id: String!) { stockReferenceRequestFulfillment(id: $id) }",
    "variables": {
      "id": "sr_abc123"
    }
  }'

Node.js

async function requestFulfillment(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 StockReferenceRequestFulfillment($id: String!) {
          stockReferenceRequestFulfillment(id: $id)
        }
      `,
      variables: { id },
    }),
  });

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

const success = await requestFulfillment(accessToken, 'sr_abc123');

Python

import requests

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

success = request_fulfillment(access_token, 'sr_abc123')

PHP

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

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

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

$success = requestFulfillment($accessToken, 'sr_abc123');

Go

package main

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

func requestFulfillment(accessToken string, id string) (bool, error) {
    query := `
        mutation StockReferenceRequestFulfillment($id: String!) {
            stockReferenceRequestFulfillment(id: $id)
        }
    `

    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 false, err
    }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)

    if errs, ok := result["errors"]; ok {
        return false, fmt.Errorf("graphql error: %v", errs)
    }
    data := result["data"].(map[string]interface{})
    return data["stockReferenceRequestFulfillment"].(bool), nil
}