Job API

Home
Essential Knowledge
By Type
Building Blocks
APIs
Releases

Essential knowledge

Author:

Fluent Commerce

Changed on:

20 Feb 2025

Overview

A Job represents a container that can hold multiple batches. A job stays open until midnight (UTC), where the status will change to CLOSED. All jobs are processed concurrently.

Key points

Overview of each endpoint for Job API
Also provides the common errors and resolutions

Property	Value
URL	`<root_url>/api/v4.1/job`
Methods	`GET` , `POST`
Scheme	`https`
Auth	`OAUTH`
Permissions	`JOB_VIEW, BATCH_VIEW`
Content-Type	`application/json`

Retailer Batch

The Retailer Batch is used to create new Retailers within a Fluent Order Management Account. This can be used when a new retail operation is being onboarded to an existing Fluent Account or during the initial setup of the Fluent Account to create all the required Retailers.

Inventory Batch

The Inventory Batch is designed to send large volumes of inventory data, primarily to update the Last On Hand inventory quantities for inventory positions. While its primary purpose is to handle large-scale inventory updates and ensure the OMS reflects the latest inventory levels after a few days of operations, it is flexible enough to support other inventory types as needed, providing adaptability for diverse inventory management scenarios.

Please read How to Submit Inventory Batches for a guide to using the inventory batch.

Operations

[GET] /job/{jobId} Finds Job details by Job Id

Returns the details of the Job filtered by the given Job ID provided on the API.

Authentication

Required

Permissions

JOB_VIEW and BATCH_VIEW permissions are required.

Parameters

Name	Default Value	Multiple?	Description
JobId		❌	The unique Job identifier assigned to the Job

Responses

Response Content-Type:

`application/json`

Code	Description
200	Successful Operation
400	Client Error - Bad Request
401	Authorization Error - Invalid Bearer Token / No permission
403	Authorization Error - Forbidden
404	Client Error - Not Found
500	Server Error

Example:

Request:

`https://<accountId>.sandbox.api.fluentretail.com/api/v4.1/job/{{jobId}}`

1{
2    "jobId": "230",
3    "status": "OPEN",
4    "createdOn": "2023-07-20T12:39:43.912+0000",
5    "batch": [
6        {
7            "batchId": "298",
8            "status": "COMPLETE",
9            "createdOn": "2023-07-20T12:39:43.912+0000"
10        }
11    ]
12}

Language: json

Name: Example Success Response for job with no meta key word

Description:

Example Success Response for job with no meta key word

1{
2    "jobId": "5003488",
3    "status": "OPEN",
4    "batch": [],
5    "createdOn": "2025-02-20T08:23:47.933+00:00",
6    "meta": {
7        "preprocessing": "skip"
8    }
9}

Language: json

Name: Example Success Response with Job which has meta key word set for preprocessing

Description:

Example Success Response with Job which has meta key word set for preprocessing

1{
2    "errors": [
3        {
4            "code": "401",
5            "message": "InvalidInput, Logged in user has no retailer"
6        }
7    ]
8}

Language: json

Name: Example Error Response

Description:

Example Error Response

[POST] /job Creates a job record for storing a series of batches.

Creates a job record for storing a series of batches.

Authentication

Required

Permissions

JOB_VIEW and BATCH_VIEW permissions are required.

Name	Type	Required	Description
name	String	Yes	The name assigned to the Job.
retailerId	String	Yes	The retailer ID for which the Job is created.
meta	Object	No	Optional. Additional metadata for the Job. Currently supports the following key: preprocessing (String) - Values: `"skip"` , true - Description: Indicates whether to use Batch Preprocessing Process (BPP). Note: The behavior of this key is influenced by the `fc.enable.batch.preprocessing` setting.

Responses

Response Content-Type:

`application/json`

Code	Description
200	Successful Operation
400	Client Error - Bad Request
401	Authorization Error - Invalid Bearer Token / No permission
403	Authorization Error - Forbidden
404	Client Error - Not Found
500	Server Error

Example:

Request:

`https://<AccountId>.sandbox.api.fluentretail.com/api/v4.1/job`

1{
2    "name": "NIGHTLYIMPORT",
3    "retailerId": "197",
4       "meta": {
5        "preprocessing": "skip"
6    }
7}

Language: json

Name: Example Request body

Description:

Example Request body

1{
2    "id":"223"
3}

Language: json

Name: Example Success Response

Description:

Example Success Response

1{
2    "errors": [
3        {
4            "code": "401",
5            "message": "InvalidInput, Logged in user has no retailer"
6        }
7    ]
8}

Language: json

Name: Example Error Response

Description:

Example Error Response

Inventory Batch Preprocessing Settings and Behavior in Job API

The

`meta`

object allows for the inclusion of additional metadata when creating a Job. The currently supported key within

`meta`

`preprocessing`

, which can influence whether the Batch Preprocessing Process (BPP) is utilized based on the account's settings.

The behavior of the

`meta.preprocessing`

key is governed by the `fc.enable.batch.preprocessing`
configuration setting. Below is a table outlining the expected behavior:

`fc.enable.batch.preprocessing ` value	`meta.preprocessing` Value	Additional Info in Job Payload	Result
true	"preprocessing": "skip"	BPP should not be used	Do not use BPP
true	"preprocessing": "enabled"	BPP should be used	Use BPP
true	"meta": null or "meta": {}	BPP should be used	Use BPP
true	Omitted or previously created Jobs	BPP should be used	Use BPP
false	Any value	BPP should not be used (overridden)	Do not use BPP

When
`fc.enable.batch.preprocessing`
is
`true`
:
- "preprocessing": "skip"
  - Action: BPP should not be used.
- "preprocessing": "enabled" ( any value other than "skip" )
  - Action: BPP should be used.
- "meta": null or "meta": {}
  - Action: BPP should be used.
- Jobs without
  `meta`
  - Action: BPP should be used.
When
`fc.enable.batch.preprocessing`
is
`false`
:
- Regardless of the
  `meta.preprocessing`
  value (including
  `null`
  or omitted)
  - Action: BPP should not be used.

The fc.enable.batch.preprocessing setting takes precedence over the
```
`meta.preprocessing`
```
value. If fc.enable.batch.preprocessing is set to
```
`FALSE`
```
, BPP will not be used regardless of the
```
`meta.preprocessing`
```
value.
Ensure that when setting
```
`meta.preprocessing`
```
, only the supported values (
```
`"skip"`
```
or
```
`"any value not skip"`
```
) are used to avoid unexpected behavior.
A job-level override will affect only the batches containing inventory data created under the specific job, and this impact will remain in effect until the job expires.

Job Expiry

Understanding when a job expires is essential for managing batch operations effectively. This section outlines the job expiration policy to help you plan your batch submissions accordingly.

Expiration Time: Jobs expire at midnight UTC (00:00 AM UTC) on the day they are created.
Job Creation Time: All job creation timestamps are recorded in Coordinated Universal Time (UTC).

Job Validity Duration:
- Creation Time: Regardless of the time a job is created during the day, it remains open only until midnight UTC of the creation day.
- Example:
  - A job created at 23:46 UTC on October 28th expires at 00:00 UTC on October 29th, remaining open for approximately 14 minutes.
  - A job created at 03:00 UTC on October 28th expires at 00:00 UTC on October 29th, remaining open for nearly 21 hours.
Attempting to Add Batches to Expired Jobs:
- Response Code: If you attempt to add a batch to an expired job, the API will respond with a
```
` 403 Forbidden`
```
  error. At this point, the job moves to CLOSED status. Otherwise, it will continue to be in OPEN status, but you will not be able to add any new batch to it.

Monitor Job Creation Times: Since jobs expire at midnight UTC, plan your job creation times to maximize the window available for batch submissions.
Handle Expiration Errors Gracefully: Implement error handling in your application to manage 403 responses, allowing you to recreate jobs or notify users as necessary.

Job Creation:
- Time: 23:46 UTC on October 28th, 2022
- Expiration Time: 00:00 UTC on October 29th, 2022
Batch Submission Attempt:
- Attempted Time: 00:03 UTC on October 29th, 2022

Outcome: 403 error was returned because the job had expired.

[GET] /job/{jobId}/batch/{batchId} Get Batch Details by Batch Id

Returns the details of the Batch by the given Batch ID provided on the API.

Authentication

Required

Permissions

JOB_VIEW and BATCH_VIEW permissions are required.

Parameters

Name	Default Value	Multiple?	Description
BatchId		❌	The unique Batch identifier assigned to the Batch

Responses

Response Content Type:

`application/json`

Code	Description
200	Successful Operation
400	Client Error - Bad Request
401	Authorization Error - Invalid Bearer Token / No permission
403	Authorization Error - Forbidden
404	Client Error - Not Found
500	Server Error

Example

Request:

`https://<AccountId>.sandbox.api.fluentretail.com/api/v4.1/job/298/batch/433`

1{
2    "batchId": "433",
3    "entityType": "INVENTORY",
4    "status": "COMPLETE",
5    "start": 1,
6    "count": 10,
7    "total": 0,
8    "results": [],
9    "createdOn": "2022-10-14T04:01:06.939+0000"
10}

Language: json

Name: Example Success Response

Description:

Example Success Response

1{
2    "errors": [
3        {
4            "code": "401",
5            "message": "InvalidInput, Logged in user has no retailer"
6        }
7    ]
8}

Language: json

Name: Example Error Response

Description:

Example Error Response

[POST] /job/{jobId}/batch Create a new Batch on the given Job

Creates a new Batch on the given Job.

Authentication

Required

Permissions

JOB_VIEW and BATCH_VIEW permissions are required.

Parameters

Name	Required	Type	Description
*action*	yes	String	The type of operation occurring - "CREATE" or "UPSERT"
entityType	yes	String	The Entity type in the batches - "INVENTORY" or "RETAILER"
entities	yes	JSON array	The entities to be batched - See below for type models

Responses

Response Content-Type:

`application/json`

Code	Description
200	Successful Operation
400	Client Error - Bad Request
401	Authorization Error - Invalid Bearer Token / No permission
403	Authorization Error - Forbidden
404	Client Error - Not Found
500	Server Error

Example

Request:

`https://<AccountId>.sandbox.api.fluentretail.com/api/v4.1/job/298/batch`

1{
2  "action": "UPSERT",
3  "entityType": "INVENTORY",
4  "source": "your-batch-source",
5  "event": "YourCustomEventName", // Optional, defaults to "InventoryChanged"
6  "catalogueRef": "<inventoryCatalogRef>", // Optional, defaults to "DEFAULT:<retailerId>"
7  "entities": [
8    {
9      "locationRef": "LOC1",
10      "skuRef": "SKU1",
11      "qty":40,
12      "correctedQty": 0,
13      "type": "PURCHASE_ORDER", // Optional
14      "ref": "SKU1:LOC1:FUTURE", // Optional
15      "status": "ACTIVE", // Optional
16      "retailerId": <retailerId>,
17      "attributes": {      // Optional
18        "expectedOn": "2024-11-30T00:00:00.00Z", // Optional
19        "storageAreaRef": "LOC1-SR2", // Optional
20        "condition": "NEWWEBHOOK" // Optional
21      }
22    }
23    // Additional entities can be included here
24  ]
25}

Language: json

Name: Example Request Body

Description:

Example Request Body

1{
2    "id":"433"
3}

Language: json

Name: Example Success Response

Description:

Example Success Response

1{
2    "errors": [
3        {
4            "code": "401",
5            "message": "InvalidInput, Logged in user has no retailer"
6        }
7    ]
8}

Language: json

Name: Example Error Response

Description:

Example Error Response

Models

Job Model

Key	Type	Mandatory?	Possible Values	Constraints	Description
name	String	✅			A User provided name by which to identify the job
retailerId	String	❌			The retailer identifier assigned by Fluent Commerce
jobId	String	❌			The unique identifier assigned to the Job
status	String	✅	OPEN, CLOSED		The location status
createdOn	DateTime	✅			The Date/time when the Job was created
batch	Array [batchId(integer), status(string), createdOn(DateTime)]	✅	Batch Status - COMPLETE, RUNNING, PENDING		Provides list of batches assigned to the Job . Array includes Unique batch identifier(batchId), The batch status and Date/time when the Batch was created

Error Model

Key	Type	Possible Values	Description
errors	Array		List of errors
code	String	400, 401, 403, 404, 500	error code
message	String		description of the error

Common errors and resolutions

Response Code	Message	Resolution
401	"Expired JWT"	The Authorization token has expired, generate a new token and send the request again
403	"Job is already completed"	The specific Job has expired, please generate a new Job ID and send the batch again

Job API

Overview

Key points

Retailer Batch

Inventory Batch

Operations

[GET] /job/{jobId} Finds Job details by Job Id

[POST] /job Creates a job record for storing a series of batches.

[POST] /job/{jobId}/batch Create a new Batch on the given Job

Models

Job Model

Error Model

Common errors and resolutions

Fluent Commerce

Building Blocks

By Type

Helpful Resources

Quick Links