Skip to main content
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

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.