Commerce API: your first request

Requests go to your shop installation. api.netseller.net hosts the reference, not the API for your shop.

1. Prepare access

Obtain an API key with settings:read, catalog:read and an assigned shop from the operator. Keep it server-side. These examples use Bash and curl; replace the example host with your installation.

export NETSELLER_API_BASE_URL="https://shop.example.com/api/v1"
# Set NETSELLER_API_KEY from your secret store before protected requests.
curl -sS "$NETSELLER_API_BASE_URL/status"

The status endpoint is public. A successful response contains data.status: "ok".

2. Find your shop

curl -sS \
  -H "Authorization: Bearer $NETSELLER_API_KEY" \
  "$NETSELLER_API_BASE_URL/shops?page=1&perPage=25"

This requires settings:read. Use a returned shop ID in subsequent requests. With exactly one active assigned shop, NetSeller can select it when shopId is omitted.

3. Read products

Replace 2 with your shop ID:

curl -sS \
  -H "Authorization: Bearer $NETSELLER_API_KEY" \
  "$NETSELLER_API_BASE_URL/products?shopId=2&page=1&perPage=25"

This requires catalog:read. Responses use data, meta and errors; collection metadata includes pagination.

Handle failures

Status	Check
401	Missing or invalid key
403	Required scope and shop assignment
422	Request parameters or body
428	Required concurrency precondition missing
412	Stale or invalid validator; read the resource again

Preserve X-Request-ID or meta.requestId when reporting a problem. For writes, follow the endpoint’s Idempotency-Key and If-Match requirements. Reuse an idempotency key only for a retry of the same request.

See the API reference for schemas, scopes and write examples.