Catalogue

Read the overview first. It has the rules every route follows: the token, pages, languages, how texts and money are sent, and the status codes.

The catalogue can be read in two ways, and the same item id answers differently in each. That is on purpose.

	The back office routes	The storefront's view
Address	`v1/alfa/items`	`v1/alfa/catalog/items`
What you see	Every item, whatever its state	Only items a shopper could see: published, inside their publication dates, allowed for the visitor
An unpublished item	200	404
What a record holds	The stored record, as the edit form has it	The item as the shop shows it: texts in one language, the calculated price, the fields and combinations, the pictures
Writing	Create, change, delete	Read only

Build a shop front or an app on the storefront's view. Edit through the back office routes.

Items

v1/alfa/items, the five standard routes.

Create. The name in the site's default language, a default category and a state are enough. Prices are exact decimal text. currency_id 47 is the euro of a fresh installation; read v1/alfa/currencies for the ids of your shop.

curl -X POST -H "X-Joomla-Token: YOUR_TOKEN" -H "Content-Type: application/json" \
  "https://your-shop.example/api/index.php/v1/alfa/items" \
  -d '{
    "name_en_gb": "Cordless drill",
    "sku": "DRILL-18V",
    "state": 1,
    "manage_stock": 0,
    "id_category_default": 1,
    "categories": [1],
    "prices": [{"id": 0, "value": "19.90", "currency_id": 47, "quantity_start": 1}]
  }'

The answer, status 200, shortened:

{
  "data": {
    "type": "items",
    "id": "1",
    "attributes": {
      "id": 1,
      "id_category_default": 1,
      "sku": "DRILL-18V",
      "manage_stock": 0,
      "state": 1,
      "prices": [{"id": 1, "value": "19.90", "currency_id": 47, "quantity_start": 1, "state": 1}],
      "categories": [1],
      "name": "Cordless drill",
      "translations": {"en_gb": {"name": "Cordless drill", "alias": ""}}
    }
  },
  "meta": {
    "tasks": [{
      "id": 2, "type": "job", "handler": "price.set.prepare", "state": "pending",
      "links": {"self": "https://your-shop.example/api/index.php/v1/alfa/tasks/2"}
    }]
  }
}

meta.tasks is there because a new price leaves work for the price index. See Tasks.

Stock. Stock is not a field to overwrite. A stock figure in the body is an instruction to the stock service and counts only when the body carries stock. See Stock.

A list row holds: id, name, alias, sku, gtin, mpn, state, stock, available_quantity, manage_stock, stock_action, is_virtual, combination_count, id_category_default, category_ids, manufacturer_ids, publish_up, publish_down, modified, ordering.

One record holds also: short_desc, full_desc, meta_title, meta_desc, quantity_min, quantity_max, quantity_step, stock_low, backorder, min_qty, width, height, depth, weight, meta_data, robots, prices, categories, manufacturers, medias, translations, fields, options, combinations, informational, created_by, modified_by.

Related lists you can send: categories, manufacturers, allowedUsers, allowedUserGroups, prices, robots. Left out, each stays as it was.

Options, combinations and item field values (fields, options, combinations, informational) are for reading. Do not send them in a write, nor the item form's keys for them and for its downloads: see Known defects, row 14. A program that reads an item and sends it back leaves them out. Set them on the item's page in the administrator.

Planned for 2.2.1, which is not released: a create or change that carries any of these keys answers 422 naming them, and nothing is saved. A refused change leaves the item as it was; it is not checked out. The keys are fields, options, combinations, informational, and the item form's combinations_default, deleted_combination_ids, deleted_option_value_ids, deleted_info_value_ids, info_values, field_order, field_required and item_downloads. For a body that carries options, the reason reads: "options cannot be written through the API: an item's options, combinations, item field values and downloads are edited on its page in the administrator. Send the item without them; nothing was saved."

Planned for 2.2.1, which is not released: the list gains filter[stock] and filter[fields]. See The filters of each list.

Delete. An item that was never sold is removed (204). An item that an order holds stays, archived (state 2), and the answer is still 204.

Manufacturers

v1/alfa/manufacturers, the five standard routes.

{"name_en_gb": "Acme Tools", "website": "https://example.com", "state": 1}

A list row holds: id, name, alias, website, state, item_count, modified, ordering.

One record holds also: desc, meta_title, meta_desc, meta_data, robots, medias, translations.

Item fields

v1/alfa/itemfields, the five standard routes. An item field is a property of an item that the shopper sees or chooses, such as a colour. type names the item field plugin that handles it. See Item field plugins.

{"name_en_gb": "Colour", "field_name": "colour", "type": "choice", "state": 1}

A list row holds: id, field_name, name, type, informational, required, filterable, searchable, show_on_listing, state, ordering.

One record holds also: description, categories, translations.

Related lists you can send: categories. 2.2.0 also accepts values, but do not send it, nor the field form's deleted_value_ids: a value is kept by its id whatever field it belongs to, so a value of another field named there moves under this field, and deleted_value_ids deletes the unused values of any field. See Known defects, row 15. Edit a field's values on its page in the administrator.

Planned for 2.2.1, which is not released: a create or change that carries values or deleted_value_ids answers 422 naming them, and nothing is saved; the field is not checked out.

Planned for 2.2.1, which is not released: deleting an item field that items still use (their combinations, offered options or specifications) is refused with 409 and the reason, and nothing is deleted.

The storefront's view

Two routes, read only:

Method and address	What it does
`GET v1/alfa/catalog/items`	Lists the items a shopper could see
`GET v1/alfa/catalog/items/:id`	One item as the shop shows it

The token is still needed, and its user needs the permission "Items: View".

Add lang= for the language of the texts, and currency= and place= for the price. Without them the price is worked out with the shop's defaults, which is wrong for a shop that sells in several currencies.

One item, shortened:

{
  "data": {
    "type": "catalogitems",
    "id": "1",
    "attributes": {
      "id": 1,
      "sku": "DRILL-18V",
      "name": "Cordless drill",
      "stockStatus": "in_stock",
      "categories": {"1": {"name": "Tools", "media": [], "layouts": []}},
      "cartState": {"salable": true, "showNotify": false},
      "price": {
        "base_total": {"amount": "19.90", "formatted": "19,90 €"},
        "tax_total": {"amount": "0.00", "formatted": "0,00 €"},
        "total": {"amount": "19.90", "formatted": "19,90 €"},
        "price": {"amount": "19.90", "formatted": "19,90 €", "minor_units": 1990},
        "currency": {"id": 47, "code": "EUR", "symbol": "€", "decimal_places": 2},
        "discounts": {"count": 0, "has_discounts": false, "applied": []},
        "taxes": {"effective_rate": "0", "count": 0, "applied": []}
      },
      "payment_methods": [],
      "shipment_methods": []
    }
  }
}

A list row holds: id, name, alias, sku, stock, available_quantity, stockStatus, is_virtual, price, medias, variant, cartState.

One record holds also: short_desc, full_desc, meta_title, meta_desc, gtin, mpn, manage_stock, stock_action, stock_low_message, stock_zero_message, width, height, depth, weight, quantity_min, quantity_max, quantity_step, categories, manufacturers, fields, options, combinations, informational, payment_methods, shipment_methods, publish_up, publish_down.

The price here is worked out when you ask, by the same pricing code as the item page. See Pricing.

Not documented yet

The parts of the price object one by one, and the variant, combinations and cartState objects.
How to send combinations and item field values of an item in a write. The API has no supported way to write them.

Items​

Categories​

Manufacturers​

Item fields​

The storefront's view​

Not documented yet​

Items

Categories

Manufacturers

Item fields

The storefront's view

Not documented yet