Suzuri APIsuzuri.jp ↗
Access Suzuri.jp product details, creator profiles, user catalogs, keyword search, and item types via 5 structured JSON endpoints.
What is the Suzuri API?
The Suzuri.jp API exposes 5 endpoints covering product details, creator profiles, and keyword search across Japan's print-on-demand merchandise platform. The get_product endpoint returns title, price in JPY, category, availability, and image URL for any variant product ID. The search_products endpoint accepts a keyword query and optional page number, returning matching product IDs and canonical URLs for further lookup.
curl -X GET 'https://api.parse.bot/scraper/71908d50-afe7-444e-874e-c37df6af0fb8/get_product?product_id=82832311' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace suzuri-jp-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""SUZURI marketplace: search products, explore sellers, browse item types."""
from parse_apis.suzuri_api import Suzuri, NotFoundError
client = Suzuri()
# Search for products by keyword — limit caps total items fetched.
for result in client.products.search(query="cat", limit=3):
print(result.id, result.url)
# Drill into the first search result to get full product details.
hit = client.products.search(query="anime", limit=1).first()
if hit:
product = hit.details()
print(product.name, product.price, product.currency)
# Fetch a product directly by its variant ID.
try:
detail = client.products.get(product_id="82832311")
print(detail.name, detail.brand, detail.price_with_tax)
except NotFoundError as exc:
print(f"Product gone: {exc}")
# Browse a creator's shop via the constructible User resource.
user = client.user(name="beecat88")
for item in user.products.list(limit=3):
print(item.title, item.price_with_tax, item.item.humanize_name)
# List available item types on the platform.
for it in client.itemtypes.list(limit=5):
print(it.humanize_name, it.image_url)
print("exercised: products.search / products.get / hit.details / user.products.list / itemtypes.list")
Retrieve full details of a specific product including title, price, description, brand, and availability. Uses the variant product ID (as returned by search_products or get_user_products). Returns stale_input with kind 'input_not_found' if the product does not exist.
| Param | Type | Description |
|---|---|---|
| product_idrequired | string | The variant product ID (e.g., '82832311'). This is the 'id' field from search_products or get_user_products results. |
{
"type": "object",
"fields": {
"id": "string, the product variant ID",
"url": "string, canonical product URL on suzuri.jp",
"name": "string, product name including item type",
"brand": "string or null, seller/brand name",
"image": "string, URL of product image",
"price": "integer, price before tax in JPY",
"category": "string or null, product category name in Japanese",
"currency": "string, currency code (JPY)",
"description": "string, product description",
"availability": "string, schema.org availability URL",
"priceWithTax": "integer or null, price including tax in JPY"
},
"sample": {
"data": {
"id": "82832311",
"url": "https://suzuri.jp/beecat88/19451304/t-shirt/s/black",
"name": "チベットモンキー Regular Fit T-Shirt",
"brand": "B-shop",
"image": "https://lens.suzuri.jp/v3/500x500/t-shirt/s/black/front/19451304/1771570155-8485x2943.png.1.0+0.0+0.1204.jpg?h=e86404b22e2837f1432f191874ac37633b081de5&printed=true",
"price": 4380,
"category": "スタンダードTシャツ",
"currency": "JPY",
"description": "チベットモンキーを描きました。",
"availability": "http://schema.org/InStock",
"priceWithTax": 4818
},
"status": "success"
}
}About the Suzuri API
Product and Search Endpoints
The get_product endpoint takes a product_id string (a variant ID surfaced by search_products or get_user_products) and returns a full product record: id, name, brand, price (pre-tax integer in JPY), currency, category (Japanese text), description, image, url, and availability as a schema.org URL. If the product ID does not exist, the response includes a stale_input field with kind input_not_found. The search_products endpoint accepts a query string plus optional page and limit parameters; results are an array of objects with id and url, suitable for feeding into get_product for detailed data.
Creator and Catalog Endpoints
get_user retrieves a creator's profile by username, returning a numeric id, name, displayName, avatarUrl, and a profile object containing a body field with the bio text. get_user_products lists all products sold by a given username with cursor-based pagination: each response includes a pageInfo object with endCursor and hasNextPage, plus a products array whose items carry id, title, url, sampleImageUrl, priceWithTax, and nested item details. Pass pageInfo.endCursor as the cursor parameter to walk through the full catalog, and use limit to control page size.
Item Type Catalog
get_item_list requires no inputs and returns the full list of product types available on the platform — objects with id, name (slug), humanizeName (display label), and imageUrl. This is useful for understanding the product type vocabulary referenced in individual product records or for building filters in a catalog browser.
The Suzuri API is a managed, monitored endpoint for suzuri.jp — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when suzuri.jp changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official suzuri.jp API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Monitor JPY price changes on specific Suzuri variant products by polling
get_productwith tracked IDs - Build a creator directory by fetching profile bios and avatars via
get_userfor a list of usernames - Paginate through a creator's full product catalog using
get_user_productswith cursor-based iteration - Run keyword searches with
search_productsto discover products matching a theme, then enrich results withget_product - Enumerate all available merchandise types (t-shirts, stickers, hoodies) using
get_item_listto populate a filter UI - Aggregate product availability and pricing data across multiple creators for comparison tools
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Suzuri.jp have an official developer API?+
What does `get_user_products` return, and how does pagination work?+
get_user_products returns a products array and a pageInfo object per response. Each product includes id, title, url, sampleImageUrl, priceWithTax, and item details. When pageInfo.hasNextPage is true, pass the pageInfo.endCursor string as the cursor parameter in your next request to retrieve the following page. The limit parameter controls how many products appear per page.Does `search_products` return full product details?+
search_products returns only id and url per result — not price, description, or availability. To get full product data, pass each returned id to get_product. The limit parameter caps the number of results client-side, and page controls which page of the platform's results to read.Are product reviews or ratings available through this API?+
Is there a limitation on how `get_item_list` categorizes products?+
get_item_list returns item types in the t-shirts category only — it does not enumerate all merchandise categories on Suzuri. The response includes id, name, humanizeName, and imageUrl per item type. If you need item types from other categories, you can fork this API on Parse and revise the endpoint to target additional category data.