API documentationIncident ManagementFeedback

Listings

More Listings-API information can be found here: REST API documentation - Listings. Functional details can be found under Products – Listings.

Create a listing

Before creating a listing, a facility must be created first. Listings are always related to a specific facility.

A listing can be created by performing the following PUT call with the JSON body:

PUT https://{YOUR_TENANT_NAME}.api.fulfillmenttools.com/api/facilities/{facilityId}/listings
{
  "listings": [
    {
      "imageUrl": "https://upload.wikimedia.org/wikipedia/en/3/35/Wonka_Bar%2C_packaging.jpg",
      "price": 2.99,
      "tenantArticleId": "4892",
      "titleLocalized": {
        "de_DE": "Wonkas Schokoriegel",
        "en_US": "Wonkas Chocolate Bar"
      },
    }
  ]
}

If the request was successful, a HTTP 200 OK response will be received without a body.

Get listings

All listings of a facility can be get by using the paginated GET endpoint to find all listings for a specific facilityId:

GET https://{YOUR_TENANT_NAME}.api.fulfillmenttools.com/api/facilities/{facilityId}/listings

If the request was successful, a HTTP 200 OK response will be received containing all listings for that facility.

{
    "total": 1,
    "listings": [
        {
            "id": "5d174533-29b9-464b-9325-94bfacefe335_4892",
            "version": 1,
            "status": "ACTIVE",
            "tenantArticleId": "4892",
            "created": "2023-08-22T12:19:14.129Z"
        }
    ]
}

Alternatively, there is a GET endpoint to find a specific listing by its tenantArticleId:

GET https://{YOUR_TENANT_NAME}.api.fulfillmenttools.com/api/facilities/{facilityId}/listings/{tenantArticleId}

This will result in a HTTP 200 OK response containing a more detailed view of that listing:

{
  "attributes": null,
  "imageUrl": "https://upload.wikimedia.org/wikipedia/en/3/35/Wonka_Bar%2C_packaging.jpg",
  "price": 2.99,
  "tenantArticleId": "4892",
  "titleLocalized": {
    "de_DE": "Wonkas Schokoriegel",
    "en_US": "Wonkas Chocolate Bar"
  },
  "scannableCodes": [],
  "created": "2023-08-22T12:19:14.129Z",
  "lastModified": "2023-08-22T12:19:14.129Z",
  "version": 1,
  "facilityId": "5d174533-29b9-464b-9325-94bfacefe335",
  "id": "5d174533-29b9-464b-9325-94bfacefe335_4892",
  "status": "ACTIVE"
}

Bulk insert listings

When inserting listings for different facilities, it is recommended to use the bulk insert API to minimize the number of calls.

There are 2 options for using the endpoint:

The listing version must be sent for an update; otherwise, a new listing is created. If a listing with the same tenantArticleId already exists, the entire update batch fails.

Search listings for obtaining the version

First, the listings that should be updated need to be searched to obtain the listing's version. Afterwards, the listings bulk API can be used to update multiple listings for multiple facilities simultaneously.

In the following example, all listings of tenantArticleId 4711 are updated. First, listings are searched to get the listing (including the version).

POST https://{YOUR_TENANT_NAME}.api.fulfillmenttools.com/api/listings/search
{
  "query": {
    "tenantArticleId": {
      "eq": "4711"
    }
  }
}

It might be necessary to iterate over multiple pages to get all listings with the corresponding tenantArticleId.

The search returns the complete listings.

Update listings with ListingForBulkUpsertBySelector

Multiple listings can be updated by performing the following PUT call with the JSON body:

PUT https://{YOUR_TENANT_NAME}.api.fulfillmenttools.com/api/listings
{
  "listings": [
    {
      "tenantArticleId": "4711",
      "selector": [
        {
          "facility": {
            "facilityRef": "facility1"
          },
          "version": 42
        },
        {
          "facility": {
            "facilityRef": "facility2"
          },
          "version": 43
        }
      ],
       ... // the full updated listing
    }
  ]
}

Each entry of the selector array refers to the listing for this tenantArticleId in a specific facility and the version of the currently present listing. Up to 25 listings can be updated in each batch - either by providing 25 selectors for a single listing, or multiple listings with multiple selectors. The endpoint returns the listings and a summary of all operations:

This is an all-or-nothing behavior. If one listing insert fails, all others will fail too.

{
  "listings": [
    {
      ...
    },
    ...
  ],
  "summary": {
    "created": 0,
    "updated": 2
  }
}

Update listings with ListingForBulkUpsertByFacility

Multiple listings can be updated by performing the following PUT call with the JSON body:

PUT https://{YOUR_TENANT_NAME}.api.fulfillmenttools.com/api/listings
{
  "listings": [
    {
      "tenantArticleId": "4711",
      "facility": {
        "facilityRef": "facility1"
      },
      "version": 42,
      ... // the full updated listing
    },
    {
      "tenantArticleId": "4711",
      "facility": {
        "facilityRef": "facility2"
      },
      "version": 43,
      ... // the full updated listing
    },
    ...
  ]
}

The endpoint returns the listings and a summary of all operations:

This is an all-or-nothing behavior. If one listing insert fails, all others will fail too.

{
  "listings": [
    {
      ...
    },
    ...
  ],
  "summary": {
    "created": 0,
    "updated": 2
  }
}

Last updated