Skip to content
Crossmart Docs

Each store’s products by display state, and the latest failed listings, as of now

GET
/api/v1/workspaces/{workspaceId}/analytics/listings
curl --request GET \
  --url https://api.crossmart.io/api/v1/workspaces/example/analytics/listings \
  --header 'x-api-key: <x-api-key>'

Counts follow the same rule as each store’s product list. Each failed listing carries displayState, displayReason and displayRequirement, so a client can link to the fix.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
workspaceId
required
string

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json
object
stores
required

Every store, oldest first

Array<object>
object
connectionId
required
string format: uuid
channel
required
string
Allowed values: shopify ebay google_merchant etsy amazon walmart
displayName
required
string
status
required
string
Allowed values: CONNECTED NEEDS_REAUTH DISCONNECTED ERROR
statusReason
required

Why the store needs reconnecting or is in error; null otherwise

string
nullable
lastSyncedAt
required
string format: date-time
nullable
states
required

Every display state, in order, with how many products are in it: the same states and rule as the store’s product list (draft counts the catalog products not in the store)

Array<object>
object
state
required
string
Allowed values: draft needs_details ready publishing published failed removing removed
count
required

Products of the catalog in this state on the store

number
failedListings
required

Listings the channel refused on their last sync

number
recentFailures
required

The latest listings a channel refused, latest first, each with its display state and requirement so a client can link to the fix

Array<object>
object
id
required
string format: uuid
status
required
string
Allowed values: PENDING ACTIVE INACTIVE ERROR DELISTED
source
required

How the product joined the store: by hand, by an import, or by the automatic rule

string
Allowed values: MANUAL IMPORT RULE
externalId
required

The product’s id on the channel

string
nullable
externalUrl
required

Where to see it on the channel

string
nullable
lastError
required

Why the last sync failed

string
nullable
missingRequirement
required

What the channel refused the last publish for lacking (such as item_specifics), when the merchant can add it; null otherwise

string
Allowed values: reconnect account_settings shipping_policy payment_policy return_policy ship_from_location listing_setup item_details shipping_profile processing_profile images active_product category item_specifics option_names
lastSyncedAt
required
string format: date-time
nullable
syncRequestedAt
required

When a sync or retry queued its publish, update or delist; null once that job finished or gave up. While set, a selected listing shows displayState: publishing.

string format: date-time
nullable
category
required

The channel category it is listed in, on channels with categories (eBay)

object
id
required
string
name
required

The category with its ancestors, as the channel shows it

string
productId
required
string format: uuid
productTitle
required
string
imageUrl
required
string
nullable
variantCount
required
number
displayState
required

The product on this store, in one state computed by the server: draft (not selected for the store), needs_details (selected, but the store setup or the product lacks something publishing needs), ready (publishable, not sent yet), publishing (queued or in flight, including an update of a published listing that a sync or retry queued), published, failed, removing (being taken off) or removed.

string
Allowed values: draft needs_details ready publishing published failed removing removed
displayReason
required

For needs_details and failed: a short, merchant-readable reason (what to add, or the channel’s message). Never holds secrets. Null for the other states.

string
nullable
displayRequirement
required

For needs_details: the requirement to fix first, so a client can open the right place. Store-setup requirements (reconnect, account_settings, shipping_policy, payment_policy, return_policy, ship_from_location, listing_setup) come before the product’s (images, active_product, option_names), which the server checks before publishing; category and item_specifics are known once the channel refused a publish. Null for the other states.

string
Allowed values: reconnect account_settings shipping_policy payment_policy return_policy ship_from_location listing_setup item_details shipping_profile processing_profile images active_product category item_specifics option_names
connectionId
required

The store the listing is on

string format: uuid
failedListings
required

Failed listings in all, across the stores

number

Example 

{
  "stores": [
    {
      "channel": "shopify",
      "displayName": "Demo Store",
      "status": "CONNECTED",
      "states": [
        {
          "state": "draft"
        }
      ]
    }
  ],
  "recentFailures": [
    {
      "status": "PENDING",
      "source": "MANUAL",
      "missingRequirement": "reconnect",
      "category": {
        "id": "20625",
        "name": "Home & Garden > Kitchen, Dining & Bar > Dinnerware & Serving Dishes > Mugs"
      },
      "displayState": "draft",
      "displayReason": "Choose a shipping policy in this eBay connection’s listing defaults.",
      "displayRequirement": "reconnect"
    }
  ]
}