Listings

For detailed API specifications, see the REST API documentation for Listings. For functional details, refer to Products – Listings.

Creating a listing

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

To create a listing, send a PUT request to the following endpoint with a 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"
      }
    }
  ]
}

A successful request returns an HTTP 200 OK response.

Retrieving listings

To retrieve all listings for a specific facility, send a paginated GET request to the following endpoint using the facilityId:

GET https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/facilities/{facilityId}/listings

A successful request returns an HTTP 200 OK response 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, to retrieve a specific listing by its tenantArticleId, use the following GET endpoint:

GET https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/facilities/{facilityId}/listings/{tenantArticleId}

The endpoint returns an HTTP 200 OK response with a detailed view of the specified 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 upserting listings

To upsert listings for multiple facilities while minimizing API calls, use the bulk upsert endpoint.

There are two options for using the endpoint:

• ListingForBulkUpsertBySelector: Allows sending listing information once and updating it for multiple facilities.

• ListingForBulkUpsertByFacility: Allows sending different listing information for the same tenantArticleId for multiple facilities.

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.

Searching for the listing version

Before updating existing listings, their current version must be retrieved. This can be done by searching for the listings. The bulk API can then be used to update multiple listings across various facilities simultaneously.

The following example demonstrates searching for all listings with tenantArticleId 4711 to retrieve their current versions.

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. More information can be found under Pagination.

The search returns the complete listings.

Updating with ListingForBulkUpsertBySelector

To update multiple listings, send a PUT request to the following endpoint 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
        }
      ],
      "targetingStrategy": "MULTI_SELECTOR",
       ... // the full updated listing
    }
  ]
}

Each object in the selector array specifies a listing in a particular facility by its tenantArticleId and current version. A single batch can update up to 25 listings. This can be achieved by providing 25 selectors for one listing, or through multiple listings with their respective selectors. The endpoint returns the updated listings and a summary of the operations.

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

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

Updating with ListingForBulkUpsertByFacility

To update multiple listings, send a PUT request to the following endpoint with the JSON body:

PUT https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/listings

{
  "listings": [
    {
      "tenantArticleId": "4711",
      "facility": {
        "facilityRef": "facility1"
      },
      "targetingStrategy": "SINGLE_FACILITY",
      "version": 42,
      ... // the full updated listing
    },
    {
      "tenantArticleId": "4711",
      "facility": {
        "facilityRef": "facility2"
      },
      "targetingStrategy": "SINGLE_FACILITY",
      "version": 43,
      ... // the full updated listing
    },
    ...
  ]
}

The endpoint returns the updated listings and a summary of the operations.

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

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