Catalogues and licences

FurniOps keeps data in catalogues. Your organisation has its own: everything your sources bring in. The network catalogue holds vendor data FurniOps maintains for many organisations. A catalogue licence (lic_…) lets your organisation see part of the network catalogue.

What a licence grantsCopy Anchor Link

A licence names a catalogue and narrows it two ways:

• Sources: every source of the catalogue, or a list of them.
• Field groups: which kinds of field you see. Every field is in exactly one group.

Several licences on one catalogue add up: their sources and field groups unite. A licence can have a start and an end; outside that window it grants nothing. Licences are arranged with FurniOps, not through the API.

How the narrowing worksCopy Anchor Link

• A product or variant data field is shown when its group is granted and the value comes from a licensed source. A value FurniOps set itself, with no source behind it, follows its group alone.
• An offer is shown only when it is from a licensed source and price or stock is granted. Of its fields, you see only the granted groups. Without stock, availability reads unknown.
• A licence that grants only offer groups (price, stock) does not show the products those offers belong to.
• An update event left with no visible field is skipped, and the change feed's cursor moves past it, so you never receive an empty change.

Because a licence can leave fields out, every field of a product's or variant's data, and every price and stock field of an offer, is optional in the API's schemas. Identity fields (id, status, version, an offer's source and observed_at) are always present. Check for a field before using it:

for (const variant of product.variants) {
  for (const offer of variant.offers) {
    if (offer.cost !== undefined) {
      // The licence grants price, and this source gave a cost.
    }
  }
}

One projection on every pathCopy Anchor Link

The read API, the change feed, the stream and webhooks all pass data through one licence projection. A field you cannot read with GET /v1/products/{id} never reaches you in an event either, and a fat payload's object equals what the read API would have shown at that version. When your licence changes, the next read and the next event follow it.

A source's licence basisCopy Anchor Link

Each of your sources records why FurniOps may use its data, in licence_basis:

It is required when you create a source and can be changed with PATCH /v1/sources/{id}.