nayax-lynx-inventory

The Nayax Lynx inventory system organizes vending machine stock into a four-level hierarchy: product groups contain products, products are mapped to machines, and pick lists drive restocking trips.

Authentication

Every request uses a bearer token in the Authorization header:

Authorization: Bearer <user-token>

Get the token from the Nayax dashboard: click the menu with your name, go to Account Settings → Security and Login, scroll down to User Tokens, click Show Token, and copy it. This single value is what older docs called "Token", "API Token", or "Bearer Token" — they are the same credential. Lynx user tokens do not expire. A 401 with a response body means the token is valid but lacks permission for that endpoint; it does not mean the token expired.

Base URL

Sandbox base: https://qa-lynx.nayax.com/operational. Every path in this skill is relative to that base — for example, /v1/productGroups resolves to https://qa-lynx.nayax.com/operational/v1/productGroups.

Prerequisites: ActorID and MachineID

Steps 2 through 4 need an ActorID (your operator ID) and a MachineID. Neither is guessable:

• ActorID is the operator tied to your token. List the operators you can access with GET /v1/actors/hierarchy.
• MachineID is the numeric machine identifier. List machines with GET /v1/machines, or filter to one operator with GET /v1/machines?OperatorID={ActorID}, then read MachineID from each record. Do not use the machine serial — these paths take the numeric ID only.

The 4-step workflow

These steps must be completed in order. Skipping or reversing a step causes 400 errors or missing data downstream.

Step	Action	Endpoint	Reference
1	Create product groups	POST /v1/productGroups	<references/product-groups.md>
2	Create operator products	POST /v1/operators/{ActorID}/products	<references/products.md>
3	Map products to machines	POST /v1/machines/{MachineID}/machineProducts	<references/machine-products.md>
4	Generate pick lists for restocking	POST /v1/machines/{MachineID}/pickLists	<references/pick-lists.md>

Read the relevant reference file before writing code or answering questions about any of these steps.

Critical rules

• Always create product groups before products. Products require a valid ProductGroupID. There is no way to create a product without one.
• Tax endpoints on product groups are 403-gated. GET/POST/PUT/DELETE /v1/productGroups/{id}/tax return 403 with a standard operator token. Do not attempt these without confirmed elevated permissions.
• ProductGroupCode may be silently ignored. The API accepts the field on POST but does not appear to persist a caller-supplied value. Do not rely on ProductGroupCode for lookups — use ProductGroupID instead.
• Create Pick List returns an empty response body on success. POST /v1/machines/{MachineID}/pickLists returns 200 OK with no body. An empty body is the success state, not an error. Confirm creation with GET /v1/machines/{MachineID}/pickList.
• An empty pick list ([]) on a brand-new machine is normal. GET /v1/machines/{MachineID}/pickList returns [] when the machine has no sales or stock history yet. This means "nothing to restock right now," not a failure or a missing pick list. To see line items, the machine needs sales activity, or populate the list with PUT /v1/machines/{MachineID}/pickList.
• Update Pick List crashes with 500 if Products is empty. Always include at least one product object in the Products array when calling PUT /v1/machines/{MachineID}/pickList.
• Machine Products use NayaxProductID, not ProductID. NayaxProductID is the system-assigned identifier returned in the create-product response. The operator-scoped ProductID is a different field and will not resolve when mapping to a machine.

Key documentation

• Inventory Workflow — Canonical step order
• Product Groups — Group creation and management
• Operator Products — Product creation and field reference
• Pick Lists — Pick list generation and actions
• Security and Token — How to obtain and use bearer tokens