Postman collections
Ready-to-import Postman collections for every POS GROVE API category. Each request comes with its path and query parameters, an example body, a saved example answer and the permission it needs — so you can make your first call in a couple of minutes.
Overview
- POS API — your own POS GROVE installation (
https://your-store/api/v1): 94 requests in 15 categories. Download one category, or all of them in one collection with a folder per category. - Domain & wallet API — POS GROVE (
https://update.posgrove.com/api/v1): 19 requests for domains, DNS, nameservers, orders and the wallet. - Format: Postman Collection v2.1. The collections are generated from the same source as this reference (openapi.json), so they always match it.
- Every collection signs requests for you and checks that each answer has the standard
{ "success": … }envelope (see the Tests tab).
Import into Postman
From a file: download a collection below, then in Postman choose Import (or press Ctrl/⌘ + O) and drop the file in.
From a link (nothing to download; importing the same link again later offers to replace your copy with the latest version): choose Import, paste the link and press Enter. For example, every POS API endpoint:
https://posgrove.com/docs/postman/pos-api-all.postman_collection.json
Then open the collection, go to Variables and set baseUrl (and your key or token — next section). Save with Ctrl/⌘ + S.
Sign in
| Collection | baseUrl | Credential |
|---|---|---|
| POS API | Your POS GROVE address followed by /api/v1, e.g. https://shop.example.com/api/v1 | Paste an API key (Online store → API & Webhooks) into accessToken, or run Sign in → Get an access token with a username and password: the token (valid 12 hours) is saved into accessToken automatically. |
| Domain & wallet API | Already set to https://update.posgrove.com/api/v1 | Create a key under Account → Developer API and paste it (pgk_…) into apiKey. |
Requests that need no credential (getting a token, listing domain prices) are set to No auth. Treat keys and tokens like passwords: keep them out of shared workspaces and exported collections, or store them in an environment variable marked secret.
POS API, by category
Each category collection works on its own: it includes the Get an access token request in a Sign in folder.
| Category | Requests | What it covers | Download |
|---|---|---|---|
| All POS API endpoints | 94 | Every category in one collection, one folder per category. | Download |
| Authentication | 4 | Get an access token with a username and password, or use an API key created in Online store > API & Webhooks. Send either as `Authorization: Bearer <token>` (API keys may also use `X-API-Key`). | Download link |
| Users | 5 | Staff accounts. Password hashes, two-factor secrets and session data are never returned. API keys need the `admin` scope. | Download link |
| Stores | 2 | Stores (branches). Without the pos.stores permission you only see the store your account is assigned to. API keys need the `pos` scope. | Download link |
| Products | 8 | Products, variants, prices and stock. Reading needs pos.products or pos.pos; changes need pos.products. Cost prices are only shown with pos.products. API keys need the `pos` scope. | Download link |
| Orders & refunds | 8 | Sales orders and refunds. Reading needs pos.sales or pos.pos; selling needs pos.pos. Orders are created in your store with catalogue prices. API keys need the `pos` scope. | Download link |
| Customers | 6 | CRM customers, with loyalty balances. Reading needs crm.customers (or pos.pos, for looking up customers at the till); changes need crm.addcustomer. API keys need the `crm` scope. | Download link |
| CRM | 6 | Leads (crm.leads), support tickets (crm.view), the loyalty report (crm.loyalty) and a customer timeline. API keys need the `crm` scope. | Download link |
| HR | 7 | Employees (hr.employees), attendance (hr.attendance), leave (hr.leaves) and payroll (hr.payroll). Read only. API keys need the `hr` scope. | Download link |
| Finance | 21 | Read-only access to the Finance module. Each list needs the matching Finance permission (e.g. financial.finexpenses). API keys need the `finance` scope. | Download link |
| Projects | 5 | Projects (project.project) and tasks (project.alltask), limited to the ones you take part in. API keys need the `projects` scope. | Download link |
| Reports | 3 | Sales reports (pos.report or pos.sales). Cancelled and refunded orders are left out. Default period: the last 30 days. API keys need the `reports` scope. | Download link |
| Admin | 3 | Activity log, permissions and settings. API keys need the `admin` scope. | Download link |
| Notifications | 2 | Your own in-app notifications (the bell). No extra permission needed. API keys need the `notifications` scope, or plain read/write. | Download link |
| Webhooks | 12 | Send events to other systems. Each delivery is a signed JSON POST (see the X-Webhook-Signature header: HMAC-SHA256 of "<timestamp>.<body>" with the webhook secret), retried with growing delays when the receiver is down. Needs pos.onlinestore; API keys need the `admin` scope. | Download link |
| AI assistant | 2 | Questions about sales, stock, customers, finance, HR and projects, answered from this installation's data without any internet service. API keys need the `ai` scope (or plain read) plus the scope of the data asked about. | Download link |
Domain & wallet API
Search, register, renew and manage domains, DNS and nameservers, paid from your POS GROVE wallet. Paid from your POS GROVE wallet; see the Domain & wallet API reference for prices, errors and limits.
Download the collection (19 requests)
https://posgrove.com/docs/postman/domain-wallet-api.postman_collection.json
Environments
Optional. Use an environment when you work with more than one store (for example a test and a live installation): import it, fill in the values, and pick it in the top-right corner of Postman. Environment values take priority over the collection's variables.
- POS API environment —
pos-grove-store.postman_environment.json - Domain & wallet API environment —
pos-grove-domains.postman_environment.json
Tips
- Path values such as
:idare filled in on the request's Params tab. Optional query parameters are listed there too, switched off — tick the ones you need. - Requests that change data (
POST,PUT,PATCH,DELETE) work on your real data. Try them on a test store first. - For
PATCHrequests the body starts empty: send only the fields you change. The request's description lists the fields. - Each request's Examples show a typical successful answer.
- Run a whole folder with the Collection Runner to smoke-test an installation after an update.
- Permission and scope notes in each description tell you what the user or API key must be allowed to do; a missing permission answers
403.
Other API tools
Insomnia, Bruno, Hoppscotch and Thunder Client import Postman v2.1 collections directly. Tools that prefer OpenAPI (Swagger UI, Stoplight, code generators) can use openapi.json.