Getting started
The Lister Public API provides secure, programmatic access to operational and sales data from your Upright Labs Lister account. It enables clients to export data for use in external systems, reporting tools, or custom integrations. All endpoints are authenticated and exclude personally identifiable information (PII) to ensure data security.
Table of Contents
- GET /reports/listings/goodwillfinds
- GET /reports/listings/shopgoodwill
- GET /reports/listings/ebay
- GET /reports/listings/shopify
- GET /reports/productivity/operational
- GET /reports/productivity/user
- GET /reports/paid_orders
- GET /reports/order_items
- GET /reports/shipments
- GET /reports/refunds
- GET /reports/manifest_items
- GET /manifests
- POST /api/manifests
- PUT /api/manifests
- GET /event_logs
- GET /v4/products (Get products)
- GET /v5/products (Get products)
- POST /v5/products (Create products)
- PUT /v4/products (Update product or variants)
- GET /v5/images/presign
- Uploading images
Authentication
All API calls must supply an X-Authorization header with your generated API token. You can generate an API token from Admin > Developer in Lister.
Date formats
Every date uses an ISO8601 format.
Rate limits
- You can request up to 365 days of data in a given report, however calls may time out or return an error if results exceed 10 thousand records. You can prevent this by modifying your query to reduce your results by API call.
Resources
- All API calls should be made to https://app.uprightlabs.com/api/<resource>
- For documentation on our downloadable reports, please visit the report section in our help center documentation. These reports return similar data to the API.
Reporting
GET /reports/listings/goodwillfinds
Returns all Goodwillfinds listings created within the timeframe
Params time_start: String time_end: String
- Example
- Response
GET /reports/listings/shopgoodwill
Returns all Shopgoodwill listings created within the timeframe
Params time_start: String time_end: String
- Example
- Response
GET /reports/listings/ebay
Returns all eBay listings created within the timeframe
Params time_start: String time_end: String
- Example
- Response
GET /reports/listings/shopify
Returns all Shopify listings created within the timeframe
Params time_start: String time_end: String
external_market_id: Integer (optional) - The Shopify Product ID to filter by
- Example
- Response
GET /reports/productivity/operational
Returns operational productivity stats recorded in the timeframe grouped by interval
Params time_start: String time_end: String
interval: String - hour, day, week, month, quarter, year; What timeframe to group stats by.
user_id: Integer (optional) - Filter data by a particular user; defaults to all.
- Example
- Response
GET /reports/productivity/user
Returns user productivity stats recorded in the timeframe
Params time_start: String time_end: String
hide_inactive_users: Boolean (optional) - Exclude inactive users in the response; defaults to false
- Example
- Response
GET /reports/paid_orders
Returns all paid orders within the timeframe
Params time_start: String time_end: String
payment_status: String (optional) - One or more of “ALL”, “PENDING”, “UNPAID”, “PAID”, “PARTIALLY_PAID”, “REFUNDED”, “PARTIALLY_REFUNDED” (comma separated; defaults to ALL to if left blank)
- Example
- Response
GET /reports/order_items
Returns all ordered items paid within a timeframe
Params time_start: String time_end: String
- Example
- Response
GET /reports/shipments
Returns all shipments created within the timeframe
Params time_start: String time_end: String
- Example
- Response
GET /reports/refunds
Returns all refunds submitted within the timeframe
Params time_start: String time_end: String
- Example
- Response
GET /reports/manifest_items
Returns all manifest items created within the timeframe
Params start_date: String end_date: String
- Example
- Response
GET /manifests
Returns all manifests created within the timeframe
Params page: Integer (optional). Defaults to 1
per_page: Integer (optional) - How many items to return per call. Defaults to 5, max 100.
sort: String (optional) - Each key in the manifest response can be sorted by adding either “.desc” or “.asc”, eg: “sort=created_at.desc”
supplier_id: Integer (optional) - Filter manifests by a particular supplier.
barcode: String (optional) - Filter manifests by a barcode. This supports partial matching.
state: String (optional) - Filter manifests by a status. Options include CREATED, MISSING, READY_FOR_PICKUP, IN_TRANSIT, RECEIVED, PARTIALLY_PROCESSED, PROCESSED
- Example
- Response
POST /api/manifests
Creates a manifest
- Params
- Example
- Response
PUT /api/manifests
Update a manifest
- Params
- Example
GET /event_logs
Returns all event logs in the given timeframe
Params
created_between: String represented as an array - Must provide two timestamps to search event logs. Eg: “created_between[]=2022-08-01&created_between[]=2022-08-03”
user_id: Integer (optional) - Filter logs by a particular user
per_page: Integer - default 20, max 100. How many entries to return in each call.
cursor: String - the information to get the next or last page of results, this is the value provided from the previous call and will return the results based on the previous_cursor or next_cursor token provided
- Example
- Response
Inventory Management
GET /v4/products (Get products)
Returns a product and all of its listings by product ID.
- Params
- Example
- Response
GET /v5/products (Get products)
Returns a list of products
Params
tags[]: String represented as an array - Name of the tag to filter by
query: String - Search by title or SKU
- Example
- Response
POST /v5/products (Create products)
Creates either a draft or a live product. Only “title” is required if draft=True.
- Params
- Example
- Response
PUT /v4/products (Update product or variants)
- Params
- Example
Update a product
- Update variant(s)
- Response
GET /v5/images/presign
Get info to upload an image to the Lister data storage
Params
- type: String - the mime-type of the kind of upload, eg “image/jpg”.
- Example
- Response
Uploading images
Uploading images to Lister takes part in 3 steps
- Call our secure presign API to authorize a direct upload to the Lister S3 bucket.
- Initiate a direct multipart form upload using the response data from Step 1
- Update the product in Lister with the location of the image in S3
To best illustrate ****how to do this, we’ll use an example in JS
POS
POST /api/pos/products_sold
Mark product as sold in store
- Params
Where sku-1 and sku-2 are skus of products to mark as sold in store:
- Example
- Response
Admin
GET /api/users
Get a list of all users ever for your organization
- Params
show_all - Optional. Query parameter to include inactive users. When this parameter is omitted, only active teammates will be returned. - Example
- Response
GET /api/inventory_locations
Get a list of all inventory locations
- Example
- Response
