Availability Service

Download OpenAPI specification:Download

Emporix: documentation@emporix.com URL: https://emporix.com

Manage the availability and physical location of a product.

Key Features:

  • Availability and stock at hand of a product in a physical location
  • Manage the exact location of products inside a warehouse / store - zones, rack, shelf, bin
  • Search for a products location in a physical place
  • Availability of a product on either a virtual site (website, mobile site) or physical site (warehouse, store)
  • Stock levels of products at a site
  • The physical location of a product - such as a rack, shelf, or bin - to, for example, guide packers to it

Key Benefits:

  • Turn stores into mini DCs
  • Enable Click & Collect from a store
  • Run dark stores or fulfillment from a warehouse
  • Use location information to optimize the pick-pack process
  • Use stock level information in local stores to feed Google Search and other digital product discovery services
  • Understand availability in different locations
  • Provide buyers with stock information before they buy
  • Show stock levels / availability based on stores, e.g. nearby to a customer
  • Offer customers accurate information about the availability of a product in a store, for example when a customer chooses Click & Collect

Locations

Retrieving all locations for a site

Retrieves all locations for a specified site.

Required scopes

  • availability.availability_view
SecurityOAuth2
Request
path Parameters
tenant
required
string

Your Emporix tenant's name.

Note: The tenant name should always be provided in lowercase.

Example: testtenant
site
required
string

Site code, defined when the site is created.

Example: shop1
Responses
200

The request was successful. A list of locations is returned.

400

The request was syntactically incorrect. Details are provided in the response.

401

The authorization token is invalid or has expired. Details are provided in the response.

403

Provided authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

The requested resource was not found.

500

Some server-side error occurred. Details are provided in the response.

get/{tenant}/locations/{site}
Request samples 
Response samples 
application/json
[
  • {
    }
]
Adding a new location to a site
Adds a new location to a specified site.




Required scopes


    

  • availability.availability_manage
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant name should always be provided in lowercase.


 
 Example:  testtenant
site
required
string
Site code, defined when the site is created.


 
 Example:  shop1
Request Body schema: application/json
id
required
string
Unique identifier of the location. 


Note: The value should be provided in the site:rack format.


 
site
required
string
Site code, defined when the site is created. The value should match the site query/path parameter value.


 
rack
string
Rack number.


 
rackName
string
Name of the rack.


 
order
required
number  >= 0 
Order of the location, expressed as a number.


 
Responses 
201
 The request was successful. The location has been added to the site.


400
The request was syntactically incorrect. Details are provided in the response.


401
The authorization token is invalid or has expired. Details are provided in the response.


403
Provided authorization scopes are not sufficient and do not match scopes required by the endpoint.


409
Resource already exists.


500
Some server-side error occurred. Details are provided in the response.


post/{tenant}/locations/{site}
Request samples 
application/json
{
  • "id": "shop1:1234",
  • "site": "shop1",
  • "rack": "1234",
  • "rackName": "Tools",
  • "order": 1
}
Response samples 
application/json
{
  • "message": "Successfully created location with id: shop1:1234",
  • "code": 201
}
Updating locations
Updates locations for a specified site.




Required scopes


    

  • availability.availability_manage
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant name should always be provided in lowercase.


 
 Example:  testtenant
site
required
string
Site code, defined when the site is created.


 
 Example:  shop1
Request Body schema: application/json
 Array 
id
string
Unique identifier of the location.


 
order
number
Order of the location, expressed as a number.


 
Responses 
200
 The request was successful. The locations have been updated.


400
The request was syntactically incorrect. Details are provided in the response.


401
The authorization token is invalid or has expired. Details are provided in the response.


403
Provided authorization scopes are not sufficient and do not match scopes required by the endpoint.


500
Some server-side error occurred. Details are provided in the response.


put/{tenant}/locations/{site}
Request samples 
application/json
[
  • {
    },
  • {
    }
]
Response samples 
application/json
{
  • "message": "Successfully modified 5 location(s)",
  • "code": 200
}
Deleting a location
Deletes a specified location.




Required scopes


    

  • availability.availability_manage
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant name should always be provided in lowercase.


 
 Example:  testtenant
location
required
string
Location's unique identifier.


 
 Example:  shop1:1234
Responses 
200
 The request was successful. The location has been deleted.


401
The authorization token is invalid or has expired. Details are provided in the response.


403
Provided authorization scopes are not sufficient and do not match scopes required by the endpoint.


500
Some server-side error occurred. Details are provided in the response.


delete/{tenant}/locations/{location} 
Request samples 
Response samples 
application/json
{
  • "message": "Successfully deleted 5 location(s)",
  • "code": 200
}
Availabilities
Retrieving all availability information for a site
Retrieves all availability information for a specified site.


Note: When a product bundle is retrieved, availability is returned both for its particular products and for the bundle as a whole. The bundle's availability is equal to the lowest availability found in its products.




Required scopes
No specific scopes are required.


SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant name should always be provided in lowercase.


 
 Example:  testtenant
query Parameters
site
required
string
Site code, defined when the site is created.


 
 Example:  site=shop1
pageSize
number
 Default:  20000
Number of items to be retrieved per page.


 
 Example:  pageSize=100
pageNumber
number
 Default:  1
Page number to be retrieved. The number of the first page is 1.


Note: If the pageNumber parameter is passed, size of the pages must be specified in the pageSize parameter.


 
 Example:  pageNumber=5
Responses 
200
The request was successful. A list of availabilities is returned.


400
The request was syntactically incorrect. Details are provided in the response.


401
The authorization token is invalid or has expired. Details are provided in the response.


403
Provided authorization scopes are not sufficient and do not match scopes required by the endpoint.


500
Some server-side error occurred. Details are provided in the response.


get/{tenant}/availability
Request samples 
Response samples 
application/json
[]
Retrieving a product's availability
Retrieves a specified product's availability details.




SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant name should always be provided in lowercase.


 
 Example:  testtenant
productId
required
string
Product's unique identifier, generated when the product is created through the Product Service.


 
 Example:  5f7c996173fc281cdd412345
query Parameters
site
required
string
Site code, defined when the site is created.


 
 Example:  site=shop1
Responses 
200
The request was successful. The product's availability details are returned.


400
The request was syntactically incorrect. Details are provided in the response.


401
The authorization token is invalid or has expired. Details are provided in the response.


403
Provided authorization scopes are not sufficient and do not match scopes required by the endpoint.


404
The requested resource was not found.


500
Some server-side error occurred. Details are provided in the response.


get/{tenant}/availability/{productId}
Request samples 
Response samples 
application/json
{
  • "id": "shop1:12345",
  • "site": "shop1",
  • "stockLevel": 10,
  • "available": true,
  • "productId": "5f7c996173fc281cdd412345",
  • "popularity": 5,
  • "createdAt": "2022-02-22T02:02:02.222Z",
  • "modifiedAt": "2022-02-22T02:02:02.222Z",
  • "distributionChannel": "ASSORTMENT",
  • "metadata": {},
  • "mixins": {
    },
  • "bundleAvailabilities": []
}
Creating a new availability for a product
Creates a new availability for a specified product.


Note: We recommend not to create a new product availability for a site named main. A site named main works as an aggregator of availability data from other sites. It's not possible to later retrieve availability for a single site when it's called main.




Required scopes


    

  • availability.availability_manage
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant name should always be provided in lowercase.


 
 Example:  testtenant
productId
required
string
Product's unique identifier, generated when the product is created through the Product Service.


 
 Example:  5f7c996173fc281cdd412345
query Parameters
site
required
string
Site code, defined when the site is created.


 
 Example:  site=shop1
Request Body schema: application/json
id
string
Unique identifier of the availability.


Note: The value should be provided in the site:productId format.


 
site
string
Site code, defined when the site is created. The value should match the site query/path parameter value.


 
stockLevel
number
Stock level of the product, expressed as a number.


 
available
boolean
Flag indicating whether the product is available.


 
productId
string
Unique identifier of the product, generated when the product is created through the Product Service.


 
popularity
integer
Popularity of the product, expressed as a number.


 
createdAt
string <date-time> 
Date and time when the availability was created.


 
modifiedAt
string <date-time> 
Date and time when the availability was last updated.


 
distributionChannel
string (DistributionChannel) 
Name of the product's distribution channel.


 Enum: "ASSORTMENT" "HOME_DELIVERY" "PICKUP"  
mixins
object
The field contains mixins values.


 
object
 
Responses 
201
The request was successful. The availability has been created.


400
The request was syntactically incorrect. Details are provided in the response.


401
The authorization token is invalid or has expired. Details are provided in the response.


403
Provided authorization scopes are not sufficient and do not match scopes required by the endpoint.


409
Resource already exists.


500
Some server-side error occurred. Details are provided in the response.


post/{tenant}/availability/{productId}
Request samples 
application/json
{}
Response samples 
application/json
{
  • "message": "Availability record has been created.",
  • "code": 201
}
Upserting availability information of a product
Updates a specified product's availability details, or crates a new availability if it doesn't exist yet. 


Note: There is no possibility to update a product bundle's availability - it is always equal to the lowest availability found in the bundled products.




Required scopes


    

  • availability.availability_manage
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant name should always be provided in lowercase.


 
 Example:  testtenant
productId
required
string
Product's unique identifier, generated when the product is created through the Product Service.


 
 Example:  5f7c996173fc281cdd412345
query Parameters
site
required
string
Site code, defined when the site is created.


 
 Example:  site=shop1
Request Body schema: application/json
id
string
Unique identifier of the availability.


Note: The value should be provided in the site:productId format.


 
site
string
Site code, defined when the site is created. The value should match the site query/path parameter value.


 
stockLevel
number
Stock level of the product, expressed as a number.


 
available
boolean
Flag indicating whether the product is available.


 
productId
string
Unique identifier of the product, generated when the product is created through the Product Service.


 
popularity
integer
Popularity of the product, expressed as a number.


 
createdAt
string <date-time> 
Date and time when the availability was created.


 
modifiedAt
string <date-time> 
Date and time when the availability was last updated.


 
distributionChannel
string (DistributionChannel) 
Name of the product's distribution channel.


 Enum: "ASSORTMENT" "HOME_DELIVERY" "PICKUP"  
mixins
object
The field contains mixins values.


 
object
 
Responses 
200
The request was successful. The availability has been updated.


201
The request was successful. The availability has been created.


400
The request was syntactically incorrect. Details are provided in the response.


401
The authorization token is invalid or has expired. Details are provided in the response.


403
Provided authorization scopes are not sufficient and do not match scopes required by the endpoint.


404
The requested resource was not found.


500
Some server-side error occurred. Details are provided in the response.


put/{tenant}/availability/{productId}
Request samples 
application/json
{}
Response samples 
application/json
{
  • "message": "Availability has been updated",
  • "code": 200
}
Deleting availability information of a product
Deletes a specified product's availability.


Note: There is no possibility to delete a product bundle's availability - it is always equal to the lowest availability found in the bundled products.




Required scopes


    

  • availability.availability_manage
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant name should always be provided in lowercase.


 
 Example:  testtenant
productId
required
string
Product's unique identifier, generated when the product is created through the Product Service.


 
 Example:  5f7c996173fc281cdd412345
query Parameters
site
required
string
Site code, defined when the site is created.


 
 Example:  site=shop1
Responses 
204
The request was successful. The availability has been deleted.


400
The request was syntactically incorrect. Details are provided in the response.


401
The authorization token is invalid or has expired. Details are provided in the response.


403
Provided authorization scopes are not sufficient and do not match scopes required by the endpoint.


404
The requested resource was not found.


500
Some server-side error occurred. Details are provided in the response.


delete/{tenant}/availability/{productId}
Request samples 
Response samples 
application/json
{
  • "code": 400,
  • "status": "Bad Request",
  • "message": "There is a validation error. Please check the details.",
  • "_embedded": {
    }
}
Retrieving product locations
Retrieves locations of specified products.




Required scopes


    

  • availability.availability_view
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant name should always be provided in lowercase.


 
 Example:  testtenant
Request Body schema: application/json
site
string
Site code, defined when the site is created.


 
productIds
Array of strings
List of product IDs. A product IDs is generated when the product is created through the Product Service.


 
Responses 
200
The request was successful. A list of locations is returned.


400
The request was syntactically incorrect. Details are provided in the response.


401
The authorization token is invalid or has expired. Details are provided in the response.


403
Provided authorization scopes are not sufficient and do not match scopes required by the endpoint.


404
The requested resource was not found.


500
Some server-side error occurred. Details are provided in the response.


post/{tenant}/search/locations
Request samples 
application/json
{
  • "site": "shop1",
  • "productIds": [
    ]
}
Response samples 
application/json
[
  • {
    }
]
Retrieving product availabilities for a site
Retrieves availabilities for specified products on a specified site.




Required scopes
No specific scopes are required.


SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant name should always be provided in lowercase.


 
 Example:  testtenant
query Parameters
allSites
boolean
 Default:  false
Flag indicating whether the results should be retrieved from all sites.


 
 Example:  allSites=true
site
required
string
Site code, defined when the site is created.


 
 Example:  site=shop1
pageSize
number
 Default:  20000
Number of items to be retrieved per page.


 
 Example:  pageSize=100
pageNumber
number
 Default:  1
Page number to be retrieved. The number of the first page is 1.


Note: If the pageNumber parameter is passed, size of the pages must be specified in the pageSize parameter.


 
 Example:  pageNumber=5
Request Body schema: application/json
 Array 
string
 
Responses 
200
The request was successful. A list of availabilities is returned.


400
The request was syntactically incorrect. Details are provided in the response.


401
The authorization token is invalid or has expired. Details are provided in the response.


403
Provided authorization scopes are not sufficient and do not match scopes required by the endpoint.


500
Some server-side error occurred. Details are provided in the response.


post/{tenant}/availability
Request samples 
application/json
[
  • "5f7c996173fc281cdd412345",
  • "5f7c996173fc281cdd412346"
]
Response samples 
application/json
[
  • {
    }
]