NogPets Shop API
Pet food, toys, beds and accessories. Only while the shop is open (else `SHOP_OFF`).
Pet food, toys, beds and accessories. Only while the shop is open (else `SHOP_OFF`).
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/nogpets-com:nogpets-com-shop-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: NogPets Shop API
version: 1.4.0
summary: Run your pet grooming business from any AI assistant; register a pet business from anywhere; book grooming, walks and sitting in Stellenbosch.
description: '**Run your pet business** (tag Run, scope `business:manage`): the owners, managers and
staff of an approved NogPets business run it from their assistant. Today''s day plan per
van or walker, bookings, clients and notes, prices, working hours, time off, service
areas, earnings, payouts and who hasn''t paid; book a phone or walk-in client, rebook,
move or cancel, send a client their Payfast link, and make an invoice link with a QR
code for any amount. Staff read their own day; owners and managers make changes.
Every change is logged with the assistant''s name, and anything that touches bookings,
prices, areas or money answers `CONFIRM_REQUIRED` with a summary first. Booking through
NogPets is for South African businesses (rand, Johannesburg time); elsewhere those tools
answer `NOT_AVAILABLE_IN_COUNTRY` and the rest works in the business''s own currency and
time zone.
**For pet businesses, anywhere in the world** (tag Business, scope `business:write`):
a groomer, dog walker or pet sitter registers and manages their business on NogPets
through their own assistant, in their own country, currency and time zone. Every
application is a draft until NogPets approves it.
**For pet owners in Stellenbosch, South Africa**, where NogPets runs its own vans and
walkers: check coverage, prices and open times without signing in; with the person''s
permission, book, move, cancel and pay, and buy from the shop when it is open. A request
we can''t serve (another town or country, or a fully booked week) is noted for a person
at NogPets to follow up (`NO_COVERAGE` / `NO_AVAILABILITY` with `leadId` and `message`).
- **The person approves money.** A card booking or order comes back with a `payUrl`
the person opens to pay on Payfast. Nothing here takes a card. A cash booking needs
`confirm: true`, sent only after the person has seen the summary and said yes.
- **Same rules as the app.** Prices, coverage, open times and cancellation windows
come from the same server code; the API adds none of its own.
- Booking money is integer cents in South African rand (ZAR): `38000` is R380. Times
are ISO 8601 instants; booking local time is Africa/Johannesburg (UTC+2). A business
application''s prices are in the business''s own `currency` (minor units) and its hours
in its own `timezone`.
- Errors are `{"error": {"code", "message", "details"}}`; `code` is stable
(e.g. `NO_COVERAGE`, `SLOT_TAKEN`, `CONFIRM_REQUIRED`).
Reads marked public need no auth. Everything about a person needs an OAuth 2.1
access token (authorization code + PKCE) or a personal API key, as a Bearer token.
The same operations are MCP tools at `https://mcp.nogpets.com/mcp`.
**Business sign-up, in order** (the first call says the `country`):
startBusinessSignup → addBusinessServices → setServiceArea → addResources → setOperatingHours → inviteStaff
(optional) → connectPayfast (optional, South Africa only, merchant id only) →
getSignupStatus → submitBusinessForReview (`confirm: true` after the person saw the
summary). Every answer carries `next` and a `statusUrl` page for the person.'
contact:
name: NogPets
email: hello@nogpets.com
url: https://nogpets.com/developers
termsOfService: https://nogpets.com/terms
servers:
- url: https://api.nogpets.com
description: Production
security: []
tags:
- name: Shop
description: Pet food, toys, beds and accessories. Only while the shop is open (else `SHOP_OFF`).
paths:
/v1/products:
get:
operationId: browseShop
tags:
- Shop
summary: Shop products
description: Active products with variants and stock, and the delivery options. `SHOP_OFF` (409) while the shop is closed.
x-shop: true
x-mcp-tool:
name: browse_shop
title: Browse the shop
annotations:
readOnlyHint: true
destructiveHint: false
idempotentHint: true
openWorldHint: false
description: 'Lists what NogPets sells (food, toys, beds, accessories, care) with prices, sizes (variants) and stock, plus the delivery options and fees. Filter with `category`, `petType` or a search `q`.
Use a product''s `id` (and a variant''s `id` when it has variants) in quote_order and buy.
'
parameters:
- name: category
in: query
schema:
type: string
enum:
- FOOD
- TOYS
- BEDS
- ACCESSORIES
- CARE
- name: petType
in: query
schema:
type: string
enum:
- DOG
- CAT
- name: q
in: query
description: Words to look for in the name, blurb and tags.
schema:
type: string
maxLength: 100
responses:
'200':
description: Products and delivery options
content:
application/json:
schema:
$ref: '#/components/schemas/Catalogue'
'409':
$ref: '#/components/responses/Conflict'
'429':
$ref: '#/components/responses/RateLimited'
/v1/orders/quote:
post:
operationId: quoteOrder
tags:
- Shop
summary: Price a shop order
description: The server's prices, delivery, discount and total. Never fails on stock or a bad code; it reports them in `problems`, `discountError`, `shippingError`.
x-shop: true
x-mcp-tool:
name: quote_order
title: Price a shop order
annotations:
readOnlyHint: true
destructiveHint: false
idempotentHint: true
openWorldHint: false
description: 'Prices a shop order before buying: lines, delivery fee, discount, total, and any problems (out of stock, bad code, delivery not possible to that postal code). Needs `items` [{productId, variantId?, qty}] and `shippingMethod` (from browse_shop; `visit` rides along with the person''s next booking and needs `bookingId` and a token), plus `postalCode` for local delivery.
Show the person the total before buy.
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderQuoteRequest'
example:
items:
- productId: kibble-lamb
variantId: 2kg
qty: 1
shippingMethod: courier
responses:
'200':
description: The quote
content:
application/json:
schema:
$ref: '#/components/schemas/OrderQuote'
'400':
$ref: '#/components/responses/BadRequest'
'409':
$ref: '#/components/responses/Conflict'
'429':
$ref: '#/components/responses/RateLimited'
/v1/orders:
post:
operationId: buy
tags:
- Shop
summary: Place a shop order
description: 'Reprices, checks stock, and places the order. Card → PENDING_PAYMENT with a `payUrl`
(the order''s page with a Pay button). Cash (only add-ons to the person''s own cash
booking, `visit`) needs `confirm: true`.'
x-shop: true
security:
- oauth2:
- orders:write
- apiKey: []
x-scopes:
- orders:write
x-mcp-tool:
name: buy
title: Buy from the shop
annotations:
readOnlyHint: false
destructiveHint: false
idempotentHint: false
openWorldHint: false
description: 'Places a shop order for the person. Same inputs as quote_order, plus `shipTo` {line1, suburb?, city, province?, postalCode, notes?} unless `shippingMethod` is `visit`. Show the person the items and total from quote_order and get a yes first.
Card (default): the result has `payUrl`, the order''s page. Give it to the person to pay on Payfast; unpaid orders close after 24 hours.
Cash is only for add-ons to their own cash booking (`shippingMethod: visit`, `bookingId`) and needs `confirm: true`.
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderRequest'
responses:
'201':
description: The order
content:
application/json:
schema:
$ref: '#/components/schemas/OrderResult'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'409':
$ref: '#/components/responses/Conflict'
'429':
$ref: '#/components/responses/RateLimited'
components:
responses:
Unauthorized:
description: No token, or it's expired or revoked. The `WWW-Authenticate` header points at the resource metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: UNAUTHENTICATED
message: A NogPets access token or API key is needed.
Conflict:
description: 'A rule said no: `NO_COVERAGE`, `NO_AVAILABILITY`, `SLOT_TAKEN`, `TOO_LATE`,
`CONFIRM_REQUIRED` (with `details.summary`), `NOTHING_TO_PAY`, `SHOP_OFF`, `STOCK`,
`SHIPPING`, `DISCOUNT`, `CASH`, `FAILED_PRECONDITION`; business sign-up: `UNDER_REVIEW`,
`APPROVED`, `NOT_READY`, `TOO_MANY`, `LISTING_TAKEN`, `PAYFAST_ZA_ONLY`. `NO_COVERAGE`
carries `details.leadId`, `details.message` (tell the person) and `details.next`.
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
slotTaken:
value:
error:
code: SLOT_TAKEN
message: That time was just taken. Pick another.
confirm:
value:
error:
code: CONFIRM_REQUIRED
message: Show the person this summary and send confirm true once they say yes.
details:
summary: Full groom for Biscuit, Tue 29 Sep at 09:00, 14 Kromrivier Street. R440 cash on the day.
Forbidden:
description: The token lacks a scope (`INSUFFICIENT_SCOPE`, with `details.scope`).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: INSUFFICIENT_SCOPE
message: This needs the bookings:write scope.
details:
scope: bookings:write
RateLimited:
description: Too many requests (`RATE_LIMIT`). `Retry-After` says when to try again.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
BadRequest:
description: The input is wrong (`INVALID_ARGUMENT`, or a pricing code such as `ONE_PRIMARY`, `PET_TYPE`, `UNKNOWN_SERVICE`).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: ONE_PRIMARY
message: Pick one main service for Biscuit
schemas:
ShippingMethod:
type: object
required:
- id
- label
- feeCents
properties:
id:
type: string
label:
type: string
feeCents:
type: integer
eta:
type: string
postalCodes:
type: array
items:
type: string
OrderRequest:
type: object
additionalProperties: false
required:
- items
- shippingMethod
properties:
items:
type: array
minItems: 1
maxItems: 20
items:
$ref: '#/components/schemas/OrderItem'
shippingMethod:
type: string
maxLength: 40
postalCode:
type: string
pattern: ^[0-9]{4}$
bookingId:
type: string
pattern: ^[A-Za-z0-9_-]{1,128}$
discountCode:
type: string
maxLength: 32
shipTo:
$ref: '#/components/schemas/ShipTo'
paymentMethod:
type: string
enum:
- CARD
- CASH
default: CARD
confirm:
type: boolean
description: 'Cash only: true once the person said yes.'
Catalogue:
type: object
required:
- products
- shipping
properties:
products:
type: array
items:
$ref: '#/components/schemas/Product'
shipping:
type: array
items:
$ref: '#/components/schemas/ShippingMethod'
freeShippingOverCents:
type:
- integer
- 'null'
note:
type: string
OrderQuoteRequest:
type: object
additionalProperties: false
required:
- items
- shippingMethod
properties:
items:
type: array
minItems: 1
maxItems: 20
items:
$ref: '#/components/schemas/OrderItem'
shippingMethod:
type: string
maxLength: 40
examples:
- courier
- local
- visit
postalCode:
type: string
pattern: ^[0-9]{4}$
bookingId:
type: string
pattern: ^[A-Za-z0-9_-]{1,128}$
discountCode:
type: string
maxLength: 32
OrderResult:
type: object
required:
- orderId
- number
- status
- totalCents
- total
- payUrl
- next
properties:
orderId:
type: string
number:
type: string
examples:
- NP-1004
status:
type: string
totalCents:
type: integer
total:
type: string
payUrl:
type:
- string
- 'null'
format: uri
description: The order's page; a Pay button while unpaid.
next:
type: string
OrderItem:
type: object
additionalProperties: false
required:
- productId
- qty
properties:
productId:
type: string
pattern: ^[A-Za-z0-9_-]{1,128}$
variantId:
type: string
maxLength: 64
qty:
type: integer
minimum: 1
maximum: 20
Variant:
type: object
required:
- id
- label
- priceCents
- inStock
properties:
id:
type: string
label:
type: string
priceCents:
type: integer
inStock:
type: boolean
ShipTo:
type: object
additionalProperties: false
required:
- line1
- city
- postalCode
properties:
line1:
type: string
maxLength: 200
suburb:
type: string
maxLength: 80
city:
type: string
maxLength: 80
province:
type: string
maxLength: 40
postalCode:
type: string
pattern: ^[0-9]{4}$
notes:
type: string
maxLength: 500
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
description: Stable, upper-case.
message:
type: string
description: Short and human; safe to show.
details:
type: object
additionalProperties: true
Product:
type: object
required:
- id
- name
- category
- priceCents
- inStock
properties:
id:
type: string
name:
type: string
slug:
type: string
category:
type: string
blurb:
type: string
petTypes:
type: array
items:
type: string
priceCents:
type: integer
compareAtCents:
type:
- integer
- 'null'
variants:
type: array
items:
$ref: '#/components/schemas/Variant'
inStock:
type: boolean
deliverWithVisit:
type: boolean
image:
type:
- string
- 'null'
format: uri
contents:
type: array
description: A box's contents (bundles only); it's in stock when every item is.
items:
type: object
required:
- productId
- name
- qty
properties:
productId:
type: string
name:
type: string
variantLabel:
type: string
qty:
type: integer
OrderQuote:
type: object
required:
- items
- subtotalCents
- shippingCents
- totalCents
- problems
- ok
properties:
items:
type: array
items:
type: object
subtotalCents:
type: integer
discount:
type:
- object
- 'null'
discountError:
type:
- string
- 'null'
shippingMethod:
type:
- string
- 'null'
shipping:
type:
- object
- 'null'
shippingCents:
type: integer
shippingError:
type:
- string
- 'null'
totalCents:
type: integer
problems:
type: array
items:
type: object
ok:
type: boolean
securitySchemes:
oauth2:
type: oauth2
description: OAuth 2.1, authorization code with PKCE (S256), public clients. Register with `POST /oauth/register` (RFC 7591). Access tokens last an hour; refresh tokens rotate.
flows:
authorizationCode:
authorizationUrl: https://api.nogpets.com/oauth/authorize
tokenUrl: https://api.nogpets.com/oauth/token
refreshUrl: https://api.nogpets.com/oauth/token
scopes:
profile: See your name, email and phone
pets: See and add your pets
addresses: See and add your addresses
bookings:read: See your bookings
bookings:write: Book, move, cancel and get payment links for your bookings
orders:write: Place shop orders for you to pay
business:write: Set up and manage your pet business on NogPets
business:manage: Run your pet business on NogPets
apiKey:
type: http
scheme: bearer
bearerFormat: npk_…
description: A personal API key from the NogPets app (Profile → Connect an AI assistant). It carries the scopes chosen when it was made.