suzuri-api

SUZURI API Reference

SUZURI (suzuri.jp) is a print-on-demand service operated by GMO Pepabo. Its public REST API allows creating, searching, and displaying original goods.

Latest API specification: https://suzuri.jp/developer/documentation/v1 Recommended upload image size by item: https://suzuri.jp/item_templates

This skill is baseline information. When implementing, prioritize the latest information above.

API Overview

Item	Value
Base URL	https://suzuri.jp/api/v1
Protocol	HTTPS required
Request format	GET: query string, POST/PUT/DELETE: application/json
Response format	JSON
JSON schema	GET https://suzuri.jp/api/v1/schema

Authentication

API key

For apps tied to your own account.https://suzuri.jp/developer/apps Issued at .

Authorization: Bearer {api_key}

Scope: read(read) / write(create, update, delete)

Note: Private products of the key issuer themselves are also retrieved. If handling only public products, filter with the published field.

OAuth 2.0

For apps where multiple users each operate with their own account.

1. GET https://suzuri.jp/oauth/authorize に client_id, scope, redirect_uri, response_type=code Specify
2. After user authorization,redirect_uri に code is returned
3. POST https://suzuri.jp/oauth/token で grant_type=authorization_code, code, redirect_uri, client_id, client_secret Send (Content-Type: application/x-www-form-urlencoded）

App registration is done at https://suzuri.jp/developer/apps . Since only one callback URL can be set per app, a separate app registration is required for each environment.redirect_uri requires HTTPS.

How to choose an authentication method

Aspect	API key	OAuth
Goods creation destination	Key issuer's shop	App user's shop
Access to private goods	Only the issuer's own	The user's own
Use case	Managing your own shop, personal tools	Multi-user apps

Resource structure

Item（アイテム: Tシャツ、マグカップなど商品種類）
  └── ItemVariant（色・サイズの組み合わせ）

Material（素材: ユーザーがアップロードしたデザイン画像）
  └── Product（商品: Material × Item の組み合わせ）

Choice（オモイデ: 商品のコレクション）
  └── Product（商品を追加）

Favorite（ズッキュン: 商品へのいいね）

When a Material is created, a Product is automatically generated for the specified item. When a Material is deleted, all linked Products are also deleted.

Endpoint list

For detailed parameters and response formats, refer to references/api-reference.md .

Operation	Method	Endpoint
Item list	GET	/items
Material list	GET	/materials
Create material	POST	/materials
Create text material	POST	/materials/text
Update material	PUT	/materials/{id}
Delete material	DELETE	/materials/{id}
Product list	GET	/products
Product details	GET	/products/{id}
Product Search	GET	/products/search
Sale Products	GET	/products/on_sale
Omoidé List	GET	/choices
Create Omoidé	POST	/choices
Update Omoidé	PUT	/choices/{id}
Delete Omoidé	DELETE	/choices/{id}
Zukkyun List	GET	/products/{id}/favorites
Add Zukkyun	POST	/products/{id}/favorites
Delete Zukkyun	DELETE	/products/{id}/favorites
User List	GET	/users
User Details	GET	/users/{id}
My Information	GET	/user
Activity	GET	/activities
Unread Count	GET	/activities/unreads

Implementation Patterns

Display the product list

GET /api/v1/products?userName={your_name}
Authorization: Bearer {token}

• Product Image: sampleImageUrl(WebP) recommended.imageUrl is a template URL and requires parameter substitution
• Product Page Link: sampleUrl Use

Create goods from an image

POST /api/v1/materials
Content-Type: application/json
Authorization: Bearer {token}

{
  "texture": "https://example.com/image.png",
  "title": "デザイン名",
  "price": 100,
  "description": "説明文",
  "products": [
    { "itemId": 1, "published": true }
  ]
}

• texture: Image URL or data URI
• price: Tribun (creator's share). Integer of 0 or greater
• products: itemId は GET /api/v1/items Retrieve in advance with
• resizeMode: contain(Fit) / cover(Fill, some items only)
• Some Items, such as embroidered items, do not support product creation via the API

Goods creation flow with preview

1. POST /api/v1/materials Create goods with
2. In the response, sampleImageUrl Display preview with
3. Purchase: sampleUrl Navigate to / Cancel: DELETE /api/v1/materials/{id} Delete including the material with

Create goods from text

POST /api/v1/materials/text
Content-Type: application/json
Authorization: Bearer {token}

{
  "text": "Hello World",
  "itemVariantId": 123
}

• text: Within 255 characters
• itemVariantId: Target item variation ID

Search for products

GET /api/v1/products/search?q={keyword}&limit=20&offset=0

Pagination

List APIs support limit と offset .

• limit: Number of items to retrieve (default 20–30, maximum 50)
• offset: Start position (default 0)
• meta.hasNext が true If , the next page exists

Rate Limits

Check in the response header: X-Ratelimit-Limit / X-Ratelimit-Remaining / X-Ratelimit-Reset

Target endpoints: POST /materials, PUT /materials/{id}, POST /materials/text, POST /products/{id}/favorites

Error Handling

Determine by HTTP status code (the contents of the response body are not guaranteed).

Code	Meaning
200	Success
201	Creation successful
204	Success (no body)
401	Authentication error
40x	Client error
50x	Server error

Image URL Template

sampleImageUrl If you use , no substitution is needed. If a custom size is required, imageUrl Substitute the following in :

• {width}x{height}: Image size
• {size}: Size specification
• {color}: Color specification
• [/angle]: Display angle (front, back, etc.)

Price Calculation

商品価格 = 素材のトリブン + アイテムバリエーション価格 + プリント箇所追加価格

In the API response, priceWithTax includes the final price including tax.