atouch API Overview

With atouch API, you can read and write product, order, and customer data from the existing atouch (Shop / Admin) platform through standard OpenAPI 3.1 + OAuth 2.1.

It is served in production at https://api.developers.atouch.jp. Alongside read access to products, orders, and customers, write access for inventory, shipping, and catalog management is available (all idempotent). See the tables below for details.

Access requires issued client credentials. Contact the operator to get started.

Available APIs (ReadOnly)

Area	Contents	Required scope
Items / Categories	Item list & detail, categories, delivery companies, own shop. Incremental fetch via updated_since, exact sku lookup	read_items / read_users
Orders	Order header, line items, shipments (buyer PII excluded). Incremental fetch via updated_since (for order polling)	read_orders
Order buyer PII	Purchaser / recipient name, address, phone	read_orders_pii
Customers	LINE identity, tags, orders	read_customers
Customer PII	Name / address / phone / email / gender	read_customers_pii

Available APIs (Write)

Area	Contents	Required scope
Inventory reservations	Reserve (hold) → confirm / release. Availability is checked atomically — no overselling. Reservations auto-expire via TTL (default 15 min)	write_reservations
Shipping status	Shipping status transitions (prepared → partial_shipped → shipped → re_shipped / returned), tracking number registration / correction	write_shipping
Stock updates	Set item stock to an absolute value (0–99999) or adjust by a delta. Items with variants require variant_id (set items are derived from their components)	write_items
Items	Create items (all kinds: normal / gift / ticket / free ticket / pre-sale ticket / set) and edit existing items (partial update, recorded in the merchant change log)	write_items
Categories	Create (up to 2 levels; sort auto-assigned to the end) and edit (name / status / sort)	write_items
Item images	Register or replace images by URL (JPEG/PNG, validated by actual bytes), reorder and delete. Create → image → publish completes via API alone	write_items
Variants	Declare axes (colour, size, …) and combinations at item creation; afterwards add and edit variants (end of sale = status: inactive). Axes are fixed at creation	write_items

All write endpoints require the Idempotency-Key header (resending the same key safely replays the result).

Only the operations that the existing admin UI itself logs are written to the merchant's change history — namely item edits, stock updates, and shipping status changes. Item creation, category operations, image operations, and variant operations are not recorded there, because the existing admin UI does not record them either (we do not invent history the platform never had). All API operations are captured separately in our own audit log.

Basics

• Base URL: https://api.developers.atouch.jp
• Protocol: HTTPS only
• Format: application/json; charset=utf-8
• Datetime (responses): ISO 8601 / RFC 3339 in UTC (e.g. 2026-06-01T03:00:00Z)
  Datetime (requests) comes in two flavors:
  ・Cursor timestamps (updated_since) — any offset is accepted (Z and +09:00 denote the same instant)
  ・Business timestamps (sell_from / sell_by / cancel_by, ticket fields) — YYYY-MM-DD HH:mm(:ss) only. Supplying an offset returns 400. The value is interpreted as the shop's local (JST) wall-clock time
  For incremental sync, pass the updated_at value from the response straight back as the next cursor. Deriving it from your own clock invites timezone drift.
• Money: { "amount": 3200, "currency": "JPY" }
• Envelope: collections use { "data": [...], "pagination": {...} } and errors use { "error": { code, message } }.
  Single resources generally use { "data": {...} }, but stock updates, image create/reorder/delete, and reservation endpoints return a bare object for backward compatibility (e.g. { "item_id": "1", "inventory": 20, "previous_inventory": 5 }). See each endpoint's response example.

Rate limits

Limits are applied per client (client_id). Defaults:

Type	Sustained rate	Burst
Reads (GET / HEAD)	5 req/sec	20
Writes (POST / PATCH / PUT / DELETE)	1 req/sec	4

• On exceeding a limit the API returns 429 ({ "error": { "code": "rate_limited" } }) with Retry-After (seconds) plus X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset. Wait for Retry-After before retrying.
• Burst is how many calls you can send back-to-back; the sustained rate is the long-run ceiling. Writes are set to 1/5 of reads.
• For bulk imports (e.g. an initial sync from another commerce platform), size your run against the write rate. As a guide, 1,000 items × (create + image + publish) ≈ 3,000 calls ≈ 50 minutes. Increasing concurrency does not raise the sustained rate.
• If your integration consistently needs more, ask us about a per-client increase.

Working with large volumes

We do not provide bulk create/update endpoints. Call the individual endpoints repeatedly.

• Attach an Idempotency-Key per item so you can safely retry and resume if the connection drops (replays of the same key are not processed twice)
• On 429, wait for Retry-After before continuing
• Hundreds to thousands of items complete in a practical amount of time within the limits above

⚠️ If repeated calls cannot meet your requirements, tell us the volume and frequency. We will consider bulk processing based on actual demand.

Integrating with external systems

Notes for two-way synchronisation with another commerce or inventory system.

• Send stock as a delta (adjustment). Pushing absolute values (inventory) on a schedule overwrites sales that happened on Atouch between pushes, inflating stock and causing overselling. Use absolute values only for the initial load and for periodic reconciliation.
• If adjustment fails with 422, re-sync with an absolute value — do not drop the delta (negative_inventory = result would go below zero, unlimited_inventory = the item tracks unlimited stock). Silently ignoring the failure loses the difference permanently.
• Origin of image fetches (allowlist these if your image host restricts access):

Item	Value
User-Agent	atouch-api/1.0 (+https://developers.atouch.jp)
Accept	image/jpeg,image/png;q=0.9,*/*;q=0.1

If you need to allowlist by source IP address, please contact us and we will share the current addresses. They are not published here because they can change with environment or infrastructure updates.

Handling of personal data (PII)

Buyer PII (name, address, phone, email, etc.) is returned only to tokens that hold the corresponding PII scope. Without it, those fields are omitted from the response entirely. Card numbers and payment-gateway tokens are never returned under any scope.

Continue to Getting Started to obtain a token and make your first call.