Your catalogue

A site’s catalogue is its products, the categories they sit in, the courses the kitchen sends them with, and the taxes they are charged with.

Codes

Every record is identified by its code. A code is the same at every site that has the record: a product copied to three venues is one code, so your system needs to store one value for it, whichever site it is reading.

Codes are made by Dnero when a record is created, and returned in the response. Store the code beside your own id for the record.

Products, modifier groups and modifiers

They are all products, with a type:

type	What it is	children
product	Sold on its own: a flat white.	Its modifier groups.
modifierGroup	A choice on a product: Milk. minChoices and maxChoices say how many options a customer picks.	Its options.
modifier	One option: Oat milk.	None.

So a flat white with a choice of milk is three kinds of record: the product, whose children include the Milk group, whose children are the milks. Read one kind with GET /products?type=modifierGroup.

Money

Prices are integers in the site’s currency’s minor units: 450 is $4.50 at a site trading in NZD. costPrice is what a product costs you, for reporting; it is never charged.

Keeping in sync

To mirror a site’s catalogue into your system:

1. The first time, read every page of each list, products and categories, and note the time you started.
2. After that, read each list with updatedSince set to when your previous sync started, and includeInactive=true so you also see what was retired.

Use the start time, not the end: anything changed while your previous sync was paging is then read again rather than missed. A record you have already seen may come round twice; apply it again by its code.

Changing the catalogue

A key with write catalogue access at a site can create and change its products and categories:

• POST /products and POST /categories create one. Send an Idempotency-Key with each.
• PATCH /products/{code} and PATCH /categories/{code} change one. Only the fields you send change.

The same rules apply as in the Dnero portal:

• names are unique among a site’s products, and among its modifiers;
• a product’s category and taxes must exist at the site and be active;
• a new product is available to sell straight away.

A request that breaks one is refused with 422 and the field in errors.

Modifier groups

Make the options first, as products of type modifier. Then make the group with them, and give the group to a product:

1. POST /products with "type": "modifier", once for each option: Oat milk, Soy milk.
2. POST /modifier-groups with "options" set to the modifiers’ codes, and how many a customer chooses (minChoices, maxChoices).
3. PUT /products/{code}/modifier-groups with the groups the product offers, in order.

Many at once

• Prices and cost prices: up to 500 products a call. All change together, or none do.
• Availability: sell products out (still on the menu, but not orderable) and bring them back, optionally at a set time.
• Pictures: from a public URL, copied into Dnero.

Other sites

POST /{kind}/copy copies products, categories, courses, taxes and tax groups to other sites, keeping their codes and bringing what they depend on, such as a product’s category. Every target site is checked before anything is copied.

Nothing is deleted. Retire a record with "active": false; past orders and reports that name it are unaffected, and it can be brought back with "active": true.

Every change a key makes is listed in the Dnero portal under Automation > Activity, with the key’s name.