> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wristler.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# What a third-party integration can do

> Every endpoint with a yes or a no, and a reason for each no.

One page, so nobody has to read a reference to find out whether a thing is
possible. Everything below is either something your integration can do today, or
something it cannot — with the reason, because "no" without one is the answer
that gets asked again next month.

The short version: **a partner works inside a business.** Every address you use
carries the id of the business you are acting for, and you reach exactly the
businesses that connected you. There is no address that answers "what is on
Wristler" — that is not something we hand out, and it is not something a sync
needs.

## The matrix

| What | Endpoint | Scope | You? |
| - | - | - | :-: |
| Check your token works | `GET /v1/me` | — | ✅ |
| Get an access token | `POST /oauth/token` | — | ✅ |
| **Businesses** | | | |
| List the businesses you may act for | `GET /v1/sellers` | `watches:read` or `orders:read` | ✅ |
| Show one business | `GET /v1/sellers/{id}` | `watches:read` or `orders:read` | ✅ |
| **Inventory** | | | |
| Read what a listing may say | `GET /v1/specifications`, `GET /v1/specifications/{id}` | `watches:read` | ✅ |
| Find the model a listing is of | `GET /v1/watch-models` | `watches:read` | ✅ |
| Look a reference up | `GET /v1/references`, `GET /v1/references/{id}` | `watches:write` | ✅ |
| List a business's stock | `GET /v1/sellers/{id}/watches` | `watches:read` | ✅ |
| Create a listing | `POST /v1/sellers/{id}/watches` | `watches:write` | ✅ |
| Copy a listing you already have | `duplicateOf` on a create | `watches:write` | ✅ |
| Show a listing | `GET /v1/sellers/{id}/watches/{id}` | `watches:read` | ✅ |
| Quote the fee on a sale at a price | `GET /v1/sellers/{id}/application-fee` | `watches:read` | ✅ |
| Update a listing | `PATCH /v1/sellers/{id}/watches/{id}` | `watches:write` | ✅ |
| Delete a listing | `DELETE /v1/sellers/{id}/watches/{id}` | `watches:write` | ✅ |
| List the gallery | `GET /v1/sellers/{id}/watches/{id}/images`, `GET /v1/sellers/{id}/watches/{id}/relationships/images` | `watches:read` | ✅ |
| Reorder or trim the gallery | `PATCH /v1/sellers/{id}/watches/{id}/relationships/images` | `watches:write` | ✅ |
| Add images to a listing | `imageSources` on the listing | `watches:write` | ✅ |
| **Orders** | | | |
| List orders to fulfil | `GET /v1/sellers/{id}/orders` | `orders:read` | ✅ |
| Show one order | `GET /v1/sellers/{id}/orders/{id}` | `orders:read` | ✅ |
| Record a shipment | `PATCH /v1/sellers/{id}/orders/{id}` | `orders:write` | ✅ |
| Download an order's receipt | `GET /v1/sellers/{id}/orders/{id}/receipt` | `orders:read` | ✅ |
| List the couriers a shipment can name | `GET /v1/couriers` | `orders:read` or `orders:write` | ✅ |
| Read a business's own figures | `GET /v1/sellers/{id}/statistics`, `GET /v1/sellers/{id}/relationships/statistics`, `GET /v1/sellers/{id}?include=statistics` | `orders:read` | ✅ |
| Read a business's dashboard over a period (7 days, 30 days, this year) | `GET /v1/sellers/{id}/dashboard` | `orders:read` | ✅ |
| Read a shop's order-fee invoices, and download them | `/v1/sellers/{id}/invoices`, `/v1/sellers/{id}/invoices/{id}`, `/v1/sellers/{id}/invoices/{id}/pdf` | `orders:read` | ✅ |
| **Not available** | | | |
| Search the whole catalogue | `GET /v1/watches` | `catalogue:read` | ❌ |
| Show any listing on Wristler | `GET /v1/watches/{id}` | `catalogue:read` | ❌ |
| Show what else somebody might want | `GET /v1/watches/{id}/related` | `catalogue:read` | ❌ |
| List the brands, with logos and counts | `GET /v1/brands` | `catalogue:read` | ❌ |
| List the countries a checkout ships to | `GET /v1/shipping-countries` | `catalogue:read` | ❌ |
| Read a seller's conversations | `GET /v1/conversations`, `GET /v1/conversations/{id}` | `messages:read` | ❌ |
| Read the messages in a thread | `GET /v1/conversations/{id}/messages` | `messages:read` | ❌ |
| Start a thread | `POST /v1/conversations` | `messages:write` | ❌ |
| Send a message, or an offer | `POST /v1/conversations/{id}/messages` | `messages:write` | ❌ |
| Accept, refuse or withdraw an offer | `PATCH /v1/conversations/{id}/messages/{id}` | `messages:write` | ❌ |
| Mark a thread read, archive it | `PATCH /v1/conversations/{id}` | `messages:write` | ❌ |
| Report something in a thread | `POST /v1/conversations/{id}/reports`, `GET /v1/conversations/{id}/reports/{id}` | `messages:write`, `messages:read` | ❌ |
| Write about an order, from either side | `POST /v1/me/orders/{id}/conversation`, `POST /v1/sellers/{id}/orders/{id}/conversation` | `messages:write` | ❌ |
| Read what may be reported | `GET /v1/report-reasons` | `messages:read` | ❌ |
| Upload a file | `POST /v1/uploads` | `uploads:write` | ❌ |
| Add images by uploading them | `imageHandles` on a listing | `uploads:write` | ❌ |
| Register a device for push | `/v1/me/devices`, `/v1/me/devices/{id}` | `account:write` | ❌ |
| Edit the account behind the token | `PATCH /v1/me` | `account:write` | ❌ |
| Close the account | `POST /v1/me/deletion`, `DELETE /v1/me` | `account:write` | ❌ |
| Send a test notification to your own devices (not in production) | `POST /v1/me/test-pushes` | `account:write` | ❌ |
| Read what somebody bought | `GET /v1/me/orders`, `GET /v1/me/orders/{id}` | `account:read` | ❌ |
| Place an order and pay for it | `POST /v1/me/orders`, `POST /v1/me/orders/{id}/payment` | `checkout:write` | ❌ |
| Read where to transfer the money | `GET /v1/me/orders/{id}/payment-instructions` | `account:read` | ❌ |
| Keep a list of favorites | `/v1/me/favorites`, `/v1/me/favorites/{id}` | `account:read`, `account:write` | ❌ |
| Block a business, and unblock it | `/v1/me/blocks`, `/v1/me/blocks/{id}` | `account:read`, `account:write` | ❌ |
| Keep a shop's quick replies | `/v1/sellers/{id}/quick-replies`, `/v1/sellers/{id}/quick-replies/{id}` | `messages:read`, `messages:write` | ❌ |
| Block a buyer from a shop, and unblock them | `/v1/sellers/{id}/buyer-blocks`, `/v1/sellers/{id}/buyer-blocks/{id}` | `messages:read`, `messages:write` | ❌ |
| Manage a second factor | `/v1/me/two-factor`, `/v1/me/two-factor-setups`, `/v1/me/recovery-codes` | `account-security:write` | ❌ |
| Link and unlink Apple or Google | `POST /v1/me/identities`, `DELETE /v1/me/identities/{id}` | `account-security:write` | ❌ |
| See the account's recent sign-ins | `GET /v1/me/sign-ins` | `account-security:write` | ❌ |
| End one session elsewhere | `DELETE /v1/me/sign-ins/{id}` | `account-security:write` | ❌ |
| Sign out, here, everywhere else or everywhere | `DELETE /v1/me/tokens/current`, `DELETE /v1/me/tokens/others`, `DELETE /v1/me/tokens` | `account-security:write` | ❌ |
| Read and clear the notification bell | `/v1/me/notifications`, `/v1/me/notifications/{id}`, `POST /v1/me/notifications/read`, `DELETE /v1/me/notifications` | `account:read`, `account:write` | ❌ |
| Choose what to be told about | `/v1/me/notification-preferences` | `account:read`, `account:write` | ❌ |
| Change a business's own details | `PATCH /v1/sellers/{id}` | `business:write` | ❌ |
| Save a search and be told about it | `/v1/me/saved-searches`, `/v1/me/saved-searches/{id}` | `account:read`, `account:write` | ❌ |
| Preview a search before saving it | `/v1/me/saved-searches/preview` | `account:read` | ❌ |
| Download a buyer's receipt | `GET /v1/me/orders/{id}/receipt` | `account:read` | ❌ |
| Sign somebody up | `POST /v1/users` | — | ❌ |
| Read the terms and privacy statement | `GET /v1/legal` | — | ❌ |
| Reset a forgotten password | `POST /v1/password-resets`, `PATCH /v1/password-resets/{token}` | — | ❌ |
| Ask for the verification email again | `POST /v1/me/email-verifications` | `account-security:write` | ❌ |
| Keep an address book | `/v1/me/addresses`, `/v1/me/addresses/{id}` | `account:read`, `account:write` | ❌ |
| Read the filter pages | `/v1/filter-pages`, `/v1/filter-pages/{id}` | `content:read` | ❌ |
| Read Insights | `/v1/articles`, `/v1/articles/{id}`, `/v1/articles/{id}/author`, `/v1/articles/{id}/relationships/author`, `/v1/articles/{id}/tags`, `/v1/articles/{id}/relationships/tags` | `content:read` | ❌ |
| Read related Insights | `GET /v1/articles/{id}/related` | `content:read` | ❌ |
| Read the Insights tags | `/v1/article-tags`, `/v1/article-tags/{id}` | `content:read` | ❌ |
| Read the other pages | `/v1/pages`, `/v1/pages/{id}` | `content:read` | ❌ |
| See who the personal shoppers are | `GET /v1/personal-shopper` | `content:read` | ❌ |
| Read the help centre | `/v1/faq-categories`, `/v1/faq-categories/{id}`, `/v1/faq-categories/{id}/articles`, `/v1/faq-categories/{id}/relationships/articles`, `/v1/faq-articles`, `/v1/faq-articles/{id}`, `/v1/faq-articles/{id}/category`, `/v1/faq-articles/{id}/relationships/category` | `content:read` | ❌ |

## Why the "no"s

* **The catalogue.** `catalogue:read` is ours for now. It is the same data the
  website serves to anyone, so this is not secrecy — but "what is for sale
  everywhere" is a different product from "keep this shop in step", and opening
  it is a decision we would rather take deliberately. Ask us; the answer is one
  line of configuration, not a rebuild.
* **Buying.** `checkout:write` moves money between two of our customers, and the
  fees and the escrow account are between us and them. There is no version of this
  where a third party places the order.
* **Messaging.** Somebody's correspondence with their buyers is a different thing
  to be trusted with than their stock list, and a seller who connects a PIM is
  not agreeing to that.
* **Anything under `/v1/me`.** `account:read`, `account:write` and
  `account-security:write` are a person's own account — what they put aside, where
  they live, what they bought, what protects the account. A partner acts for a
  business, and a business has none of those. These are not scopes we expect to
  open.
* **The pages we write.** `content:read` — the filter pages and Insights. Same
  reasoning as the catalogue: it is published on the website for anyone to read,
  so this is not secrecy, and the same one line of configuration opens it. Ask.
* **Uploading files.** `POST /v1/uploads` and the `imageHandles` field that names
  what it returns. You do not need either: your images are already on a server of
  your own, so give the listing `imageSources` — the URLs — and we fetch them. One
  call instead of nine, and an unchanged set on the next sync costs nothing,
  because we hash what we already hold. Uploading is for a client holding the
  files themselves, which is the app adding a listing from somebody's phone.
* **Devices.** Push registration for the Wristler app. There is no app of yours
  for us to push to.
* **A business's own details.** Its registered address, its VAT number, where its
  invoices go, whether it takes offers: a shop's paperwork, not its stock. A
  seller changes it in their dashboard or in the app. Ask us if your product has
  a real reason to — it is a scope, so it is a decision we can take.
* **Accounts.** Signing somebody up, resetting their password, reading the
  terms: all of it is the Wristler app, checked by the client's own kind rather
  than by a scope, because these happen before there is a token. A partner
  integrates with a business that already exists — an account created through you
  is one we could not explain to whoever owns that address.
* **Somebody's account and address book.** You act for a business, not for a
  person, and a business does not have a home address a watch is shipped to. What
  you do need is on the order: `include=addresses` gives you the name and address
  the buyer entered, as a copy taken at the moment of sale.

## What you see that the app does not, and the other way round

The same endpoint can answer a partner differently from the Wristler app, on purpose:

* **`GET /v1/sellers`** lists only the businesses that connected you. The app gets
  the public shop directory, and its search filters (`filter[q]`, `filter[country]`)
  are the app's: sent by you they answer `400` with `search_only_filter`.
* **An order's `buyerEmail` and `buyerPhone`** are always `null` for you. They are
  the shop's dashboard on a phone, read by the people who work there; your system
  gets what shipping needs -- the addresses -- not a person's email address and
  phone number, which nobody agreed to hand to a third party.
* **A listing's `descriptionTranslations`** is never served to you, even when asked
  for in `fields`. Our translator maintains it; you write `description`, and
  `translatedDescription` reads it back in the language of `Accept-Language`.

A scope you may not request is refused at the token endpoint with `invalid_scope`,
when you exchange the authorization code. The authorization step does not check it
yet, so a seller can still be shown a consent screen that names it -- approving it
gets you no token. Ask only for the scopes marked ✅ above.

## Two rules worth knowing before you build

**A grant belongs to the business, not to the person who approved it.** When a
seller connects you, they tick which of their businesses you may act for and see
exactly which scopes you are asking for. Any of their colleagues can withdraw it
later, and it survives that person leaving. You reach those businesses and no
others — never the other businesses the approver happens to work at.

**What each business allowed is checked on every request, not baked into your
token.** Your token carries the union of what every business that connected you
agreed to, so the token alone cannot answer "may I do this here". A shop that
granted you reading answers `403` to a write even when another shop granted you
writing. Narrowing or withdrawing a grant takes effect immediately; there is no
token to wait out. A narrowed grant answers `403` with `missing_scope`; a withdrawn
one answers `404`, as a business that never connected you does.

**A listing from a Connect feed belongs to the feed.** It is maintained in the
seller's own application, and the fields that feed supplies are overwritten on
every import — so changing one here is refused with `409`, which names the
fields, rather than accepted and silently undone on the next run. Every other
listing is the seller's, and you are one of the ways they work on it, alongside
the dashboard and the app.

The full reference, with every field and a console to call from, is the
*API reference* tab of this site.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.