Sourcing Auditability GraphQL API Overview

Essential knowledge

Intended Audience:

Technical User

Authors:

Kirill Gaiduk, Alexey Kaminskiy

Changed on:

3 Sept 2026

Overview

This article provides technical users with information about the Sourcing Auditability GraphQL API, which writes and reads Sourcing Audit records within the Responsive Sourcing Framework.

Key points

Prerequisites: You should have knowledge of: GraphQL API, Responsive Sourcing Framework, and the Sourcing Auditability Overview
The API exposes two operations: the `createSourcingAudit` mutation (write) and the `sourcingAudits` query (read)
Specific permissions are required: `SOURCINGAUDIT_CREATE` for the mutation, `SOURCINGAUDIT_VIEW` for the query, and `SOURCINGPROFILE_VIEW` to resolve the Sourcing Profile on a returned record
The write path enforces one payload limit - at most 100 Locations for the Strategy that produced the Fulfillments - so records stay bounded
The query returns a Relay-style connection with `cursor` pagination; the default page size is 10 and each `cursor` is an opaque Base64 pagination token
Positional quantity arrays align to the master `items` list by 0-based index: `missingItemQuantities` (per Location) and `itemQuantities` (per Fulfillment) each carry one entry per Item

What is the Sourcing Auditability GraphQL API for?

The Sourcing Auditability GraphQL API lets technical users work with the Sourcing Audit records that the Responsive Sourcing Framework produces:

Write a completed Sourcing Audit record with the `createSourcingAudit` mutation
The Sourcing Rules call this at the end of a sourcing execution
Read the Sourcing Audit records for an Order or Fulfillment Choice with the `sourcingAudits` query

For consumers the API is read-oriented: the platform writes each record once, with no updates or deletes.

Reminder

A Sourcing Audit is an immutable record of a single Sourcing Request. For the architectural context, storage rationale, and how audits appear in the Fluent Order Management System (OMS) Web App, see the Sourcing Auditability Overview.

How the API Works

The following diagram explains the Sourcing Auditability GraphQL API behavior:

The Sourcing Rules generate an audit at the end of each completed Sourcing Request
The write path validates the payload and enforces the write limit before persisting the record
The read path checks permission on the parent entity before returning any data, then returns only the records for the requested page - for an `ORDER` request, the records for the Order and all its Fulfillment Choices

Audit Failure Handling

A failed `createSourcingAudit` call does not reverse the sourcing outcome - the Sourcing Rules log the failure and continue.

Data Model

The following data model outlines the Sourcing Auditability entities:

Recommended practice

For the up-to-date data model we recommend to always refer back to the GraphQL Explorer.

Entities

The core Sourcing Auditability entities are:

Entity	Description
`SourcingAudit`	The root immutable record of one Sourcing Request - its inputs, evaluation, and outcome for an Order or Fulfillment Choice Returned by `sourcingAudits` Identified by: `entityType` `entityId` (internal id) `entityRef` (human-readable reference)
`SourcingAuditItem`	A requested Item and its quantity The `items` list is the master, positionally-referenced Item list for the whole record Stores no price data
`SourcingAuditStrategy`	The evaluation detail for one Sourcing Strategy considered during the request: Its outcome (`SKIPPED` / `EVALUATED` / `NOT_CONSIDERED`) Condition results For a successful Strategy: Produced Fulfillments Considered Locations
`SourcingAuditStrategyLocation`	A Location considered by the successful Strategy, with: Its per-Criterion scores Quantity of each Item it could not fulfill Up to 100 Locations stored only for the successful Strategy
`SourcingAuditStrategyFulfilment`	A Fulfillment produced by the successful Strategy: The Location selected for it The quantity of each Item allocated
`SourcingAuditConnection` / `SourcingAuditEdge`	The Relay-style pagination envelope returned by `sourcingAudits` Each edge wraps a `SourcingAudit` node with an opaque `cursor` used for pagination

Relationship Details

The following relationships define the Sourcing Auditability data model:

Relationship	Type	Description
Connection to Edges	One `SourcingAuditConnection` to many `SourcingAuditEdge`	The `sourcingAudits` query envelope `edges` holds one edge per returned record and `pageInfo` carries the Relay pagination flags
Edge to Audit	One `SourcingAuditEdge` to one `SourcingAudit`	Each edge wraps a single `SourcingAudit` in its `node`, with an opaque `cursor` used for pagination
Audit to Items	One `SourcingAudit` to many `SourcingAuditItem`	The `items` list is the master, positionally-significant Item list for the Sourcing Request (at least one Item) Every quantity array elsewhere in the record aligns to it by 0-based index
Audit to Strategies	One `SourcingAudit` to many `SourcingAuditStrategy`	The Strategies considered during evaluation, held in priority (execution) order
Audit to Profile	One `SourcingAudit` to one `SourcingProfile`	The Sourcing Profile and version used for the decision Resolved at read time and populated only if the caller holds `SOURCINGPROFILE_VIEW`; otherwise `null`
Strategy to Locations	One `SourcingAuditStrategy` to many `SourcingAuditStrategyLocation`	Per-Location evaluation detail Populated only for the Strategy with status `EVALUATED` that produced the Fulfillments - up to 100 Locations
Strategy to Fulfillments	One `SourcingAuditStrategy` to many `SourcingAuditStrategyFulfilment`	The Fulfillments the Strategy produced, each paired with the Location selected for it
Fulfillment to selected Location	One `SourcingAuditStrategyFulfilment` to one `SourcingAuditStrategyLocation`	`selectedLocationPosition` is a 0-based index into the Strategy's `locations` list `location` is the resolved entry - equivalent to `locations[selectedLocationPosition]`

Condition and Criteria Results

The `conditions` and `criteria` fields use the `Json` scalar and hold compact, positional arrays. Their object shapes are:

Field	Shape (one entry per element)	Description
`conditions` (on `SourcingAuditStrategy`)	`{ "p": boolean, "a": value }` - one entry per Condition, in evaluation order	`p` is whether the Condition passed `a` is the actual value from the Order or Fulfillment Choice the Condition was evaluated against, in its original type (for example `"Australia"` for a delivery-country Condition). `a` is always present
`criteria` (on `SourcingAuditStrategyLocation`)	`{ "n": number, "a": value }` - one entry per Criterion, aligned to the Criteria on the corresponding Strategy	`n` is the normalized value (0 to 1) used for ranking `a` is the optional actual value before normalization (for example, the exact distance in km for a `locationDistance` Criterion)

Operations

The Sourcing Auditability GraphQL API exposes one write operation and one read operation - the `createSourcingAudit` mutation and the `sourcingAudits` query - each governed by its own permission. The mutation stores a record; the query returns the stored records for an entity.

Permissions

The following permissions apply to the Sourcing Auditability GraphQL API:

Permission	Applies to	Purpose
`SOURCINGAUDIT_CREATE`	`createSourcingAudit` mutation	Write a Sourcing Audit record
`SOURCINGAUDIT_VIEW`	`sourcingAudits` query	Read Sourcing Audit records for an entity
`SOURCINGPROFILE_VIEW`	`sourcingAudits` query	Resolve and return the `profile` on a record Without it, `profile` is `null`

Query Permission Check

The query enforces the permission against the parent entity (the Order or Fulfillment Choice) before it reads any storage, so an unauthorized or missing parent yields an error before any records are read.

Mutation

`createSourcingAudit` writes a completed Sourcing Audit record. The Sourcing Rules call it at the end of a Sourcing Request; it is not part of a typical integration flow.

Permission: `SOURCINGAUDIT_CREATE`
Input: `CreateSourcingAuditInput!`

Mutation Write Limit

The mutation enforces a single write limit:

The Strategy that produced the Fulfillments (the successful Strategy, with status `EVALUATED`) must contain at most 100 Locations, or the API rejects the mutation
A Strategy without Fulfillments records no per-Location detail

The Sourcing Utilities independently truncate per-Location detail to 100 Locations after evaluation, so the 100-Location cap applies on both the generating and the storing side.

Example

1mutation createSourcingAudit($input: CreateSourcingAuditInput!) {
2  createSourcingAudit(input: $input) {
3    ref
4    entityType
5    entityId
6    entityRef
7    status
8    createdOn
9  }
10}

1{
2  "input": {
3    "ref": "SA-000001",
4    "entityType": "FULFILMENT_CHOICE",
5    "entityId": "789012",
6    "entityRef": "ORD-100123-1",
7    "retailer": { "id": "1" },
8    "type": "FALLBACK",
9    "status": "PARTIALLY_SOURCED",
10    "profile": { "ref": "ANZ_DEFAULT", "version": 3 },
11    "locationCount": 2,
12    "items": [
13      { "orderItemRef": "OI-1", "productRef": "SKU-BEA-1042", "productName": "Hydra-Glow Vitamin C Serum 30ml", "quantity": 5 },
14      { "orderItemRef": "OI-2", "productRef": "SKU-FAS-7781", "productName": "Merino Wool Crew Knit - Charcoal (M)", "quantity": 3 },
15      { "orderItemRef": "OI-3", "productRef": "SKU-PHA-3305", "productName": "Paracetamol 500mg Tablets - 24 Pack", "quantity": 2 }
16    ],
17    "strategies": [
18      {
19        "strategyRef": "b8e7c1a0-4f2d-4c8e-9a1b-2f6d3e5c7a90",
20        "status": "SKIPPED",
21        "evaluatedOn": "2026-08-17T09:30:00Z",
22        "locationCount": 0,
23        "conditions": [ { "p": false, "a": "STANDARD" } ]
24      },
25      {
26        "strategyRef": "c3d9f2b1-5a7e-4b6c-8d0f-1e2a3b4c5d6e",
27        "status": "EVALUATED",
28        "evaluatedOn": "2026-08-17T09:30:00Z",
29        "locationCount": 2,
30        "conditions": [ { "p": true, "a": "NSW" } ],
31        "locations": [
32          { "locationRef": "SYD01", "locationName": "Sydney CBD", "criteria": [ { "n": 1, "a": 2.4 } ], "missingItemQuantities": [ 0, 2, 0 ] },
33          { "locationRef": "MEL01", "locationName": "Melbourne Central", "criteria": [ { "n": 0.61, "a": 713.4 } ], "missingItemQuantities": [ 0, 3, 0 ] }
34        ],
35        "fulfilments": [
36          {
37            "fulfilmentRef": "FUL-1",
38            "selectedLocationPosition": 0,
39            "location": { "locationRef": "SYD01", "locationName": "Sydney CBD", "criteria": [ { "n": 1, "a": 2.4 } ], "missingItemQuantities": [ 0, 2, 0 ] },
40            "itemQuantities": [ 5, 1, 2 ]
41          }
42        ]
43      }
44    ]
45  }
46}

Language: json

Name: Sample createSourcingAudit input

Description:

Example input for a partially-sourced `FALLBACK` Sourcing Request.`entityRef` (required) is the sourced Fulfillment Choice's human-readable reference; `entityId` is its internal id. `entityType` accepts `ORDER` or `FULFILMENT_CHOICE`, but the Sourcing Rules write `FULFILMENT_CHOICE`.Shows the positional quantity arrays and the compact `conditions` / `criteria` shapes: the first Strategy is skipped (its express-only Condition fails), the second is evaluated and fulfills from the best-ranked of two candidate Locations, leaving one Item short. Each Fulfillment carries both `selectedLocationPosition` and the resolved `location` object (both required on input).

1{
2  "data": {
3    "createSourcingAudit": {
4      "ref": "SA-000001",
5      "entityType": "FULFILMENT_CHOICE",
6      "entityId": "789012",
7      "entityRef": "ORD-100123-1",
8      "status": "PARTIALLY_SOURCED",
9      "createdOn": "2026-08-17T09:30:00.000+00:00"
10    }
11  }
12}

Query

`sourcingAudits` retrieves the Sourcing Audit records for an Order or Fulfillment Choice.

Tip

Query by `ORDER` with the Order Id to retrieve the audits for the Order and all its Fulfillment Choices
Query by `FULFILMENT_CHOICE` with the Fulfillment Choice id for a single Fulfillment Choice.

The Sourcing Rules record each audit against the Fulfillment Choice that was sourced - or against the Order itself when that Fulfillment Choice has no reference (due to provided create order input) - so an `ORDER` query returns both, aggregated across the Order.

Permission: `SOURCINGAUDIT_VIEW` (plus `SOURCINGPROFILE_VIEW` to populate `profile`)
Complexity cost: `@complexityCost(value: 400)`
Returns: `SourcingAuditConnection`

Inputs

Argument	Type	Required	Description
`entityType`	`String!`	✅	The audited entity type: `ORDER` Returns the audits for the Order and all its Fulfillment Choices `FULFILMENT_CHOICE` A single Fulfillment Choice
`entityId`	`ID!`	✅	The audited entity identifier
`first`	`Int`	❌	Relay forward pagination - number of records after `after` Default page size is 10
`after`	`String`	❌	Cursor to page forward from
`last`	`Int`	❌	Relay backward pagination - number of records before `before`
`before`	`String`	❌	Cursor to page backward from

Pagination and cursors

Records are returned newest-first. Each `cursor` in the connection is an opaque Base64 token; treat it as a value to pass back, not to parse. The connection's `pageInfo` exposes `hasNextPage` and `hasPreviousPage`. To page forward, pass the last edge's `cursor` as the `after` argument.

Example

1query sourcingAudits($entityType: String!, $entityId: ID!, $first: Int, $after: String) {
2  sourcingAudits(entityType: $entityType, entityId: $entityId, first: $first, after: $after) {
3    edges {
4      cursor
5      node {
6        ref
7        entityType
8        entityId
9        entityRef
10        type
11        status
12        createdOn
13        locationCount
14        profile { ref version }
15        items { orderItemRef productRef productName quantity }
16        strategies {
17          strategyRef
18          status
19          evaluatedOn
20          locationCount
21          conditions
22          locations { locationRef locationName criteria missingItemQuantities }
23          fulfilments { fulfilmentRef selectedLocationPosition itemQuantities }
24        }
25      }
26    }
27    pageInfo { hasNextPage hasPreviousPage }
28  }
29}

1{
2  "entityType": "ORDER",
3  "entityId": "123456",
4  "first": 10
5}

1{
2  "data": {
3    "sourcingAudits": {
4      "edges": [
5        {
6          "cursor": "Y3Vyc29yOi0tLTIwMjYtMDgtMTdUMDktMzAtMDEuMDAwWi1mYjAwMDAwMS5neg==",
7          "node": {
8            "ref": "SA-000001",
9            "entityType": "FULFILMENT_CHOICE",
10            "entityId": "789012",
11            "entityRef": "ORD-100123-1",
12            "type": "FALLBACK",
13            "status": "PARTIALLY_SOURCED",
14            "createdOn": "2026-08-17T09:30:01.000+00:00",
15            "locationCount": 2,
16            "profile": { "ref": "ANZ_DEFAULT", "version": 3 },
17            "items": [
18              { "orderItemRef": "OI-1", "productRef": "SKU-BEA-1042", "productName": "Hydra-Glow Vitamin C Serum 30ml", "quantity": 5 },
19              { "orderItemRef": "OI-2", "productRef": "SKU-FAS-7781", "productName": "Merino Wool Crew Knit - Charcoal (M)", "quantity": 3 },
20              { "orderItemRef": "OI-3", "productRef": "SKU-PHA-3305", "productName": "Paracetamol 500mg Tablets - 24 Pack", "quantity": 2 }
21            ],
22            "strategies": [
23              {
24                "strategyRef": "b8e7c1a0-4f2d-4c8e-9a1b-2f6d3e5c7a90",
25                "status": "SKIPPED",
26                "evaluatedOn": "2026-08-17T09:30:01.000+00:00",
27                "locationCount": 0,
28                "conditions": [ { "p": false, "a": "STANDARD" } ],
29                "locations": [],
30                "fulfilments": []
31              },
32              {
33                "strategyRef": "c3d9f2b1-5a7e-4b6c-8d0f-1e2a3b4c5d6e",
34                "status": "EVALUATED",
35                "evaluatedOn": "2026-08-17T09:30:01.000+00:00",
36                "locationCount": 2,
37                "conditions": [ { "p": true, "a": "NSW" } ],
38                "locations": [
39                  { "locationRef": "SYD01", "locationName": "Sydney CBD", "criteria": [ { "n": 1, "a": 2.4 } ], "missingItemQuantities": [ 0, 2, 0 ] },
40                  { "locationRef": "MEL01", "locationName": "Melbourne Central", "criteria": [ { "n": 0.61, "a": 713.4 } ], "missingItemQuantities": [ 0, 3, 0 ] }
41                ],
42                "fulfilments": [
43                  { "fulfilmentRef": "FUL-1", "selectedLocationPosition": 0, "itemQuantities": [ 5, 1, 2 ] }
44                ]
45              }
46            ]
47          }
48        },
49        {
50          "cursor": "Y3Vyc29yOi0tLTIwMjYtMDgtMTdUMDktMzAtMDAuMDAwWi1wcjAwMDAwMC5neg==",
51          "node": {
52            "ref": "SA-000000",
53            "entityType": "FULFILMENT_CHOICE",
54            "entityId": "789012",
55            "entityRef": "ORD-100123-1",
56            "type": "PRIMARY",
57            "status": "NOT_SOURCED",
58            "createdOn": "2026-08-17T09:30:00.000+00:00",
59            "locationCount": 2,
60            "profile": { "ref": "ANZ_DEFAULT", "version": 3 },
61            "items": [
62              { "orderItemRef": "OI-1", "productRef": "SKU-BEA-1042", "productName": "Hydra-Glow Vitamin C Serum 30ml", "quantity": 5 },
63              { "orderItemRef": "OI-2", "productRef": "SKU-FAS-7781", "productName": "Merino Wool Crew Knit - Charcoal (M)", "quantity": 3 },
64              { "orderItemRef": "OI-3", "productRef": "SKU-PHA-3305", "productName": "Paracetamol 500mg Tablets - 24 Pack", "quantity": 2 }
65            ],
66            "strategies": [
67              {
68                "strategyRef": "a1c4f6e2-8d7b-4e39-b0a2-6c9f1d3e5a72",
69                "status": "SKIPPED",
70                "evaluatedOn": "2026-08-17T09:30:00.000+00:00",
71                "locationCount": 0,
72                "conditions": [ { "p": false, "a": "STANDARD" } ],
73                "locations": [],
74                "fulfilments": []
75              },
76              {
77                "strategyRef": "d4b0e9a7-1c62-4f8d-a3b5-7e9c0d2f4a13",
78                "status": "EVALUATED",
79                "evaluatedOn": "2026-08-17T09:30:00.000+00:00",
80                "locationCount": 2,
81                "conditions": [ { "p": true, "a": "NSW" } ],
82                "locations": [],
83                "fulfilments": []
84              }
85            ]
86          }
87        }
88      ],
89      "pageInfo": { "hasNextPage": false, "hasPreviousPage": false }
90    }
91  }
92}

Language: json

Name: Sample response for sourcingAudits

Description:

The full read for one Order. The Order was sourced in two passes, so `sourcingAudits` returns two records, newest-first. 1. The initial `PRIMARY` audit is `NOT_SOURCED` - its first Strategy was skipped (an express-only Condition failed) and its second Strategy was evaluated but produced no Fulfillments, so neither carries per-Location detail. 2. The subsequent `FALLBACK` audit (the record written by the mutation above) is `PARTIALLY_SOURCED` - its evaluated Strategy ranked two candidate Locations and fulfilled the Order from the best-ranked one, leaving one Item short. Per-Location detail (ranked candidates with their `criteria` scores and `missingItemQuantities`) appears only on the evaluated Strategy that produced the Fulfillments.Timestamps are returned in offset format and each `cursor` is an opaque Base64 token.

Selected Location Position

Within each returned Strategy, `locations` are ordered by rank (best first), so the selected Location is typically at `selectedLocationPosition: 0`.

Sourcing Auditability GraphQL API Overview

Overview

Key points

What is the Sourcing Auditability GraphQL API for?

How the API Works

Data Model

Entities

Relationship Details

Condition and Criteria Results

Operations

Permissions

Mutation

Example

Query

Inputs

Example

Related content

Sourcing Auditability Overview

Responsive Sourcing Framework Overview

How Sourcing Utilities work

How Sourcing Profile GraphQL API works

GraphQL Query Limits

Kirill Gaiduk

Contributors:

Building Blocks

By Type

Helpful Resources

Quick Links