Predictive Inventory Management Service

The Predictive Inventory Management Service enables API callers to generate stock replenishment proposals based on historical data which includes supplier orders and customer orders.

From a business perspective, replenishment proposals are relevant for distribution businesses that order stock from suppliers, on one hand, and honour orders from customers, on the other hand.

Access info

Usage

Prerequisites

• The organization(s) for which reporting is done must exist in the SBS system. You can add new organizations either from the Organizations UI or programmatically from the Organizations Service.
• Several CSV files are required as input to the Predictive Inventory Management service. It is assumed that you are generating them from your ERP or similar system. For the structure of the input files, see Appendix 1: Input structure.

Generating a replenishment proposal

To generate a replenishment proposal:

1. Obtain from your ERP system the input CSV files to be used as input. For the structure of each file, see Appendix 1: Input structure.
2. Create a new replenishment proposal by calling the createReplenishmentProposal mutation. You must supply as input argument, at the minimum, the target month, in the format YYYY-MM. As a result, a new replenishment proposal object is created, and the response contains the unique proposal ID. You will need to work with this ID in subsequent steps to further process the proposal and monitor its status.
3. Add all the input CSV files to the proposal. See Preparing input files.
4. Run the computeReplenishmentProposal mutation. This triggers a computation that takes place from several minutes to several hours, depending on the size of input CSV files.

The outcome of computing a proposal, including any possible errors, is reported in the Process object when querying the respective proposal. If the computation was successful, the process includes one or more of the following attributes:

• productCentricResult - This is the default result and it is always present. It contains, among other attributes, the name and download URL of the output file, with computation results grouped by product. For the structure of the output file, see Appendix 2: Output structure.
• customerCentricResult - This result is present if the proposal was created with the input parameter splitByCustomer = true. The result has the same structure as above, except that data inside the output file are grouped by customer.
• industryCentricResult - This result is present if the proposal was created with the input parameter splitByIndustry = true. The result has the same structure as above, except that data inside the output file are grouped by industry code.
• optimalServiceLevels - This result is present if the proposal was created with the input parameter computeAnalysisData = true. For the structure of the file, see Appendix 2: Output structure.

Preparing input files

After you have created a replenishment proposal, you can add all the CSV input files to it.

For each input CSV file, the steps are as follows:

1. Run the prepareFile mutation, for example:

mutation prepareFile($replenishmentProposalId:ID!, $input:PrepareFileInput!) {
  prepareFile(replenishmentProposalId:$replenishmentProposalId, input:$input) {
    id
    fileType
    name
    contentLength
    uploadUrl
    downloadUrl
    createdAt
  }
}

{
    "replenishmentProposalId": "YOUR_REPLENISHMENT_PROPOSAL_ID",
    "input": {
        "fileType": "CustomerOrders",
        "name": "customer-orders.csv"
    }
}

In the response, you get the file’s upload URL at which you can upload the actual file.

2. In the programming language of your API, make an HTTP PUT request to upload the file content to the upload URL. This step is similar to how you would create a file and then upload its content in the File Management Service, as described in the Tutorial: Create a file.

Note that you can add multiple files of the same type for the same replenishment proposal. For example, you can add several input CSV files of type “CustomerOrders”. If multiple files of the same type exist, SBS will aggregate and compute data found in all respective files.

After adding all the CSV files, you can check if they are indeed attached to the replenishment proposal by running the replenishmentProposal query, for example:

query ReplenishmentProposal ($id:ID! $fileId:ID, $processId:ID) {
  replenishmentProposal(id:$id) {
    id
    organizationId
    files(id: $fileId) {
        id fileType name contentLength uploadUrl downloadUrl createdAt
    }
    createdAt
  }
}

{
   "id": "YOUR_REPLENISHMENT_PROPOSAL_ID"
}

If your replenishment proposal looks good so far, you can proceed to running the computeReplenishmentProposal mutation, for example:

mutation ComputeReplenishmentProposal ($id:ID!) {
  computeReplenishmentProposal(id:$id) {
    id 
    status
    dataRange { from to } 
    targetMonth
    errorMessages
    createdAt
  }
}

{
   "id": "YOUR_REPLENISHMENT_PROPOSAL_ID"
}

Dealing with large input files

As mentioned above, when you add a file to the replenishment proposal, there are two steps involved:

1. Run prepareFile and obtain the upload URL.
2. In the programming language of your API, make an HTTP PUT request to upload the file content to the upload URL.

For the second step, note, however, that the maximum file size that you can send in a single PUT request is 5 GB. Should you need to add larger files to the replenishment proposal, you can do so through the multipart upload mutations provided by the File Management Service. In this scenario, the process looks as follows:

1. Run prepareFile and take notice the data.prepareFile.id returned in the response body. This ID corresponds to a file id of a file in File Management Service.
2. Provide the id above as input to the initiateMultipartUpload mutation and continue with the rest of steps required for multipart upload, as described in Uploading large files.

Processes

Each time when you run computeReplenishmentProposal, a new process with status NEW is attached to the replenishment proposal. You can view the proposal and the status of all its processes by running the replenishmentProposal query and requesting the processes field in the response, for example:

query ReplenishmentProposal ($id:ID! $fileId:ID, $processId:ID) {
  replenishmentProposal(id:$id) {
    id
    organizationId
    targetMonth
    splitByCustomer
    splitByIndustry
    files (id: $fileId) {
        id fileType name contentLength uploadUrl downloadUrl createdAt
    }
    processes (id: $processId) { 
        id 
        status
        dataRange { from to } 
        targetMonth
        errorMessages 
        productCentricResult { id name contentLength createdAt downloadUrl }
        customerCentricResult { id name contentLength createdAt downloadUrl }
        industryCentricResult { id name contentLength createdAt downloadUrl }
        totals {
           csvLines { customerOrders supplierOrders allFileLines }
        }
        createdAt
    }
    createdAt
  }
}

{
   "id": "YOUR_REPLENISHMENT_PROPOSAL_ID"
}

The status of any process is initially NEW. The status NEW will normally change to INPROCESS after approximately 1 minute. Note that, if you run computeReplenishmentProposal multiple times for the same proposal, each run will start a new process. In this case, you will need to track the status of each process separately. The processes field of the replenishmentProposal query provides a filter (by process ID) for that purpose.

The INPROCESS status of a process may take from a few minutes to a few hours, depending on the size of the input CSV files. After the INPROCESS status, the status may change to either ERROR (if errors are encountered) or DONE (upon successful processing).

If the status ERROR is encountered, check the errorMessages response field of the respective process for details.

If the process completes with status DONE, it generates 1-4 CSV output files. As mentioned previously, the number of files depends on the input parameters supplied at proposal creation time to the createReplenishmentProposal mutation.

If necessary, you may stop a running process through a call to killProcess. This is possible only while the process has not produced any results.

You may also delete a process through the deleteProcess mutation. You cannot delete a running process. Stop it first with killProcess.

Deleting replenishment proposals

You can delete replenishment proposals through a call to deleteReplenishmentProposal. Note, however, that it is not possible to delete a replenishment proposal if it has at least one running process that has already generated some result file. To delete such a proposal, you will need to wait for the process to finish first.

Webhooks

The Predictive Inventory Management Service supports webhooks. This means you can optionally configure SBS to send an HTTP POST request to an external server or application whenever any of the following events occur:

• COMPUTATION_SUCCESS - fires whenever a replenishment proposal computation finishes successfully.
• COMPUTATION_ERROR - fires when a replenishment proposal computation finishes with error.

The payload of each POST request includes the identifier of the replenishment proposal and the identifier of the process, for example:

The POST request of the COMPUTATION_SUCCESS event has the following payload:

{
    "service": "predictive-inventory-management-api",
    "event": "COMPUTATION_SUCCESS",
    "tenantId": "<your-tenant-id>",
    "payload": {
        "organizationId": "<your-organization-id>",
        "replenishmentProposalId": "<your-proposal-id>",
        "processId": "<your-process-id>"
    },
    "customKey1": "Custom value 1",
    "customKey2": "Custom value 2"
}

The POST request of the COMPUTATION_ERROR event has the following payload:

{
    "service": "predictive-inventory-management-api",
    "event": "COMPUTATION_ERROR",
    "tenantId": "<your-tenant-id>",
    "payload": {
        "organizationId": "<your-organization-id>",
        "replenishmentProposalId": "<your-proposal-id>",
        "processId": "<your-process-id>"
    },
    "customKey1": "Custom value 1",
    "customKey2": "Custom value 2"
}

Note that the custom keys (such as customKey1 and customKey2 above) will be present in the request body only if you configured them when creating the webhook. You may configure as many key-value pairs as required.

For information about configuring webhooks, see Webhooks.

Queries

analysisData

For a given process, this query returns replenishment proposal analysis data. Before you run this query, make sure to compute a replenishment proposal first, and set the computeAnalysisData input parameter to true. To view the results graphically as a chart, run the analysisDataViewerUrl query.

Arguments

Result

AnalysisData type

ProductsResult type

ProductEntry type

A lightweight projection of a product, used by the paginated products field. To retrieve the full detail of a single product, query the product(id) field on AnalysisData, which returns the Product type.

PerformanceResult type

GlobalScores type

Aggregated, replenishment-proposal-wide performance and coverage scores.

Customer type

Industry type

Diagnostic type

PerformanceEntry type

Product type

OptimalServiceLevel type

MonthlyDemand type

MonthlyForecast type

SplitFilter input

Kpi type

SupplierLeadTime type

CustomerLeadTime type

RealStock type

SimulatedStock type

SimulatedPlot type

analysisDataViewerUrl

Returns a URL for viewing analysis data generated by a process.

Arguments

Result

The result is a URL having the Uri type.

organizations

Returns a list of active organizations defined for the given tenant.

Result

The result is an array of Organization.

Organization type

replenishmentProposals

Returns the list of replenishment proposals for the organization ID supplied as input.

Arguments

ReplenishmentProposalsFilter input

DateFilter input

Result

The result is an array of objects of type ReplenishmentProposal.

Example

query ReplenishmentProposals ($organizationId:ID!, $filter:ReplenishmentProposalsFilter, $fileId:ID, $processId:ID) {
  replenishmentProposals(organizationId:$organizationId, filter:$filter) {
    id
    organizationId
    targetMonth
    splitByCustomer
    splitByIndustry
    files (id: $fileId) {
        id fileType name contentLength uploadUrl downloadUrl createdAt
    }
    processes (id: $processId) { 
        id 
        status
        dataRange { from to } 
        targetMonth
        errorMessages 
        productCentricResult { id name contentLength createdAt downloadUrl }
        customerCentricResult { id name contentLength createdAt downloadUrl }
        industryCentricResult { id name contentLength createdAt downloadUrl }
        totals {
           csvLines { customerOrders supplierOrders allFileLines }
        }
        createdAt
    }
    createdAt
  }
}

{
    "organizationId": "YOUR_ORGANIZATION_ID",
    "filter": {
        "createdAt": {
            "from": "2025-01-01",
            "to": "2025-12-31"
        }
    }
}

replenishmentProposal

Retrieves a single replenishment proposal by ID.

Arguments

Result

See the ReplenishmentProposal type.

version

Returns the API version.

Result

The result is of type String.

Mutations

computeReplenishmentProposal

Starts a process that computes a replenishment proposal, based on its current input data. Running this mutation will start a new process on each run.

Arguments

Result

See the Process type.

createReplenishmentProposal

Creates a replenishment proposal.

Arguments

CreateReplenishmentProposalInput input

Result

ReplenishmentProposal type

SupplierOrdersIntervalType enum

File type

Process type

DataRange type

ResultFile type

Totals type

CsvFileLines type

deleteFile

Deletes a previously uploaded CSV file.

Arguments

Result

DeletedFile type

deleteProcess

Deletes a computation process and the result files.

Arguments

Result

See the Process type.

deleteReplenishmentProposal

Deletes a replenishment proposal, including all its input and output files and processes.

Arguments

Result

See the ReplenishmentProposal type.

Example

mutation DeleteReplenishmentProposal ($id:ID!) {
  deleteReplenishmentProposal(id:$id) {
    id
  }
}

{
  "id": "YOUR_REPLENISHMENT_PROPOSAL_ID"
}

killProcess

Stops a running computation process.

Arguments

Result

See the Process type.

prepareFile

Generates a URL at which you can upload a CSV file to be used as input to the computation. Run this mutation for each CSV file that is to be supplied as input for a replenishment proposal.

Arguments

PrepareFileInput input

Result

See the File type.

Error codes

See Conventions for the error format and the codes shared across all services. This service can also return the codes listed below, grouped by the object they concern. The Returned by column names the operations and fields that report each code.

Replenishment proposals

Organizations

Processes

Input files

Files

Analysis data

Formats and access

A malformed value is rejected with the same code whether you pass it as a variable or write it into the operation text.

AI agent access (MCP)

The service serves its queries as tools to AI agent clients over the Model Context Protocol (MCP), a JSON-RPC 2.0 protocol through which a client reads a catalog of tools and calls them by name. Agent clients such as Claude Code connect to https://predictive-inventory-management-api.socrate.io/mcp.

Access

The MCP endpoint is on the same host as the GraphQL endpoint and accepts the same credentials:

• A tenant-level service access key, in the x-api-key header.
• A service access token, in the Authorization header as Bearer YOUR_SERVICE_ACCESS_TOKEN.

The endpoint speaks protocol revision 2026-07-28 and accepts protocol requests as POST only. It is stateless: every request carries its own credentials, and there is no handshake or session to open first. Your agent client must support revision 2026-07-28.

For connection instructions, open https://predictive-inventory-management-api.socrate.io/mcp in a browser. The page needs no credential.

Tools

The catalog holds one tool per query of this service:

The optional arguments of each query (filter, expiresIn) are optional arguments of its tool.

The catalog a caller receives lists only the tools whose query the scope of its key or token allows. If a service access denial blocks a query, your agent does not see a tool for it. A tool call runs the query under the caller’s own credentials and returns the data that the equivalent GraphQL query returns for that caller. Every tool is marked read-only (readOnlyHint is true), and answers from SBS alone, without calling any system outside SBS (openWorldHint is false).

Optional result fields

By default, a tool returns compact records. You request the remaining fields by naming their paths in the tool’s optional include argument:

• Replenishment proposals. Without include, replenishmentProposals and replenishmentProposal return each proposal’s own fields, such as id, targetMonth, and createdAt. Input files, processes, the messages and logs of a process, the result files of a process, and download URLs are returned only when named.
• Analysis data. Without include, analysisData returns the run’s headline fields, dataRange, globalScores, and the first page of products and of performance, each with its items and nextToken. The lists warnings, analyticsLog, customers, industries, and diagnostics are returned only when named.

A path is a sequence of field names separated by dots. Naming a path returns that field with its default content. Naming a path inside an optional field returns only that inner field: include: ["files.downloadUrl"] returns each file’s downloadUrl without its id or name. To receive the input files together with their download URLs, name both paths: include: ["files", "files.downloadUrl"].

No tool returns file upload URLs.

Proposal include values

The replenishmentProposals and replenishmentProposal tools accept these values:

Large results

The diagnostics of a large run can exceed the size limit of a tool result. In that case, an analysisData call that names diagnostics fails with a message that states the limit. The analysisData tool returns the first page of products and of performance. To read a large run in full, request the following pages through the analysisData GraphQL query with nextToken, or open the run in the viewer whose URL the analysisDataViewerUrl tool returns.

Documentation resources

Besides its tools, the endpoint publishes, as addresses, this page and the API conventions page.

Connecting an agent client

To add the endpoint to Claude Code, run:

claude mcp add --transport http predictive-inventory-management https://predictive-inventory-management-api.socrate.io/mcp --header "x-api-key: YOUR_ACCESS_KEY"

Other agent clients take the same URL and header in their own configuration.

Example

An agent client builds the protocol requests for you. To call a tool directly over HTTP, send a POST request that names the protocol revision both in the MCP-Protocol-Version header and in the request’s _meta, the method in the Mcp-Method header, and, for a tool call, the tool in the Mcp-Name header:

POST /mcp HTTP/1.1
Host: predictive-inventory-management-api.socrate.io
Content-Type: application/json
Accept: application/json
x-api-key: YOUR_ACCESS_KEY
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: replenishmentProposal

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {}
    },
    "name": "replenishmentProposal",
    "arguments": {
      "id": "YOUR_PROPOSAL_ID",
      "include": ["files", "files.downloadUrl"]
    }
  }
}

The proposal is returned in structuredContent, and as the same JSON text in content. The response below is shortened to one input file:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resultType": "complete",
    "content": [
      { "type": "text", "text": "{\"id\":\"YOUR_PROPOSAL_ID\", ...}" }
    ],
    "structuredContent": {
      "id": "YOUR_PROPOSAL_ID",
      "organizationId": "YOUR_ORGANIZATION_ID",
      "targetMonth": "2026-10",
      "backdatedTargetMonth": "2025-10",
      "splitByCustomer": false,
      "splitByIndustry": false,
      "computeAnalysisData": true,
      "demandCoverageType": "Calendar",
      "supplierOrdersInterval": 1,
      "supplierOrdersIntervalType": "Explicit",
      "monthsAheadSmoothing": 1,
      "leadTimeRecency": 12,
      "supplierOrderReceptionDays": 1,
      "imputeMissingSales": false,
      "supplyLeadTimeOffset": 0,
      "files": [
        {
          "id": "YOUR_FILE_ID",
          "fileType": "Stock",
          "name": "Stock.csv",
          "contentLength": 14839,
          "downloadUrl": "YOUR_DOWNLOAD_URL",
          "createdAt": "2026-10-07T06:10:13.189Z"
        }
      ],
      "createdAt": "2026-10-07T06:08:56.352Z"
    }
  }
}

Appendix 1: Input structure

To compute a minimal replenishment proposal (without analysis data or optimal service levels), the following CSV files are accepted as input:

1. MasterParameters.csv (required)
2. CustomerOrders.csv (required)
3. SupplierOrders.csv (required)
4. Receptions.csv (required)
5. Stock.csv (optional, required only if imputeMissingSales = true)

To compute a replenishment proposal with analysis data or optimal service levels, the following files are accepted as input:

1. MasterParameters.csv (required) - This file ensures that the analysis data charts operate with human-readable product names and codes in addition to product IDs.
2. CustomerOrders.csv (required)
3. SupplierOrders.csv (required)
4. Deliveries.csv (required)
5. Receptions.csv (required)
6. Stock.csv (required)

You may supply multiple files of the same type as input as long as they follow the structure described below. Note the following:

• Each CSV file is comma-separated.
• The first row of each CSV file is the header row. It must name every column listed in that file’s table below, spelled exactly as shown and in the same order. A file with a missing, extra, renamed, or reordered column is rejected when the replenishment proposal is computed: the process ends with status ERROR.

The Requirement column of each table applies to the cell values, not to the column. Every column is present in the header row, whatever its requirement:

• Mandatory: every row has a value.
• Optional: the cell may be empty.
• Conditional: the cell is required only in the situation that the column’s description names.

The following sections describe the structure of all input files.

CustomerOrders.csv

SupplierOrders.csv

Deliveries.csv

Receptions.csv

Stock.csv

MasterParameters.csv

The header row must list exactly the columns below, in this order. A file whose header omits a column is rejected.

Appendix 2: Output structure

The result of computing a replenishment proposal is 1-4 CSV files, depending on the input parameters you specified when creating the proposal.

1. product_centric.csv - this file is created if you did not set splitByCustomer = true or splitByIndustry = true. It contains results grouped by product.
2. customer_centric.csv - this file is created only if you created the replenishment proposal with the option splitByCustomer = true; it contains results grouped by customer ID.
3. industry_centric.csv - this file is created only if you created the replenishment proposal with the option splitByIndustry = true; it contains results grouped by industry ID.
4. optimal_service_level.csv - this file is created only if you created the replenishment proposal with the option computeAnalysisData = true.

The following sections describe the structure of all output files.

product_centric.csv

customer_centric.csv

This file has the same structure as product_centric.csv, with results grouped by the customer_id column.

industry_centric.csv

This file has the same structure as product_centric.csv, with results grouped by the industry_code_id column.

optimal_service_levels.csv