HikaShop - Developer area

Option	What it does
--format	`table` to read, `json` to pipe into something else, and also `pretty`, `csv`, `ids` and `count`. Listings show a table by default, single records show indented JSON.
--user	Which account the command acts as, given by id, user name or email address. It decides what the command may do, through the access levels of your site and of the HikaShop configuration. On WordPress this is WP-CLI's own `--user`, which behaves the same and can be set once in `wp-cli.yml`.
--yes	Required by the commands that remove data or act on many records at once. Without it they refuse and change nothing.
--live-site	Joomla only. The address of your site, needed when your configuration does not set one, so that the links the shop generates are correct.

Code	Meaning
0	It worked
1	Something went wrong
2	The command was asked for wrongly, for example a missing option
3	The record does not exist
4	This account is not allowed to do that

Option	Type	Description
--search	string	Filter on a search term
--limit	int	How many to return
--start	int	Skip this many first
--category	int	Only this category
--ids	string	Only these product ids, comma separated

Returns	Type	Description
id
name
code		The SKU. Unique within the shop.
quantity		`-1` when the product does not track stock, which is not the same as `0`.
published
has_variants		Ask `GET /products/{id}` for the variants themselves.
image	string\|null	Absolute URL of the main image, or `null`.
price		`null` when the product has no price row at all.
currency_id		A row in the shop's currency table, not an ISO code.
custom_fields	object	The listing values of this product, keyed by field namekey.

In `meta`	Type	Description
start	integer	Echoes the offset used.
limit	integer	Echoes the page size used.
total	integer	Rows matching the filter, before paging. This is how you know there is another page.
fields	object[]	The custom fields shown on listings, so a client can label the values it just received.

Argument	Description
<id> required	Product id

Returns	Type	Description
id
name
code		The SKU. Unique within the shop.
description		The long description, as HTML.
description_type		Which editor the description was written with.
published
quantity		`-1` when this product does not track stock, which is not the same as `0`.
msrp		The manufacturer's suggested price, shown struck through when the shop is configured to.
gtin		The barcode: EAN, UPC or ISBN. This is what `GET /products/lookup` matches on.
condition		New, used, refurbished. Used by the feeds rather than by the shop itself.
weight		Shipping weight, in `weight_unit`.
weight_unit		`kg`, `g`, `lb` or `oz`.
width		In `dimension_unit`.
height		In `dimension_unit`.
length		In `dimension_unit`.
dimension_unit		`m`, `cm`, `mm`, `ft` or `in`.
min_per_order		The smallest quantity a customer may order, `0` for no minimum.
max_per_order		The largest, `0` for no maximum.
sale_start	integer\|null	Unix timestamp before which the product is not on sale.
sale_end	integer\|null	Unix timestamp after which it is no longer sold.
page_title		SEO title, empty to use the name.
meta_description		SEO description.
keywords		SEO keywords.
canonical		A canonical URL, when this page should point at another.
url		The address of the product page on the shop.
alias		The slug used in that address.
access	object	Who may see the product: `mode` (`all`, `none` or `groups`) and `groups`, which are user group ids and not Joomla view levels. The two id spaces overlap and disagree, so a value that looks plausible can grant the wrong audience.
access.mode	string	`all`, `none`, or `groups` when it is restricted to some.
access.groups	integer[]	User group ids, meaningful only when the mode is `groups`.
contact		Whether this product is enquired about rather than bought.
warehouse_id		The warehouse holding the stock, `0` when the shop has none.
type		`main` for a product, `variant` for one of its variants.
parent_id		The parent product when this is a variant, `0` otherwise.
value_ids	integer[]	For a variant, the characteristic values it stands for.
manufacturer_id		The brand, `0` when unset.
manufacturer_name	string	Its name, saving a second call.
tax_id		The tax category, `0` when the product is untaxed.
tax_name	string	Its name.
tax_rate	number	The rate as a fraction, so `0.2` is twenty percent.
prices	object[]	Every price row, including the restricted ones. A product with none is not sellable.
prices.id
prices.value		Tax excluded, as stored.
prices.currency_id
prices.min_quantity		From how many items this row applies, which is how quantity breaks are expressed.
prices.access	object	Who this price is for, in the same shape as the product access.
prices.access.mode	string	As above.
prices.access.groups	integer[]	As above.
prices.users	integer[]	Named customers, empty for everyone.
prices.zone_ids	integer[]	Zones this price applies in, empty for everywhere.
prices.start_date	integer\|null	Unix timestamp.
prices.end_date	integer\|null	Unix timestamp.
images	object[]	In the order the editor shows them; the first is the main image.
images.id
images.name
images.path		Relative to the upload folder.
images.url		Absolute, ready to display.
images.ordering
images.description		The alt text.
images.access	object	Who may see it.
images.access.mode	string	As above.
images.access.groups	integer[]	As above.
images.free_download		Files only; meaningless on an image.
files	object[]	Downloadable files, in the same shape as the images.
files.id
files.name
files.path		Relative to the upload folder.
files.url		Absolute.
files.ordering
files.description
files.access	object	Who may download it.
files.free_download		Whether it can be downloaded without buying the product.
categories	object[]	The categories the product is in.
categories.id
categories.name
bundle	object[]	The products this one is made of, when it is a bundle.
bundle.id
bundle.name
bundle.code
bundle.quantity		How many of it the bundle contains.
options	object[]	Products offered as options alongside this one.
options.id
options.name
options.code
options.quantity
related	object[]	Products shown as related.
related.id
related.name
related.code
related.quantity
tags	integer[]	CMS tag ids.
characteristics	object[]	The characteristics this product varies on. Empty when it has no variants.
characteristics.id	integer	The characteristic, such as Size.
characteristics.name	string	Its name.
characteristics.values	object[]	The values of it this product uses, such as S, M and L.
characteristics.values.id	integer	The value id, which is what a variant refers to.
characteristics.values.value	string	Its name, such as `M`.
variants	object[]	Every variant, with its own code, stock, price and images. Empty for a product that does not vary.
variants.id	integer	The variant is a product in its own right, and this is its id.
variants.code	string	Its own SKU.
variants.quantity	integer	Its own stock. This is the figure to change, not the parent's.
variants.published	boolean
variants.price	number\|null	`null` when the variant has no price of its own and the parent's applies.
variants.values	object[]	Which characteristic values this variant stands for, one per characteristic.
variants.values.option_id	integer	The characteristic.
variants.values.option_name	string	Its name, so the variant can be labelled without a second call.
variants.values.value_id	integer	The value.
variants.values.value	string	Its name.
variants.images	object[]	The variant's own images, in the same shape as the product's.
variants.images.id	integer
variants.images.name	string
variants.images.path	string	Relative to the upload folder.
variants.images.url	string	Absolute.
variants.images.ordering	integer
fields	object[]	The definitions of the custom fields that apply to this product, so a client can build a form for them.
fields.namekey	string	The key used in `custom_fields`.
fields.label	string	Translated into the operator's language.
fields.type	string	`text`, `radio`, `singledropdown`, `file`, and the rest of HikaShop's field types.
fields.required	boolean	Whether the shop refuses to save the product without it.
fields.translatable	boolean	Whether its value can be translated, which is what the translation routes offer.
fields.upload_dir	string	For a file field, where its uploads are kept.
fields.raw_type	string	HikaShop's own name for the type, before it is mapped to something a client can render.
fields.default	string	The value used when none is given.
fields.options	object[]	The choices, for a field that has them. Empty for a free text one.
fields.multiple	boolean	Whether more than one choice may be selected.
fields.allowed_extensions	string	For a file field, the extensions it accepts, comma separated. Empty means the shop default.
fields.date_format	string	For a date field, the format it is stored in.
custom_fields	object	Their values, keyed by namekey.
custom_field_files	object	For custom fields holding a file, the file behind each value.

Option	Type	Description
--name required	string	Product name
--code	string	Product code, derived from the name when left out
--quantity	int	Stock, -1 for unlimited
--published	flag	Publish it
--description	string	Description
--categories	ids, comma separated	Category ids, comma separated

Returns	Type	Description
id
name
code		The SKU. Unique within the shop.
description		The long description, as HTML.
description_type		Which editor the description was written with.
published
quantity		`-1` when this product does not track stock, which is not the same as `0`.
msrp		The manufacturer's suggested price, shown struck through when the shop is configured to.
gtin		The barcode: EAN, UPC or ISBN. This is what `GET /products/lookup` matches on.
condition		New, used, refurbished. Used by the feeds rather than by the shop itself.
weight		Shipping weight, in `weight_unit`.
weight_unit		`kg`, `g`, `lb` or `oz`.
width		In `dimension_unit`.
height		In `dimension_unit`.
length		In `dimension_unit`.
dimension_unit		`m`, `cm`, `mm`, `ft` or `in`.
min_per_order		The smallest quantity a customer may order, `0` for no minimum.
max_per_order		The largest, `0` for no maximum.
sale_start	integer\|null	Unix timestamp before which the product is not on sale.
sale_end	integer\|null	Unix timestamp after which it is no longer sold.
page_title		SEO title, empty to use the name.
meta_description		SEO description.
keywords		SEO keywords.
canonical		A canonical URL, when this page should point at another.
url		The address of the product page on the shop.
alias		The slug used in that address.
access	object	Who may see the product: `mode` (`all`, `none` or `groups`) and `groups`, which are user group ids and not Joomla view levels. The two id spaces overlap and disagree, so a value that looks plausible can grant the wrong audience.
access.mode	string	`all`, `none`, or `groups` when it is restricted to some.
access.groups	integer[]	User group ids, meaningful only when the mode is `groups`.
contact		Whether this product is enquired about rather than bought.
warehouse_id		The warehouse holding the stock, `0` when the shop has none.
type		`main` for a product, `variant` for one of its variants.
parent_id		The parent product when this is a variant, `0` otherwise.
value_ids	integer[]	For a variant, the characteristic values it stands for.
manufacturer_id		The brand, `0` when unset.
manufacturer_name	string	Its name, saving a second call.
tax_id		The tax category, `0` when the product is untaxed.
tax_name	string	Its name.
tax_rate	number	The rate as a fraction, so `0.2` is twenty percent.
prices	object[]	Every price row, including the restricted ones. A product with none is not sellable.
prices.id
prices.value		Tax excluded, as stored.
prices.currency_id
prices.min_quantity		From how many items this row applies, which is how quantity breaks are expressed.
prices.access	object	Who this price is for, in the same shape as the product access.
prices.access.mode	string	As above.
prices.access.groups	integer[]	As above.
prices.users	integer[]	Named customers, empty for everyone.
prices.zone_ids	integer[]	Zones this price applies in, empty for everywhere.
prices.start_date	integer\|null	Unix timestamp.
prices.end_date	integer\|null	Unix timestamp.
images	object[]	In the order the editor shows them; the first is the main image.
images.id
images.name
images.path		Relative to the upload folder.
images.url		Absolute, ready to display.
images.ordering
images.description		The alt text.
images.access	object	Who may see it.
images.access.mode	string	As above.
images.access.groups	integer[]	As above.
images.free_download		Files only; meaningless on an image.
files	object[]	Downloadable files, in the same shape as the images.
files.id
files.name
files.path		Relative to the upload folder.
files.url		Absolute.
files.ordering
files.description
files.access	object	Who may download it.
files.free_download		Whether it can be downloaded without buying the product.
categories	object[]	The categories the product is in.
categories.id
categories.name
bundle	object[]	The products this one is made of, when it is a bundle.
bundle.id
bundle.name
bundle.code
bundle.quantity		How many of it the bundle contains.
options	object[]	Products offered as options alongside this one.
options.id
options.name
options.code
options.quantity
related	object[]	Products shown as related.
related.id
related.name
related.code
related.quantity
tags	integer[]	CMS tag ids.
characteristics	object[]	The characteristics this product varies on. Empty when it has no variants.
characteristics.id	integer	The characteristic, such as Size.
characteristics.name	string	Its name.
characteristics.values	object[]	The values of it this product uses, such as S, M and L.
characteristics.values.id	integer	The value id, which is what a variant refers to.
characteristics.values.value	string	Its name, such as `M`.
variants	object[]	Every variant, with its own code, stock, price and images. Empty for a product that does not vary.
variants.id	integer	The variant is a product in its own right, and this is its id.
variants.code	string	Its own SKU.
variants.quantity	integer	Its own stock. This is the figure to change, not the parent's.
variants.published	boolean
variants.price	number\|null	`null` when the variant has no price of its own and the parent's applies.
variants.values	object[]	Which characteristic values this variant stands for, one per characteristic.
variants.values.option_id	integer	The characteristic.
variants.values.option_name	string	Its name, so the variant can be labelled without a second call.
variants.values.value_id	integer	The value.
variants.values.value	string	Its name.
variants.images	object[]	The variant's own images, in the same shape as the product's.
variants.images.id	integer
variants.images.name	string
variants.images.path	string	Relative to the upload folder.
variants.images.url	string	Absolute.
variants.images.ordering	integer
fields	object[]	The definitions of the custom fields that apply to this product, so a client can build a form for them.
fields.namekey	string	The key used in `custom_fields`.
fields.label	string	Translated into the operator's language.
fields.type	string	`text`, `radio`, `singledropdown`, `file`, and the rest of HikaShop's field types.
fields.required	boolean	Whether the shop refuses to save the product without it.
fields.translatable	boolean	Whether its value can be translated, which is what the translation routes offer.
fields.upload_dir	string	For a file field, where its uploads are kept.
fields.raw_type	string	HikaShop's own name for the type, before it is mapped to something a client can render.
fields.default	string	The value used when none is given.
fields.options	object[]	The choices, for a field that has them. Empty for a free text one.
fields.multiple	boolean	Whether more than one choice may be selected.
fields.allowed_extensions	string	For a file field, the extensions it accepts, comma separated. Empty means the shop default.
fields.date_format	string	For a date field, the format it is stored in.
custom_fields	object	Their values, keyed by namekey.
custom_field_files	object	For custom fields holding a file, the file behind each value.

Can also fail with	Meaning
invalid_fields	One of your own fields was rejected by its own rules.
save_failed	The shop refused to save the product.

Argument	Description
<id> required	Product id

Option	Type	Description
--name	string	Product name
--code	string	Product code
--description	string	Description
--published	flag	Publish it
--msrp	float	Recommended retail price
--gtin	string	GTIN / barcode
--weight	float	Weight
--tax-id	int	Tax category id

Returns	Type	Description
id
name
code		The SKU. Unique within the shop.
description		The long description, as HTML.
description_type		Which editor the description was written with.
published
quantity		`-1` when this product does not track stock, which is not the same as `0`.
msrp		The manufacturer's suggested price, shown struck through when the shop is configured to.
gtin		The barcode: EAN, UPC or ISBN. This is what `GET /products/lookup` matches on.
condition		New, used, refurbished. Used by the feeds rather than by the shop itself.
weight		Shipping weight, in `weight_unit`.
weight_unit		`kg`, `g`, `lb` or `oz`.
width		In `dimension_unit`.
height		In `dimension_unit`.
length		In `dimension_unit`.
dimension_unit		`m`, `cm`, `mm`, `ft` or `in`.
min_per_order		The smallest quantity a customer may order, `0` for no minimum.
max_per_order		The largest, `0` for no maximum.
sale_start	integer\|null	Unix timestamp before which the product is not on sale.
sale_end	integer\|null	Unix timestamp after which it is no longer sold.
page_title		SEO title, empty to use the name.
meta_description		SEO description.
keywords		SEO keywords.
canonical		A canonical URL, when this page should point at another.
url		The address of the product page on the shop.
alias		The slug used in that address.
access	object	Who may see the product: `mode` (`all`, `none` or `groups`) and `groups`, which are user group ids and not Joomla view levels. The two id spaces overlap and disagree, so a value that looks plausible can grant the wrong audience.
access.mode	string	`all`, `none`, or `groups` when it is restricted to some.
access.groups	integer[]	User group ids, meaningful only when the mode is `groups`.
contact		Whether this product is enquired about rather than bought.
warehouse_id		The warehouse holding the stock, `0` when the shop has none.
type		`main` for a product, `variant` for one of its variants.
parent_id		The parent product when this is a variant, `0` otherwise.
value_ids	integer[]	For a variant, the characteristic values it stands for.
manufacturer_id		The brand, `0` when unset.
manufacturer_name	string	Its name, saving a second call.
tax_id		The tax category, `0` when the product is untaxed.
tax_name	string	Its name.
tax_rate	number	The rate as a fraction, so `0.2` is twenty percent.
prices	object[]	Every price row, including the restricted ones. A product with none is not sellable.
prices.id
prices.value		Tax excluded, as stored.
prices.currency_id
prices.min_quantity		From how many items this row applies, which is how quantity breaks are expressed.
prices.access	object	Who this price is for, in the same shape as the product access.
prices.access.mode	string	As above.
prices.access.groups	integer[]	As above.
prices.users	integer[]	Named customers, empty for everyone.
prices.zone_ids	integer[]	Zones this price applies in, empty for everywhere.
prices.start_date	integer\|null	Unix timestamp.
prices.end_date	integer\|null	Unix timestamp.
images	object[]	In the order the editor shows them; the first is the main image.
images.id
images.name
images.path		Relative to the upload folder.
images.url		Absolute, ready to display.
images.ordering
images.description		The alt text.
images.access	object	Who may see it.
images.access.mode	string	As above.
images.access.groups	integer[]	As above.
images.free_download		Files only; meaningless on an image.
files	object[]	Downloadable files, in the same shape as the images.
files.id
files.name
files.path		Relative to the upload folder.
files.url		Absolute.
files.ordering
files.description
files.access	object	Who may download it.
files.free_download		Whether it can be downloaded without buying the product.
categories	object[]	The categories the product is in.
categories.id
categories.name
bundle	object[]	The products this one is made of, when it is a bundle.
bundle.id
bundle.name
bundle.code
bundle.quantity		How many of it the bundle contains.
options	object[]	Products offered as options alongside this one.
options.id
options.name
options.code
options.quantity
related	object[]	Products shown as related.
related.id
related.name
related.code
related.quantity
tags	integer[]	CMS tag ids.
characteristics	object[]	The characteristics this product varies on. Empty when it has no variants.
characteristics.id	integer	The characteristic, such as Size.
characteristics.name	string	Its name.
characteristics.values	object[]	The values of it this product uses, such as S, M and L.
characteristics.values.id	integer	The value id, which is what a variant refers to.
characteristics.values.value	string	Its name, such as `M`.
variants	object[]	Every variant, with its own code, stock, price and images. Empty for a product that does not vary.
variants.id	integer	The variant is a product in its own right, and this is its id.
variants.code	string	Its own SKU.
variants.quantity	integer	Its own stock. This is the figure to change, not the parent's.
variants.published	boolean
variants.price	number\|null	`null` when the variant has no price of its own and the parent's applies.
variants.values	object[]	Which characteristic values this variant stands for, one per characteristic.
variants.values.option_id	integer	The characteristic.
variants.values.option_name	string	Its name, so the variant can be labelled without a second call.
variants.values.value_id	integer	The value.
variants.values.value	string	Its name.
variants.images	object[]	The variant's own images, in the same shape as the product's.
variants.images.id	integer
variants.images.name	string
variants.images.path	string	Relative to the upload folder.
variants.images.url	string	Absolute.
variants.images.ordering	integer
fields	object[]	The definitions of the custom fields that apply to this product, so a client can build a form for them.
fields.namekey	string	The key used in `custom_fields`.
fields.label	string	Translated into the operator's language.
fields.type	string	`text`, `radio`, `singledropdown`, `file`, and the rest of HikaShop's field types.
fields.required	boolean	Whether the shop refuses to save the product without it.
fields.translatable	boolean	Whether its value can be translated, which is what the translation routes offer.
fields.upload_dir	string	For a file field, where its uploads are kept.
fields.raw_type	string	HikaShop's own name for the type, before it is mapped to something a client can render.
fields.default	string	The value used when none is given.
fields.options	object[]	The choices, for a field that has them. Empty for a free text one.
fields.multiple	boolean	Whether more than one choice may be selected.
fields.allowed_extensions	string	For a file field, the extensions it accepts, comma separated. Empty means the shop default.
fields.date_format	string	For a date field, the format it is stored in.
custom_fields	object	Their values, keyed by namekey.
custom_field_files	object	For custom fields holding a file, the file behind each value.

Can also fail with	Meaning
not_found	No such product, or the operator may not change it.
invalid_fields	One of your own fields was rejected by its own rules.
nothing	The body held no field this shop knows, so nothing would have been written.

Argument	Description
<id> required	Product id

Returns	Type	Description
id	integer	The product that was deleted.
deleted	boolean	True when the row is gone.

Can also fail with	Meaning
not_found	No such product, or the operator may not delete it.
delete_failed	The shop refused to delete it.

Argument	Description
<id> required	Product id

Option	Type	Description
--quantity required	int	New quantity, -1 for unlimited

Returns	Type	Description
id	integer
quantity	integer	As stored, so you can confirm what was written.

Can also fail with	Meaning
not_found	No such product, or the operator may not change it.
has_variants	It is a parent: set the stock on one of its variants.

Argument	Description
<id> required	Product id

Option	Type	Description
--value required	float	The price
--currency	int	Currency id, the shop's own when left out
--min-quantity	int	Quantity this price starts at

Returns	Type	Description
id	integer
value	number	Tax excluded, as stored.
currency_id	integer
min_quantity	integer	From how many items this row applies, which is how a quantity break is expressed.
access	object	Which user groups the price is for.
access.mode	string	`all`, `none` or `groups`.
access.groups	integer[]	User group ids, not view levels.
users	integer[]	Named customers, empty for everyone.
zone_ids	integer[]	Zones it applies in, empty for everywhere.
start_date	integer\|null	Unix timestamp.
end_date	integer\|null	Unix timestamp.

Can also fail with	Meaning
invalid_request	No prices array was sent.
invalid_price	A price in the set cannot be stored, and the message says which one and why. Nothing is saved: a set is replaced whole or not at all.
not_found	No such product, or the operator may not change it.

Option	Type	Description
--threshold	int	Stock level to report at or below
--limit	int	How many to return

Returns	Type	Description
id		The parent product.
variant_id		The variant that is low, `0` when the parent itself is.
name
code		The SKU of whichever record is low.
quantity		What is left.

Option	Type	Description
--search	string	Filter on a search term
--limit	int	How many to return
--start	int	Skip this many first
--status	string	Only this order status

Returns	Type	Description
id		The order id, which is what every other order route takes.
number		The order number the customer sees, which is not the id.
status		A namekey, not a label. `GET /statuses` translates it.
created		Unix timestamp.
total		What the customer owes, tax included, in the order currency.
currency_id		The order keeps the currency it was placed in, which need not be the shop default.
customer	object	Enough to name the buyer in a list.
customer.name
customer.email
custom_fields	object	The listing values of your own order fields, keyed by namekey.

In `meta`	Type	Description
start	integer	Echoes the offset used.
limit	integer	Echoes the page size used.
total	integer	Orders matching the filter, before paging.
fields	object[]	The definitions behind `custom_fields`.

Argument	Description
<id> required	Order id

Returns	Type	Description
fees	object	The `discount`, `shipping` and `payment` amounts, which is what `PUT /orders/{id}/fees` writes.
fees.discount	object	Its `amount`, its `tax`, the `tax_namekeys` behind that tax, and the coupon `code` when one was used.
fees.discount.amount	number	A positive figure, already subtracted from the total.
fees.discount.tax	number	The tax on it.
fees.discount.tax_namekeys	string[]	Which tax rates that came from.
fees.discount.code	string	The coupon code, empty for a discount applied by hand.
fees.shipping	object	The shipping charge and what carried it.
fees.shipping.amount	number	Tax excluded.
fees.shipping.tax	number	The tax on it.
fees.shipping.tax_namekeys	string[]	Which tax rates that came from.
fees.shipping.method	string	The plugin that handled it.
fees.shipping.method_name	string	As the merchant named it.
fees.payment	object	The payment fee and what took it.
fees.payment.amount	number	Tax excluded.
fees.payment.tax	number	The tax on it.
fees.payment.tax_namekeys	string[]	Which tax rates that came from.
fees.payment.method	string	The plugin that took it.
fees.payment.method_name	string	As the merchant named it.
totals	object	The figures. See the shape below.
totals.total	number	What the customer owes, tax included.
totals.discount	number	The discount applied, as a positive figure already subtracted.
totals.shipping	number	The shipping charged.
totals.payment	number	The payment fee charged.
totals.tax	number	The tax within the total, not on top of it.
id
number		The number the customer sees.
status		A namekey.
created		Unix timestamp.
modified		Unix timestamp of the last change.
currency_id		The currency the order was placed in.
customer	object	Who placed it.
customer.name
customer.email
payment_method	string	How it was paid, as the shop names it.
shipping_method	string	How it ships.
invoice_number	string	Empty until an invoice has been issued.
invoice_created	integer\|null	Unix timestamp of the invoice.
items	object[]	The lines: `id`, `name`, `code`, `quantity`, `price`, `tax` and whether the line can still be edited.
items.id	integer	The line id, which is what `PUT /orders/{id}/products/{lineId}` takes. It is not the product id.
items.name	string	The product as it was named when ordered, which may since have changed.
items.code	string	Its SKU at the time.
items.quantity	integer
items.price	number	Unit price, tax excluded, as agreed at the time.
items.tax	number	Tax on the line.
items.editable	boolean	False once the line can no longer be changed, for instance on a shipped order.
billing_address	object\|null	The address as it was at the time, `null` when there is none. It is a copy, not a pointer at the customer's current address.
shipping_address	object\|null	The same, for delivery.
shipping_address_override	boolean	Whether the delivery address was set apart from the billing one.
history	object[]	What has happened to the order, oldest first.
history.status		The namekey it moved to.
history.created		Unix timestamp.
history.type		What caused it: a payment notification, an operator, the shop itself.
history.reason		The note recorded with the change, when there was one.
history.notified	boolean	Whether the customer was emailed about it.
fields	object[]	The definitions of your own order fields.
custom_fields	object	Their values, keyed by namekey.
custom_field_files	object	For a field holding a file, the file behind the value.
tax_rates	object[]	The rates that made up the tax, each with its namekey and rate, so a total can be explained rather than only shown.
tax_rates.namekey	string	The tax rate as the shop names it.
tax_rates.rate	number	As a fraction, so `0.1` is ten percent.

Argument	Description
<id> required	Order id
<status> required	Status namekey, e.g. confirmed or shipped

Option	Type	Description
--notify	flag	Email the customer about the change
--reason	string	Note stored with the change

Returns	Type	Description
id	integer	The order id.
status		The namekey the order now has.
changed		False when the order already had that status.
notified	boolean	Whether the customer was actually emailed, which can be false even when you asked, if the status has no notification configured.

Can also fail with	Meaning
invalid_status	No such status namekey on this shop.
not_found	No such order, or the operator may not see it.
save_failed	The order could not be saved.

Option	Type	Description
--customer	int	HikaShop customer id
--guest	flag	Create it for a guest instead

Returns	Type	Description
id	integer	The order that was created, to add lines to.

Can also fail with	Meaning
no_customer	Neither a user_id nor a usable guest was given.
save_failed	The order could not be created.

Argument	Description
<id> required	Order id

Option	Type	Description
--product required	int	Product id
--quantity	int	How many
--price	float	Unit price, the product's own when left out

Returns	Type	Description
totals	object	The order totalled, so a client need not compute it and disagree with the shop.
totals.total	number	What the customer owes, tax included.
totals.discount	number	The discount applied, as a positive figure already subtracted.
totals.shipping	number	The shipping charged.
totals.payment	number	The payment fee charged.
totals.tax	number	The tax within the total, not on top of it.
items.id	integer	The line id, which is what the line routes take. It is not the product id.
items.name	string	The product as it was named when ordered.
items.code	string	Its SKU at the time.
items.quantity	integer
items.price	number	Unit price, tax excluded, as agreed at the time.
items.tax	number	Tax on the line.
items.editable	boolean	False once the line can no longer be changed.
id	integer	The order.
items	object[]	The lines as they now stand, in the same shape as on the order.

Can also fail with	Meaning
not_found	No such order or product, or the operator may not change the order.
save_failed	The order could not be saved.

Option	Type	Description
--search	string	Filter on a search term
--limit	int	How many to return
--start	int	Skip this many first

Returns	Type	Description
id		The HikaShop customer id, which is not the CMS user id.
name		The account name, or for a guest the name on their default address, since a guest has no account to take one from.
email
type		`registered` for an account, `guest` for someone who ordered without one.
created		Unix timestamp of the first time the shop saw them.
order_count		How many orders they have placed, so a list can be sorted by worth without a second call.

In `meta`	Type	Description
start	integer	Echoes the offset used.
limit	integer	Echoes the page size used.
total	integer	Customers matching the filter, before paging.

Argument	Description
<id> required	Customer id

Returns	Type	Description
id	integer	The HikaShop customer id, which is what every customer route takes.
cms_id	integer	The Joomla or WordPress user id, `0` for a guest with no account.
name	string
email	string
username	string	The login, empty for a guest.
type	string	`registered` or `guest`.
blocked	boolean	Whether the CMS account is disabled.
can_edit_account	boolean	Whether this operator may change the login and password of this particular account. False for an account above their own level, which is how a super user is protected from staff.
groups_editable	boolean	Whether this operator may change which groups the customer is in.
groups	object[]	The groups they are in.
groups.id	integer
groups.title	string
available_groups	object[]	Every group, with whether this operator may put the customer into it, so a picker can grey out the rest rather than offering a refusal.
available_groups.id	integer
available_groups.title	string
available_groups.assignable	boolean	False for a group this operator may not grant.
created	integer	Unix timestamp of the first time the shop saw them.
addresses	object[]	Their addresses, defaults first.
addresses.id	integer
addresses.types	string[]	Which of `billing` and `shipping` it is used for.
addresses.name	string
addresses.company	string
addresses.street	string
addresses.city	string
addresses.post_code	string
addresses.telephone	string
addresses.default	boolean	Whether it is the default for one of its types.
addresses.formatted	object	The address laid out the way this shop lays addresses out, which depends on its address format setting.
addresses.formatted.text	string	Several lines, for an invoice or a label.
addresses.formatted.one_line	string	One line, for a list.
orders	object[]	Their orders, newest first, enough to list them.
orders.id	integer
orders.number	string	The number the customer sees.
orders.status	string	A namekey.
orders.created	integer	Unix timestamp.
orders.total	number	Tax included, in the order currency.
orders.currency_id	integer	That currency.
fields	object[]	The definitions of your own customer fields.
custom_fields	object	Their values, keyed by namekey.
custom_field_files	object	For a field holding a file, the file behind the value.

Can also fail with	Meaning
not_found	No such customer, or the operator may not see them.

Option	Type	Description
--email required	string	Email address
--name	string	Full name

Overview

The connector plugin ships inside HikaShop Business and answers JSON over HTTPS. The mobile application is one client of it; anything it does, your own code can do.

Every response carries the same envelope, {"data": …, "meta": …, "error": null}, and every route except POST /pair carries a device token as Authorization: Bearer <token>. A token holds the scopes read and optionally write, and the operator it is bound to keeps their own access levels, so a device may hold write and still be refused an order its operator cannot see.

The base path is a plugin parameter and a shop can move it. Nothing else here changes between shops.

The three links at the top of this page are the same API in a form a machine reads: the OpenAPI 3.1 description of every route, in YAML or in JSON, which API clients, test tools and code generators open directly, and the whole thing as one Markdown file to hand to an assistant.

the envelope

{
  "data": { … },
  "meta": null,
  "error": null
}

Pairing a device

A client never sees the merchant's password. It is given a pairing code instead, generated in System > App Devices of the backend, and exchanges it once for a token of its own.

The code is nine characters, lives five minutes, may be tried five times before it dies, and can only be spent once. POST /pair is rate limited to thirty attempts per minute per address, which is the only route that answers without a token.

What comes back is the token, the scopes the code granted, and the id of the device row. The token is shown once and stored only as a SHA-256 hash, so a device that loses it pairs again rather than recovering it. Revoking a device is deleting its row in that same screen, and every token it held stops working at once.

the exchange

curl -X POST "$SHOP/hikashop-api/v1/pair" \
  -H "Content-Type: application/json" \
  -d '{ "code": "K7QM-2F84", "device_name": "Counter tablet" }'

# then, for everything else
curl "$SHOP/hikashop-api/v1/products" \
  -H "Authorization: Bearer $TOKEN"

Scopes and access levels

Two separate checks run on every request, and the narrower one wins.

The scope is what the device may do at all: read, and write if the pairing code granted it. A device without write is refused every route that changes anything, whoever holds it.

The access levels are the shop's own, belonging to the operator the device is bound to. They decide which records that person may see and change, exactly as they do in the backend. So a device holding write can still be refused an order, and a device holding only read sees a smaller catalogue than another one.

This is why an integration should be given its own device rather than borrowing one: revoke it and nothing else is disturbed, and its operator's access levels are the ceiling on what it can reach.

refused for the scope

{
  "data": null,
  "error": {
    "code": "forbidden",
    "message": "This device does not have the required scope."
  }
}

The envelope, errors and paging

Every JSON answer has the same three keys. data is the payload, meta carries paging and other context when there is any and is null otherwise, and error is null on success.

On failure data is null and error holds a stable code and a human message. Read the code, not the message: the message is written for a person and may be translated or reworded, the code is what your own logic should branch on.

Listings page with start and limit in the query, and answer with start, limit and total in the envelope's meta. total counts the rows matching the filter before paging, so it is how you know there is another page. limit is capped, usually at a hundred, and asking for more silently gets you the cap rather than an error.

One thing to note about a listing: data is the list itself, not an object wrapping it. The paging lives in meta.

Codes every route can return

CodeHTTPMeans

invalid_request400A required field is missing or malformed.

unauthorized401No token, or a token that is unknown, revoked or unpublished.

forbidden403The device lacks the scope, or the operator lacks the access level.

not_found404No such record, or no such route. Also returned when the operator may not see the record, so that it cannot be probed for.

too_many_requests429Rate limited. Only /pair does this.

a page of a listing

{
  "data": [ … ],
  "meta": { "start": 0, "limit": 20, "total": 307 },
  "error": null
}

Calling it from a browser

The API answers cross-origin requests, because the application is a web application as well as a phone one. Access-Control-Allow-Origin is *, the allowed methods are GET, POST, PUT, DELETE and OPTIONS, and the allowed headers are Authorization, Content-Type and X-Hikashop-Token. A preflight is answered immediately and may be cached for a day.

* with a bearer token is deliberate and safe in the way cookies would not be: nothing is sent automatically by the browser, so a page on another origin can only call this API if it already holds a token, and a token is only ever obtained by pairing.

Send the token in the Authorization header. Never put it in the query string, where it would be written to every access log between you and the shop.

the preflight

OPTIONS /hikashop-api/v1/products

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, X-Hikashop-Token
Access-Control-Max-Age: 86400

Adding your own routes

A HikaShop plugin can serve paths of its own through the same base path, the same envelope and the same authentication, by listening to three events.

onConnectorBeforeRoute fires before any matching, so it can intercept a path the connector also serves. onConnectorRoute fires only when nothing matched, which is where a new path belongs. onConnectorBeforeResponse fires just before the JSON is written, for adding a field to an answer somebody else built.

The listener receives one object by reference, carrying path (the part after the base path), method, base_path, response, and handled. Authenticate with requireScope() exactly as the connector's own routes do, answer through $ctx->response, and set $ctx->handled = true so the router stops rather than falling through to its 404.

a plugin serving its own path

public function onConnectorRoute(&$ctx) {
    if ($ctx->path !== 'warehouse/stock' || $ctx->method !== 'GET')
        return;

    $device = HikashopConnectorAuth::requireScope($ctx->response, 'read');
    if ($device === null)
        return;          // it has already answered 401 or 403

    $ctx->response->data(array('pallets' => $this->countPallets()));
    $ctx->handled = true;
}

What this shop is

GET /site read since 6.6.0

The first call a client makes. It says what it has connected to, who it is connected as, and what that operator is allowed to do, which is enough to draw an interface without asking for anything it will only be refused.

Nothing here changes often. Cache it, and use GET /version to know when to look again.

Response

FieldTypeDescription

appstringAlways hikashop-connector. A cheap way to be sure you are talking to this API and not to something else answering on that path.

api_versionstringSemver of the API itself, not of HikaShop. A minor bump adds fields or routes, a major one breaks something.

site_namestringWhat the site calls itself, which is what a merchant recognises the shop by.

hikashop_versionstring|nullThe HikaShop release running there.

cmsobjectWhat it is running on.

namebooleanjoomla or wordpress.

versionstring|nullThe CMS release.

editionstringstarter, essential or business. This API only answers on Business, so in practice it is business unless the licence has lapsed.

logostringThe shop's logo as an absolute URL, empty when none is set. The same setting the invoices use.

currencyobjectThe shop's money.

defaultintegerThe currency id, a row in the shop's own table, not an ISO code.

price_with_taxbooleanWhether prices are shown to customers with tax included. Display only: the prices in this API are as stored.

operatorobjectThe user the device is bound to.

idinteger0 when the device is bound to nobody, which is a device paired without an operator.

namestring|nullTheir display name.

rolestringadmin when they may manage the component, staff otherwise.

scopesstring[]What this device may do: read, and write when it was granted.

permissionsobjectWhat the operator's access levels allow, keyed by resource (product, order, category, discount, user, zone, characteristic, massaction, dashboard), each with view, manage and delete. Use it to leave controls out rather than showing a screen full of refusals. Its keys are the resources this HikaShop knows about, so an add-on can add one.

capabilitiesobjectWhat this shop can do beyond the basics.

posbooleanReserved for the point of sale, false for now.

pushbooleanReserved for push notifications, false for now.

multivendorbooleanWhether HikaMarket is installed.

GET/site

curl "$SHOP/hikashop-api/v1/site" \
  -H "Authorization: Bearer $TOKEN"

200success

{
    "data": {
        "app": "hikashop-connector",
        "api_version": "1.0.0",
        "site_name": "HikaShop Test",
        "hikashop_version": "6.5.1",
        "cms": {
            "name": "joomla",
            "version": "6.1.1"
        },
        "edition": "essential",
        "logo": "",
        "currency": {
            "default": 1
        },
        "price_with_tax": true,
        "operator": {
            "id": 0,
            "name": null,
            "role": "staff"
        },
        "scopes": [
            "read",
            "write"
        ],
        "permissions": {
            "category": {
                "view": true,
                "manage": true,
                "delete": true
            },
            "characteristic": {
                "view": true,
                "manage": true,
                "delete": true
            },
            "product": {
                "view": true,
                "manage": true,
                "delete": true
            },
            "order": {
                "view": true,
                "manage": true,
                "delete": true
            },
            "discount": {
                "view": true,
                "manage": true,
                "delete": true
            },
            "user": {
                "view": true,
                "manage": true,
                "delete": true
            },
            "zone": {
                "view": true,
                "manage": true,
                "delete": true
            },
            "dashboard": {
                "view": true,
                "manage": true,
                "delete": true
            },
            "massaction": {
                "view": true,
                "manage": true,
                "delete": true
            }
        },
        "capabilities": {
            "pos": false,
            "push": false,
            "multivendor": false
        }
    },
    "meta": null,
    "error": null
}

The settings that decide how prices read

GET /settings read since 6.6.0

The handful of configuration flags a client needs in order to show the same figures the shop's own pages show. They are read only here; they are changed in the backend.

Response

FieldTypeDescription

product_contactbooleanWhether products can be enquired about rather than bought.

product_waitlistbooleanWhether customers can join a waiting list for something out of stock.

price_with_taxbooleanShow prices with tax included.

floating_tax_pricesbooleanWhether the tax shown depends on the customer, which means a price cannot be cached across customers.

show_original_pricebooleanShow the price before a discount alongside the discounted one.

round_calculationsintegerWhen rounding happens during a calculation. Match it or your totals will differ from the shop by a cent.

GET/settings

curl "$SHOP/hikashop-api/v1/settings" \
  -H "Authorization: Bearer $TOKEN"

200success

{
    "data": {
        "product_contact": false,
        "product_waitlist": false,
        "price_with_tax": true,
        "floating_tax_prices": false,
        "show_original_price": false,
        "round_calculations": 0
    },
    "meta": null,
    "error": null
}

Change tokens for the cacheable resources

GET /version read since 6.6.0

Three opaque tokens, one for each resource worth caching. A token changes when its resource does, so a client keeps the copy it has until the token moves.

Compare them, do not read them. They are strings today and their meaning is deliberately not part of this contract.

This is what makes a dictionary of several thousand strings affordable: fetch it once, ask this cheap route afterwards.

Response

FieldTypeDescription

i18nstringMoves when the shop's translations change.

statusesstringMoves when an order status is added, renamed or unpublished.

languagesstringMoves when the shop's languages change.

GET/version

curl "$SHOP/hikashop-api/v1/version" \
  -H "Authorization: Bearer $TOKEN"

200success

{
    "data": {
        "i18n": "1786385909",
        "statuses": "1834471105",
        "languages": "1820052638"
    },
    "meta": null,
    "error": null
}

The shop's order statuses

GET /statuses read since 6.6.0

Every published order status, in the order the backend shows them. A shop invents its own, so this list is not a fixed set and should never be hard coded.

The namekey is the identifier to send to POST /orders/{id}/status; the name is for a person to read.

Response a list

FieldTypeDescription

namekeystringThe identifier. This is what you send when changing an order.

namestringTranslated into the operator's language, ready to display.

label_keystringThe translation key behind that name, if you would rather translate it yourself.

colorstringThe colour the backend uses for this status, empty when none is set.

GET/statuses

curl "$SHOP/hikashop-api/v1/statuses" \
  -H "Authorization: Bearer $TOKEN"

200success

{
    "data": [
        {
            "namekey": "created",
            "name": "created",
            "label_key": "ORDER_STATUS_CREATED",
            "color": ""
        },
        {
            "namekey": "confirmed",
            "name": "confirmed",
            "label_key": "ORDER_STATUS_CONFIRMED",
            "color": ""
        },
        {
            "namekey": "cancelled",
            "name": "cancelled",
            "label_key": "ORDER_STATUS_CANCELLED",
            "color": ""
        },
        {
            "namekey": "refunded",
            "name": "refunded",
            "label_key": "ORDER_STATUS_REFUNDED",
            "color": ""
        },
        "… 4 more, trimmed for the example"
    ],
    "meta": null,
    "error": null
}

HikaShop's own translation of a locale

GET /i18n read since 6.6.0

The shop's translation dictionary for one locale, so that a client can name things exactly as the merchant's own site names them, including whatever they have overridden.

It is large. Cache it against the i18n token from GET /version rather than fetching it again.

Query

ParameterTypeDescription

localestringA HikaShop language tag such as en-GB. Falls back to the site language when it is not installed.

Response

FieldTypeDescription

localestringThe locale actually served, which may not be the one asked for.

stringsobjectTranslation key to translated text. Thousands of keys, and a shop can add or override any of them, so there is no list to give.

GET/i{id}n?locale=en-GB

curl "$SHOP/hikashop-api/v1/i{id}n?locale=en-GB" \
  -H "Authorization: Bearer $TOKEN"

200success

{
    "data": {
        "locale": "en-GB",
        "strings": {
            "PRICE_BEGINNING": "",
            "PRICE_BEFORE_ORIG": " (",
            "PRICE_AFTER_ORIG": ") ",
            "PRICE_DISCOUNT_START": "",
            "PRICE_DISCOUNT_END": "",
            "PRICE_BEFORE_TAX": " (",
            "PRICE_AFTER_TAX": " excl VAT) ",
            "PRICE_END": "",
            "FREE_PRICE": "Free",
            "PRICE_SEPARATOR": "<br/>",
            "PER_UNIT_AT_LEAST_X_BOUGHT": " per unit for buying at least %s",
            "PER_UNIT": " each",
            "ITEM_NOT_SOLD_ANYMORE": "Item not sold anymore",
            "ITEM_SOLD_ON_DATE": "This item will be sold starting on %s",
            "ADD_TO_CART": "Add to cart",
            "NO_STOCK": "No stock",
            "X_ITEMS_IN_STOCK": "%s items in stock",
            "X_ITEMS_IN_STOCK_ONE": "%s item in stock",
            "X_ITEMS_IN_STOCK_1": "%s item in stock",
            "SPECIFICATIONS": "Specifications",
            "REFRESH_INFORMATION": "Refresh information",
            "NO_VALUES_FOUND": "No values found",
            "PRODUCT": "Product",
            "CART_PRODUCT_NAME": "Name",
            "CART_PRODUCT_QUANTITY": "Qty",
            "CART_PRODUCT_PRICE": "Price",
            "CART_PRODUCT_UNIT_PRICE": "Unit price",
            "CART_PRODUCT_TOTAL_PRICE": "Total price",
            "CART_EMPTY": "The cart is empty",
            "HIKASHOP_TOTAL": "Total",
            "HIKASHOP_FINAL_TOTAL": "Final total",
            "PROCEED_TO_CHECKOUT": "Proceed to checkout",
            "REFRESH_CART": "Refresh cart",
            "PRODUCT_NOT_AVAILABLE": "The product %s is not available",
            "NOT_ENOUGH_STOCK_FOR_PRODUCT": "There is not enough stock for the product %s",
            "PRODUCT_NOT_YET_ON_SALE": "The product %s is not yet on sale",
            "PRODUCT_NOT_SOLD_ANYMORE": "The product %s is no longer on sale",
            "PRODUCT_SUCCESSFULLY_ADDED_TO_CART": "Product successfully added to the cart",
            "HIKASHOP_CHECKOUT_CART": "Cart",
            "HIKASHOP_CHECKOUT_CONFIRM": "Confirm",
            "HIKASHOP_CHECKOUT_STATUS": "Status",
            "HIKASHOP_CHECKOUT_SHIPPING": "Shipping",
            "HIKASHOP_CHECKOUT_PAYMENT": "Payment",
            "HIKASHOP_CHECKOUT_END": "End",
            "HIKASHOP_CHECKOUT_COUPON": "Coupon",
            "HIKASHOP_CHECKOUT_LOGIN": "Login",
            "HIKASHOP_CHECKOUT_ADDRESS": "Address",
            "NEXT": "Next",
            "CONTINUE_SHOPPING": "Continue shopping",
            "THANK_YOU_FOR_PURCHASE": "Thank you for your purchase.",
            "ORDER_IS_COMPLETE": "Your order is now complete.",
            "CURRENCY_NOT_ACCEPTED_FOR_PAYMENT": "The currency you selected is not accepted for payments",
            "PLEASE_ACCEPT_TERMS_BEFORE_FINISHING_ORDER": "Please accept the Terms and Conditions before proceeding",
            "PLEASE_ACCEPT_TERMS": "Please accept the Terms and Conditions before proceeding",
            "ADDITIONAL_INFORMATION": "Additional information",
            "LOGIN_OR_REGISTER_ACCOUNT": "Login or create a new account",
            "REGISTRATION_NOT_ALLOWED": "Registration not allowed",
            "WHEN_CLICKING_ACTIVATION": "Upon clicking on the activation link, your account will be activated and you will be able to continue your order",
            "PASSWORDS_DO_NOT_MATCH": "Passwords do not match",
            "VALID_EMAIL": "Please enter a valid e-mail address",
            "…": "4480 more keys, trimmed for the example"
        }
    },
    "meta": null,
    "error": null
}

The shop's languages

GET /languages read since 6.6.0

Which languages the shop publishes, and whether content translation is switched on at all.

When enabled is false the shop is single-language and the translation routes have nothing to do. The default language is marked and comes last, because it is the one already being edited on the main form rather than a translation of it.

Response

FieldTypeDescription

enabledbooleanWhether this shop translates its content. False on a single-language site.

languagesobject[]The published languages.

idintegerThe language id in the shop's table.

codestringThe tag, such as fr-FR.

shortcodestringThe lower-case underscored form, such as fr_fr, which is what the translation tables key on.

site_defaultbooleanTrue for the language the shop is written in. Its text is the original, not a translation.

GET/languages

curl "$SHOP/hikashop-api/v1/languages" \
  -H "Authorization: Bearer $TOKEN"

200success

{
    "data": {
        "enabled": true,
        "languages": [
            {
                "id": 2,
                "code": "fr-FR",
                "shortcode": "fr_fr",
                "site_default": false
            },
            {
                "id": 1,
                "code": "en-GB",
                "shortcode": "en_gb",
                "site_default": true
            }
        ]
    },
    "meta": null,
    "error": null
}

Read one product

GET /products/{id} read since 6.6.0

Everything the product editor needs in one call: the record, its prices, its images and files, its categories, its characteristics and variants, and the definitions of the custom fields that apply to it.

Ask for a variant's id and you get the variant, with parent_id set. A parent's variants are listed in full, so you rarely need to.

Path

ParameterTypeDescription

idrequiredintegerA parent product or a variant.

Response

FieldTypeDescription

idinteger

namestring

codestringThe SKU. Unique within the shop.

descriptionstringThe long description, as HTML.

description_typestringWhich editor the description was written with.

publishedboolean

quantityinteger-1 when this product does not track stock, which is not the same as 0.

msrpnumberThe manufacturer's suggested price, shown struck through when the shop is configured to.

gtinstringThe barcode: EAN, UPC or ISBN. This is what GET /products/lookup matches on.

conditionstringNew, used, refurbished. Used by the feeds rather than by the shop itself.

weightnumberShipping weight, in weight_unit.

weight_unitstringkg, g, lb or oz.

widthnumberIn dimension_unit.

heightnumberIn dimension_unit.

lengthnumberIn dimension_unit.

dimension_unitstringm, cm, mm, ft or in.

min_per_orderintegerThe smallest quantity a customer may order, 0 for no minimum.

max_per_orderintegerThe largest, 0 for no maximum.

sale_startinteger|nullUnix timestamp before which the product is not on sale.

sale_endinteger|nullUnix timestamp after which it is no longer sold.

page_titlestringSEO title, empty to use the name.

meta_descriptionstringSEO description.

keywordsstringSEO keywords.

canonicalstringA canonical URL, when this page should point at another.

urlstringThe address of the product page on the shop.

aliasstringThe slug used in that address.

accessobjectWho may see the product: mode (all, none or groups) and groups, which are user **group** ids and not Joomla view levels. The two id spaces overlap and disagree, so a value that looks plausible can grant the wrong audience.

modestringall, none, or groups when it is restricted to some.

groupsinteger[]User group ids, meaningful only when the mode is groups.

contactbooleanWhether this product is enquired about rather than bought.

warehouse_idintegerThe warehouse holding the stock, 0 when the shop has none.

typestringmain for a product, variant for one of its variants.

parent_idintegerThe parent product when this is a variant, 0 otherwise.

value_idsinteger[]For a variant, the characteristic values it stands for.

manufacturer_idintegerThe brand, 0 when unset.

manufacturer_namestringIts name, saving a second call.

tax_idintegerThe tax category, 0 when the product is untaxed.

tax_namestringIts name.

tax_ratenumberThe rate as a fraction, so 0.2 is twenty percent.

pricesobject[]Every price row, including the restricted ones. A product with none is not sellable.

idinteger

valuenumberTax excluded, as stored.

currency_idinteger

min_quantityintegerFrom how many items this row applies, which is how quantity breaks are expressed.

accessobjectWho this price is for, in the same shape as the product access.

modestringAs above.

groupsinteger[]As above.

usersinteger[]Named customers, empty for everyone.

zone_idsinteger[]Zones this price applies in, empty for everywhere.

start_dateinteger|nullUnix timestamp.

end_dateinteger|nullUnix timestamp.

imagesobject[]In the order the editor shows them; the first is the main image.

idinteger

namestring

pathstringRelative to the upload folder.

urlstringAbsolute, ready to display.

orderinginteger

descriptionstringThe alt text.

accessobjectWho may see it.

modestringAs above.

groupsinteger[]As above.

free_downloadbooleanFiles only; meaningless on an image.

filesobject[]Downloadable files, in the same shape as the images.

idinteger

namestring

pathstringRelative to the upload folder.

urlstringAbsolute.

orderinginteger

descriptionstring

accessobjectWho may download it.

free_downloadbooleanWhether it can be downloaded without buying the product.

categoriesobject[]The categories the product is in.

idinteger

namestring

bundleobject[]The products this one is made of, when it is a bundle.

idinteger

namestring

codestring

quantityintegerHow many of it the bundle contains.

optionsobject[]Products offered as options alongside this one.

idinteger

namestring

codestring

quantityinteger

relatedobject[]Products shown as related.

idinteger

namestring

codestring

quantityinteger

tagsinteger[]CMS tag ids.

characteristicsobject[]The characteristics this product varies on. Empty when it has no variants.

idintegerThe characteristic, such as Size.

namestringIts name.

valuesobject[]The values of it this product uses, such as S, M and L.

idintegerThe value id, which is what a variant refers to.

valuestringIts name, such as M.

variantsobject[]Every variant, with its own code, stock, price and images. Empty for a product that does not vary.

idintegerThe variant is a product in its own right, and this is its id.

codestringIts own SKU.

quantityintegerIts own stock. This is the figure to change, not the parent's.

publishedboolean

pricenumber|nullnull when the variant has no price of its own and the parent's applies.

valuesobject[]Which characteristic values this variant stands for, one per characteristic.

option_idintegerThe characteristic.

option_namestringIts name, so the variant can be labelled without a second call.

value_idintegerThe value.

valuestringIts name.

imagesobject[]The variant's own images, in the same shape as the product's.

idinteger

namestring

pathstringRelative to the upload folder.

urlstringAbsolute.

orderinginteger

fieldsobject[]The definitions of the custom fields that apply to this product, so a client can build a form for them.

namekeystringThe key used in custom_fields.

typestringtext, radio, singledropdown, file, and the rest of HikaShop's field types.

raw_typestringHikaShop's own name for the type, before it is mapped to something a client can render.

labelstringTranslated into the operator's language.

defaultstringThe value used when none is given.

requiredbooleanWhether the shop refuses to save the product without it.

optionsobject[]The choices, for a field that has them. Empty for a free text one.

multiplebooleanWhether more than one choice may be selected.

translatablebooleanWhether its value can be translated, which is what the translation routes offer.

upload_dirstringFor a file field, where its uploads are kept.

allowed_extensionsstringFor a file field, the extensions it accepts, comma separated. Empty means the shop default.

date_formatstringFor a date field, the format it is stored in.

custom_fieldsobjectTheir values, keyed by namekey. The keys are whatever this shop has configured; fields in the same response says what they are.

custom_field_filesobjectFor custom fields holding a file, the file behind each value. Keyed the same way.

GET/products/{id}

curl "$SHOP/hikashop-api/v1/products/{id}" \
  -H "Authorization: Bearer $TOKEN"

200success

{
    "data": {
        "id": 8645,
        "name": "Merino Socks — Pair",
        "code": "DEMO-0012",
        "description": "A socks we have carried since the shop opened, and still the one we use ourselves.",
        "description_type": "",
        "published": true,
        "quantity": 46,
        "msrp": 0,
        "gtin": "",
        "condition": "",
        "weight": 1.545,
        "weight_unit": "kg",
        "width": 0,
        "height": 0,
        "length": 0,
        "dimension_unit": "m",
        "min_per_order": 0,
        "max_per_order": 0,
        "sale_start": 0,
        "sale_end": 0,
        "page_title": "",
        "meta_description": "",
        "keywords": "",
        "canonical": "",
        "url": "",
        "alias": "",
        "access": {
            "mode": "all",
            "groups": []
        },
        "contact": false,
        "warehouse_id": 0,
        "type": "main",
        "parent_id": 0,
        "value_ids": [],
        "manufacturer_id": 0,
        "manufacturer_name": "",
        "tax_id": 0,
        "tax_name": "",
        "tax_rate": 0,
        "prices": [
            {
                "id": 4641,
                "value": 108.92,
                "currency_id": 1,
                "min_quantity": 0,
                "access": {
                    "mode": "all",
                    "groups": []
                },
                "users": [],
                "zone_ids": [],
                "start_date": 0,
                "end_date": 0
            }
        ],
        "images": [
            {
                "id": 7767,
                "name": "Merino Socks — Pair",
                "path": "demo-0012.png",
                "url": "http://localhost:8080/apidoc_capture/images/com_hikashop/upload/demo-0012.png",
                "ordering": 1,
                "description": "",
                "access": {
                    "mode": "all",
                    "groups": []
                },
                "free_download": false
            },
            {
                "id": 7768,
                "name": "Merino Socks — Pair",
                "path": "demo-0012-2.png",
                "url": "http://localhost:8080/apidoc_capture/images/com_hikashop/upload/demo-0012-2.png",
                "ordering": 2,
                "description": "",
                "access": {
                    "mode": "all",
                    "groups": []
                },
                "free_download": false
            },
            {
                "id": 7769,
                "name": "Merino Socks — Pair",
                "path": "demo-0012-3.png",
                "url": "http://localhost:8080/apidoc_capture/images/com_hikashop/upload/demo-0012-3.png",
                "ordering": 3,
                "description": "",
                "access": {
                    "mode": "all",
                    "groups": []
                },
                "free_download": false
            }
        ],
        "files": [],
        "categories": [
            {
                "id": 237,
                "name": "Wallets"
            }
        ],
        "bundle": [],
        "options": [],
        "related": [],
        "tags": [],
        "characteristics": [
            {
                "id": 8,
                "name": "Size",
                "values": [
                    {
                        "id": 9,
                        "value": "S"
                    },
                    {
                        "id": 10,
                        "value": "L"
                    },
                    {
                        "id": 21,
                        "value": "M"
                    },
                    {
                        "id": 35,
                        "value": "XS"
                    },
                    "… 1 more, trimmed for the example"
                ]
            }
        ],
        "variants": [
            {
                "id": 8646,
                "code": "DEMO-0012-XS",
                "quantity": 11,
                "published": true,
                "price": null,
                "values": [
                    {
                        "option_id": 8,
                        "option_name": "Size",
                        "value_id": 35,
                        "value": "XS"
                    }
                ],
                "images": [
                    {
                        "id": 7770,
                        "name": "Merino Socks — Pair — XS",
                        "path": "demo-0012-xs.png",
                        "url": "http://localhost:8080/apidoc_capture/images/com_hikashop/upload/demo-0012-xs.png",
                        "ordering": 1
                    }
                ]
            },
            {
                "id": 8647,
                "code": "DEMO-0012-S",
                "quantity": 0,
                "published": true,
                "price": null,
                "values": [
                    {
                        "option_id": 8,
                        "option_name": "Size",
                        "value_id": 9,
                        "value": "S"
                    }
                ],
                "images": [
                    {
                        "id": 7771,
                        "name": "Merino Socks — Pair — S",
                        "path": "demo-0012-s.png",
                        "url": "http://localhost:8080/apidoc_capture/images/com_hikashop/upload/demo-0012-s.png",
                        "ordering": 1
                    }
                ]
            },
            {
                "id": 8648,
                "code": "DEMO-0012-M",
                "quantity": 21,
                "published": true,
                "price": null,
                "values": [
                    {
                        "option_id": 8,
                        "option_name": "Size",
                        "value_id": 21,
                        "value": "M"
                    }
                ],
                "images": [
                    {
                        "id": 7772,
                        "name": "Merino Socks — Pair — M",
                        "path": "demo-0012-m.png",
                        "url": "http://localhost:8080/apidoc_capture/images/com_hikashop/upload/demo-0012-m.png",
                        "ordering": 1
                    }
                ]
            },
            {
                "id": 8649,
                "code": "DEMO-0012-L",
                "quantity": 1,
                "published": true,
                "price": null,
                "values": [
                    {
                        "option_id": 8,
                        "option_name": "Size",
                        "value_id": 10,
                        "value": "L"
                    }
                ],
                "images": [
                    {
                        "id": 7773,
                        "name": "Merino Socks — Pair — L",
                        "path": "demo-0012-l.png",
                        "url": "http://localhost:8080/apidoc_capture/images/com_hikashop/upload/demo-0012-l.png",
                        "ordering": 1
                    }
                ]
            },
            "… 1 more, trimmed for the example"
        ],
        "fields": [
            {
                "namekey": "test_ajax_image",
                "type": "ajaximage",
                "raw_type": "ajaximage",
                "label": "Test Ajax Image",
                "default": "",
                "required": false,
                "options": [],
                "multiple": false,
                "translatable": false,
                "upload_dir": "",
                "allowed_extensions": "",
                "date_format": "%Y-%m-%d"
            },
            {
                "namekey": "product_gtin",
                "type": "text",
                "raw_type": "text",
                "label": "GTIN",
                "default": "",
                "required": false,
                "options": [],
                "multiple": false,
                "translatable": false,
                "upload_dir": "",
                "allowed_extensions": "",
                "date_format": ""
            }
        ],
        "custom_fields": {
            "test_ajax_image": null,
            "product_gtin": null
        },
        "custom_field_files": {
            "test_ajax_image": []
        }
    },
    "meta": null,
    "error": null
}

Resolve a scanned barcode

GET /products/lookup read since 6.6.0

One product from one barcode, for a scanner. It matches the product code and the GTIN, and it looks at variants as well as parents, because the thing with a barcode on it is usually the variant.

Exactly one product comes back, or not_found. It is deliberately not a search: a scanner needs an answer, not a list.

Query

ParameterTypeDescription

barcoderequiredstringWhat the scanner read. Matched against the product code and the GTIN.

Response

FieldTypeDescription

idintegerThe product to open. For a variant, this is its parent.

variant_idintegerThe variant that was scanned, 0 when the barcode belonged to the parent.

namestring

codestringThe SKU that matched.

gtinstringThe barcode held on the record, which may differ in leading zeros from what was scanned.

quantityintegerThe stock of whichever record matched, so a stock take needs no second call.

Errors

CodeHTTPMeans

missing_barcode400No barcode was given.

not_found404Nothing in the shop carries that code.

GET/products/lookup?barcode=TEST{id}

curl "$SHOP/hikashop-api/v1/products/lookup?barcode=TEST{id}" \
  -H "Authorization: Bearer $TOKEN"

200success

{
    "data": {
        "id": 1,
        "variant_id": 0,
        "name": "Test Product (Vendor 2)",
        "code": "TEST001",
        "gtin": "",
        "quantity": -1
    },
    "meta": null,
    "error": null
}

Products running out

GET /products/low-stock read since 6.6.0

Sellable items at or below a stock threshold, cheapest first to reorder. Variants are listed in their own right, since that is where the stock actually sits.

Products that do not track stock are left out: they are not running out of anything.

Query

ParameterTypeDescription

thresholdintegerAt or below which a product counts as low. Defaults to 5.

limitintegerDefaults to 20, capped at 100.

Response a list

FieldTypeDescription

idintegerThe parent product.

variant_idintegerThe variant that is low, 0 when the parent itself is.

namestring

codestringThe SKU of whichever record is low.

quantityintegerWhat is left.

GET/products/low-stock?threshold={id}&limit=3

curl "$SHOP/hikashop-api/v1/products/low-stock?threshold={id}&limit=3" \
  -H "Authorization: Bearer $TOKEN"

200success

{
    "data": [
        {
            "id": 8657,
            "variant_id": 0,
            "name": "Botanical Shampoo Bottle — 500 ml",
            "code": "DEMO-0019",
            "quantity": 0
        },
        {
            "id": 8896,
            "variant_id": 0,
            "name": "Brass Colored Pencils — 12",
            "code": "DEMO-0193",
            "quantity": 0
        },
        {
            "id": 9007,
            "variant_id": 0,
            "name": "Brass Colored Pencils — 36",
            "code": "DEMO-0279",
            "quantity": 0
        }
    ],
    "meta": null,
    "error": null
}

Set a product's stock

POST /products/{id}/stock write since 6.6.0

Sets the tracked quantity to an absolute figure, which is what a stock take does. It is not an adjustment: send what the shelf holds, not the difference.

A product with variants keeps no stock of its own, so set it on the variant instead. Asking to set it on the parent is refused rather than silently ignored.

Path

ParameterTypeDescription

idrequiredintegerThe product or variant to set.

Body

FieldTypeDescription

quantityrequiredintegerThe new absolute quantity. -1 turns stock tracking off for this product.

Response

FieldTypeDescription

idinteger

quantityintegerAs stored, so you can confirm what was written.

Errors

CodeHTTPMeans

not_found404No such product, or the operator may not change it.

has_variants409It is a parent: set the stock on one of its variants.

POST/products/2/stock

curl -X POST "$SHOP/hikashop-api/v1/products/2/stock" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 42
}'

200success

{
    "data": {
        "id": 2,
        "quantity": 42
    },
    "meta": null,
    "error": null
}

List customers

GET /customers read since 6.6.0

The customers the operator may see, with enough to recognise one and to know whether they have bought anything.

Guests are included. A shop that lets people order without an account still has a row for each of them, and type is how you tell the two apart.

Query

ParameterTypeDescription

startintegerOffset. Defaults to 0.

limitintegerDefaults to 20, capped at 100.

searchstringMatches the email address, the account name and login, and the first name and surname on any of their addresses, including the two together, so John Doe finds a guest who has never had an account.

Response a list

FieldTypeDescription

idintegerThe HikaShop customer id, which is not the CMS user id.

namestringThe account name, or for a guest the name on their default address, since a guest has no account to take one from.

emailstring

typestringregistered for an account, guest for someone who ordered without one.

createdintegerUnix timestamp of the first time the shop saw them.

order_countintegerHow many orders they have placed, so a list can be sorted by worth without a second call.

Envelope meta

FieldTypeDescription

startintegerEchoes the offset used.

limitintegerEchoes the page size used.

totalintegerCustomers matching the filter, before paging.

GET/customers?limit=2

curl "$SHOP/hikashop-api/v1/customers?limit=2" \
  -H "Authorization: Bearer $TOKEN"

200success

{
    "data": [
        {
            "id": 5272,
            "name": "E2E Tester",
            "email": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
            "type": "guest",
            "created": 1786354936,
            "order_count": 0
        },
        {
            "id": 5271,
            "name": "E2E Tester",
            "email": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
            "type": "guest",
            "created": 1786353021,
            "order_count": 0
        }
    ],
    "meta": {
        "start": 0,
        "limit": 2,
        "total": 336
    },
    "error": null
}

List discounts and coupons

GET /discounts read since 6.6.0

Both kinds of reduction live in one table and are told apart by type: a discount applies by itself when its conditions are met, a coupon waits for its code to be entered.

The restriction fields are the interesting part, and they are all lists of ids: which products, which categories, which zones, which customers, and the same again for exclusions. An empty list means no restriction of that kind rather than none allowed.

Query

ParameterTypeDescription

startintegerOffset. Defaults to 0.

limitintegerDefaults to 20, capped at 100.

typestringdiscount or coupon, to list one kind.

searchstringMatches the code.

Response a list

FieldTypeDescription

idinteger

typestringdiscount applies by itself, coupon waits for its code.

codestringWhat the customer types. Empty on a discount.

kindstringWhether the value is a percentage or a fixed amount.

valuenumberThe reduction, read according to kind.

currency_idintegerThe currency a fixed amount is in.

publishedboolean

startinteger|nullUnix timestamp before which it does not apply.

endinteger|nullUnix timestamp after which it expires.

minimum_ordernumberOrder total below which it does not apply, 0 for none.

maximum_ordernumberOrder total above which it stops applying, 0 for none.

quotaintegerHow many times it may be used in total, 0 for no limit.

quota_per_userintegerHow many times one customer may use it, 0 for no limit.

used_timesintegerHow many times it already has been.

tax_includedbooleanWhether the value is understood as tax included.

tax_idintegerThe tax category of the reduction itself.

shipping_percentnumberA reduction on the shipping rather than on the goods.

minimum_productsintegerFewest items in the cart for it to apply.

maximum_productsintegerMost items for it to still apply.

product_idsinteger[]Restricted to these products. Empty means all of them.

exclude_product_idsinteger[]Never applies to these.

category_idsinteger[]Restricted to these categories.

category_childsbooleanWhether those categories include their sub-categories.

exclude_category_idsinteger[]Never applies in these categories.

exclude_category_childsbooleanWhether those exclusions include sub-categories.

zone_idsinteger[]Restricted to these zones.

user_idsinteger[]Restricted to these customers.

accessobjectWhich user groups it is for, in the usual mode and groups shape.

modestringall, none, or groups when it is restricted to some.

groupsinteger[]User **group** ids, and not Joomla view levels. The two id spaces overlap and disagree, so a value that looks plausible can grant the wrong audience.

exclude_accessobjectWhich user groups it is never for.

modestringall, none, or groups when it is restricted to some.

groupsinteger[]User **group** ids, and not Joomla view levels. The two id spaces overlap and disagree, so a value that looks plausible can grant the wrong audience.

auto_loadbooleanFor a coupon, whether the shop applies it without the customer typing it.

product_onlybooleanWhether it reduces only the goods and leaves the fees alone.

discounted_productsintegerHow many products in the cart it applied to, on a discount that has been used.

Envelope meta

FieldTypeDescription

startintegerEchoes the offset used.

limitintegerEchoes the page size used.

totalintegerRows matching the filter, before paging.

GET/discounts?limit=2

curl "$SHOP/hikashop-api/v1/discounts?limit=2" \
  -H "Authorization: Bearer $TOKEN"

200success

{
    "data": [
        {
            "id": 435,
            "type": "discount",
            "code": "auto-2",
            "kind": "percent",
            "value": 9,
            "currency_id": 0,
            "published": true,
            "start": 0,
            "end": 0,
            "minimum_order": 0,
            "maximum_order": 0,
            "quota": 0,
            "quota_per_user": 0,
            "used_times": 0,
            "tax_included": false,
            "tax_id": 0,
            "shipping_percent": 0,
            "minimum_products": 0,
            "maximum_products": 0,
            "product_ids": [],
            "exclude_product_ids": [],
            "category_ids": [],
            "category_childs": false,
            "exclude_category_ids": [],
            "exclude_category_childs": false,
            "zone_ids": [],
            "user_ids": [],
            "access": {
                "mode": "all",
                "groups": []
            },
            "exclude_access": {
                "mode": "none",
                "groups": []
            },
            "auto_load": false,
            "product_only": false,
            "discounted_products": 0
        },
        {
            "id": 434,
            "type": "coupon",
            "code": "E2E1786215747620",
            "kind": "percent",
            "value": 12,
            "currency_id": 0,
            "published": true,
            "start": 0,
            "end": 0,
            "minimum_order": 0,
            "maximum_order": 0,
            "quota": 0,
            "quota_per_user": 0,
            "used_times": 0,
            "tax_included": false,
            "tax_id": 0,
            "shipping_percent": 0,
            "minimum_products": 0,
            "maximum_products": 0,
            "product_ids": [],
            "exclude_product_ids": [],
            "category_ids": [],
            "category_childs": false,
            "exclude_category_ids": [],
            "exclude_category_childs": false,
            "zone_ids": [],
            "user_ids": [],
            "access": {
                "mode": "all",
                "groups": []
            },
            "exclude_access": {
                "mode": "none",
                "groups": []
            },
            "auto_load": false,
            "product_only": false,
            "discounted_products": 0
        }
    ],
    "meta": {
        "start": 0,
        "limit": 2,
        "total": 5
    },
    "error": null
}

The category tree

GET /categories read since 6.6.0

One level of the category tree at a time, unpublished categories included, which is what makes this a management view rather than a shop one.

Pass a parent_id to walk down. has_children tells you whether there is anything below without asking, so a tree can be drawn lazily.

HikaShop keeps its manufacturers and its tax categories in the same table as the product categories, told apart by their root. Ask for the tree you want.

Query

ParameterTypeDescription

parent_idintegerWhose children to list. Omit for the top level.

startintegerOffset. Defaults to 0.

limitintegerDefaults to 20, capped at 100.

searchstringMatches the name, across the whole tree rather than one level.

Response a list

FieldTypeDescription

idinteger

namestring

parent_idintegerIts parent, so a flat answer can be rebuilt into a tree.

publishedboolean

has_childrenbooleanWhether anything sits below it.

imagestring|nullAbsolute URL of its image, null when it has none.

Envelope meta

FieldTypeDescription

totalintegerCategories matching, before paging.

startintegerEchoes the offset used.

limitintegerEchoes the page size used.

GET/categories?limit=3

curl "$SHOP/hikashop-api/v1/categories?limit=3" \
  -H "Authorization: Bearer $TOKEN"

200success

{
    "data": [
        {
            "id": 218,
            "name": "Bags & Wear",
            "parent_id": 2,
            "published": true,
            "has_children": true,
            "image": "http://localhost:8080/apidoc_capture/images/com_hikashop/upload/demo-cat-218.png"
        },
        {
            "id": 220,
            "name": "Beauty",
            "parent_id": 2,
            "published": true,
            "has_children": true,
            "image": "http://localhost:8080/apidoc_capture/images/com_hikashop/upload/demo-cat-220.png"
        },
        {
            "id": 194,
            "name": "Boots",
            "parent_id": 2,
            "published": true,
            "has_children": true,
            "image": ""
        }
    ],
    "meta": {
        "total": 20,
        "start": 0,
        "limit": 3
    },
    "error": null
}

Read one category

GET /categories/{id} read since 6.6.0

A category with its description, its image, who may see it, and your own category fields.

Path

ParameterTypeDescription

idrequiredintegerThe category id.

Response

FieldTypeDescription

fieldsobject[]The definitions of your own category fields.

idinteger

namestring

parent_idintegerIts parent.

typestringWhich tree it belongs to: product, manufacturer, tax, and so on.

descriptionstringThe long description, as HTML.

meta_descriptionstringSEO description.

publishedboolean

accessobjectWho may see it.

modestringall, none, or groups when it is restricted to some.

groupsinteger[]User **group** ids, and not Joomla view levels. The two id spaces overlap and disagree, so a value that looks plausible can grant the wrong audience.

imagestring|nullAbsolute URL of its image, null when it has none.

custom_fieldsobjectTheir values, keyed by namekey. The keys depend on the shop; fields says what they are.

custom_field_filesobjectFor a field holding a file, the file behind the value. Keyed the same way.

GET/categories/2

curl "$SHOP/hikashop-api/v1/categories/2" \
  -H "Authorization: Bearer $TOKEN"

200success

{
    "data": {
        "fields": [],
        "id": 2,
        "name": "product category",
        "parent_id": 1,
        "type": "product",
        "description": "",
        "meta_description": "",
        "published": true,
        "access": {
            "mode": "all",
            "groups": []
        },
        "image": "",
        "custom_fields": [],
        "custom_field_files": []
    },
    "meta": null,
    "error": null
}

The shop's own bulk operations

GET /massactions read since 6.6.0

The mass actions the merchant has configured for a listing, so a client can offer the merchant's own bulk operations rather than a fixed set of its own.

Whatever they built in the backend appears here, and running one is POST /massactions/{id}.

Query

ParameterTypeDescription

tablerequiredstringWhich listing: product, order, user, category, address.

Response a list

FieldTypeDescription

idintegerWhat to run.

namestringAs the merchant named it.

descriptionstringTheir own note about what it does, when they wrote one.

tablestringThe listing it belongs to.

restrictedbooleanWhether it may only run on a selection rather than on everything matching a filter.

Errors

CodeHTTPMeans

invalid_request400The table is not one the shop has mass actions for.

forbidden403The operator may not view that kind of record.

GET/massactions?table=product

curl "$SHOP/hikashop-api/v1/massactions?table=product" \
  -H "Authorization: Bearer $TOKEN"

200success

{
    "data": [
        {
            "id": 2,
            "name": "Unpublish selected",
            "description": "Takes the chosen products off sale.",
            "table": "product",
            "restricted": false
        }
    ],
    "meta": null,
    "error": null
}

Browse the upload folder

GET /media/browse read since 6.6.0

Folders and images inside the shop's upload folder, so an existing image can be picked instead of uploaded again.

Paths are relative to that folder and never escape it: a path pointing outside is refused rather than resolved.

Query

ParameterTypeDescription

folderstringWhich folder to list, relative to the upload folder. Omit for its root.

offsetintegerOffset into the images, for a folder with many.

Response

FieldTypeDescription

folderstringThe folder being listed.

parentstringThe folder above, for walking back up.

has_parentbooleanFalse at the root, where there is nothing above.

foldersobject[]The folders inside it.

imagesobject[]The images inside it.

namestringThe file name.

pathstringRelative to the upload folder, which is what a product image stores.

urlstringAbsolute, ready to display.

totalintegerHow many images the folder holds in all.

offsetintegerEchoes the offset used.

Errors

CodeHTTPMeans

not_found404No such folder, or a path that tried to leave the upload folder.

GET/media/browse

curl "$SHOP/hikashop-api/v1/media/browse" \
  -H "Authorization: Bearer $TOKEN"

200success

{
    "data": {
        "folder": "",
        "parent": "",
        "has_parent": false,
        "folders": [],
        "images": [
            {
                "name": "demo-0001.png",
                "path": "demo-0001.png",
                "url": "http://localhost:8080/apidoc_capture/images/com_hikashop/upload/demo-0001.png"
            },
            {
                "name": "demo-0002-2.png",
                "path": "demo-0002-2.png",
                "url": "http://localhost:8080/apidoc_capture/images/com_hikashop/upload/demo-0002-2.png"
            },
            {
                "name": "demo-0002.png",
                "path": "demo-0002.png",
                "url": "http://localhost:8080/apidoc_capture/images/com_hikashop/upload/demo-0002.png"
            },
            {
                "name": "demo-0003.png",
                "path": "demo-0003.png",
                "url": "http://localhost:8080/apidoc_capture/images/com_hikashop/upload/demo-0003.png"
            },
            "… 579 more, trimmed for the example"
        ],
        "total": 583,
        "offset": 0
    },
    "meta": null,
    "error": null
}

Search countries, states and zones

GET /zones read since 6.6.0

The shop's zones, which are its countries, its states and any grouping the merchant made of them. Meant for filling a picker: search for a name, or resolve ids you already hold.

An address stores a zone by its namekey rather than its id, which is why both come back.

Query

ParameterTypeDescription

searchstringMatches the name.

idsstringComma separated zone ids, to resolve a known set.

typestringRestrict to country, state or a zone group.

Response a list

FieldTypeDescription

idinteger

namekeystringWhat an address stores, such as FRA or US-CA.

namestringTranslated where the shop has a translation for it.

typestringcountry, state, or the kind of grouping it is.

GET/zones?search=fra

curl "$SHOP/hikashop-api/v1/zones?search=fra" \
  -H "Authorization: Bearer $TOKEN"

200success

{
    "data": [
        {
            "id": 73,
            "namekey": "country_France_73",
            "name": "France",
            "type": "country"
        },
        {
            "id": 2195,
            "namekey": "state_Al_Jufrah_2195",
            "name": "Al Jufrah",
            "type": "state"
        },
        {
            "id": 2196,
            "namekey": "state_Al_Kufrah_2196",
            "name": "Al Kufrah",
            "type": "state"
        },
        {
            "id": 1631,
            "namekey": "state_Francisco_Moraz__n_1631",
            "name": "Francisco Morazán",
            "type": "state"
        },
        "… 4 more, trimmed for the example"
    ],
    "meta": null,
    "error": null
}

Search customers for a picker

GET /users read since 6.6.0

A short list of customers matching a search, for the pickers that restrict a price or a discount to named people. GET /customers is the listing to use for anything else.

Query

ParameterTypeDescription

searchstringMatches the name and the email address.

idsstringComma separated ids, to resolve a known set.

Response a list

FieldTypeDescription

idintegerThe customer id, which is what a restriction stores.

namestring

emailstringEnough to tell two people of the same name apart.

GET/users?search=a

curl "$SHOP/hikashop-api/v1/users?search=a" \
  -H "Authorization: Bearer $TOKEN"

200success

{
    "data": [
        {
            "id": 5272,
            "name": "",
            "email": "This email address is being protected from spambots. You need JavaScript enabled to view it."
        },
        {
            "id": 20,
            "name": "",
            "email": "This email address is being protected from spambots. You need JavaScript enabled to view it."
        },
        {
            "id": 4939,
            "name": "",
            "email": "This email address is being protected from spambots. You need JavaScript enabled to view it."
        },
        {
            "id": 4940,
            "name": "",
            "email": "This email address is being protected from spambots. You need JavaScript enabled to view it."
        },
        "… 26 more, trimmed for the example"
    ],
    "meta": null,
    "error": null
}

Reference data for the product editor

GET /products/meta read since 6.6.0

Everything a product form needs to offer choices: the currencies with their formatting, the tax categories, the characteristics and their values, the units, the field definitions, the warehouses and the tags.

One call rather than eight, and it changes rarely, so cache it.

Response

FieldTypeDescription

currenciesobject[]Every published currency, with enough to format an amount the way the shop does.

idintegerWhat a price stores.

codestringThe ISO code, such as EUR.

symbolstring

namestring

decimalsintegerHow many decimal places to show.

decimal_sepstringThe decimal separator.

thousands_sepstringThe thousands separator.

symbol_beforebooleanWhether the symbol goes before the figure.

spacebooleanWhether a space separates the symbol from the figure.

rounding_incrementnumberWhat amounts are rounded to, for a currency without small coins.

main_currency_idintegerThe shop's own currency.

tax_categoriesobject[]The tax categories a product can be put in.

idintegerWhat tax_id on a product stores.

namestring

parent_idintegerThey live in the category tree, so they have a parent like anything else there.

characteristicsobject[]Every characteristic in the shop, with its values, for building variants.

idinteger

namestring

valuesobject[]Its values.

idintegerWhat a variant refers to.

valuestringIts name, such as M.

weight_unitsstring[]The weight units the shop accepts, such as kg.

dimension_unitsstring[]The dimension units the shop accepts, such as m.

product_fieldsobject[]The definitions of your own product fields.

namekeystringThe key its value is stored under.

typestringWhat to render: text, radio, singledropdown, file, and the rest.

raw_typestringHikaShop's own name for the type.

labelstringTranslated into the operator's language.

defaultstringThe value used when none is given.

requiredbooleanWhether the shop refuses to save without it.

optionsobject[]The choices, for a field that has them.

valuestringWhat to send back when this choice is picked.

labelstringWhat to show.

label_keystringThe translation key behind the label, when there is one.

multiplebooleanWhether more than one may be chosen.

translatablebooleanWhether its value can be translated.

upload_dirstringFor a file field, where its uploads are kept.

allowed_extensionsstringFor a file field, the extensions it accepts. Empty means the shop default.

date_formatstringFor a date field, the format it is stored in.

category_fieldsobject[]The definitions of your own category fields.

namekeystringThe key its value is stored under.

labelstringTranslated into the operator's language.

typestringWhat to render: text, radio, singledropdown, file, and the rest.

raw_typestringHikaShop's own name for the type.

requiredbooleanWhether the shop refuses to save without it.

defaultstringThe value used when none is given.

optionsobject[]The choices, for a field that has them.

valuestringWhat to send back when this choice is picked.

labelstringWhat to show.

label_keystringThe translation key behind the label, when there is one.

multiplebooleanWhether more than one may be chosen.

translatablebooleanWhether its value can be translated.

upload_dirstringFor a file field, where its uploads are kept.

allowed_extensionsstringFor a file field, the extensions it accepts. Empty means the shop default.

date_formatstringFor a date field, the format it is stored in.

bundle_supportedbooleanWhether this edition can sell bundles.

warehousesobject[]The warehouses stock can be held in. Empty when the shop has none.

idintegerWhat warehouse_id on a product stores.

namestring

tagsobject[]The CMS tags a product can carry.

idinteger

namestring

parent_idintegerTags are a tree in both Joomla and WordPress.

GET/products/meta

curl "$SHOP/hikashop-api/v1/products/meta" \
  -H "Authorization: Bearer $TOKEN"

200success

{
    "data": {
        "currencies": [
            {
                "id": 1,
                "code": "EUR",
                "symbol": "€",
                "name": "Euro",
                "decimals": 2,
                "decimal_sep": ",",
                "thousands_sep": ".",
                "symbol_before": false,
                "space": true,
                "rounding_increment": 0
            },
            {
                "id": 2,
                "code": "USD",
                "symbol": "$",
                "name": "United States dollar",
                "decimals": 2,
                "decimal_sep": ".",
                "thousands_sep": ",",
                "symbol_before": true,
                "space": false,
                "rounding_increment": 0
            }
        ],
        "main_currency_id": 1,
        "tax_categories": [
            {
                "id": 11,
                "name": "Default tax category",
                "parent_id": 3
            },
            {
                "id": 3,
                "name": "taxation category",
                "parent_id": 1
            }
        ],
        "characteristics": [
            {
                "id": 1,
                "name": "Vendor",
                "values": []
            },
            {
                "id": 5,
                "name": "Color",
                "values": [
                    {
                        "id": 6,
                        "value": "Red"
                    },
                    {
                        "id": 7,
                        "value": "Blue"
                    }
                ]
            },
            {
                "id": 8,
                "name": "Size",
                "values": [
                    {
                        "id": 9,
                        "value": "S"
                    },
                    {
                        "id": 10,
                        "value": "L"
                    },
                    {
                        "id": 21,
                        "value": "M"
                    },
                    {
                        "id": 35,
                        "value": "XS"
                    },
                    "… 1 more, trimmed for the example"
                ]
            },
            {
                "id": 14,
                "name": "Colour",
                "values": [
                    {
                        "id": 15,
                        "value": "Charcoal"
                    },
                    {
                        "id": 16,
                        "value": "Navy"
                    },
                    {
                        "id": 17,
                        "value": "Oatmeal"
                    },
                    {
                        "id": 18,
                        "value": "Forest"
                    },
                    "… 2 more, trimmed for the example"
                ]
            },
            "… 1 more, trimmed for the example"
        ],
        "weight_units": [
            "kg",
            "g",
            "mg",
            "lb",
            "… 2 more, trimmed for the example"
        ],
        "dimension_units": [
            "m",
            "dm",
            "cm",
            "mm",
            "… 3 more, trimmed for the example"
        ],
        "product_fields": [
            {
                "namekey": "test_ajax_image",
                "type": "ajaximage",
                "raw_type": "ajaximage",
                "label": "Test Ajax Image",
                "default": "",
                "required": false,
                "options": [],
                "multiple": false,
                "translatable": false,
                "upload_dir": "",
                "allowed_extensions": "",
                "date_format": "%Y-%m-%d"
            },
            {
                "namekey": "product_gtin",
                "type": "text",
                "raw_type": "text",
                "label": "GTIN",
                "default": "",
                "required": false,
                "options": [],
                "multiple": false,
                "translatable": false,
                "upload_dir": "",
                "allowed_extensions": "",
                "date_format": ""
            }
        ],
        "category_fields": [],
        "bundle_supported": true,
        "warehouses": [
            {
                "id": 1,
                "name": "Default Warehouse"
            },
            {
                "id": 2,
                "name": "Main Warehouse (renamed)"
            }
        ],
        "tags": []
    },
    "meta": null,
    "error": null
}

Replace a product's prices

PUT /products/{id}/prices write since 6.6.0

Replaces the whole price set, it does not merge into it. Send every price the product should have, including the ones you are not changing; anything you leave out is deleted.

That is deliberate, because a price set is a set: quantity breaks and audience restrictions only make sense against each other.

Path

ParameterTypeDescription

idrequiredintegerThe product or variant.

Body

FieldTypeDescription

pricesrequiredobject[]The complete set. Each needs at least a value and a currency_id; min_quantity, access, users, zone_ids, start_date and end_date are optional and default to no restriction.

Response a list

FieldTypeDescription

idinteger

valuenumberTax excluded, as stored.

currency_idinteger

min_quantityintegerFrom how many items this row applies, which is how a quantity break is expressed.

accessobjectWhich user groups the price is for.

modestringall, none or groups.

groupsinteger[]User group ids, not view levels.

usersinteger[]Named customers, empty for everyone.

zone_idsinteger[]Zones it applies in, empty for everywhere.

start_dateinteger|nullUnix timestamp.

end_dateinteger|nullUnix timestamp.

Errors

CodeHTTPMeans

invalid_request400No prices array was sent.

invalid_price400A price in the set cannot be stored, and the message says which one and why. Nothing is saved: a set is replaced whole or not at all.

not_found404No such product, or the operator may not change it.

PUT/products/{id}/prices

curl -X PUT "$SHOP/hikashop-api/v1/products/{id}/prices" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prices": [
        {
            "value": 19.9,
            "currency_id": 1,
            "min_quantity": 1
        }
    ]
}'

200success

{
    "data": [
        {
            "id": 4930,
            "value": 19.9,
            "currency_id": 1,
            "min_quantity": 1,
            "access": {
                "mode": "all",
                "groups": []
            },
            "users": [],
            "zone_ids": [],
            "start_date": 0,
            "end_date": 0
        }
    ],
    "meta": null,
    "error": null
}

Replace a product's categories

PUT /products/{id}/categories write since 6.6.0

Replaces the set of categories the product is in. As with the prices, send the complete set: what you leave out is removed.

Path

ParameterTypeDescription

idrequiredintegerThe product.

Body

FieldTypeDescription

categoriesrequiredinteger[]The complete set of category ids. An empty array takes the product out of every category, which hides it from the shop.

Response a list

FieldTypeDescription

idintegerThe category.

namestringIts name, so a client need not look it up.

Errors

CodeHTTPMeans

not_found404No such product, or the operator may not change it.

PUT/products/{id}/categories

curl -X PUT "$SHOP/hikashop-api/v1/products/{id}/categories" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "categories": [
        "230"
    ]
}'

200success

{
    "data": [
        {
            "id": 230,
            "name": "Planners"
        }
    ],
    "meta": null,
    "error": null
}

A product's translations

GET /products/{id}/translations read since 6.6.0

Which of a record's texts can be translated, what they say now in each language, and what the original says. enabled is false on a single-language shop, where there is nothing to do.

columns is the list of translatable things: HikaShop's own (the name, the description, the SEO texts) plus every custom field the merchant flagged translatable. It is built the same way the backend builds it, so what you are offered is exactly what the shop will store.

The labels and values of a custom field itself are website configuration and are not offered here; they belong in the backend.

Path

ParameterTypeDescription

idrequiredintegerThe product.

Response

FieldTypeDescription

enabledbooleanFalse on a single-language shop, where the rest is empty.

languagesobject[]The shop's languages. The default one is marked and comes last, because its text is the original rather than a translation of it.

idinteger

codestringThe tag, such as fr-FR.

shortcodestringThe lower-case underscored form the translation tables key on.

site_defaultbooleanTrue for the language the shop is written in.

columnsobject[]What can be translated on this record: HikaShop's own texts plus every custom field flagged translatable.

namestringThe column name, such as product_name. This is the key to send a translation under.

typestringtext for a line, textarea for prose, so a client knows which control to draw.

valuesobjectWhat each language says now, keyed by language code and then by column. Keyed by language code, and within that by column name, both of which depend on the shop.

originalobjectWhat the record itself says, keyed by column, so a translator can see what they are translating. Keyed by column name, which depends on the fields this shop has.

Errors

CodeHTTPMeans

not_found404No such record, or the operator may not see it.

translation_disabled400This shop does not translate content.

GET/products/1/translations

curl "$SHOP/hikashop-api/v1/products/1/translations" \
  -H "Authorization: Bearer $TOKEN"

200success

{
    "data": {
        "enabled": true,
        "languages": [
            {
                "id": 2,
                "code": "fr-FR",
                "shortcode": "fr_fr",
                "site_default": false
            },
            {
                "id": 1,
                "code": "en-GB",
                "shortcode": "en_gb",
                "site_default": true
            }
        ],
        "columns": [
            {
                "name": "product_name",
                "type": "text"
            },
            {
                "name": "product_description",
                "type": "html"
            },
            {
                "name": "product_page_title",
                "type": "text"
            },
            {
                "name": "product_url",
                "type": "text"
            },
            "… 4 more, trimmed for the example"
        ],
        "original": {
            "product_name": "Test Product (Vendor 2)",
            "product_description": "Test product owned by vendor 2",
            "product_page_title": "",
            "product_url": "",
            "product_meta_description": "",
            "product_keywords": "",
            "product_alias": "",
            "product_canonical": ""
        },
        "values": []
    },
    "meta": null,
    "error": null
}

A category's translations

GET /categories/{id}/translations read since 6.6.0

The same as for a product, for a category: its name, its description, its SEO texts and its translatable custom fields.

Path

ParameterTypeDescription

idrequiredintegerThe category.

Response

FieldTypeDescription

enabledbooleanFalse on a single-language shop, where the rest is empty.

languagesobject[]The shop's languages. The default one is marked and comes last, because its text is the original rather than a translation of it.

idinteger

codestringThe tag, such as fr-FR.

shortcodestringThe lower-case underscored form the translation tables key on.

site_defaultbooleanTrue for the language the shop is written in.

columnsobject[]What can be translated on this record: HikaShop's own texts plus every custom field flagged translatable.

namestringThe column name, such as product_name. This is the key to send a translation under.

typestringtext for a line, textarea for prose, so a client knows which control to draw.

valuesobjectWhat each language says now, keyed by language code and then by column. Keyed by language code, and within that by column name, both of which depend on the shop.

originalobjectWhat the record itself says, keyed by column, so a translator can see what they are translating. Keyed by column name, which depends on the fields this shop has.

Errors

CodeHTTPMeans

not_found404No such record, or the operator may not see it.

translation_disabled400This shop does not translate content.

GET/categories/2/translations

curl "$SHOP/hikashop-api/v1/categories/2/translations" \
  -H "Authorization: Bearer $TOKEN"

200success

{
    "data": {
        "enabled": true,
        "languages": [
            {
                "id": 2,
                "code": "fr-FR",
                "shortcode": "fr_fr",
                "site_default": false
            },
            {
                "id": 1,
                "code": "en-GB",
                "shortcode": "en_gb",
                "site_default": true
            }
        ],
        "columns": [
            {
                "name": "category_name",
                "type": "text"
            },
            {
                "name": "category_description",
                "type": "html"
            },
            {
                "name": "category_product_page_info",
                "type": "html"
            },
            {
                "name": "category_page_title",
                "type": "text"
            },
            "… 4 more, trimmed for the example"
        ],
        "original": {
            "category_name": "product category",
            "category_description": "",
            "category_product_page_info": "",
            "category_page_title": "",
            "category_meta_description": "",
            "category_keywords": "",
            "category_alias": "",
            "category_canonical": ""
        },
        "values": []
    },
    "meta": null,
    "error": null
}

Save a product's translations

PUT /products/{id}/translations write since 6.6.0

Writes the translations of one record. Send only the languages you changed; the rest are left alone.

Where the shop uses Falang, the values go into its tables. Where it does not, they become language overrides keyed on the original text, which is why renaming a product re-keys its translations rather than losing them.

Path

ParameterTypeDescription

idrequiredintegerThe product.

Body

An object keyed by language, each holding an object of column name to text:

{ "2": { "product_name": "Lampe de bureau", "product_description": "…" } }

The keys are the language ids from languages in the GET, and the column names are the ones from columns. A language you do not send is left alone, and so is a column you do not send within a language you do.

Response

FieldTypeDescription

idintegerThe record that was saved.

savedintegerHow many languages were written, so a client can tell that something was actually stored.

Errors

CodeHTTPMeans

not_found404No such record, or the operator may not change it.

translation_disabled400This shop does not translate content.

PUT/products/1/translations

curl -X PUT "$SHOP/hikashop-api/v1/products/1/translations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "2": {
        "product_name": "Lampe de bureau"
    }
}'

200success

{
    "data": {
        "id": 1,
        "saved": 1
    },
    "meta": null,
    "error": null
}

Save a category's translations

PUT /categories/{id}/translations write since 6.6.0

The same as for a product, for a category.

Path

ParameterTypeDescription

idrequiredintegerThe category.

Body

An object keyed by language, each holding an object of column name to text:

{ "2": { "product_name": "Lampe de bureau", "product_description": "…" } }

The keys are the language ids from languages in the GET, and the column names are the ones from columns. A language you do not send is left alone, and so is a column you do not send within a language you do.

Response

FieldTypeDescription

idintegerThe record that was saved.

savedintegerHow many languages were written.

Errors

CodeHTTPMeans

not_found404No such record, or the operator may not change it.

translation_disabled400This shop does not translate content.

PUT/categories/2/translations

curl -X PUT "$SHOP/hikashop-api/v1/categories/2/translations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "2": {
        "category_name": "Sacs et v\u00eatements"
    }
}'

200success

{
    "data": {
        "id": 2,
        "saved": 1
    },
    "meta": null,
    "error": null
}

Dashboard figures

GET /stats/dashboard read since 6.6.0

Revenue, orders, average basket and new customers over a period, the same figures again for the period before it so a change can be shown, the series behind them, and the best sellers.

Only orders the shop counts as sold are included, so a cancelled order does not inflate a total. Amounts are in the shop's own currency.

Query

ParameterTypeDescription

rangestringday, week, month or year. Defaults to month.

Response

FieldTypeDescription

rangestringThe period the figures cover.

currency_idintegerThe shop's currency, which every amount here is in.

totalsobjectThe four headline figures.

revenuenumberTaken in the period.

ordersintegerHow many were placed.

average_ordernumberRevenue divided by orders.

customersintegerNew customers in the period.

previousobjectThe same four figures for the preceding period of the same length, for a comparison.

revenuenumberTaken in the preceding period.

ordersintegerPlaced in it.

average_ordernumberIts average basket.

customersintegerNew customers in it.

series_granularitystringWhether the series is by day, week, month or year, which follows from the range.

revenue_seriesobject[]One point per interval, for a chart.

datestringThe interval, as a date.

revenuenumberTaken in it.

top_productsobject[]The best sellers of the period.

namestring

quantityintegerHow many were sold.

GET/stats/dashboard?range=month

curl "$SHOP/hikashop-api/v1/stats/dashboard?range=month" \
  -H "Authorization: Bearer $TOKEN"

200success

{
    "data": {
        "range": "month",
        "currency_id": 1,
        "totals": {
            "revenue": 10724.83,
            "orders": 39,
            "average_order": 275,
            "customers": 30
        },
        "previous": {
            "revenue": 13450.9,
            "orders": 39,
            "average_order": 344.89,
            "customers": 32
        },
        "series_granularity": "day",
        "revenue_series": [
            {
                "date": "+33 2 00 00 00 00",
                "revenue": 0
            },
            {
                "date": "+33 2 00 00 00 00",
                "revenue": 257.18
            },
            {
                "date": "+33 2 00 00 00 00",
                "revenue": 385.24
            },
            {
                "date": "+33 2 00 00 00 00",
                "revenue": 303.63
            },
            "… 27 more, trimmed for the example"
        ],
        "top_products": [
            {
                "name": "Test Product (Vendor 2)",
                "quantity": 7
            },
            {
                "name": "Slow-Roasted Coffee Beans — 250 g",
                "quantity": 6
            },
            {
                "name": "Speckled Scented Candle — 380 g",
                "quantity": 4
            },
            {
                "name": "Anodised Keyboard — Tenkeyless",
                "quantity": 3
            },
            "… 1 more, trimmed for the example"
        ]
    },
    "meta": null,
    "error": null
}

The user groups

GET /groups read since 6.6.0

The CMS user groups, for the pickers that restrict a price, a discount or a product to some of them. The list is the same shape on Joomla and on WordPress, which is the point of it: a client does not need to know which it is talking to.

These are the ids an access object holds. They are user groups and not Joomla view levels.

Response a list

FieldTypeDescription

idintegerWhat an access object stores.

titlestringThe name of the group.

GET/groups

curl "$SHOP/hikashop-api/v1/groups" \
  -H "Authorization: Bearer $TOKEN"

200success

{
    "data": [
        {
            "id": 1,
            "title": "Mr"
        },
        {
            "id": 9,
            "title": "Mr"
        },
        {
            "id": 6,
            "title": "Mr"
        },
        {
            "id": 7,
            "title": "Mr"
        },
        "… 5 more, trimmed for the example"
    ],
    "meta": null,
    "error": null
}

Price a product in an order

GET /orders/{id}/products/precompute read since 6.6.0

What a product would cost on this order, before adding it. The order's customer, currency and zone all bear on the price, so this asks the shop rather than guessing from the catalogue.

Use it to show a line before it is committed, then POST /orders/{id}/products to add it.

Path

ParameterTypeDescription

idrequiredintegerThe order.

Query

ParameterTypeDescription

product_idrequiredintegerThe product or variant to price.

quantityintegerHow many, which matters where the product has quantity breaks. Defaults to 1.

Response

FieldTypeDescription

product_idintegerWhat was priced.

namestring

codestringIts SKU.

quantityintegerThe quantity the price was worked out for.

pricenumberUnit price, tax excluded, in the order currency.

taxnumberTax per unit, worked out for this order rather than in general.

tax_namekeysstring[]Which tax rates that came from.

Errors

CodeHTTPMeans

not_found404No such order or no such product, or the operator may not see them.

GET/orders/{id}/products/precompute?product_id=1&quantity=2

curl "$SHOP/hikashop-api/v1/orders/{id}/products/precompute?product_id=1&quantity=2" \
  -H "Authorization: Bearer $TOKEN"

200success

{
    "data": {
        "product_id": 1,
        "name": "Test Product (Vendor 2)",
        "code": "TEST001",
        "quantity": 2,
        "price": 9.99,
        "tax": 0,
        "tax_namekeys": []
    },
    "meta": null,
    "error": null
}

Read one customer

GET /customers/{id} read since 6.6.0

A customer with their addresses, their orders, which groups they are in and your own customer fields.

can_edit_account and groups_editable are worth reading before drawing a form: they say whether this operator may change this particular account at all, so a client can leave the controls out rather than offer something that will be refused. A customer can have many addresses and one default of each kind.

Path

ParameterTypeDescription

idrequiredintegerThe customer id.

Response

FieldTypeDescription

idintegerThe HikaShop customer id, which is what every customer route takes.

cms_idintegerThe Joomla or WordPress user id, 0 for a guest with no account.

namestring

emailstring

usernamestringThe login, empty for a guest.

typestringregistered or guest.

blockedbooleanWhether the CMS account is disabled.

can_edit_accountbooleanWhether this operator may change the login and password of this particular account. False for an account above their own level, which is how a super user is protected from staff.

groups_editablebooleanWhether this operator may change which groups the customer is in.

groupsobject[]The groups they are in.

idinteger

titlestring

available_groupsobject[]Every group, with whether this operator may put the customer into it, so a picker can grey out the rest rather than offering a refusal.

idinteger

titlestring

assignablebooleanFalse for a group this operator may not grant.

createdintegerUnix timestamp of the first time the shop saw them.

addressesobject[]Their addresses, defaults first.

idinteger

typesstring[]Which of billing and shipping it is used for.

namestring

companystring

streetstring

citystring

post_codestring

telephonestring

defaultbooleanWhether it is the default for one of its types.

formattedobjectThe address laid out the way this shop lays addresses out, which depends on its address format setting.

textstringSeveral lines, for an invoice or a label.

one_linestringOne line, for a list.

ordersobject[]Their orders, newest first, enough to list them.

idinteger

numberstringThe number the customer sees.

statusstringA namekey.

createdintegerUnix timestamp.

totalnumberTax included, in the order currency.

currency_idintegerThat currency.

fieldsobject[]The definitions of your own customer fields.

custom_fieldsobjectTheir values, keyed by namekey. The keys depend on the shop; fields says what they are.

custom_field_filesobjectFor a field holding a file, the file behind the value. Keyed the same way.

Errors

CodeHTTPMeans

not_found404No such customer, or the operator may not see them.

GET/customers/{id}

curl "$SHOP/hikashop-api/v1/customers/{id}" \
  -H "Authorization: Bearer $TOKEN"

200success

{
    "data": {
        "id": 14,
        "cms_id": 156,
        "name": "Admin",
        "email": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
        "username": "admin",
        "type": "registered",
        "blocked": false,
        "can_edit_account": false,
        "groups_editable": false,
        "groups": [
            {
                "id": 8,
                "title": "Mr"
            }
        ],
        "available_groups": [
            {
                "id": 1,
                "title": "Mr",
                "assignable": false
            },
            {
                "id": 9,
                "title": "Mr",
                "assignable": false
            },
            {
                "id": 6,
                "title": "Mr",
                "assignable": false
            },
            {
                "id": 7,
                "title": "Mr",
                "assignable": false
            },
            "… 5 more, trimmed for the example"
        ],
        "created": 1778653121,
        "addresses": [
            {
                "id": 13,
                "types": [
                    "shipping"
                ],
                "name": "Test Buyer",
                "company": "Lilas SARL",
                "street": "12 rue des Lilas",
                "city": "Nantes",
                "post_code": "44000",
                "telephone": "+33 2 00 00 00 00",
                "default": true,
                "formatted": {
                    "text": "Alex Marchand\r\n12 rue des Lilas\r\n44000 Nantes\r\nFrance",
                    "one_line": "Marchand Alex - 12 rue des Lilas, Nantes (France)"
                }
            },
            {
                "id": 12,
                "types": [
                    "billing"
                ],
                "name": "Test Buyer",
                "company": "Lilas SARL",
                "street": "12 rue des Lilas",
                "city": "Nantes",
                "post_code": "44000",
                "telephone": "+33 2 00 00 00 00",
                "default": true,
                "formatted": {
                    "text": "Alex Marchand\r\n12 rue des Lilas\r\n44000 Nantes\r\nFrance",
                    "one_line": "Marchand Alex - 12 rue des Lilas, Nantes (France)"
                }
            },
            {
                "id": 24,
                "types": [
                    "billing"
                ],
                "name": "John Doe",
                "company": "Lilas SARL",
                "street": "12 rue des Lilas",
                "city": "Nantes",
                "post_code": "44000",
                "telephone": "+33 2 00 00 00 00",
                "default": false,
                "formatted": {
                    "text": "Alex Marchand\r\n12 rue des Lilas\r\n44000 Nantes\r\nFrance",
                    "one_line": "Marchand Alex - 12 rue des Lilas, Nantes (France)"
                }
            },
            {
                "id": 23,
                "types": [
                    "shipping"
                ],
                "name": "John Doe",
                "company": "Lilas SARL",
                "street": "12 rue des Lilas",
                "city": "Nantes",
                "post_code": "44000",
                "telephone": "+33 2 00 00 00 00",
                "default": false,
                "formatted": {
                    "text": "Alex Marchand\r\n12 rue des Lilas\r\n44000 Nantes\r\nFrance",
                    "one_line": "Marchand Alex - 12 rue des Lilas, Nantes (France)"
                }
            }
        ],
        "orders": [
            {
                "id": 20,
                "number": "X20",
                "status": "confirmed",
                "created": 1783721323,
                "total": 14.99,
                "currency_id": 1
            },
            {
                "id": 18,
                "number": "U18",
                "status": "confirmed",
                "created": 1783347376,
                "total": 14.99,
                "currency_id": 1
            },
            {
                "id": 16,
                "number": "S16",
                "status": "created",
                "created": 1783345950,
                "total": 14.99,
                "currency_id": 1
            },
            {
                "id": 2,
                "number": "TEST-VOTE-1",
                "status": "confirmed",
                "created": 1778653148,
                "total": 100,
                "currency_id": 1
            },
            "… 96 more, trimmed for the example"
        ],
        "fields": [],
        "custom_fields": [],
        "custom_field_files": []
    },
    "meta": null,
    "error": null
}

Delete a customer

DELETE /customers/{id} write since 6.6.0

Removes a customer and their addresses.

A customer with orders is refused, which is what the backend does too: delete their orders first, and then the customer.

Path

ParameterTypeDescription

idrequiredintegerThe customer id.

Response

FieldTypeDescription

deletedbooleanTrue when the row is gone.

Errors

CodeHTTPMeans

not_found404No such customer, or the operator may not delete them.

has_orders400They have orders. Delete those first.

delete_failed400The shop refused to delete the row.

DELETE/customers/{id}

curl -X DELETE "$SHOP/hikashop-api/v1/customers/{id}" \
  -H "Authorization: Bearer $TOKEN"

200success

{
    "data": {
        "deleted": 5272
    },
    "meta": null,
    "error": null
}

Update a customer's profile

PUT /customers/{id} write since 6.6.0

Changes the name, the email address, the login, the password, the user groups and your own customer fields, and answers with the customer as it now stands.

The password is written straight into the CMS account and is never returned by anything. Changing the email of a registered customer changes the account they log in with, which is why a clash is refused rather than silently ignored.

Path

ParameterTypeDescription

idrequiredintegerThe customer id.

Body

FieldTypeDescription

namestringTheir display name.

emailstringMust not belong to another account.

usernamestringThe login, for a registered customer.

passwordstringA new password. Send it only when changing it.

groupsinteger[]The user groups they belong to, as ids from GET /groups.

custom_fieldsobjectYour own customer fields, keyed by namekey.

Response

FieldTypeDescription

idintegerThe HikaShop customer id, which is what every customer route takes.

cms_idintegerThe Joomla or WordPress user id, 0 for a guest with no account.

namestring

emailstring

usernamestringThe login, empty for a guest.

typestringregistered or guest.

blockedbooleanWhether the CMS account is disabled.

can_edit_accountbooleanWhether this operator may change the login and password of this particular account. False for an account above their own level, which is how a super user is protected from staff.

groups_editablebooleanWhether this operator may change which groups the customer is in.

groupsobject[]The groups they are in.

idinteger

titlestring

available_groupsobject[]Every group, with whether this operator may put the customer into it, so a picker can grey out the rest rather than offering a refusal.

idinteger

titlestring

assignablebooleanFalse for a group this operator may not grant.

createdintegerUnix timestamp of the first time the shop saw them.

addressesobject[]Their addresses, defaults first.

idinteger

typesstring[]Which of billing and shipping it is used for.

namestring

companystring

streetstring

citystring

post_codestring

telephonestring

defaultbooleanWhether it is the default for one of its types.

formattedobjectThe address laid out the way this shop lays addresses out, which depends on its address format setting.

textstringSeveral lines, for an invoice or a label.

one_linestringOne line, for a list.

ordersobject[]Their orders, newest first, enough to list them.

idinteger

numberstringThe number the customer sees.

statusstringA namekey.

createdintegerUnix timestamp.

totalnumberTax included, in the order currency.

currency_idintegerThat currency.

fieldsobject[]The definitions of your own customer fields.

custom_fieldsobjectTheir values, keyed by namekey. The keys depend on the shop; fields says what they are.

custom_field_filesobjectFor a field holding a file, the file behind the value. Keyed the same way.

Errors

CodeHTTPMeans

not_found404No such customer, or the operator may not change them.

invalid_email400The email address is not one.

forbidden_target400The operator may not change this particular account, which is how a super user is protected from being edited by staff.

username_taken400Another account has that login.

email_taken400Another account has that email address.

account_save_failed400The CMS refused to save the account.

invalid_fields400One of your own fields was rejected by its own rules.

PUT/customers/{id}

curl -X PUT "$SHOP/hikashop-api/v1/customers/{id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alex Marchand"
}'

200success

{
    "data": {
        "id": 20,
        "cms_id": 0,
        "name": "John Doe",
        "email": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
        "username": "",
        "type": "guest",
        "blocked": false,
        "can_edit_account": true,
        "groups_editable": false,
        "groups": [],
        "available_groups": [
            {
                "id": 1,
                "title": "Mr",
                "assignable": false
            },
            {
                "id": 9,
                "title": "Mr",
                "assignable": false
            },
            {
                "id": 6,
                "title": "Mr",
                "assignable": false
            },
            {
                "id": 7,
                "title": "Mr",
                "assignable": false
            },
            "… 5 more, trimmed for the example"
        ],
        "created": 1783721823,
        "addresses": [
            {
                "id": 26,
                "types": [
                    "billing"
                ],
                "name": "John Doe",
                "company": "Lilas SARL",
                "street": "12 rue des Lilas",
                "city": "Nantes",
                "post_code": "44000",
                "telephone": "+33 2 00 00 00 00",
                "default": true,
                "formatted": {
                    "text": "Alex Marchand\r\n12 rue des Lilas\r\n44000 Nantes\r\nFrance",
                    "one_line": "Marchand Alex - 12 rue des Lilas, Nantes (France)"
                }
            },
            {
                "id": 25,
                "types": [
                    "shipping"
                ],
                "name": "John Doe",
                "company": "Lilas SARL",
                "street": "12 rue des Lilas",
                "city": "Nantes",
                "post_code": "44000",
                "telephone": "+33 2 00 00 00 00",
                "default": true,
                "formatted": {
                    "text": "Alex Marchand\r\n12 rue des Lilas\r\n44000 Nantes\r\nFrance",
                    "one_line": "Marchand Alex - 12 rue des Lilas, Nantes (France)"
                }
            }
        ],
        "orders": [
            {
                "id": 26,
                "number": "B2D6",
                "status": "created",
                "created": 1785338765,
                "total": 14.99,
                "currency_id": 1
            },
            {
                "id": 28,
                "number": "B2F8",
                "status": "confirmed",
                "created": 1783722444,
                "total": 14.99,
                "currency_id": 1
            },
            {
                "id": 30,
                "number": "ZBUNDLE",
                "status": "confirmed",
                "created": 1783722444,
                "total": 14.99,
                "currency_id": 1
            },
            {
                "id": 22,
                "number": "Z22",
                "status": "created",
                "created": 1783721823,
                "total": 14.99,
                "currency_id": 1
            }
        ],
        "fields": [],
        "custom_fields": [],
        "custom_field_files": []
    },
    "meta": null,
    "error": null
}

Give a guest an account

POST /customers/{id}/account write since 6.6.0

Turns a guest into a registered customer, keeping their orders and addresses, and answers with the customer as it now stands.

This is the useful direction: someone ordered without an account, then asked for one. Creating the account separately would leave their history behind.

Path

ParameterTypeDescription

idrequiredintegerThe guest customer.

Body

FieldTypeDescription

usernamerequiredstringThe login to create.

passwordrequiredstringTheir password. Never returned by anything afterwards.

namestringTheir display name, defaulting to the one on the guest record.

groupsinteger[]The user groups to put them in.

Response

FieldTypeDescription

idintegerThe HikaShop customer id, which is what every customer route takes.

cms_idintegerThe Joomla or WordPress user id, 0 for a guest with no account.

namestring

emailstring

usernamestringThe login, empty for a guest.

typestringregistered or guest.

blockedbooleanWhether the CMS account is disabled.

can_edit_accountbooleanWhether this operator may change the login and password of this particular account. False for an account above their own level, which is how a super user is protected from staff.

groups_editablebooleanWhether this operator may change which groups the customer is in.

groupsobject[]The groups they are in.

idinteger

titlestring

available_groupsobject[]Every group, with whether this operator may put the customer into it, so a picker can grey out the rest rather than offering a refusal.

idinteger

titlestring

assignablebooleanFalse for a group this operator may not grant.

createdintegerUnix timestamp of the first time the shop saw them.

addressesobject[]Their addresses, defaults first.

idinteger

typesstring[]Which of billing and shipping it is used for.

namestring

companystring

streetstring

citystring

post_codestring

telephonestring

defaultbooleanWhether it is the default for one of its types.

formattedobjectThe address laid out the way this shop lays addresses out, which depends on its address format setting.

textstringSeveral lines, for an invoice or a label.

one_linestringOne line, for a list.

ordersobject[]Their orders, newest first, enough to list them.

idinteger

numberstringThe number the customer sees.

statusstringA namekey.

createdintegerUnix timestamp.

totalnumberTax included, in the order currency.

currency_idintegerThat currency.

fieldsobject[]The definitions of your own customer fields.

custom_fieldsobjectTheir values, keyed by namekey. The keys depend on the shop; fields says what they are.

custom_field_filesobjectFor a field holding a file, the file behind the value. Keyed the same way.

Errors

CodeHTTPMeans

not_found404No such customer.

already_registered400They already have an account.

missing_credentials400A username and a password are both required.

invalid_email400The address on the guest record is not usable as an account email.

email_taken400Another account has that email address.

username_taken400Another account has that login.

account_save_failed400The CMS refused to create the account.

POST/customers/{id}/account

curl -X POST "$SHOP/hikashop-api/v1/customers/{id}/account" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "doccapture5271",
    "password": "not-a-real-password-9x"
}'

200success

{
    "data": {
        "id": 5271,
        "cms_id": 171,
        "name": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
        "email": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
        "username": "doccapture5271",
        "type": "registered",
        "blocked": false,
        "can_edit_account": true,
        "groups_editable": false,
        "groups": [
            {
                "id": 2,
                "title": "Mr"
            }
        ],
        "available_groups": [
            {
                "id": 1,
                "title": "Mr",
                "assignable": false
            },
            {
                "id": 9,
                "title": "Mr",
                "assignable": false
            },
            {
                "id": 6,
                "title": "Mr",
                "assignable": false
            },
            {
                "id": 7,
                "title": "Mr",
                "assignable": false
            },
            "… 5 more, trimmed for the example"
        ],
        "created": 1786353021,
        "addresses": [
            {
                "id": 4362,
                "types": [
                    "billing"
                ],
                "name": "E2E Tester",
                "company": "Lilas SARL",
                "street": "12 rue des Lilas",
                "city": "Nantes",
                "post_code": "44000",
                "telephone": "+33 2 00 00 00 00",
                "default": true,
                "formatted": {
                    "text": "Alex Marchand\r\n12 rue des Lilas\r\n44000 Nantes\r\nFrance",
                    "one_line": "Marchand Alex - 12 rue des Lilas, Nantes (France)"
                }
            }
        ],
        "orders": [],
        "fields": [],
        "custom_fields": [],
        "custom_field_files": []
    },
    "meta": null,
    "error": null
}

Create a product

POST /products public since 6.6.0

Creates a product and answers with its id. Only the name is required; everything else can be set now or later with PUT /products/{id}.

Prices, images and categories are separate calls, so a new product is not sellable until it has at least one price.

Body

Any of the fields a product carries: name (required), code, description, published, msrp, gtin, condition, weight, weight_unit, width, height, length, dimension_unit, min_per_order, max_per_order, sale_start, sale_end, page_title, meta_description, keywords, canonical, url, alias, tax_id, manufacturer_id, contact, warehouse_id, plus access and custom_fields.

They mean what they mean on GET /products/{id}. A field the shop's own schema does not have is ignored rather than refused, which is what lets one client talk to shops of different vintages.

Response

FieldTypeDescription

idstring

namestring

codestringThe SKU. Unique within the shop.

descriptionstringThe long description, as HTML.

description_typestringWhich editor the description was written with.

publishedboolean

quantityinteger-1 when this product does not track stock, which is not the same as 0.

msrpintegerThe manufacturer's suggested price, shown struck through when the shop is configured to.

gtinstringThe barcode: EAN, UPC or ISBN. This is what GET /products/lookup matches on.

conditionstringNew, used, refurbished. Used by the feeds rather than by the shop itself.

weightintegerShipping weight, in weight_unit.

weight_unitstringkg, g, lb or oz.

widthintegerIn dimension_unit.

heightintegerIn dimension_unit.

lengthintegerIn dimension_unit.