Skip to main content
cURL

Authorizations

​
Authorization
string
header
required

An API key: Authorization: Bearer alura_sk_....

Query Parameters

​
q
string

Words to find in the title, tags, materials, category or shop name; every word must match.

Example:

"mug"

​
category_id
string

An Etsy category ID (see /v1/categories); matches the category and every category under it.

Pattern: ^[1-9][0-9]{0,9}$
​
price_min
string

Lowest price in USD.

Pattern: ^\d{1,9}(\.\d{1,2})?$
​
price_max
string

Highest price in USD.

Pattern: ^\d{1,9}(\.\d{1,2})?$
Example:

"30"

​
est_sales_min
string

Fewest estimated lifetime sales.

Pattern: ^\d{1,10}$
​
est_sales_max
string

Most estimated lifetime sales.

Pattern: ^\d{1,10}$
​
est_monthly_sales_min
string

Fewest estimated sales per month (average).

Pattern: ^\d{1,10}$
​
est_monthly_sales_max
string

Most estimated sales per month (average).

Pattern: ^\d{1,10}$
​
reviews_min
string

Fewest reviews.

Pattern: ^\d{1,10}$
​
listed_after
string

Listed on Etsy at or after this time.

Pattern: ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d{1,3})?)?(Z|[+-]\d{2}:\d{2}))?$
​
listed_before
string

Listed on Etsy at or before this time.

Pattern: ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d{1,3})?)?(Z|[+-]\d{2}:\d{2}))?$
​
who_made
enum<string>

Who made the product.

Available options:
i_did,
someone_else,
collective
​
when_made
enum<string>

When the product was made.

Available options:
made_to_order,
2020_2025,
2020_2024,
2020_2023,
2010_2019,
2006_2009,
2000_2005,
before_2006,
1990s,
1980s,
1970s,
1960s,
1950s,
1940s,
1930s,
1920s,
1910s,
1900s,
1800s,
1700s,
before_1700
​
is_digital
enum<string>

true: digital downloads only; false: physical products only.

Available options:
true,
false
​
is_personalizable
enum<string>

Whether the seller offers personalization.

Available options:
true,
false
​
free_shipping
enum<string>

Whether shipping is free.

Available options:
true,
false
​
shop_country
string

The shop's country, as an ISO 3166-1 alpha-2 code (US).

Pattern: ^[A-Za-z]{2}$
​
sort
enum<string>
default:relevance

relevance (default: best match for q, else most estimated sales), or a field. Sorting by a field leaves out products where that value is unknown. est_revenue orders by Alura's stored lifetime revenue, which values each sale at the price when it was estimated; est_lifetime_revenue_usd values every sale at today's price, so products whose price changed can appear out of order by that value.

Available options:
relevance,
est_sales,
est_monthly_sales,
est_revenue,
price,
newest,
reviews,
listing_score
Example:

"est_sales"

​
order
enum<string>

desc (default) or asc. Not accepted with sort=relevance, which is always best match first.

Available options:
asc,
desc
​
limit
integer

Page size: default 25, at most 100.

Required range: 1 <= x <= 100
​
cursor
string

The next_cursor of the previous page. Bound to the query, the workspace and the key.

​
fields
string

Comma-separated dotted paths to return; id, object and as_of always come back.

Response

OK

​
object
string
required
Allowed value: "list"
​
data
object[]
required
​
has_more
boolean
required
​
next_cursor
string | null
required
​
total
object
required