JSON API – Listings (Overview & Common Concepts)

Overview

The Listings JSON API allows you to retrieve listing data from Feedvisor in JSON format without generating export files.

This API supports multiple marketplaces using the same endpoint pattern and the same filtering behavior. Marketplace-specific supported fields may differ, but the following concepts are shared:

• authentication

• pagination

• query operators

• filter syntax

• response envelope structure

Marketplace-specific field support is documented separately:

• JSON API – Fetch Amazon Listings

• JSON API – Fetch Walmart Listings

---

Endpoint

GET /external/{accountId}/v2/listings

Base URL

https://api-gateway.feedvisor.com

Example

https://api-gateway.feedvisor.com/external/1234/v2/listings

Parameter	Description
accountId	Your Feedvisor account identifier

---

Authentication

All requests require a valid bearer token.

Header

Authorization: Bearer <access_token>

Example

Authorization: Bearer eyJhbGciOi...

---

Pagination

Results are returned in pages.

Response pagination fields

Field	Description
totalItemsCount	Total number of matching items across all pages
totalPagesCount	Total number of pages for the current query
page	Current page returned
items	List of listing configurations returned for the page

Example response envelope

{
  "totalItemsCount": 2,
  "totalPagesCount": 1,
  "page": 0,
  "items": [
    {}
  ]
}

---

Filter Logic

Multiple query parameters may be combined in the same request.

All filters are applied using logical AND.

Example

GET /external/1234/v2/listings?sku=[BW:ABC]&price=[GTE:10]&brand=[EQCS:Acme]

This means:

• SKU begins with ABC

• price is greater than or equal to 10

• brand equals Acme

All three conditions must match.

---

Query Operations Guide

Query operations define how a value is filtered.

---

Text-Based Query Operations

These operations apply to text fields.

Operator	Meaning	Description	Example
EQCS	Equals (Case Sensitive)	Must exactly match the queried value, case-sensitive	[EQCS:Abcd]
NEQCS	Not Equals (Case Sensitive)	Must not match the queried value, case-sensitive	[NEQCS:abcd]
BW	Begins With	The field starts with the queried text	[BW:Ab]
EW	Ends With	The field ends with the queried text	[EW:cd]
CON	Contains	The field contains the queried text	[CON:bc]
NCON	Not Contains	The field does not contain the queried text	[NCON:xyz]

---

Numeric-Specific Query Operations

These operations apply only to numeric fields.

Operator	Meaning	Description	Example
RNG	In Range	The value is within the specified range, inclusive	[RNG:5.5,12]
NRNG	Not In Range	The value is outside the specified range	[NRNG:10.50,12]

---

Numeric & Date Query Operations

These operations apply to numeric fields and dates.

Operator	Meaning	Description	Example
GT	Greater Than	Field value is larger than the queried value	[GT:5.5]
GTE	Greater Than or Equal To	Field value is larger than or equal to the queried value	[GTE:10]
LT	Less Than	Field value is smaller than the queried value	[LT:12]
LTE	Less Than or Equal To	Field value is smaller than or equal to the queried value	[LTE:9]
NGT	Not Greater Than	Same as LTE	[NGT:9]
NLT	Not Less Than	Same as GTE	[NLT:10]

---

Text & Numeric Query Operations

These operations can be used for both text and numeric fields.

Operator	Meaning	Description	Example
EQ	Equals	Must exactly match the queried value	[EQ:10], [EQ:Abcd]
NEQ	Not Equals	Must not match the queried value	[NEQ:5.5], [NEQ:abc]
IN	In	Field value is in the specified list	[IN:5.5,10], [IN:Abcd,def]

Use : after the operator for consistency in examples, for example [EQ:10].
If your backend also accepts = in some operators, document that separately only if officially supported.

---

Example Request

GET /external/1234/v2/listings?sku=[BW:ABC]&price=[GTE:10]&brand=[EQCS:Acme]
Authorization: Bearer YOUR_TOKEN

---

Example Response

{
  "totalItemsCount": 2,
  "totalPagesCount": 1,
  "page": 0,
  "items": [
    {
      "sku": "ABC-1001",
      "price": 19.99,
      "brand": "Acme"
    },
    {
      "sku": "ABC-1002",
      "price": 24.99,
      "brand": "Acme"
    }
  ]
}

---

Errors

Code	Meaning
400	Invalid request or invalid filter format
401	Authentication failed
403	Access denied
404	Endpoint not found
500	Internal server error