Overview
The two ShopEazy APIs, which one you need, and what they cost to use.
ShopEazy has two public APIs. Both are served from one base URL:
https://api.shopeazy.co| Storefront API | Merchant API (Beta) | |
|---|---|---|
| Path prefix | /v1/store | /v1/merchant |
| Credential | A per-store key (sez_pub_... or sez_sk_...) | A person's OAuth access token |
| Acts as | The store, towards its shoppers | A person who works for the business |
| Used by | Your own site or app for one store | Tools and AI apps that run a shop for a merchant |
| Client | @shopeazy/storefront-client | @shopeazy/merchant-client |
| Plan | Growth and Scale | Every plan |
Which one do you need
- Building a site or app for one store? Use the Storefront API. Read the catalogue, quote and place orders, take payment, run membership and file enquiries. The merchant issues you a key and can revoke it.
- Building a tool that works on a merchant's behalf? Use the Merchant API. The merchant connects your app, chooses what it may do, and can disconnect it at any time. The ShopEazy mobile app and connected AI apps use this API.
You can use both. They are separate credentials, and neither can do the other's job.
Beta
The Merchant API is in Beta (version 0.9). Its contract is still settling, so expect new operations and fields, and read the changelog before you upgrade.
Versions
Both APIs are versioned under /v1. Within v1 a contract only grows: new operations, optional fields, enum values and error codes. Anything that goes away is deprecated first, with at least 90 days' notice and Deprecation and Sunset headers. Breaking changes only ever ship under a new prefix, /v2, beside v1. Read Versioning and deprecation for the full promise.
Today the Storefront API contract is at version 1.5.0 and the Merchant API contract is at 0.9.
Plans
The Storefront API comes with the Growth and Scale plans, and while a business is on a live trial. A store on Starter has the hosted storefront only: its keys answer 403 plan_limit until it upgrades, and the console will not issue a key. Keys and data are kept, so upgrading again brings the site straight back.
The Merchant API works on every plan. A few operations need a bigger plan or an add-on, and writes are refused with 403 subscription_locked while a plan is not active. See Plans.
What is served today
The Storefront API contract describes every operation the hosted storefront has, so a site built outside ShopEazy can do all a hosted store does. Some of those operations are coming soon: they are in the contract, and their routes are being built. Each page of the Storefront API reference says so on the operation.
Coming soon on the Storefront API:
- Discount codes
- Bank transfer (EFT) payment
- Courier locker search
- Categories and search
- Tour departures
- Reviews, read side
- The shopper's address book, profile, and email verification and password reset codes
- Navigation, pages, home content, announcement bar and pop-up
- Newsletter sign-up
- Saved baskets
This documentation only describes served operations as available.