Availabilities

Retrieving all availability information for a site

get

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 availability is equal to the lowest availability found in its products.

Additional scope information

The availability.availability_view_by_vendor scope is required only when fetching availabilities for a specific vendor.

Required scopes

This endpoint requires the following scopes:

: Needed to view availabilities belonging to the vendor.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

Your Emporix tenant name.

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

Example: testtenant

sitestringRequired

Site code, defined when the site is created.

Example: shop1

Query parameters

pageSizenumberOptional

Number of items to be retrieved per page.

Default: 20000Example: 100

pageNumbernumberOptional

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.

Default: 1Example: 5

qstringOptional

A standard query parameter is used to search for specific values.

See: Standard Practices - Query parameter

sortstringOptional

List of properties used to sort the results, separated by colons. Possible values:

{fieldName}
{fieldName}:asc
{fieldName}:desc

Responses

200

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

application/json

400

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

application/json

401

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

application/json

403

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

application/json

500

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

application/json

get/availability/{tenant}/availability/site/{site}

GET /availability/{tenant}/availability/site/{site} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "id": "shop1:12345",
    "site": "shop1",
    "stockLevel": 10,
    "available": true,
    "productId": "5f7c996173fc281cdd412345",
    "popularity": 5,
    "distributionChannel": "ASSORTMENT",
    "metadata": {
      "mixins": {
        "productCustomAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/productCustomAttributesMixIn.v29.json"
      },
      "createdAt": "2022-02-22T02:02:02.222Z",
      "modifiedAt": "2022-02-22T02:02:02.222Z"
    },
    "mixins": {
      "productCustomAttributes": {
        "minOrderQuantity": 2
      }
    }
  }
]

Retrieving product availabilities

post

Retrieves availabilities for specified products. The request body accepts one of two mutually exclusive formats:

List of product IDs — retrieves availabilities for the specified products. If the product ID refers to a product bundle, availability information for the entire bundle is returned. The site query parameter is optional.
Q-param object — retrieves availabilities matching the provided query criteria. The response will not include avaialbilities for product bundles. The site query parameter must not be provided together with the Q-param body.

Additional scope information

The availability.availability_view_by_vendor scope is required only when fetching availabilities for a specific vendor.

Required scopes

This endpoint requires the following scopes:

: Needed to view availabilities belonging to the vendor.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

Your Emporix tenant name.

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

Example: testtenant

Query parameters

sitestringOptional

Site code, defined when the site is created. If it's not provided, then availabilities for all sites are returned.

Example: shop1

pageSizenumberOptional

Number of items to be retrieved per page.

Default: 20000Example: 100

pageNumbernumberOptional

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.

Default: 1Example: 5

sortstringOptional

List of properties used to sort the results, separated by colons. Possible values:

{fieldName}
{fieldName}:asc
{fieldName}:desc

Body

string[]Optional

IDs of products for which availabilities should be retrieved.

Responses

200

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

application/json

400

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

application/json

401

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

application/json

403

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

application/json

500

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

application/json

post/availability/{tenant}/availability/search

POST /availability/{tenant}/availability/search HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 55

[
  "5f7c996173fc281cdd412345",
  "5f7c996173fc281cdd412346"
]

[
  {
    "id": "shop1:12345",
    "site": "shop1",
    "stockLevel": 10,
    "available": true,
    "productId": "5f7c996173fc281cdd412345",
    "popularity": 5,
    "distributionChannel": "ASSORTMENT",
    "metadata": {
      "mixins": {
        "productCustomAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/productCustomAttributesMixIn.v29.json"
      },
      "createdAt": "2022-02-22T02:02:02.222Z",
      "modifiedAt": "2022-02-22T02:02:02.222Z"
    },
    "mixins": {
      "productCustomAttributes": {
        "minOrderQuantity": 2
      }
    },
    "bundleAvailabilities": [
      {
        "id": "shop1:678",
        "site": "shop1",
        "stockLevel": 10,
        "available": true,
        "productId": "5f7c996173fc281cdd412345",
        "popularity": 5,
        "distributionChannel": "ASSORTMENT",
        "metadata": {
          "createdAt": "2022-02-22T02:02:02.222Z",
          "modifiedAt": "2022-02-22T02:02:02.222Z"
        }
      }
    ]
  }
]

Retrieving a product availability

get

Retrieves a specified product availability details.

Additional scope information

The availability.availability_view_by_vendor scope is required only when fetching availabilities for a specific vendor.

Required scopes

This endpoint requires the following scopes:

: Needed to view availabilities belonging to the vendor.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

Your Emporix tenant name.

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

Example: testtenant

productIdstringRequired

Product unique identifier, generated when the product is created through the Product Service.

Example: 5f7c996173fc281cdd412345

sitestringRequired

Site code, defined when the site is created.

Example: shop1

Responses

200

The request was successful. The product availability details are returned.

application/json

Availability details.

idstringOptional

Unique identifier of the availability.

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

Example: shop1:12345

sitestringOptional

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

Example: shop1

stockLevelnumberOptional

Stock level of the product, expressed as a number.

Example: 10

availablebooleanOptional

Flag indicating whether the product is available.

Example: true

productIdstringOptional

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

Example: 5f7c996173fc281cdd412345

vendorIdstringOptional

Id of a vendor to which the availability belongs.

popularityintegerOptional

Popularity of the product, expressed as a number.

Example: 5

distributionChannelstring · enumOptional

Name of the product distribution channel.

Example: ASSORTMENTPossible values:

400

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

application/json

401

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

application/json

403

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

application/json

404

The requested resource was not found.

application/json

500

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

application/json

get/availability/{tenant}/availability/{productId}/{site}

GET /availability/{tenant}/availability/{productId}/{site} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "id": "shop1:12345",
  "site": "shop1",
  "stockLevel": 10,
  "available": true,
  "productId": "5f7c996173fc281cdd412345",
  "popularity": 5,
  "distributionChannel": "ASSORTMENT",
  "metadata": {
    "mixins": {
      "productCustomAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/productCustomAttributesMixIn.v29.json"
    },
    "createdAt": "2022-02-22T02:02:02.222Z",
    "modifiedAt": "2022-02-22T02:02:02.222Z"
  },
  "mixins": {
    "productCustomAttributes": {
      "minOrderQuantity": 2
    }
  },
  "bundleAvailabilities": [
    {
      "id": "shop1:678",
      "site": "shop1",
      "stockLevel": 10,
      "available": true,
      "productId": "5f7c996173fc281cdd412345",
      "popularity": 5,
      "distributionChannel": "ASSORTMENT",
      "metadata": {
        "mixins": {
          "productCustomAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/productCustomAttributesMixIn.v29.json"
        },
        "createdAt": "2022-02-22T02:02:02.222Z",
        "modifiedAt": "2022-02-22T02:02:02.222Z"
      },
      "mixins": {
        "productCustomAttributes": {
          "minOrderQuantity": 2
        }
      }
    }
  ]
}

Creating a new availability for a product

post

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.

Additional scope information

The availability.availability_manage_by_vendor scope allows to create availabilities for products belonging to the vendor.

Required scopes

This endpoint requires the following scopes:

: Needed to manage availabilities.
: Needed to manage availabilities belonging to the vendor.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

Your Emporix tenant name.

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

Example: testtenant

productIdstringRequired

Product unique identifier, generated when the product is created through the Product Service.

Example: 5f7c996173fc281cdd412345

sitestringRequired

Site code, defined when the site is created.

Example: shop1

Body

stockLevelnumberOptional

Stock level of the product, expressed as a number.

Example: 10

availablebooleanOptional

Flag indicating whether the product is available.

Example: true

popularityintegerOptional

Popularity of the product, expressed as a number.

Example: 5

distributionChannelstring · enumOptional

Name of the product distribution channel.

Example: ASSORTMENTPossible values:

Responses

201

The request was successful. The availability has been created.

application/json

idstringOptional

ID of the created resource.

400

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

application/json

401

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

application/json

403

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

application/json

409

Resource already exists.

application/json

500

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

application/json

post/availability/{tenant}/availability/{productId}/{site}

POST /availability/{tenant}/availability/{productId}/{site} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 293

{
  "stockLevel": 10,
  "available": true,
  "popularity": 5,
  "distributionChannel": "ASSORTMENT",
  "metadata": {
    "mixins": {
      "productCustomAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/productCustomAttributesMixIn.v29.json"
    }
  },
  "mixins": {
    "productCustomAttributes": {
      "minOrderQuantity": 2
    }
  }
}

{
  "id": "5f7c996173fc281cdd412345."
}

Upserting availability information of a product

put

Updates a specified product availability details, or crates a new availability if it doesn't exist yet.

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

Additional scope information

The availability.availability_manage_by_vendor scope is only required when updating or creating availabilities belonging to the vendor.

Required scopes

This endpoint requires the following scopes:

: Needed to manage availabilities.
: Needed to manage availabilities belonging to the vendor.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

Your Emporix tenant name.

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

Example: testtenant

productIdstringRequired

Product unique identifier, generated when the product is created through the Product Service.

Example: 5f7c996173fc281cdd412345

sitestringRequired

Site code, defined when the site is created.

Example: shop1

Body

stockLevelnumberOptional

Stock level of the product, expressed as a number.

Example: 10

availablebooleanOptional

Flag indicating whether the product is available.

Example: true

popularityintegerOptional

Popularity of the product, expressed as a number.

Example: 5

distributionChannelstring · enumOptional

Name of the product distribution channel.

Example: ASSORTMENTPossible values:

Responses

201

The request was successful. The availability has been created.

application/json

idstringOptional

ID of the created resource.

204

The request was successful. The availability has been updated.

400

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

application/json

401

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

application/json

403

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

application/json

404

The requested resource was not found.

application/json

500

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

application/json

put/availability/{tenant}/availability/{productId}/{site}

PUT /availability/{tenant}/availability/{productId}/{site} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 293

{
  "stockLevel": 10,
  "available": true,
  "popularity": 5,
  "distributionChannel": "ASSORTMENT",
  "metadata": {
    "mixins": {
      "productCustomAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/productCustomAttributesMixIn.v29.json"
    }
  },
  "mixins": {
    "productCustomAttributes": {
      "minOrderQuantity": 2
    }
  }
}

{
  "id": "5f7c996173fc281cdd412345."
}

Deleting availability information of a product

delete

Deletes a specified product availability.

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

Additional scope information

The availability.availability_manage_by_vendor scope is only required when deleting availabilities belonging to the vendor.

Required scopes

This endpoint requires the following scopes:

: Needed to manage availabilities.
: Needed to manage availabilities belonging to the vendor.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

Your Emporix tenant name.

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

Example: testtenant

productIdstringRequired

Product unique identifier, generated when the product is created through the Product Service.

Example: 5f7c996173fc281cdd412345

sitestringRequired

Site code, defined when the site is created.

Example: shop1

Responses

204

The request was successful. The availability has been deleted.

No content

400

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

application/json

401

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

application/json

403

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

application/json

404

The requested resource was not found.

application/json

500

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

application/json

delete/availability/{tenant}/availability/{productId}/{site}

DELETE /availability/{tenant}/availability/{productId}/{site} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

Creating multiple product availabilities

post

Creates availability records for a product based on its ID and site. A product can have different availability across sites, so each record is uniquely defined by the combination of productId and site. The maximum batch size is 200.

Note: We recommend not to create new product availabilities 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.

Additional scope information

The availability.availability_manage_by_vendor scope is only required when creating availabilities belonging to the vendor.

Required scopes

This endpoint requires the following scopes:

: Needed to manage availabilities.
: Needed to manage availabilities belonging to the vendor.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

Your Emporix tenant name.

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

Example: testtenant

Header parameters

venodr-idstringOptional

Unique identifier of the vendor. The presence of this header will limit the operation to products assigned to the provided vendor.

Example: 68ad7d45c42fc8121a611fec

Bodyobject · AvailabilityBulkDto[]

productIdstringOptional

Unique identifier of the product.

Example: 12345

sitestringOptional

Unique identifier of the site.

Example: shop1

stockLevelnumberOptional

Stock level of the product, expressed as a number.

Example: 10

availablebooleanOptional

Flag indicating whether the product is available.

Example: true

popularityintegerOptional

Popularity of the product, expressed as a number.

Example: 5

distributionChannelstring · enumOptional

Name of the product distribution channel.

Example: ASSORTMENTPossible values:

Responses

207

Multi-status response.

application/json

idstringOptional

ID of the affected availability (in the format :<).

Example: shop1:12345

indexintegerOptional

Index of the processed item, matching the item position in request body.

Example: 1

codeintegerOptional

HTTP Status Code.

Example: 204

statusstringOptional

HTTP Status description.

Example: No Content

messagestringOptional

Error message. Present only when an error occurs (HTTP status code from groups 4xx or 5xx)

Example: There is no availability for productId: 12345 and site: shop1

400

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

application/json

401

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

application/json

403

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

application/json

500

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

application/json

post/availability/{tenant}/availability/bulk

POST /availability/{tenant}/availability/bulk HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 330

[
  {
    "productId": "12345",
    "site": "shop1",
    "stockLevel": 10,
    "available": true,
    "popularity": 5,
    "distributionChannel": "ASSORTMENT",
    "metadata": {
      "mixins": {
        "productCustomAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/productCustomAttributesMixIn.v29.json"
      }
    },
    "mixins": {
      "productCustomAttributes": {
        "minOrderQuantity": 2
      }
    }
  }
]

[
  {
    "id": "shop1:12345",
    "index": 0,
    "code": 201,
    "status": "Created"
  },
  {
    "id": "shop2:98765",
    "index": 1,
    "code": 400,
    "status": "Bad Request",
    "message": "Product: '98765' does not belong to vendor: '68ad7d45c42fc8121a611fec'"
  }
]

Upserting multiple availabilities information of a product

put

Creates or updates product availability records based on product ID and site. If an availability does not yet exist for a given productId and site, it is created. If it already exists, it is updated. The maximum batch size is 200.

Additional scope information

The availability.availability_manage_by_vendor scope is only required when creating or updating availabilities belonging to the vendor.

Required scopes

This endpoint requires the following scopes:

: Needed to manage availabilities.
: Needed to manage availabilities belonging to the vendor.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

Your Emporix tenant name.

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

Example: testtenant

Header parameters

venodr-idstringOptional

Unique identifier of the vendor. The presence of this header will limit the operation to products assigned to the provided vendor.

Example: 68ad7d45c42fc8121a611fec

Bodyobject · AvailabilityBulkDto[]

productIdstringOptional

Unique identifier of the product.

Example: 12345

sitestringOptional

Unique identifier of the site.

Example: shop1

stockLevelnumberOptional

Stock level of the product, expressed as a number.

Example: 10

availablebooleanOptional

Flag indicating whether the product is available.

Example: true

popularityintegerOptional

Popularity of the product, expressed as a number.

Example: 5

distributionChannelstring · enumOptional

Name of the product distribution channel.

Example: ASSORTMENTPossible values:

Responses

207

Multi-status response.

application/json

idstringOptional

ID of the affected availability (in the format :<).

Example: shop1:12345

indexintegerOptional

Index of the processed item, matching the item position in request body.

Example: 1

codeintegerOptional

HTTP Status Code.

Example: 204

statusstringOptional

HTTP Status description.

Example: No Content

messagestringOptional

Error message. Present only when an error occurs (HTTP status code from groups 4xx or 5xx)

Example: There is no availability for productId: 12345 and site: shop1

400

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

application/json

401

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

application/json

403

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

application/json

500

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

application/json

put/availability/{tenant}/availability/bulk

PUT /availability/{tenant}/availability/bulk HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 330

[
  {
    "productId": "12345",
    "site": "shop1",
    "stockLevel": 10,
    "available": true,
    "popularity": 5,
    "distributionChannel": "ASSORTMENT",
    "metadata": {
      "mixins": {
        "productCustomAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/productCustomAttributesMixIn.v29.json"
      }
    },
    "mixins": {
      "productCustomAttributes": {
        "minOrderQuantity": 2
      }
    }
  }
]

[
  {
    "id": "shop1:12345",
    "index": 0,
    "code": 201,
    "status": "Created"
  },
  {
    "id": "shop2:98765",
    "index": 1,
    "code": 204,
    "status": "No Content"
  },
  {
    "id": "shop3:98765",
    "index": 2,
    "code": 400,
    "status": "Bad Request",
    "message": "Product: '98765' does not belong to vendor: '68ad7d45c42fc8121a611fec'"
  }
]

Deleting multiple availabilities information of a product

delete

Deletes product availability records identified by the combination of productId and site. The maximum batch size is 200.

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

Additional scope information

The availability.availability_manage_by_vendor scope is only required when deleting availabilities belonging to the vendor.

Required scopes

This endpoint requires the following scopes:

: Needed to manage availabilities.
: Needed to manage availabilities belonging to the vendor.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

Your Emporix tenant name.

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

Example: testtenant

Header parameters

venodr-idstringOptional

Unique identifier of the vendor. The presence of this header will limit the operation to products assigned to the provided vendor.

Example: 68ad7d45c42fc8121a611fec

Bodyobject · AvailabilityDeleteBulkDto[]

productIdstringOptional

Unique identifier of the product.

Example: 12345

sitestringOptional

Unique identifier of the site.

Example: shop1

Responses

207

Multi-status response.

application/json

idstringOptional

ID of the affected availability (in the format :<).

Example: shop1:12345

indexintegerOptional

Index of the processed item, matching the item position in request body.

Example: 1

codeintegerOptional

HTTP Status Code.

Example: 204

statusstringOptional

HTTP Status description.

Example: No Content

messagestringOptional

Error message. Present only when an error occurs (HTTP status code from groups 4xx or 5xx)

Example: There is no availability for productId: 12345 and site: shop1

400

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

application/json

401

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

application/json

403

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

application/json

500

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

application/json

delete/availability/{tenant}/availability/bulk

DELETE /availability/{tenant}/availability/bulk HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 38

[
  {
    "productId": "12345",
    "site": "shop1"
  }
]

[
  {
    "id": "shop1:12345",
    "index": 0,
    "code": 204,
    "status": "No Content"
  },
  {
    "id": "shop2:98765",
    "index": 1,
    "code": 204,
    "status": "No Content"
  }
]

PreviousLocations NextModels

Last updated 1 month ago

Was this helpful?