Create a new Inventory Feed via GraphQL API

Get Started
Functionality
Learning
Extension
Dev Tooling
APIs
Releases

How-to Guide

Author:

Fluent Commerce

Changed on:

1 July 2025

Key Points

After following this guide a user will be able to create a new Inventory Feed
The output from this feed can be used to supply inventory availability data to any system
Additional steps will outline optional configuration that can be applied to Inventory Feeds

Steps

Assumptions

This guide assumes the destination S3 bucket has already been created.

Important Callout on Destination S3 Bucket!

Region RestrictionThe destination S3 bucket for your feed must be located in the same AWS Region as the Fluent-managed source bucket. Pointing a feed to a destination S3 bucket in a different Region will result in an exception (`IllegalLocationConstraintException`)Available Options:

Cross-Region Access: Keep your feed files in the source Region and configure your jobs (e.g., Lambda, Glue) so they can be read directly from that location.
Self-Managed Replication: Set up S3 Cross-Region Replication (CRR) to automatically copy new objects from the source Region bucket to a bucket in your desired Region.

It is not necessary to recreate destination S3 buckets when activating or deactivating inventory feeds. The same destination S3 bucket can be used for multiple inventory feeds, making it crucial not to delete the S3 bucket on the destination side unless absolutely required.

Required Steps

A few steps must occur in a specific order to create and enable an Inventory Feed. The feed will not be enabled if steps are skipped or not completed correctly.

Create and configure Inventory Feed

Inventory Feeds are currently created via API. The GraphQL API mutation to do this is createInventoryFeed. See GraphQL API schema for details of the required data for that mutation. When successful, the creation event will respond with a value to add as an S3 Bucket Policy. This value will allow the data to be replicated into your target bucket.

Initial Status

Inventory Feeds will always be set to the status “CREATED” after step one. Once activated with the correct S3 bucket policies applied the feed can be set to “ACTIVE”.

Required Data

Field	Description	Type
ref	Unique reference for the Inventory Feed	String
source	Target source and filters to apply when generating data for Inventory Feed	InventorySourceInput
destination	Target AWS S3 bucket destination for Inventory Feed	InventoryDestinationInput

InventorySourceInput

The `source` field consists of:

type (InventoryDataType!): The type of inventory data. You can choose from:
- `INVENTORY_CATALOGUE`
- `INVENTORY_POSITION`
- `VIRTUAL_CATALOGUE`
- `VIRTUAL_POSITION`
filters ([InventoryDataFilterInput]): Optional filters to apply to the inventory data. Each filter consists of:
- name (InventoryFilterName!): The name of the filter. You can choose from:
  - `REF`
  - `TYPE`
  - `STATUS`
  - `CATALOGUE_REF`
- operator (InventoryOperator!): The operator for the filter. You can choose from:
  - `IN`
  - `NOT_IN`
  - `EQUAL_TO`
  - `NOT_EQUAL_TO`
- value (Json!): The value to filter by. This can be a single value or an array of values.

How Filters Work

When setting up filters, you first select an inventory data type and then optionally set filters based on that data type. Filters are combined using "AND" conditions, meaning all conditions must be met. Within each filter, "IN" and "NOT IN" operators can handle multiple values with an "OR" condition.

Examples

INVENTORY_POSITION Example

If you select `INVENTORY_POSITION` as the inventory data type and apply the following filters:

STATUS EQUAL_TO "ACTIVE"
CATALOGUE_REF IN ["DEFAULT:1", "DEFAULT:67"]

This setup means:

Fetch all inventory positions where the status is equal to "ACTIVE"
AND the catalogue reference is either "DEFAULT:1" or "DEFAULT:67"

VIRTUAL_POSITION Example

If you select `VIRTUAL_POSITION` as the inventory data type and apply the following filters:

STATUS EQUAL_TO "AT_RISK"
CATALOGUE_REF IN ["BASE:1", "AGGREGATE:1"]

This setup means:

Fetch all virtual positions where the status is equal to "AT_RISK"
AND the catalogue reference is either "BASE:1" or "AGGREGATE:1"

Example Mutation

1mutation {
2  createInventoryFeed(
3    input: {
4      ref: "Example_Inventory_Feed"
5      dataFormat: PARQUET
6      destination: {
7        type: AWS_S3
8        destinationAttributes: [
9          { key: AWS_ACCOUNT_ID, value: "AWS account ID" }
10          { key: AWS_S3_BUCKET_NAME, value: "Target S3 bucket name" }
11        ]
12      }
13      source: {
14        type: INVENTORY_POSITION
15        filters: [
16          {name: STATUS, operator: EQUAL_TO, value: "ACTIVE"}
17        ]
18      }
19    }
20  ) {
21    ref
22    dataFormat
23    destination {
24      type
25      destinationAttributes {
26        key
27        value
28      }
29    }
30    source  {
31      type
32      filters{
33        name
34        operator
35        value
36      }
37    }
38    attributes{
39      name
40      value
41    }
42  }
43}

Example Response

1{
2  "data": {
3    "createInventoryFeed": {
4      "ref": "Example_Inventory_Feed",
5      "dataFormat": "PARQUET",
6      "destination": {
7        "type": "AWS_S3",
8        "destinationAttributes": [
9          {
10            "key": "AWS_ACCOUNT_ID",
11            "value": "889803876844"
12          },
13          {
14            "key": "AWS account ID",
15            "value": "Target S3 bucket name"
16          }
17        ]
18      },
19      "source": {
20        "type": "INVENTORY_POSITION",
21        "filters": [
22          {
23            "name": "STATUS",
24            "operator": "EQUAL_TO",
25            "value": "ACTIVE"
26          }
27        ]
28      },
29      "attributes": [
30        {
31          "name": "roleArn",
32          "value": "arn:aws:iam::{source AWS account ID}:role/service-role/{IAM role name}"
33        }
34      ]
35    }
36  }
37}

Add security policy to target S3 bucket

You can add the new security policy to your target S3 bucket by following this guide from AWS: Adding a bucket policy by using the Amazon S3 console - Amazon Simple Storage Service.Once this new policy has been applied, the data produced from the Inventory Feed will be replicated into the target S3 bucket as soon as there is a new piece of data produced by the Inventory feed.

Example Policy

1{
2  "Version": "2012-10-17",
3  "Id": "",
4  "Statement": [
5    {
6      "Sid": "Set permissions for objects",
7      "Effect": "Allow",
8      "Principal": {
9        "AWS": "arn:aws:iam::{SourceAccountId}:role/service-role/{RoleName}"
10      },
11      "Action": [
12        "s3:ReplicateObject",
13        "s3:ReplicateDelete"
14      ],
15      "Resource": "arn:aws:s3:::{DestinationBucketName}/*"
16    },
17    {
18      "Sid": "Set permissions on bucket",
19      "Effect": "Allow",
20      "Principal": {
21        "AWS": "arn:aws:iam::{SourceAccountId}:role/service-role/{RoleName}"
22      },
23      "Action": [
24        "s3:List*",
25        "s3:GetBucketVersioning",
26        "s3:PutBucketVersioning"
27      ],
28      "Resource": "arn:aws:s3:::{DestinationBucketName}"
29    }
30  ]
31}

Update inventory feed to Active

After correctly creating the Inventory Feed and configuring the bucket policy on the target S3 bucket, you can update the Inventory Feed to “ACTIVE”. From this point, the Inventory Feed will begin running on the schedule as defined against the entity.

Validation

When setting a feed to “ACTIVE” we validate everything is set correctly. If this update fails see How to Troubleshoot Inventory Feeds

Example mutation

1mutation{
2    updateInventoryFeed(input: {
3  	    ref: "Example_Inventory_Feed",
4        status: "ACTIVE"
5    }) {
6        ref
7        status
8    }
9}

Optional Configuration

Additionally, there is a range of optional configurations available for Inventory Feeds.

Optional Data

Field	Description	Type
name	Human readable name to describe the Inventory Feed	String
dataFormat	Output format for Inventory Feed	InventoryDataFormat
frequencyCronExpression	Frequency for how often a specific Inventory Feed should run (follows the UNIX Cron standard)	String

Example Mutation

1mutation {
2  createInventoryFeed(
3    input: {
4      ref: "Example_Inventory_Feed"
5      name: "Example Inventory Feed"
6      destination: {
7        type: AWS_S3
8        destinationAttributes: [
9          { key: AWS_ACCOUNT_ID, value: "AWS account ID" }
10          { key: AWS_S3_BUCKET_NAME, value: "Target S3 bucket name" }
11        ]
12      }
13      source: {
14        type: VIRTUAL_POSITION
15        filters: [
16          {name: STATUS, operator: EQUAL_TO, value: "ACTIVE"}
17        ]
18      }
19      dataFormat: PARQUET
20      frequencyCronExpression: "0 13 * * */2"
21    }
22  ) {
23    ref
24    name
25    destination {
26      type
27      destinationAttributes {
28        key
29        value
30      }
31    }
32    source  {
33      type
34      filters{
35        name
36        operator
37        value
38      }
39    }
40    attributes{
41      name
42      value
43    }
44    dataFormat
45    frequencyCronExpression
46  }
47}
48

Create a new Inventory Feed via GraphQL API

Key Points

Steps

Create and configure Inventory Feed

Required Data

InventorySourceInput

How Filters Work

Examples

INVENTORY_POSITION Example

VIRTUAL_POSITION Example

Example Mutation

Example Response

Add security policy to target S3 bucket

Example Policy

Update inventory feed to Active

Example mutation

Optional Data

Example Mutation

Fluent Commerce

Building Blocks

By Type

Helpful Resources

Quick Links