[Skip to main content](#vessel-content) ## [ Command line ](/support/documentation/543-hikashop-cli) Details Written by: jobsigen Category: [Developer area](/support/documentation/hikashop/developer-area) Published: 01 September 2026 Hits: 622 HikaShop can be driven from a command line, so that a shop can be managed from a terminal, a cron entry, a deployment script or a Makefile, without opening a browser. It works on both platforms, using the command line each of them already provides: the Joomla console for a Joomla site, and WP-CLI for a WordPress one. Nothing is sent over the network. The commands run inside your own site, on the machine the site is installed on, so there is no key to create and nothing to open to the outside. ### Getting started On Joomla the commands come from the "Console - HikaShop" plugin, installed and enabled with HikaShop. On WordPress they come with the HikaShop plugin itself and need [WP-CLI](https://wp-cli.org/). Ask for the list: ``` php cli/joomla.php list # Joomla wp hikashop # WordPress ``` Each platform spells the same command its own way, Joomla with colons and WordPress with spaces. Everything else is identical: the same arguments, the same options, the same output and the same exit codes. ``` php cli/joomla.php hikashop:product:list --limit=5 wp hikashop product list --limit=5 ``` ### Options every command understands | 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. | With no `--user` a command runs as nobody in particular. On a shop that has not restricted anything this is enough; on a shop that has restricted a kind of record to a group of users, the command is refused and says to name a user. Choosing an account also means your change log records who made the change. ### What the shell gets back Only the data is printed to the standard output, so `--format=json` can always be piped into another program. Warnings and error messages go to the error output and never mix into it. Answers carry the same envelope the Connector API uses: `data` is what you asked for, `meta` holds the paging of a listing, and `error` is `null` unless something went wrong. The tables below describe what is inside `data`. The exit code says what happened, which is what a script should test: | 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 | The commands for your products, orders, customers, categories, coupons and mass actions come through the HikaShop Connector plugin, which ships with the Business edition. The commands for the shop itself, its configuration, its caches and its database, are available in every edition. Running the cron this way needs the Essential or the Business edition, as the cron itself does. ### All commands [product:list](#hkcli-product-list)[product:get](#hkcli-product-get)[product:create](#hkcli-product-create)[product:update](#hkcli-product-update)[product:delete](#hkcli-product-delete)[product:stock](#hkcli-product-stock)[product:price](#hkcli-product-price)[product:lowstock](#hkcli-product-lowstock)[order:list](#hkcli-order-list)[order:get](#hkcli-order-get)[order:status](#hkcli-order-status)[order:create](#hkcli-order-create)[order:addproduct](#hkcli-order-addproduct)[customer:list](#hkcli-customer-list)[customer:get](#hkcli-customer-get)[customer:create](#hkcli-customer-create)[customer:delete](#hkcli-customer-delete)[category:list](#hkcli-category-list)[category:create](#hkcli-category-create)[category:delete](#hkcli-category-delete)[discount:list](#hkcli-discount-list)[discount:create](#hkcli-discount-create)[discount:delete](#hkcli-discount-delete)[massaction:list](#hkcli-massaction-list)[massaction:run](#hkcli-massaction-run)[dbcheck](#hkcli-dbcheck)[shop:statuses](#hkcli-shop-statuses)[shop:stats](#hkcli-shop-stats)[config:get](#hkcli-config-get)[config:set](#hkcli-config-set)[cache:clean](#hkcli-cache-clean)[cron:run](#hkcli-cron-run)[log:list](#hkcli-log-list)[log:get](#hkcli-log-get)[log:clear](#hkcli-log-clear) ### Products #### product:list List products. The catalogue as the backend sees it, unpublished products included, which is what makes this different from the front end. Variants are not listed on their own. A parent carries `has_variants`, and `GET /products/{id}` returns the variants themselves. ``` php cli/joomla.php hikashop:product:list [--search=] [--limit=] [--start=] [--category=] [--ids=] wp hikashop product list [--search=] [--limit=] [--start=] [--category=] [--ids=] ``` | 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. | #### product:get Show one product. 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. ``` php cli/joomla.php hikashop:product:get wp hikashop product get ``` | 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. | | sections | object\[\] | Information other plugins show on this record, each with a `key`, a `title` and `rows` (`label`, `value`, and optionally `url`, `badge` and `ref`). Empty when no plugin adds any; on a customer, core adds their paid downloads. See the guide on adding information and settings. | | extensions | object\[\] | Settings other plugins keep on this record, in groups (`key`, `title`, `fields`), each field described like a custom field plus its current `value`. Send changes back as `extensions` with the record's save. Empty when no plugin adds any. | #### product:create Create a product. 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. ``` php cli/joomla.php hikashop:product:create --name= [--code=] [--quantity=] [--published] [--description=] [--categories=] wp hikashop product create --name= [--code=] [--quantity=] [--published] [--description=] [--categories=] ``` | 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. | | sections | object\[\] | Information other plugins show on this record, each with a `key`, a `title` and `rows` (`label`, `value`, and optionally `url`, `badge` and `ref`). Empty when no plugin adds any; on a customer, core adds their paid downloads. See the guide on adding information and settings. | | extensions | object\[\] | Settings other plugins keep on this record, in groups (`key`, `title`, `fields`), each field described like a custom field plus its current `value`. Send changes back as `extensions` with the record's save. Empty when no plugin adds any. | | 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. | #### product:update Change a product. Changes the fields you send and leaves the rest alone, which is the opposite of the price and category calls: this one merges. Sending nothing to change is refused rather than treated as a success, so a client cannot believe it saved something it did not. ``` php cli/joomla.php hikashop:product:update [--name=] [--code=] [--description=] [--published] [--msrp=] [--gtin=] [--weight=] [--tax-id=] wp hikashop product update [--name=] [--code=] [--description=] [--published] [--msrp=] [--gtin=] [--weight=] [--tax-id=] ``` | 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. | | sections | object\[\] | Information other plugins show on this record, each with a `key`, a `title` and `rows` (`label`, `value`, and optionally `url`, `badge` and `ref`). Empty when no plugin adds any; on a customer, core adds their paid downloads. See the guide on adding information and settings. | | extensions | object\[\] | Settings other plugins keep on this record, in groups (`key`, `title`, `fields`), each field described like a custom field plus its current `value`. Send changes back as `extensions` with the record's save. Empty when no plugin adds any. | | 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. | | invalid\_extensions | The product was saved, but a plugin refused some of its values: `error.details` says which, as `{ group key: { namekey: message } }`. | #### product:delete Delete a product and its variants. Deletes a product and its variants. Orders that already contain it are untouched: an order line records what was sold at the time, and it does not stop meaning something because the catalogue changed. ``` php cli/joomla.php hikashop:product:delete --yes wp hikashop product delete --yes ``` | 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. | #### product:stock Set a product's stock. 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. ``` php cli/joomla.php hikashop:product:stock --quantity= wp hikashop product stock --quantity= ``` | 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. | #### product:price Replace a product's price set. 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. ``` php cli/joomla.php hikashop:product:price --value= [--currency=] [--min-quantity=] wp hikashop product price --value= [--currency=] [--min-quantity=] ``` | 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. | #### product:lowstock List sellable products at or below a stock threshold. 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. ``` php cli/joomla.php hikashop:product:lowstock [--threshold=] [--limit=] wp hikashop product lowstock [--threshold=] [--limit=] ``` | 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. | ### Orders #### order:list List orders. The orders the operator may see, newest first. It is the listing the app's order screen is built on, so it carries just enough to draw a row and no more; ask for one order when you need the rest. ``` php cli/joomla.php hikashop:order:list [--search=] [--limit=] [--start=] [--status=] wp hikashop order list [--search=] [--limit=] [--start=] [--status=] ``` | 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`. | #### order:get Show one order. The whole order: its lines, its totals, its addresses, its history and your own fields. Money is in the currency the order was placed in, which is not necessarily the shop's. Do not convert it: an order is a record of what was agreed at the time. ``` php cli/joomla.php hikashop:order:get wp hikashop order get ``` | 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. | | fields.namekey | string | The key its value is stored under. | | fields.label | string | Translated into the operator's language. | | fields.type | string | What to render: `text`, `radio`, `singledropdown`, `file`, and the rest. | | fields.raw\_type | string | HikaShop's own name for the type. | | fields.required | boolean | Whether the shop refuses to save without it. | | fields.default | string | The value used when none is given. | | fields.options | object\[\] | The choices, for a field that has them. | | fields.options.value | string | What to send back when this choice is picked. | | fields.options.label | string | What to show. | | fields.options.label\_key | string | The translation key behind the label, when there is one. | | fields.multiple | boolean | Whether more than one may be chosen. | | fields.translatable | boolean | Whether its value can be translated. | | fields.upload\_dir | string | For a file field, where its uploads are kept. | | fields.allowed\_extensions | string | For a file field, the extensions it accepts. Empty means the shop default. | | fields.date\_format | string | For a date field, the format it is stored in. | | 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. | | sections | object\[\] | Information other plugins show on this record, each with a `key`, a `title` and `rows` (`label`, `value`, and optionally `url`, `badge` and `ref`). Empty when no plugin adds any; on a customer, core adds their paid downloads. See the guide on adding information and settings. | | extensions | object\[\] | Settings other plugins keep on this record, in groups (`key`, `title`, `fields`), each field described like a custom field plus its current `value`. Send changes back as `extensions` with the record's save. Empty when no plugin adds any. | #### order:status Change an order's status. Moves the order and, when asked, sends the customer the same notification the backend would have sent. This calls the same code the backend does, so stock, invoices and every plugin listening on a status change behave exactly as they do there. It is not a database update. ``` php cli/joomla.php hikashop:order:status [--notify] [--reason=] wp hikashop order status [--notify] [--reason=] ``` | 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. | #### order:create Create an empty order for a customer. Creates an empty order for a customer, to be filled in with lines, fees and an address. Give it either an existing `user_id` or a `guest` with at least an email address, which is how an order gets taken over the telephone from somebody who has never bought before. ``` php cli/joomla.php hikashop:order:create [--customer=] [--guest] wp hikashop order create [--customer=] [--guest] ``` | 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. | #### order:addproduct Add a product line to an order. Adds a product to an existing order and re-totals it. Send a `price` only to override what the shop would charge; leave it out and the order's own pricing applies, which is what `GET /orders/{id}/products/precompute` shows you beforehand. ``` php cli/joomla.php hikashop:order:addproduct --product= [--quantity=] [--price=] wp hikashop order addproduct --product= [--quantity=] [--price=] ``` | 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. | ### Customers #### customer:list List customers. 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. ``` php cli/joomla.php hikashop:customer:list [--search=] [--limit=] [--start=] wp hikashop customer list [--search=] [--limit=] [--start=] ``` | 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. | #### customer:get Show one customer. 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. ``` php cli/joomla.php hikashop:customer:get wp hikashop customer get ``` | 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. | | sections | object\[\] | Information other plugins show on this record, each with a `key`, a `title` and `rows` (`label`, `value`, and optionally `url`, `badge` and `ref`). Empty when no plugin adds any; on a customer, core adds their paid downloads. See the guide on adding information and settings. | | extensions | object\[\] | Settings other plugins keep on this record, in groups (`key`, `title`, `fields`), each field described like a custom field plus its current `value`. Send changes back as `extensions` with the record's save. Empty when no plugin adds any. | | Can also fail with | Meaning | |---|---| | not\_found | No such customer, or the operator may not see them. | #### customer:create Create a customer. Creates a customer from an email address and a name, as a guest: no account, no password, nothing for them to log in with. `POST /customers/{id}/account` turns one into a registered customer afterwards. ``` php cli/joomla.php hikashop:customer:create --email= [--name=] wp hikashop customer create --email= [--name=] ``` | Option | Type | Description | |---|---|---| | --email required | string | Email address | | --name | string | Full name | | Returns | Type | Description | |---|---|---| | id | integer | The customer that was created. | | Can also fail with | Meaning | |---|---| | email\_taken | Another customer already has that address. | | save\_failed | The shop refused to save it. | #### customer:delete Delete a customer. 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. ``` php cli/joomla.php hikashop:customer:delete --yes wp hikashop customer delete --yes ``` | Argument | Description | |---|---| | <id> required | Customer id | | Returns | Type | Description | |---|---|---| | deleted | boolean | True when the row is gone. | | Can also fail with | Meaning | |---|---| | not\_found | No such customer, or the operator may not delete them. | | has\_orders | They have orders. Delete those first. | | delete\_failed | The shop refused to delete the row. | ### Categories #### category:list List product categories. 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. ``` php cli/joomla.php hikashop:category:list wp hikashop category list ``` | Returns | Type | Description | |---|---|---| | id | | | | name | | | | parent\_id | | Its parent, so a flat answer can be rebuilt into a tree. | | published | | | | has\_children | | Whether anything sits below it. | | image | string\|null | Absolute URL of its image, `null` when it has none. | | In `meta` | Type | Description | |---|---|---| | total | integer | Categories matching, before paging. | | start | integer | Echoes the offset used. | | limit | integer | Echoes the page size used. | #### category:create Create a product category. Creates a category under another, or at the top of the product tree when no parent is given. ``` php cli/joomla.php hikashop:category:create --name= wp hikashop category create --name= ``` | Option | Type | Description | |---|---|---| | --name required | string | Category name | | Returns | Type | Description | |---|---|---| | id | integer | The category that was created. | | name | string | | | parent\_id | integer | Where it sits. | | published | boolean | | | 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 it. | #### category:delete Delete a product category. Deletes a category. The products in it are not deleted; they simply stop being in it, and a product left in no category at all disappears from the shop's listings. ``` php cli/joomla.php hikashop:category:delete --yes wp hikashop category delete --yes ``` | Argument | Description | |---|---| | <id> required | Category id | | Returns | Type | Description | |---|---|---| | id | integer | The category that was deleted. | | deleted | boolean | True when the row is gone. | | Can also fail with | Meaning | |---|---| | not\_found | No such category, or the operator may not delete it. | ### Coupons and discounts #### discount:list List coupons and discounts. 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. ``` php cli/joomla.php hikashop:discount:list [--limit=] [--start=] wp hikashop discount list [--limit=] [--start=] ``` | Option | Type | Description | |---|---|---| | --limit | int | How many to return | | --start | int | Skip this many first | | Returns | Type | Description | |---|---|---| | id | integer | | | type | string | `discount` applies by itself, `coupon` waits for its code. | | code | string | What the customer types. Empty on a discount. | | kind | string | Whether the value is a percentage or a fixed amount. | | value | number | The reduction, read according to `kind`. | | currency\_id | integer | The currency a fixed amount is in. | | published | boolean | | | start | integer\|null | Unix timestamp before which it does not apply. | | end | integer\|null | Unix timestamp after which it expires. | | minimum\_order | number | Order total below which it does not apply, `0` for none. | | maximum\_order | number | Order total above which it stops applying, `0` for none. | | quota | integer | How many times it may be used in total, `0` for no limit. | | quota\_per\_user | integer | How many times one customer may use it, `0` for no limit. | | used\_times | integer | How many times it already has been. | | tax\_included | boolean | Whether the value is understood as tax included. | | tax\_id | integer | The tax category of the reduction itself. | | shipping\_percent | number | A reduction on the shipping rather than on the goods. | | minimum\_products | integer | Fewest items in the cart for it to apply. | | maximum\_products | integer | Most items for it to still apply. | | product\_ids | integer\[\] | Restricted to these products. Empty means all of them. | | exclude\_product\_ids | integer\[\] | Never applies to these. | | category\_ids | integer\[\] | Restricted to these categories. | | category\_childs | boolean | Whether those categories include their sub-categories. | | exclude\_category\_ids | integer\[\] | Never applies in these categories. | | exclude\_category\_childs | boolean | Whether those exclusions include sub-categories. | | zone\_ids | integer\[\] | Restricted to these zones. | | user\_ids | integer\[\] | Restricted to these customers. | | access | object | Who this is for. | | exclude\_access | object | Who this is for. | | auto\_load | boolean | For a coupon, whether the shop applies it without the customer typing it. | | product\_only | boolean | Whether it reduces only the goods and leaves the fees alone. | | discounted\_products | integer | How many products in the cart it applied to, on a discount that has been used. | | access.mode | string | `all`, `none`, or `groups` when it is restricted to some. | | access.groups | integer\[\] | 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\_access.mode | string | `all`, `none`, or `groups` when it is restricted to some. | | exclude\_access.groups | integer\[\] | 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. | | 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. | #### discount:create Create a coupon or a discount. Creates a reduction and answers with it as the shop stored it. `type` decides which kind it is: a `coupon` needs a `code`, a `discount` applies by itself. Either way `value` is required, read according to `kind`. ``` php cli/joomla.php hikashop:discount:create [--code=] --value= [--kind=] [--type=] [--published] wp hikashop discount create [--code=] --value= [--kind=] [--type=] [--published] ``` | Option | Type | Description | |---|---|---| | --code | string | Coupon code | | --value required | float | Amount or percentage | | --kind | string | percent or flat | | --type | string | coupon or discount | | --published | flag | Publish it | | Returns | Type | Description | |---|---|---| | id | integer | | | type | string | `discount` applies by itself, `coupon` waits for its code. | | code | string | What the customer types. Empty on a discount. | | kind | string | Whether the value is a percentage or a fixed amount. | | value | number | The reduction, read according to `kind`. | | currency\_id | integer | The currency a fixed amount is in. | | published | boolean | | | start | integer\|null | Unix timestamp before which it does not apply. | | end | integer\|null | Unix timestamp after which it expires. | | minimum\_order | number | Order total below which it does not apply, `0` for none. | | maximum\_order | number | Order total above which it stops applying, `0` for none. | | quota | integer | How many times it may be used in total, `0` for no limit. | | quota\_per\_user | integer | How many times one customer may use it, `0` for no limit. | | used\_times | integer | How many times it already has been. | | tax\_included | boolean | Whether the value is understood as tax included. | | tax\_id | integer | The tax category of the reduction itself. | | shipping\_percent | number | A reduction on the shipping rather than on the goods. | | minimum\_products | integer | Fewest items in the cart for it to apply. | | maximum\_products | integer | Most items for it to still apply. | | product\_ids | integer\[\] | Restricted to these products. Empty means all of them. | | exclude\_product\_ids | integer\[\] | Never applies to these. | | category\_ids | integer\[\] | Restricted to these categories. | | category\_childs | boolean | Whether those categories include their sub-categories. | | exclude\_category\_ids | integer\[\] | Never applies in these categories. | | exclude\_category\_childs | boolean | Whether those exclusions include sub-categories. | | zone\_ids | integer\[\] | Restricted to these zones. | | user\_ids | integer\[\] | Restricted to these customers. | | access | object | Who this is for. | | exclude\_access | object | Who this is for. | | auto\_load | boolean | For a coupon, whether the shop applies it without the customer typing it. | | product\_only | boolean | Whether it reduces only the goods and leaves the fees alone. | | discounted\_products | integer | How many products in the cart it applied to, on a discount that has been used. | | access.mode | string | `all`, `none`, or `groups` when it is restricted to some. | | access.groups | integer\[\] | 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\_access.mode | string | `all`, `none`, or `groups` when it is restricted to some. | | exclude\_access.groups | integer\[\] | 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. | | Can also fail with | Meaning | |---|---| | code\_required | A coupon needs a code. | | code\_taken | Another coupon already uses that code. | | value\_required | A reduction needs a value. | | not\_found | Not reachable when creating: the same handler serves the update, where it means no such discount. | | save\_failed | The shop refused to save it. | #### discount:delete Delete a coupon or discount. Deletes a reduction. Orders that already used it keep the amount they were given: the discount on an order is a figure, not a pointer at this row. ``` php cli/joomla.php hikashop:discount:delete --yes wp hikashop discount delete --yes ``` | Argument | Description | |---|---| | <id> required | Discount id | | Returns | Type | Description | |---|---|---| | deleted | boolean | True when the row is gone. | | Can also fail with | Meaning | |---|---| | not\_found | No such discount, or the operator may not delete it. | ### Mass actions #### massaction:list List the shop's own bulk operations. 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}`. ``` php cli/joomla.php hikashop:massaction:list [--table=] wp hikashop massaction list [--table=
] ``` | Option | Type | Description | |---|---|---| | --table | string | Which listing, e.g. product or order | | Returns | Type | Description | |---|---|---| | id | | What to run. | | name | | As the merchant named it. | | description | | Their own note about what it does, when they wrote one. | | table | | The listing it belongs to. | | restricted | boolean | Whether it may only run on a selection rather than on everything matching a filter. | | Can also fail with | Meaning | |---|---| | invalid\_request | The table is not one the shop has mass actions for. | | forbidden | The operator may not view that kind of record. | #### massaction:run Run a bulk operation over a selection. Runs one of the merchant's own bulk operations over a selection. It runs the same code the backend runs, so whatever the action does there it does here, including whatever a third-party plugin added to it. Give it the ids to work on. ``` php cli/joomla.php hikashop:massaction:run --ids= --yes wp hikashop massaction run --ids= --yes ``` | Argument | Description | |---|---| | <id> required | Mass action id | | Option | Type | Description | |---|---|---| | --ids required | ids, comma separated | Record ids to act on, comma separated | | Returns | Type | Description | |---|---|---| | ok | boolean | Whether the action reported success. | | count | integer | How many records it worked on. | | report | string | Whatever the action had to say, ready to show. Its wording is the action's own. | | Can also fail with | Meaning | |---|---| | invalid\_request | No ids were sent, or the action is not one this shop has. | | forbidden | The operator may not work on that kind of record. | ### The shop itself #### dbcheck Bring the database schema up to date, what you want after restoring a dump. Runs inside the site itself and needs no plugin beyond HikaShop. ``` php cli/joomla.php hikashop:dbcheck wp hikashop dbcheck ``` | Returns | Type | Description | |---|---|---| | checked | boolean | Always true once the check has run. | | report | string\[\] | What it changed, one line per change. Empty when the schema was already correct. | #### shop:statuses List the shop's order statuses. 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. ``` php cli/joomla.php hikashop:shop:statuses wp hikashop shop statuses ``` | Returns | Type | Description | |---|---|---| | namekey | | The identifier. This is what you send when changing an order. | | name | | Translated into the operator's language, ready to display. | | label\_key | | The translation key behind that name, if you would rather translate it yourself. | | color | | The colour the backend uses for this status, empty when none is set. | #### shop:stats Show the dashboard totals. 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. ``` php cli/joomla.php hikashop:shop:stats [--range=] wp hikashop shop stats [--range=] ``` | Option | Type | Description | |---|---|---| | --range | string | day, week, month or year | | Returns | Type | Description | |---|---|---| | range | string | The period the figures cover. | | currency\_id | integer | The shop's currency, which every amount here is in. | | totals | object | The four headline figures. | | totals.revenue | number | Taken in the period. | | totals.orders | integer | How many were placed. | | totals.average\_order | number | Revenue divided by orders. | | totals.customers | integer | New customers in the period. | | previous | object | The same four figures for the preceding period of the same length, for a comparison. | | previous.revenue | number | Taken in the preceding period. | | previous.orders | integer | Placed in it. | | previous.average\_order | number | Its average basket. | | previous.customers | integer | New customers in it. | | series\_granularity | string | Whether the series is by day, week, month or year, which follows from the range. | | revenue\_series | object\[\] | One point per interval, for a chart. | | revenue\_series.date | string | The interval, as a date. | | revenue\_series.revenue | number | Taken in it. | | top\_products | object\[\] | The best sellers of the period. | | top\_products.name | string | | | top\_products.quantity | integer | How many were sold. | ### Configuration #### config:get Read one configuration value. Runs inside the site itself and needs no plugin beyond HikaShop. ``` php cli/joomla.php hikashop:config:get wp hikashop config get ``` | Argument | Description | |---|---| | <key> required | Configuration key, e.g. main\_currency | | Returns | Type | Description | |---|---|---| | key | string | The key that was read. | | value | mixed | Its value, as the shop stores it. | | Can also fail with | Meaning | |---|---| | not\_found | No configuration key of that name. | #### config:set Change one configuration value. Runs inside the site itself and needs no plugin beyond HikaShop. ``` php cli/joomla.php hikashop:config:set wp hikashop config set ``` | Argument | Description | |---|---| | <key> required | Configuration key | | <value> required | New value | | Returns | Type | Description | |---|---|---| | key | string | The key that was changed. | | was | mixed | The value before the change, so a script can put it back. | | now | mixed | The value after it. | | Can also fail with | Meaning | |---|---| | not\_found | No configuration key of that name. This changes existing keys, it does not invent them. | | save\_failed | The configuration could not be written. | ### Caches #### cache:clean Empty the shop's caches. Runs inside the site itself and needs no plugin beyond HikaShop. ``` php cli/joomla.php hikashop:cache:clean wp hikashop cache clean ``` | Returns | Type | Description | |---|---|---| | cleaned | string\[\] | Which caches were emptied: the shop's own plugin cache, and the platform's. | ### Cron #### cron:run Run the scheduled tasks the shop would run on a page hit. Runs inside the site itself and needs no plugin beyond HikaShop. ``` php cli/joomla.php hikashop:cron:run wp hikashop cron run ``` | Returns | Type | Description | |---|---|---| | launched | boolean | False when the cron was not due to run yet. | | messages | string\[\] | The summary the cron would otherwise have emailed. | | details | string\[\] | The detail lines behind that summary. | | Can also fail with | Meaning | |---|---| | cron\_disabled | The cron is turned off in the shop configuration. | ### Log #### log:list List the entries of the HikaShop log, newest first. Runs inside the site itself and needs no plugin beyond HikaShop. ``` php cli/joomla.php hikashop:log:list [--source=] [--type=] [--level=] [--order=] [--request=] [--since=] [--until=] [--search=] [--limit=] [--start=] wp hikashop log list [--source=] [--type=] [--level=] [--order=] [--request=] [--since=] [--until=] [--search=] [--limit=] [--start=] ``` | Option | Type | Description | |---|---|---| | --source | string | Only this source: a plugin name such as paypal, or a part of HikaShop such as mail | | --type | string | Only this type: payment, shipping, plugin or core | | --level | string | This level and the worse ones: debug, info, warning or error | | --order | int | Only the entries about this order id | | --request | string | Only the entries written by this request | | --since | string | From this date, e.g. 2026-10-01 or "2 hours ago" | | --until | string | Up to this date; a bare day is included | | --search | string | Text in the message, the data, the source, the address or the IP | | --limit | int | How many to return | | --start | int | Skip this many first | | Returns | Type | Description | |---|---|---| | id | int | Entry id. | | created | int | When it was written, as a Unix timestamp. | | level | string | debug, info, warning or error. | | source | string | What wrote it: a plugin name, or a part of HikaShop. | | type | string | payment, shipping, plugin or core. | | message | string | The text of the entry, or the beginning of its data. | | order\_id | int | The order it is about, 0 when none. | | user\_id | int | The user logged in when it was written, 0 for a guest or a server call. | | ip | string | IP address of the request. | | url | string | Address of the request, secrets masked. | | request | string | Id shared by the entries one request wrote. | | data\_size | int | Size in bytes of the data the entry holds beyond its message. | | In `meta` | Type | Description | |---|---|---| | total | int | How many entries match, on every page. | #### log:get Show one entry of the HikaShop log with its data. Runs inside the site itself and needs no plugin beyond HikaShop. ``` php cli/joomla.php hikashop:log:get wp hikashop log get ``` | Argument | Description | |---|---| | <id> required | Log entry id | | Returns | Type | Description | |---|---|---| | id | int | Entry id. | | created | int | When it was written, as a Unix timestamp. | | level | string | debug, info, warning or error. | | source | string | What wrote it: a plugin name, or a part of HikaShop. | | type | string | payment, shipping, plugin or core. | | message | string | The text of the entry, or the beginning of its data. | | order\_id | int | The order it is about, 0 when none. | | user\_id | int | The user logged in when it was written, 0 for a guest or a server call. | | ip | string | IP address of the request. | | url | string | Address of the request, secrets masked. | | request | string | Id shared by the entries one request wrote. | | data\_size | int | Size in bytes of the data the entry holds beyond its message. | | data | mixed | What the entry holds beyond its message: decoded JSON when it was an array or object, text otherwise. Secrets were masked when it was written. | | Can also fail with | Meaning | |---|---| | not\_found | No log entry with that id. | #### log:clear Delete the entries of the HikaShop log that match the filters. Runs inside the site itself and needs no plugin beyond HikaShop. ``` php cli/joomla.php hikashop:log:clear [--source=] [--type=] [--level=] [--order=] [--request=] [--since=] [--until=] [--search=] [--all] --yes wp hikashop log clear [--source=] [--type=] [--level=] [--order=] [--request=] [--since=] [--until=] [--search=] [--all] --yes ``` | Option | Type | Description | |---|---|---| | --source | string | Only this source: a plugin name such as paypal, or a part of HikaShop such as mail | | --type | string | Only this type: payment, shipping, plugin or core | | --level | string | This level and the worse ones: debug, info, warning or error | | --order | int | Only the entries about this order id | | --request | string | Only the entries written by this request | | --since | string | From this date, e.g. 2026-10-01 or "2 hours ago" | | --until | string | Up to this date; a bare day is included | | --search | string | Text in the message, the data, the source, the address or the IP | | --all | flag | Delete every entry; needed when no filter is given | | Returns | Type | Description | |---|---|---| | deleted | int | How many entries were deleted. | | Can also fail with | Meaning | |---|---| | no\_filter | No filter was given and --all was not: nothing is deleted by accident. | ### Anything the named commands do not cover Everything the HikaShop Connector API can do is reachable from the command line as well, with the same paths and the same content the [Connector API](/support/documentation?alias=hikashop-connector-api)page documents, through a single command: ``` php cli/joomla.php hikashop:api GET products --query="limit=5&search=shirt" php cli/joomla.php hikashop:api PUT products/12 --data='{"name":"New name"}' wp hikashop api POST orders/44/status --data='{"status":"shipped"}' ``` The body can also be read from a file, or from the output of another program, with `--data-file=` or `--data-file=-` for the standard input. ### Examples ``` # The products lowest on stock php cli/joomla.php hikashop:product:lowstock --threshold=3 # Every order id waiting to be confirmed, one per line, for a script to loop over wp hikashop order list --status=created --format=ids # Create a product and give it a price php cli/joomla.php hikashop:product:create --name="Blue mug" --code=MUG-BLUE --quantity=40 --published php cli/joomla.php hikashop:product:price 812 --value=12.50 # Mark an order shipped and tell the customer wp hikashop order status 44 shipped --notify # After restoring a backup php cli/joomla.php hikashop:dbcheck ``` ### Running it from a cron The scheduled tasks of your shop can be run from your server's own scheduler, which is more reliable than waiting for a visitor to open a page: ``` 0 * * * * cd /path/to/your/site && php cli/joomla.php hikashop:cron:run --live-site=https://www.example.com 0 * * * * wp --path=/path/to/your/site hikashop cron run ``` The older `cli/hikashop_cron.php` script still works and does the same thing, so a cron entry that already uses it does not need changing. ## [ Connector API ](/support/documentation/542-hikashop-connector-api) Details Written by: jobsigen Category: [Developer area](/support/documentation/hikashop/developer-area) Published: 01 September 2026 Hits: 826 # HikaShop Connector API https://your-shop.tld/hikashop-api/v1 Version 6.7.0  (current) [YAML](https://www.hikashop.com/images/doc/hk/api/connector-api-6.7.0.yaml "OpenAPI 3.1, YAML") [JSON](https://www.hikashop.com/images/doc/hk/api/connector-api-6.7.0.json "OpenAPI 3.1, JSON") [MARKDOWN](https://www.hikashop.com/images/doc/hk/api/connector-api-6.7.0.md "One flat file, for an assistant") ## 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 `. 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. ``` { "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. ``` 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. ``` { "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. ``` { "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. ``` 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 information and settings to customers, orders and products Since 6.7.0, a plugin can add to the records the connector already serves, rather than serving a path of its own: something to **show** on a customer, an order or a product, and settings to **edit** there. A client draws both without knowing the plugin exists, so an add-on reaches the mobile application, a helpdesk or your own code with no work on their side. The detail of a customer, an order or a product carries two lists, empty when no plugin answers: \- `sections`, information to display. A section has a `key` (namespace it with your plugin's name), a `title` and `rows`. A row has a `label` and a `value` already formatted for display (the shop knows the currency, the date format and the language; the client does not), and optionally a `url`, a `badge` (`text` and a `tone`: `neutral`, `success`, `warning` or `danger`) and a `ref` to another record (`type` `customer`, `order` or `product`, and its `id`). - `extensions`, groups of settings. A group has a `key`, a `title` and `fields`, each described like the shop's own custom fields (`namekey`, `type`, `label`, `required`, `options`...) plus its current `value`, a string. The types are `text`, `textarea`, `number`, `email`, `url`, `boolean`, `singledropdown`, `multipledropdown`, `radio`, `checkbox`, `date`, `datetime` and `wysiwyg`; anything else is dropped, so a plugin cannot hand a client something it cannot draw. A client that does not know a type shows a text input, which is why `boolean` also carries yes/no options. A field may be `readonly`. To save, send `extensions` with the record's usual save (`PUT /customers/{id}`, `PUT /products/{id}`, `PUT /orders/{id}/fields`) as `{ "group key": { "namekey": "value" } }`. The record's own fields are saved first, then each group, and each plugin only receives its own group's values, for the fields it declared. A plugin refusing a value answers per field, and the route returns `invalid_extensions` with those messages in `error.details`, keyed by group and then field. Three events, each given one object by reference: `onConnectorElementSections` and `onConnectorElementForm` carry `type`, `id` and `device`, and your plugin appends to `sections` or `groups`; `onConnectorElementSave` also carries `group` and `values`, and your plugin fills `errors` (namekey => message) when it refuses something. Check `type` first: every plugin hears every record. ``` public function onConnectorElementSections(&$ctx) { if ($ctx->type !== 'product' || !$this->isAuction($ctx->id)) return; $ctx->sections[] = array('key' => 'auction.bids', 'title' => 'Bids', 'rows' => array( array('label' => 'Highest bid', 'value' => '120.00 EUR'), array('label' => 'Ends', 'value' => '3 October 2026 18:00', 'badge' => array('text' => 'ending soon', 'tone' => 'warning')), )); } public function onConnectorElementForm(&$ctx) { if ($ctx->type !== 'product') return; $ctx->groups[] = array('key' => 'auction', 'title' => 'Auction', 'fields' => array( array('namekey' => 'auction_end', 'type' => 'datetime', 'label' => 'Ends', 'required' => true, 'value' => $this->endOf($ctx->id)), array('namekey' => 'auction_reserve', 'type' => 'number', 'label' => 'Reserve price', 'value' => $this->reserveOf($ctx->id)), )); } public function onConnectorElementSave(&$ctx) { if ($ctx->type !== 'product' || $ctx->group !== 'auction') return; if (isset($ctx->values['auction_reserve']) && $ctx->values['auction_reserve'] < 0) $ctx->errors['auction_reserve'] = 'The reserve cannot be negative.'; else $this->store($ctx->id, $ctx->values); } ``` ## 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. ``` 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 expand all 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.nameboolean`joomla` or `wordpress`. versionstring\|nullThe CMS release. editionstring`starter`, `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.idinteger`0` when the device is bound to nobody, which is a device paired without an operator. namestring\|nullTheir display name. rolestring`admin` 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. ``` curl "$SHOP/hikashop-api/v1/site" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "data": { "app": "hikashop-connector", "api_version": "1.0.0", "site_name": "HikaShop Test", "hikashop_version": "6.6.0", "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 expand all 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. ``` curl "$SHOP/hikashop-api/v1/settings" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "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 expand all 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. ``` curl "$SHOP/hikashop-api/v1/version" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "data": { "i18n": "1790620910", "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 expand all 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. ``` curl "$SHOP/hikashop-api/v1/statuses" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "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 expand all 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. ``` curl "$SHOP/hikashop-api/v1/i{id}n?locale=en-GB" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "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": "
", "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", "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", "CREATE_OR_SELECT_ADDRESS": "Please create or select an address", "SAME_AS_BILLING": "Use the same address as for billing", "…": "4831 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 expand all 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. ``` curl "$SHOP/hikashop-api/v1/languages" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "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 expand all 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\_unitstring`kg`, `g`, `lb` or `oz`. widthnumberIn `dimension_unit`. heightnumberIn `dimension_unit`. lengthnumberIn `dimension_unit`. dimension\_unitstring`m`, `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.modestring`all`, `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. typestring`main` 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\|null`null` 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`. typestring`text`, `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. sectionsobject\[\]Information other plugins show on this record, each with a `key`, a `title` and `rows` (`label`, `value`, and optionally `url`, `badge` and `ref`). Empty when no plugin adds any; on a customer, core adds their paid downloads. See the guide on adding information and settings. extensionsobject\[\]Settings other plugins keep on this record, in groups (`key`, `title`, `fields`), each field described like a custom field plus its current `value`. Send changes back as `extensions` with the record's save. Empty when no plugin adds any. ``` curl "$SHOP/hikashop-api/v1/products/{id}" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "data": { "id": 8661, "name": "Full-Grain Sneakers", "code": "DEMO-0023", "description": "Our best-selling sneakers. Back in stock, and worth the wait.", "description_type": "", "published": true, "quantity": 0, "msrp": 0, "gtin": "", "condition": "", "weight": 0.213, "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": 4652, "value": 308.3, "currency_id": 1, "min_quantity": 0, "access": { "mode": "all", "groups": [] }, "users": [], "zone_ids": [], "start_date": 0, "end_date": 0 } ], "images": [ { "id": 7791, "name": "Full-Grain Sneakers", "path": "demo-0023.png", "url": "http://localhost:8080/joomla6_ext/images/com_hikashop/upload/demo-0023.png", "ordering": 1, "description": "", "access": { "mode": "all", "groups": [] }, "free_download": false }, { "id": 7792, "name": "Full-Grain Sneakers", "path": "demo-0023-2.png", "url": "http://localhost:8080/joomla6_ext/images/com_hikashop/upload/demo-0023-2.png", "ordering": 2, "description": "", "access": { "mode": "all", "groups": [] }, "free_download": false }, { "id": 7793, "name": "Full-Grain Sneakers", "path": "demo-0023-3.png", "url": "http://localhost:8080/joomla6_ext/images/com_hikashop/upload/demo-0023-3.png", "ordering": 3, "description": "", "access": { "mode": "all", "groups": [] }, "free_download": false } ], "files": [], "categories": [ { "id": 238, "name": "Shoes" } ], "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": 8662, "code": "DEMO-0023-XS", "quantity": 1, "published": true, "price": null, "values": [ { "option_id": 8, "option_name": "Size", "value_id": 35, "value": "XS" } ], "images": [ { "id": 7794, "name": "Full-Grain Sneakers — XS", "path": "demo-0023-xs.png", "url": "http://localhost:8080/joomla6_ext/images/com_hikashop/upload/demo-0023-xs.png", "ordering": 1 } ] }, { "id": 8663, "code": "DEMO-0023-S", "quantity": 23, "published": true, "price": null, "values": [ { "option_id": 8, "option_name": "Size", "value_id": 9, "value": "S" } ], "images": [ { "id": 7795, "name": "Full-Grain Sneakers — S", "path": "demo-0023-s.png", "url": "http://localhost:8080/joomla6_ext/images/com_hikashop/upload/demo-0023-s.png", "ordering": 1 } ] }, { "id": 8664, "code": "DEMO-0023-M", "quantity": 40, "published": true, "price": null, "values": [ { "option_id": 8, "option_name": "Size", "value_id": 21, "value": "M" } ], "images": [ { "id": 7796, "name": "Full-Grain Sneakers — M", "path": "demo-0023-m.png", "url": "http://localhost:8080/joomla6_ext/images/com_hikashop/upload/demo-0023-m.png", "ordering": 1 } ] }, { "id": 8665, "code": "DEMO-0023-L", "quantity": 38, "published": true, "price": null, "values": [ { "option_id": 8, "option_name": "Size", "value_id": 10, "value": "L" } ], "images": [ { "id": 7797, "name": "Full-Grain Sneakers — L", "path": "demo-0023-l.png", "url": "http://localhost:8080/joomla6_ext/images/com_hikashop/upload/demo-0023-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": [] }, "sections": [], "extensions": [] }, "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 expand all 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. ``` curl "$SHOP/hikashop-api/v1/products/lookup?barcode=TEST{id}" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "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 expand all 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. ``` curl "$SHOP/hikashop-api/v1/products/low-stock?threshold={id}&limit=3" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "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 expand all 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. ``` curl -X POST "$SHOP/hikashop-api/v1/products/2/stock" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "quantity": 42 }' ``` ``` { "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. emailstringThe exact email address, ignoring case: one customer or none. For a client that knows who it is looking for, such as a helpdesk matching a message to its sender, where `search` would also find `This email address is being protected from spambots. You need JavaScript enabled to view it.` for `This email address is being protected from spambots. You need JavaScript enabled to view it.`. ### Response a list expand all 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 typestring`registered` 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. ``` curl "$SHOP/hikashop-api/v1/customers?limit=2" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "data": [ { "id": 5424, "name": "Alex Marchand", "email": "This email address is being protected from spambots. You need JavaScript enabled to view it.", "type": "guest", "created": 1790620906, "order_count": 0 }, { "id": 5412, "name": "", "email": "This email address is being protected from spambots. You need JavaScript enabled to view it.", "type": "guest", "created": 1789923608, "order_count": 0 } ], "meta": { "start": 0, "limit": 2, "total": 384 }, "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`. typestring`discount` or `coupon`, to list one kind. searchstringMatches the code. ### Response a list expand all FieldTypeDescription idinteger typestring`discount` 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.modestring`all`, `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.modestring`all`, `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. ``` curl "$SHOP/hikashop-api/v1/discounts?limit=2" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "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": 5, "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 expand all 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. ``` curl "$SHOP/hikashop-api/v1/categories?limit=3" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "data": [ { "id": 17, "name": "Unrelated Cat", "parent_id": 2, "published": true, "has_children": false, "image": "" }, { "id": 18, "name": "StoreLinkr Cat", "parent_id": 2, "published": true, "has_children": true, "image": "" }, { "id": 20, "name": "Via Ajax Cat", "parent_id": 2, "published": true, "has_children": false, "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 expand all 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.modestring`all`, `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. ``` curl "$SHOP/hikashop-api/v1/categories/2" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "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 expand all 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. ``` curl "$SHOP/hikashop-api/v1/massactions?table=product" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "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 expand all 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. ``` curl "$SHOP/hikashop-api/v1/media/browse" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "data": { "folder": "", "parent": "", "has_parent": false, "folders": [], "images": [ { "name": "demo-0001.png", "path": "demo-0001.png", "url": "http://localhost:8080/joomla6_ext/images/com_hikashop/upload/demo-0001.png" }, { "name": "demo-0002-2.png", "path": "demo-0002-2.png", "url": "http://localhost:8080/joomla6_ext/images/com_hikashop/upload/demo-0002-2.png" }, { "name": "demo-0002.png", "path": "demo-0002.png", "url": "http://localhost:8080/joomla6_ext/images/com_hikashop/upload/demo-0002.png" }, { "name": "demo-0003.png", "path": "demo-0003.png", "url": "http://localhost:8080/joomla6_ext/images/com_hikashop/upload/demo-0003.png" }, "… 583 more, trimmed for the example" ], "total": 587, "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 expand all FieldTypeDescription idinteger namekeystringWhat an address stores, such as `FRA` or `US-CA`. namestringTranslated where the shop has a translation for it. typestring`country`, `state`, or the kind of grouping it is. ``` curl "$SHOP/hikashop-api/v1/zones?search=fra" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "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 expand all FieldTypeDescription idintegerThe customer id, which is what a restriction stores. namestring emailstringEnough to tell two people of the same name apart. ``` curl "$SHOP/hikashop-api/v1/users?search=a" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "data": [ { "id": 5424, "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 expand all 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. ``` curl "$SHOP/hikashop-api/v1/products/meta" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "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 expand all 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.modestring`all`, `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. ``` 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 } ] }' ``` ``` { "data": [ { "id": 4947, "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 expand all 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. ``` curl -X PUT "$SHOP/hikashop-api/v1/products/{id}/categories" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "categories": [ "2" ] }' ``` ``` { "data": [ { "id": 2, "name": "product category" } ], "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 expand all 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. typestring`text` 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. ``` curl "$SHOP/hikashop-api/v1/products/1/translations" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "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": { "2": { "product_name": "Lampe de bureau" } } }, "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 expand all 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. typestring`text` 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. ``` curl "$SHOP/hikashop-api/v1/categories/2/translations" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "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": { "2": { "category_name": "Sacs et vêtements" } } }, "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 expand all 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. ``` 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" } }' ``` ``` { "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 expand all 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. ``` 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" } }' ``` ``` { "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 rangestring`day`, `week`, `month` or `year`. Defaults to `month`. ### Response expand all 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. ``` curl "$SHOP/hikashop-api/v1/stats/dashboard?range=month" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "data": { "range": "month", "currency_id": 1, "totals": { "revenue": 0, "orders": 0, "average_order": 0, "customers": 0 }, "previous": { "revenue": 6309.8, "orders": 22, "average_order": 286.81, "customers": 18 }, "series_granularity": "day", "revenue_series": [ { "date": "+33 2 00 00 00 00", "revenue": 0 }, { "date": "+33 2 00 00 00 00", "revenue": 0 }, { "date": "+33 2 00 00 00 00", "revenue": 0 }, { "date": "+33 2 00 00 00 00", "revenue": 0 }, "… 27 more, trimmed for the example" ], "top_products": [] }, "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 expand all FieldTypeDescription idintegerWhat an access object stores. titlestringThe name of the group. ``` curl "$SHOP/hikashop-api/v1/groups" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "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 expand all 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. ``` curl "$SHOP/hikashop-api/v1/orders/{id}/products/precompute?product_id=1&quantity=2" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "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 expand all 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. typestring`registered` 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. sectionsobject\[\]Information other plugins show on this record, each with a `key`, a `title` and `rows` (`label`, `value`, and optionally `url`, `badge` and `ref`). Empty when no plugin adds any; on a customer, core adds their paid downloads. See the guide on adding information and settings. extensionsobject\[\]Settings other plugins keep on this record, in groups (`key`, `title`, `fields`), each field described like a custom field plus its current `value`. Send changes back as `extensions` with the record's save. Empty when no plugin adds any. ### Errors CodeHTTPMeans not\_found404No such customer, or the operator may not see them. ``` curl "$SHOP/hikashop-api/v1/customers/{id}" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "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": 4372, "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": 4371, "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": 4380, "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": 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": 4379, "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": 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)" } }, "… 4 more, trimmed for the example" ], "orders": [ { "id": 2, "number": "TEST-VOTE-1", "status": "confirmed", "created": 1786877040, "total": 100, "currency_id": 1 }, { "id": 18, "number": "U18", "status": "confirmed", "created": 1786358640, "total": 14.99, "currency_id": 1 }, { "id": 20, "number": "X20", "status": "confirmed", "created": 1785840240, "total": 14.99, "currency_id": 1 }, { "id": 16, "number": "S16", "status": "created", "created": 1783345950, "total": 14.99, "currency_id": 1 }, "… 96 more, trimmed for the example" ], "fields": [], "custom_fields": [], "custom_field_files": [], "sections": [], "extensions": [] }, "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 expand all 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. ``` curl -X DELETE "$SHOP/hikashop-api/v1/customers/{id}" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "data": { "deleted": 5424 }, "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. extensionsobjectSettings other plugins keep on this record, as `{ group key: { namekey: value } }`, for the groups and fields its `extensions` lists. Saved after the record's own fields. See the guide on adding information and settings. ### Response expand all 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. typestring`registered` 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. sectionsobject\[\]Information other plugins show on this record, each with a `key`, a `title` and `rows` (`label`, `value`, and optionally `url`, `badge` and `ref`). Empty when no plugin adds any; on a customer, core adds their paid downloads. See the guide on adding information and settings. extensionsobject\[\]Settings other plugins keep on this record, in groups (`key`, `title`, `fields`), each field described like a custom field plus its current `value`. Send changes back as `extensions` with the record's save. Empty when no plugin adds any. ### 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. invalid\_extensions400The record's own fields were saved, but a plugin refused some of its values: `error.details` says which, as `{ group key: { namekey: message } }`. ``` curl -X PUT "$SHOP/hikashop-api/v1/customers/{id}" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Alex Marchand" }' ``` ``` { "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": 1786963440, "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": 1785321840, "total": 14.99, "currency_id": 1 }, { "id": 30, "number": "ZBUNDLE", "status": "confirmed", "created": 1784803440, "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": [], "sections": [], "extensions": [] }, "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 expand all 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. typestring`registered` 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. ``` curl -X POST "$SHOP/hikashop-api/v1/customers/{id}/account" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "username": "doccapture5412", "password": "not-a-real-password-9x" }' ``` ``` { "data": { "id": 5412, "cms_id": 181, "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": "doccapture5412", "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": 1789923608, "addresses": [], "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 expand all 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\_unitstring`kg`, `g`, `lb` or `oz`. widthintegerIn `dimension_unit`. heightintegerIn `dimension_unit`. lengthintegerIn `dimension_unit`. dimension\_unitstring`m`, `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.modestring`all`, `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. typestring`main` 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.idstring valuestringTax excluded, as stored. currency\_idstring min\_quantitystringFrom 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.idstring namestring pathstringRelative to the upload folder. urlstringAbsolute, ready to display. orderingstring descriptionstringThe alt text. accessobjectWho may see it.modestringAs above. groupsinteger\[\]As above. free\_downloadstringFiles only; meaningless on an image. filesobject\[\]Downloadable files, in the same shape as the images.idstring namestring pathstringRelative to the upload folder. urlstringAbsolute. orderingstring descriptionstring accessobjectWho may download it. free\_downloadstringWhether 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.idstring namestring codestring quantitystringHow many of it the bundle contains. optionsobject\[\]Products offered as options alongside this one.idstring namestring codestring quantitystring relatedobject\[\]Products shown as related.idstring namestring codestring quantitystring 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\|null`null` 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`. typestring`text`, `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 depend on the shop; `fields` says what they are. custom\_field\_filesobjectFor custom fields holding a file, the file behind each value. Keyed the same way. sectionsobject\[\]Information other plugins show on this record, each with a `key`, a `title` and `rows` (`label`, `value`, and optionally `url`, `badge` and `ref`). Empty when no plugin adds any; on a customer, core adds their paid downloads. See the guide on adding information and settings. extensionsobject\[\]Settings other plugins keep on this record, in groups (`key`, `title`, `fields`), each field described like a custom field plus its current `value`. Send changes back as `extensions` with the record's save. Empty when no plugin adds any. ### Errors CodeHTTPMeans invalid\_fields400One of your own fields was rejected by its own rules. save\_failed500The shop refused to save the product. ``` curl -X POST "$SHOP/hikashop-api/v1/products" \ -H "Content-Type: application/json" \ -d '{ "name": "Documentation capture product", "code": "DOC-CAPTURE-1" }' ``` ``` { "data": { "id": 9149, "name": "Documentation capture product", "code": "DOC-CAPTURE-1", "description": "", "description_type": "", "published": false, "quantity": -1, "msrp": 0, "gtin": "", "condition": "", "weight": 0, "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": "documentation-capture-product", "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": [], "images": [], "files": [], "categories": [ { "id": 2, "name": "product category" } ], "bundle": [], "options": [], "related": [], "tags": [], "characteristics": [], "variants": [], "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": "" }, { "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": [] }, "sections": [], "extensions": [] }, "meta": null, "error": null } ``` ## Update a product PUT /products/**{id}** write since 6.6.0 Changes the fields you send and leaves the rest alone, which is the opposite of the price and category calls: this one merges. Sending nothing to change is refused rather than treated as a success, so a client cannot believe it saved something it did not. ### Path ParameterTypeDescription idrequiredintegerThe product or variant. ### Body The same fields as `POST /products`, all of them optional here. A field you do not send keeps its value; `access` and `custom_fields` are accepted too, and `extensions` for other plugins' settings (`{ group key: { namekey: value } }`, saved after the product's own fields; see the guide on adding information and settings). ### Response expand all 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\_unitstring`kg`, `g`, `lb` or `oz`. widthintegerIn `dimension_unit`. heightintegerIn `dimension_unit`. lengthintegerIn `dimension_unit`. dimension\_unitstring`m`, `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.modestring`all`, `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. typestring`main` 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.idstring namestring pathstringRelative to the upload folder. urlstringAbsolute. orderingstring descriptionstring accessobjectWho may download it. free\_downloadstringWhether 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.idstring namestring codestring quantitystringHow many of it the bundle contains. optionsobject\[\]Products offered as options alongside this one.idstring namestring codestring quantitystring relatedobject\[\]Products shown as related.idstring namestring codestring quantitystring 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\|null`null` 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`. typestring`text`, `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 depend on the shop; `fields` says what they are. custom\_field\_filesobjectFor custom fields holding a file, the file behind each value. Keyed the same way. sectionsobject\[\]Information other plugins show on this record, each with a `key`, a `title` and `rows` (`label`, `value`, and optionally `url`, `badge` and `ref`). Empty when no plugin adds any; on a customer, core adds their paid downloads. See the guide on adding information and settings. extensionsobject\[\]Settings other plugins keep on this record, in groups (`key`, `title`, `fields`), each field described like a custom field plus its current `value`. Send changes back as `extensions` with the record's save. Empty when no plugin adds any. ### Errors CodeHTTPMeans not\_found404No such product, or the operator may not change it. invalid\_fields400One of your own fields was rejected by its own rules. nothing400The body held no field this shop knows, so nothing would have been written. invalid\_extensions400The product was saved, but a plugin refused some of its values: `error.details` says which, as `{ group key: { namekey: message } }`. ``` curl -X PUT "$SHOP/hikashop-api/v1/products/{id}" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Desk lamp, brass" }' ``` ``` { "data": { "id": 9136, "name": "Desk lamp, brass", "code": "HS-TEST-27025", "description": "", "description_type": "", "published": false, "quantity": -1, "msrp": 0, "gtin": "", "condition": "", "weight": 0, "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": "desk-lamp-brass", "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": 4947, "value": 19.9, "currency_id": 1, "min_quantity": 1, "access": { "mode": "all", "groups": [] }, "users": [], "zone_ids": [], "start_date": 0, "end_date": 0 } ], "images": [ { "id": 8333, "name": "documentation-capture.png", "path": "documentation-capture.png", "url": "http://localhost:8080/joomla6_ext/images/com_hikashop/upload/documentation-capture.png", "ordering": 1, "description": "A one pixel image", "access": { "mode": "all", "groups": [] }, "free_download": false } ], "files": [], "categories": [ { "id": 2, "name": "product category" } ], "bundle": [], "options": [], "related": [], "tags": [], "characteristics": [], "variants": [], "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": "" }, { "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": [] }, "sections": [], "extensions": [] }, "meta": null, "error": null } ``` ## Delete a product DELETE /products/**{id}** write since 6.6.0 Deletes a product and its variants. Orders that already contain it are untouched: an order line records what was sold at the time, and it does not stop meaning something because the catalogue changed. ### Path ParameterTypeDescription idrequiredintegerThe product. ### Response expand all FieldTypeDescription idintegerThe product that was deleted. deletedbooleanTrue when the row is gone. ### Errors CodeHTTPMeans not\_found404No such product, or the operator may not delete it. delete\_failed400The shop refused to delete it. ``` curl -X DELETE "$SHOP/hikashop-api/v1/products/{id}" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "data": { "id": 9136, "deleted": true }, "meta": null, "error": null } ``` ## Reconcile the variant set PUT /products/**{id}**/variants write since 6.6.0 Takes the variants a product should have and makes the shop agree: it creates the ones that are missing, updates the ones that exist and removes the ones you left out. A variant is identified by the characteristic values it stands for rather than by an id, because that is what makes it that variant. Send the whole set. ### Path ParameterTypeDescription idrequiredintegerThe parent product. ### Body FieldTypeDescription variantsrequiredobject\[\]The complete set. Each needs the characteristic `values` it stands for, and may carry `code`, `quantity`, `published` and `price`. ### Response expand all FieldTypeDescription characteristicsobject\[\]The characteristics the product now varies on, as they stand after the change. variantsobject\[\]The variants as they now stand, in the same shape as on the product. ### Errors CodeHTTPMeans not\_found404No such product, or the operator may not change it. ``` curl -X PUT "$SHOP/hikashop-api/v1/products/{id}/variants" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "variants": [] }' ``` ``` { "data": { "characteristics": [], "variants": [] }, "meta": null, "error": null } ``` ## Edit one variant PUT /products/**{id}**/variants/**{vid}** write since 6.6.0 Changes one variant without touching the others, which is what a stock correction or a price change on a single size needs. ### Path ParameterTypeDescription idrequiredintegerThe parent product. vidrequiredintegerThe variant. ### Body Any of `code`, `quantity`, `published` and `price`, and your own product fields. What you do not send is left alone. ### Response expand all 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\_unitstring`kg`, `g`, `lb` or `oz`. widthintegerIn `dimension_unit`. heightintegerIn `dimension_unit`. lengthintegerIn `dimension_unit`. dimension\_unitstring`m`, `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.modestring`all`, `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. typestring`main` 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.idstring valuestringTax excluded, as stored. currency\_idstring min\_quantitystringFrom 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.idstring namestring pathstringRelative to the upload folder. urlstringAbsolute. orderingstring descriptionstring accessobjectWho may download it. free\_downloadstringWhether it can be downloaded without buying the product. categoriesobject\[\]The categories the product is in.idstring namestring bundleobject\[\]The products this one is made of, when it is a bundle.idstring namestring codestring quantitystringHow many of it the bundle contains. optionsobject\[\]Products offered as options alongside this one.idstring namestring codestring quantitystring relatedobject\[\]Products shown as related.idstring namestring codestring quantitystring 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\|null`null` 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`. typestring`text`, `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 depend on the shop; `fields` says what they are. custom\_field\_filesobjectFor custom fields holding a file, the file behind each value. Keyed the same way. sectionsobject\[\]Information other plugins show on this record, each with a `key`, a `title` and `rows` (`label`, `value`, and optionally `url`, `badge` and `ref`). Empty when no plugin adds any; on a customer, core adds their paid downloads. See the guide on adding information and settings. extensionsobject\[\]Settings other plugins keep on this record, in groups (`key`, `title`, `fields`), each field described like a custom field plus its current `value`. Send changes back as `extensions` with the record's save. Empty when no plugin adds any. ### Errors CodeHTTPMeans not\_found404No such variant, or the operator may not change it. invalid\_fields400One of your own fields was rejected by its own rules. ``` curl -X PUT "$SHOP/hikashop-api/v1/products/{id}/variants/{id}" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "quantity": 7 }' ``` ``` { "data": { "id": 8671, "name": "Waxed Canvas Sandals — XS", "code": "DEMO-0027-XS", "description": "", "description_type": "", "published": true, "quantity": 7, "msrp": 0, "gtin": "", "condition": "", "weight": 0, "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": "variant", "parent_id": 8670, "value_ids": [ 35 ], "manufacturer_id": 0, "manufacturer_name": "", "tax_id": 0, "tax_name": "", "tax_rate": 0, "prices": [], "images": [ { "id": 7805, "name": "Waxed Canvas Sandals — XS", "path": "demo-0027-xs.png", "url": "http://localhost:8080/joomla6_ext/images/com_hikashop/upload/demo-0027-xs.png", "ordering": 1, "description": "", "access": { "mode": "all", "groups": [] }, "free_download": false } ], "files": [], "categories": [], "bundle": [], "options": [], "related": [], "tags": [], "characteristics": [], "variants": [], "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": "" }, { "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": [] }, "sections": [], "extensions": [] }, "meta": null, "error": null } ``` ## Apply a coupon to an order POST /orders/**{id}**/coupon write since 6.6.0 Applies a coupon by its code and re-totals the order. The shop validates it again here against this order: its dates, its quota, its minimum, the products in the cart and the customer. A coupon that appears in `GET /coupons` can still be refused for this particular order, which is the point of validating rather than trusting the list. ### Path ParameterTypeDescription idrequiredintegerThe order. ### Body FieldTypeDescription coderequiredstringThe coupon code, as the customer would type it. ### Response expand all FieldTypeDescription idintegerThe order. feesobjectThe discount, shipping and payment amounts of the order. discountobjectIts `amount`, its `tax`, the `tax_namekeys` behind that tax, and the coupon `code` when one was used.amountnumberA positive figure, already subtracted from the total. taxnumberThe tax on it. tax\_namekeysstring\[\]Which tax rates that came from. codestringThe coupon code, empty for a discount applied by hand. shippingobjectThe shipping charge and what carried it.amountnumberTax excluded. taxnumberThe tax on it. tax\_namekeysstring\[\]Which tax rates that came from. methodstringThe plugin that handled it. method\_namestringAs the merchant named it. paymentobjectThe payment fee and what took it.amountnumberTax excluded. taxnumberThe tax on it. tax\_namekeysstring\[\]Which tax rates that came from. methodstringThe plugin that took it. method\_namestringAs the merchant named it. totalsobjectThe order totalled, so a client need not compute it and disagree with the shop.totalnumberWhat the customer owes, tax included. discountnumberThe discount applied, as a positive figure already subtracted. shippingnumberThe shipping charged. paymentnumberThe payment fee charged. taxnumberThe tax within the total, not on top of it. ### Errors CodeHTTPMeans not\_found404No such order, or the operator may not change it. invalid\_coupon400No such code, or it does not apply to this order. save\_failed500The order could not be saved. ``` curl -X POST "$SHOP/hikashop-api/v1/orders/{id}/coupon" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "code": "APPTEST10" }' ``` ``` { "data": { "id": 5630, "fees": { "discount": { "amount": 10, "tax": 0, "tax_namekeys": [], "code": "APPTEST10" }, "shipping": { "amount": 6.9, "tax": 0, "tax_namekeys": [], "method": "manual", "method_name": "Vendor 2 only shipping" }, "payment": { "amount": 0, "tax": 0, "tax_namekeys": [], "method": "paypalcheckout", "method_name": "PayPal Checkout Express Test" } }, "totals": { "total": 303.92, "discount": 10, "shipping": 6.9, "payment": 0, "tax": 0 } }, "meta": null, "error": null } ``` ## Remove the discount from an order DELETE /orders/**{id}**/coupon write since 6.6.0 Takes the coupon or the hand-applied discount off the order and re-totals it. There is nothing to send. ### Path ParameterTypeDescription idrequiredintegerThe order. ### Response expand all FieldTypeDescription idintegerThe order. feesobjectThe discount, shipping and payment amounts of the order. discountobjectIts `amount`, its `tax`, the `tax_namekeys` behind that tax, and the coupon `code` when one was used.amountnumberA positive figure, already subtracted from the total. taxnumberThe tax on it. tax\_namekeysstring\[\]Which tax rates that came from. codestringThe coupon code, empty for a discount applied by hand. shippingobjectThe shipping charge and what carried it.amountnumberTax excluded. taxnumberThe tax on it. tax\_namekeysstring\[\]Which tax rates that came from. methodstringThe plugin that handled it. method\_namestringAs the merchant named it. paymentobjectThe payment fee and what took it.amountnumberTax excluded. taxnumberThe tax on it. tax\_namekeysstring\[\]Which tax rates that came from. methodstringThe plugin that took it. method\_namestringAs the merchant named it. totalsobjectThe order totalled, so a client need not compute it and disagree with the shop.totalnumberWhat the customer owes, tax included. discountnumberThe discount applied, as a positive figure already subtracted. shippingnumberThe shipping charged. paymentnumberThe payment fee charged. taxnumberThe tax within the total, not on top of it. ### Errors CodeHTTPMeans not\_found404No such order, or the operator may not change it. save\_failed500The order could not be saved. ``` curl -X DELETE "$SHOP/hikashop-api/v1/orders/{id}/coupon" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "data": { "id": 5630, "fees": { "discount": { "amount": 0, "tax": 0, "tax_namekeys": [], "code": "" }, "shipping": { "amount": 6.9, "tax": 0, "tax_namekeys": [], "method": "manual", "method_name": "Vendor 2 only shipping" }, "payment": { "amount": 0, "tax": 0, "tax_namekeys": [], "method": "paypalcheckout", "method_name": "PayPal Checkout Express Test" } }, "totals": { "total": 313.92, "discount": 0, "shipping": 6.9, "payment": 0, "tax": 0 } }, "meta": null, "error": null } ``` ## Add a line to an order POST /orders/**{id}**/products write since 6.6.0 Adds a product to an existing order and re-totals it. Send a `price` only to override what the shop would charge; leave it out and the order's own pricing applies, which is what `GET /orders/{id}/products/precompute` shows you beforehand. ### Path ParameterTypeDescription idrequiredintegerThe order. ### Body FieldTypeDescription product\_idrequiredintegerThe product or variant to add. quantityintegerHow many. Defaults to `1`. pricenumberUnit price, tax excluded, to override the shop. Omit to let the shop price it. tax\_namekeysstring\[\]Which tax rates to apply, when overriding the price. Omit to let the shop decide. ### Response expand all FieldTypeDescription idintegerThe order. itemsobject\[\]The lines as they now stand, in the same shape as on the order.idintegerThe line id, which is what the line routes take. It is not the product id. namestringThe product as it was named when ordered. codestringIts SKU at the time. quantityinteger pricenumberUnit price, tax excluded, as agreed at the time. taxnumberTax on the line. editablebooleanFalse once the line can no longer be changed. totalsobjectThe order totalled, so a client need not compute it and disagree with the shop.totalnumberWhat the customer owes, tax included. discountnumberThe discount applied, as a positive figure already subtracted. shippingnumberThe shipping charged. paymentnumberThe payment fee charged. taxnumberThe tax within the total, not on top of it. ### Errors CodeHTTPMeans not\_found404No such order or product, or the operator may not change the order. save\_failed500The order could not be saved. ``` curl -X POST "$SHOP/hikashop-api/v1/orders/{id}/products" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "product_id": "1", "quantity": 1 }' ``` ``` { "data": { "id": 5630, "items": [ { "id": 20630, "name": "Nordic Design item", "code": "SEED-7-44", "quantity": 1, "price": 307.02, "tax": 0, "editable": true }, { "id": 20642, "name": "Test Product (Vendor 2)", "code": "TEST001", "quantity": 1, "price": 0, "tax": 0, "editable": true } ], "totals": { "total": 313.92, "discount": 0, "shipping": 6.9, "payment": 0, "tax": 0 } }, "meta": null, "error": null } ``` ## Change a line's quantity PUT /orders/**{id}**/products/**{lineId}** write since 6.6.0 Changes how many of one line the order holds, and re-totals it. A quantity of `0` removes the line. The id in the path is the **line** id from `items`, not the product id: the same product can appear on an order more than once. ### Path ParameterTypeDescription idrequiredintegerThe order. lineIdrequiredintegerThe line, from `items\[\].id` on the order. ### Body FieldTypeDescription quantityrequiredintegerThe new quantity. `0` removes the line. ### Response expand all FieldTypeDescription idintegerThe order. itemsobject\[\]The lines as they now stand.idintegerThe line id, which is what the line routes take. It is not the product id. namestringThe product as it was named when ordered. codestringIts SKU at the time. quantityinteger pricenumberUnit price, tax excluded, as agreed at the time. taxnumberTax on the line. editablebooleanFalse once the line can no longer be changed. totalsobjectThe order totalled, so a client need not compute it and disagree with the shop.totalnumberWhat the customer owes, tax included. discountnumberThe discount applied, as a positive figure already subtracted. shippingnumberThe shipping charged. paymentnumberThe payment fee charged. taxnumberThe tax within the total, not on top of it. ### Errors CodeHTTPMeans not\_found404No such order or line, or the operator may not change it. save\_failed500The order could not be saved. ``` curl -X PUT "$SHOP/hikashop-api/v1/orders/{id}/products/{id}" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "quantity": 2 }' ``` ``` { "data": { "id": 5630, "items": [ { "id": 20630, "name": "Nordic Design item", "code": "SEED-7-44", "quantity": 1, "price": 307.02, "tax": 0, "editable": true }, { "id": 20642, "name": "Test Product (Vendor 2)", "code": "TEST001", "quantity": 2, "price": 0, "tax": 0, "editable": true } ], "totals": { "total": 313.92, "discount": 0, "shipping": 6.9, "payment": 0, "tax": 0 } }, "meta": null, "error": null } ``` ## Run a mass action POST /massactions/**{id}** write since 6.6.0 Runs one of the merchant's own bulk operations over a selection. It runs the same code the backend runs, so whatever the action does there it does here, including whatever a third-party plugin added to it. Give it the ids to work on. ### Path ParameterTypeDescription idrequiredintegerThe mass action, from `GET /massactions`. ### Body FieldTypeDescription idsrequiredinteger\[\]The records to run it over, from the listing the action belongs to. ### Response expand all FieldTypeDescription okbooleanWhether the action reported success. countintegerHow many records it worked on. reportstringWhatever the action had to say, ready to show. Its wording is the action's own. ### Errors CodeHTTPMeans invalid\_request400No ids were sent, or the action is not one this shop has. forbidden403The operator may not work on that kind of record. ``` curl -X POST "$SHOP/hikashop-api/v1/massactions/2" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "ids": [ "9135" ] }' ``` ``` { "data": { "ok": true, "count": 1, "report": [] }, "meta": null, "error": null } ``` ## Create an order by hand POST /orders write since 6.6.0 Creates an empty order for a customer, to be filled in with lines, fees and an address. Give it either an existing `user_id` or a `guest` with at least an email address, which is how an order gets taken over the telephone from somebody who has never bought before. ### Body FieldTypeDescription user\_idintegerAn existing customer. Give this or `guest`. guestobjectA new guest customer, needing at least `email` and usually a name. ### Response expand all FieldTypeDescription idintegerThe order that was created, to add lines to. ### Errors CodeHTTPMeans no\_customer400Neither a user\_id nor a usable guest was given. save\_failed500The order could not be created. ``` curl -X POST "$SHOP/hikashop-api/v1/orders" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "guest": { "email": "This email address is being protected from spambots. You need JavaScript enabled to view it.", "name": "Alex Marchand" } }' ``` ``` { "data": { "id": 5648 }, "meta": null, "error": null } ``` ## Save an order's custom fields PUT /orders/**{id}**/fields write since 6.6.0 Writes the merchant's own order fields. Only the fields you send are touched. ### Path ParameterTypeDescription idrequiredintegerThe order. ### Body FieldTypeDescription fieldsobjectKeyed by field namekey. May be left out when only `extensions` are sent. extensionsobjectSettings other plugins keep on this record, as `{ group key: { namekey: value } }`, for the groups and fields its `extensions` lists. Saved after the record's own fields. See the guide on adding information and settings. ### Response expand all FieldTypeDescription idintegerThe order. custom\_fieldsobjectThe values as they now stand. The keys depend on the shop. custom\_field\_filesobjectFor a field holding a file, the file behind the value. Keyed the same way. extensionsobject\[\]The other plugins' settings on the order as they now stand, as in `GET /orders/{id}`. ### Errors CodeHTTPMeans not\_found404No such order, or the operator may not change it. invalid\_fields400A field was rejected by its own rules. save\_failed500The order could not be saved. invalid\_extensions400The record's own fields were saved, but a plugin refused some of its values: `error.details` says which, as `{ group key: { namekey: message } }`. ``` curl -X PUT "$SHOP/hikashop-api/v1/orders/{id}/fields" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "fields": [] }' ``` ``` { "data": { "id": 5630, "custom_fields": { "hstestfile1755": null, "hstestfile1859": null, "hstestfile26994": null, "hstestfile28016": null, "hstestfile27610": null }, "custom_field_files": { "hstestfile1755": [], "hstestfile1859": [], "hstestfile26994": [], "hstestfile28016": [], "hstestfile27610": [] }, "extensions": [] }, "meta": null, "error": null } ``` ## Save an address of an order PUT /orders/**{id}**/address/**{type}** write since 6.6.0 Writes the billing or shipping address of an order, using the fields `GET` gave you. The address on an order is its own copy, so changing it here does not change the customer's address book, and vice versa. That is deliberate: an invoice should not change because somebody moved. ### Path ParameterTypeDescription idrequiredintegerThe order. typerequiredstring`billing` or `shipping`. ### Body FieldTypeDescription fieldsrequiredobjectKeyed by address field namekey, the same keys `GET` returned in `values`. ### Response expand all FieldTypeDescription typestringWhich address was written. address\_idintegerThe address row, created if there was none. valuesobjectThe values as stored. Keyed by whatever address fields this shop has. country\_namestringThe country spelled out. state\_namestringThe state spelled out, empty where the country has none. summaryobjectThe address ready to show, without re-reading the order.namestring companystring formattedobjectLaid out the way this shop lays addresses out, which follows its address format setting.textstringSeveral lines, for an invoice or a label. one\_linestringOne line, for a list. streetstring citystring post\_codestring ### Errors CodeHTTPMeans not\_found404No such order, or the operator may not change it. invalid\_fields400A field was rejected by its own rules. invalid\_address400The address is not one the shop will accept, usually a missing required field. ``` curl -X PUT "$SHOP/hikashop-api/v1/orders/{id}/address/billing" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "fields": { "address_title": "Mr", "address_firstname": "Alex", "address_lastname": "Marchand", "address_street": "12 rue des Lilas", "address_post_code": "44000", "address_city": "Nantes", "address_telephone": "+33 2 00 00 00 00", "address_country": "country_France_73", "address_state": "state_Paris_1381" } }' ``` ``` { "data": { "type": "billing", "address_id": 4385, "values": { "address_title": "Mr", "address_firstname": "Alex", "address_lastname": "Marchand", "address_company": "Lilas SARL", "address_street": "12 rue des Lilas", "address_post_code": "44000", "address_city": "Nantes", "address_telephone": "+33 2 00 00 00 00", "address_country": "country_France_73", "address_state": "state_Paris_1381", "address_vat": "FR00000000000" }, "country_name": "France", "state_name": "Paris", "summary": { "name": "John Doe", "company": "Lilas SARL", "formatted": { "text": "Alex Marchand\r\n12 rue des Lilas\r\n44000 Nantes\r\nFrance", "one_line": "Marchand Alex - 12 rue des Lilas, Nantes (France)" }, "street": "12 rue des Lilas", "city": "Nantes", "post_code": "44000" } }, "meta": null, "error": null } ``` ## Attach an image or a file POST /products/**{id}**/images write since 6.6.0 Adds an image or a downloadable file to a product, either by sending the bytes or by pointing at something already in the upload folder. Send `data` as base64 to upload, or `path` to attach a file that `GET /media/browse` already showed you. The extension is checked against what the shop allows, so a refusal is the shop's policy rather than a fault. The same route serves `/images` and `/files`; which one you call decides where it goes. ### Path ParameterTypeDescription idrequiredintegerThe product. ### Body FieldTypeDescription datastringThe bytes, base64 encoded. Give this or `path`. pathstringA file already in the upload folder, relative to it, as `GET /media/browse` returns. namestringThe file name to store it under. Defaults to the one in the path. descriptionstringThe alt text for an image, or a note on a file. accessobjectWho may see or download it, in the usual mode and groups shape. ### Response expand all FieldTypeDescription idinteger namestring pathstringRelative to the upload folder. urlstringAbsolute, ready to display. orderingintegerWhere it sits among the others; the first image is the one the shop shows. descriptionstringThe alt text for an image, or a note on a file. accessobjectWho may see or download it.modestring`all`, `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. free\_downloadbooleanFiles only: whether it can be downloaded without buying the product. ### Errors CodeHTTPMeans not\_found404No such product, or the operator may not change it. bad\_type400The extension is not one this shop accepts. write\_failed500The upload folder refused the file, which is usually a permissions problem. ``` curl -X POST "$SHOP/hikashop-api/v1/products/{id}/images" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFAAH/q842iQAAAABJRU5ErkJggg==", "name": "documentation-capture.png", "description": "A one pixel image" }' ``` ``` { "data": { "id": 8336, "name": "documentation-capture.png", "path": "documentation-capture.png", "url": "http://localhost:8080/joomla6_ext/images/com_hikashop/upload/documentation-capture.png", "ordering": 1, "description": "A one pixel image", "access": { "mode": "all", "groups": [] }, "free_download": false }, "meta": null, "error": null } ``` ## Edit an image or a file PUT /products/**{id}**/files/**{fileId}** write since 6.6.0 Changes the name, the description or the access of something already attached, without re-uploading the bytes. ### Path ParameterTypeDescription idrequiredintegerThe product. fileIdrequiredintegerThe image or file. ### Body Any of `name`, `description`, `access` and, for a file, `free_download`. What you do not send is left alone. ### Response expand all FieldTypeDescription idinteger namestring pathstringRelative to the upload folder. urlstringAbsolute, ready to display. orderingintegerWhere it sits among the others; the first image is the one the shop shows. descriptionstringThe alt text for an image, or a note on a file. accessobjectWho may see or download it.modestring`all`, `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. free\_downloadbooleanFiles only: whether it can be downloaded without buying the product. ### Errors CodeHTTPMeans not\_found404No such file on that product, or the operator may not change it. ``` curl -X PUT "$SHOP/hikashop-api/v1/products/{id}/files/{id}" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "documentation-capture.png", "description": "A one pixel image" }' ``` ``` { "data": { "id": 8336, "name": "documentation-capture.png", "path": "documentation-capture.png", "url": "http://localhost:8080/joomla6_ext/images/com_hikashop/upload/documentation-capture.png", "ordering": 1, "description": "A one pixel image", "access": { "mode": "all", "groups": [] }, "free_download": false }, "meta": null, "error": null } ``` ## Remove an image or a file DELETE /products/**{id}**/files/**{fileId}** write since 6.6.0 Detaches an image or a file from a product. The bytes stay in the upload folder: another product may be using the same file, and the API will not delete somebody's media because one product stopped pointing at it. ### Path ParameterTypeDescription idrequiredintegerThe product. fileIdrequiredintegerThe image or file. ### Response expand all FieldTypeDescription idintegerWhat was detached. deletedbooleanTrue when the row is gone. ### Errors CodeHTTPMeans not\_found404No such file on that product, or the operator may not change it. ``` curl -X DELETE "$SHOP/hikashop-api/v1/products/{id}/files/{id}" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "data": { "id": 8337, "deleted": true }, "meta": null, "error": null } ``` ## Reorder images and files PUT /products/**{id}**/media/order write since 6.6.0 Sets the order of a product's images or files. The first image is the one the shop shows, so this is how you choose it. ### Path ParameterTypeDescription idrequiredintegerThe product. ### Body FieldTypeDescription imagesinteger\[\]File ids in the order you want them. filesinteger\[\]The same for downloadable files. ### Response expand all FieldTypeDescription imagesobject\[\]The images as they now stand, in their new order, each in the same shape as on the product.idinteger namestring pathstringRelative to the upload folder. urlstringAbsolute, ready to display. orderingintegerWhere it sits among the others; the first image is the one the shop shows. descriptionstringThe alt text for an image, or a note on a file. accessobjectWho may see or download it.modestring`all`, `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. free\_downloadbooleanFiles only: whether it can be downloaded without buying the product. filesobject\[\]The files as they now stand, in the same shape as on the product.idinteger namestring pathstringRelative to the upload folder. urlstringAbsolute, ready to display. orderingintegerWhere it sits among the others; the first image is the one the shop shows. descriptionstringThe alt text for an image, or a note on a file. accessobjectWho may see or download it.modestring`all`, `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. free\_downloadbooleanFiles only: whether it can be downloaded without buying the product. ### Errors CodeHTTPMeans not\_found404No such product, or the operator may not change it. ``` curl -X PUT "$SHOP/hikashop-api/v1/products/{id}/media/order" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "images": [ 7756, 7757 ] }' ``` ``` { "data": { "images": [ { "id": 7756, "name": "Lacquered Fountain Pen — Broad", "path": "demo-0002.png", "url": "http://localhost:8080/joomla6_ext/images/com_hikashop/upload/demo-0002.png", "ordering": 0, "description": "", "access": { "mode": "all", "groups": [] }, "free_download": false }, { "id": 7757, "name": "Lacquered Fountain Pen — Broad", "path": "demo-0002-2.png", "url": "http://localhost:8080/joomla6_ext/images/com_hikashop/upload/demo-0002-2.png", "ordering": 1, "description": "", "access": { "mode": "all", "groups": [] }, "free_download": false } ], "files": [] }, "meta": null, "error": null } ``` ## The bytes of an image GET /media/content read since 6.6.0 The bytes of one image from the upload folder, so a client can edit it: crop it, rotate it, and send it back. This is the one route that does not answer with the envelope. It answers with the file, and with the cross-origin header that lets a browser read it into a canvas, which the shop's own image URLs do not carry. Without it, a web client cannot export an edited image at all. A path that tries to leave the upload folder is refused rather than resolved. ### Query ParameterTypeDescription pathrequiredstringThe image, relative to the upload folder. ### Response The content of the file requested, with the content type taken from its extension. ### Errors CodeHTTPMeans not\_found404No such file, or a path that tried to leave the upload folder. ## Upload the value of a file field POST /fields/**{table}**/**{namekey}**/file write since 6.6.0 Uploads the file that is the value of one of your own custom fields. Only the two field types that hold one accept it: `ajaximage` and `ajaxfile`. The field is named rather than numbered, and the table says which kind of record it belongs to, so the same route serves a product field, a category field and a customer field. ### Path ParameterTypeDescription tablerequiredstringWhich kind of record: `product`, `category`, `user`, `order`, `address`. namekeyrequiredstringThe field, as `fields\[\].namekey` gives it. ### Body FieldTypeDescription datarequiredstringThe bytes, base64 encoded. namestringThe file name to store it under. ### Response expand all FieldTypeDescription pathstringRelative to the field's own upload folder. This is the value to store on the record. namestringThe file name it was stored under. urlstringAbsolute, where the shop serves it from. ### Errors CodeHTTPMeans not\_found404No such record kind. bad\_field400No such field, or it does not hold a file. bad\_type400The extension is not one this shop accepts. write\_failed500The upload folder refused the file. ``` curl -X POST "$SHOP/hikashop-api/v1/fields/product/test_ajax_image/file" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFAAH/q842iQAAAABJRU5ErkJggg==", "name": "documentation-capture-field.png" }' ``` ``` { "data": { "path": "documentation-capture-field_2.png", "name": "documentation-capture-field_2.png", "url": "http://localhost:8080/joomla6_ext/images/com_hikashop/upload/documentation-capture-field_2.png" }, "meta": null, "error": null } ``` ## The shipping and payment methods an order can move to GET /orders/**{id}**/methods read since 6.6.0 What this order could ship and be paid by, with what it uses now, so a change can be offered as a choice rather than as free text. A method is identified by its plugin and its instance together, written `plugin_id`, which is the pairing the backend posts back. An order that ships from several warehouses carries one method per shipment, and `multiple` says so. ### Path ParameterTypeDescription idrequiredintegerThe order. ### Response expand all FieldTypeDescription shippingobjectThe shipping choice.currentstringWhat the order uses now, as `plugin_id`. `_` when nothing is set, so the current one always matches an option. multiplebooleanTrue when the order ships in several shipments and carries a method for each. optionsobject\[\]What it could move to.valuestringThe `plugin_id` pairing to send when changing the method. labelstringAs the merchant named it. groupsobject\[\]For an order that ships in several shipments, the shipments and the method chosen for each. Empty otherwise. paymentobjectThe payment choice, in the same shape.currentstringWhat the order uses now. multiplebooleanAlways false: an order is paid one way. optionsobject\[\]What it could move to.valuestringThe `plugin_id` pairing to send. labelstringAs the merchant named it. ### Errors CodeHTTPMeans not\_found404No such order, or the operator may not see it. ``` curl "$SHOP/hikashop-api/v1/orders/{id}/methods" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "data": { "shipping": { "current": "manual_1", "multiple": false, "options": [ { "value": "manual_1", "label": "Vendor 2 only shipping" }, { "value": "manual_6", "label": "Test Flat Shipping" }, { "value": "manual_3", "label": "Express Test Flat Rate" }, { "value": "fedextest_2-1", "label": "FedEx TEST - FedEx Ground" } ], "groups": [] }, "payment": { "current": "paypalcheckout_3", "multiple": false, "options": [ { "value": "banktransfer_1", "label": "Bank transfer" }, { "value": "linepay_2", "label": "LINE Pay" }, { "value": "paypalcheckout_3", "label": "PayPal Checkout Express Test" } ] } }, "meta": null, "error": null } ``` ## Make an address the default PUT /customers/**{id}**/addresses/**{aid}**/default write since 6.6.0 Marks one of a customer's addresses as their default, and answers with the customer as it now stands. The default is per kind: an address used for billing becomes the default billing address, and the one it replaces stops being it. Nothing is sent in the body. ### Path ParameterTypeDescription idrequiredintegerThe customer. aidrequiredintegerThe address, from `addresses\[\].id`. ### Response expand all 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. typestring`registered` 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 address, or the operator may not change them. ``` curl -X PUT "$SHOP/hikashop-api/v1/customers/{id}/addresses/{id}/default" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "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": 1786963440, "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": 1785321840, "total": 14.99, "currency_id": 1 }, { "id": 30, "number": "ZBUNDLE", "status": "confirmed", "created": 1784803440, "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 } ``` ## Create a characteristic or one of its values POST /products/characteristics write since 6.6.0 Creates a characteristic, such as Size, or a value of one, such as XL. Send a `name` for a characteristic, or a `value` with the `parent_id` of the characteristic it belongs to. They are the same records at two levels, which is why one route serves both. ### Body FieldTypeDescription namestringThe name of a new characteristic. Give this or `value`. valuestringThe name of a new value, with `parent_id`. parent\_idintegerThe characteristic a value belongs to. ### Response expand all FieldTypeDescription idintegerWhat was created, which is what a variant refers to. valuestringIts name. parent\_idinteger`0` for a characteristic, the characteristic for a value. ### Errors CodeHTTPMeans invalid\_request400Neither a name nor a value was given. save\_failed500The shop refused to save it. ``` curl -X POST "$SHOP/hikashop-api/v1/products/characteristics" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Documentation capture" }' ``` ``` { "data": { "id": 904, "value": "Documentation capture", "parent_id": 0 }, "meta": null, "error": null } ``` ## Create a product category POST /products/categories write since 6.6.0 Creates a category under another, or at the top of the product tree when no parent is given. ### Body FieldTypeDescription namerequiredstringIts name. parent\_idintegerThe category to put it under. Omit for the top of the tree. publishedbooleanDefaults to published. descriptionstringThe long description, as HTML. meta\_descriptionstringSEO description. accessobjectWho may see it. custom\_fieldsobjectYour own category fields, keyed by namekey. ### Response expand all FieldTypeDescription idintegerThe category that was created. namestring parent\_idintegerWhere it sits. publishedboolean ### Errors CodeHTTPMeans invalid\_fields400One of your own fields was rejected by its own rules. save\_failed500The shop refused to save it. ``` curl -X POST "$SHOP/hikashop-api/v1/products/categories" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Documentation capture" }' ``` ``` { "data": { "id": 288, "name": "Documentation capture", "parent_id": 2, "published": true }, "meta": null, "error": null } ``` ## Create a manufacturer POST /products/manufacturers write since 6.6.0 Creates a brand. HikaShop keeps manufacturers in the category tree under their own root, so this takes the same fields as a category and answers the same way. ### Body FieldTypeDescription namerequiredstringThe brand name. parent\_idintegerA manufacturer to nest it under, which most shops do not use. publishedbooleanDefaults to published. descriptionstringThe long description, as HTML. meta\_descriptionstringSEO description. accessobjectWho may see it. custom\_fieldsobjectYour own category fields. ### Response expand all FieldTypeDescription idintegerThe manufacturer that was created, which is what `manufacturer_id` on a product stores. namestring parent\_idintegerIts root. publishedboolean ### Errors CodeHTTPMeans invalid\_fields400One of your own fields was rejected by its own rules. save\_failed500The shop refused to save it. ``` curl -X POST "$SHOP/hikashop-api/v1/products/manufacturers" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Documentation capture brand" }' ``` ``` { "data": { "id": 289, "name": "Documentation capture brand", "parent_id": 10, "published": true }, "meta": null, "error": null } ``` ## Update a category PUT /categories/**{id}** write since 6.6.0 Changes the fields you send and leaves the rest alone. It serves manufacturers and the other trees as well, since they are all categories. ### Path ParameterTypeDescription idrequiredintegerThe category. ### Body Any of `name`, `parent_id`, `published`, `description`, `meta_description`, `access` and `custom_fields`. What you do not send keeps its value. ### Response expand all FieldTypeDescription idstring 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. 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.modestring`all`, `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. ### Errors CodeHTTPMeans not\_found404No such category, or the operator may not change it. invalid\_fields400One of your own fields was rejected by its own rules. ``` curl -X PUT "$SHOP/hikashop-api/v1/categories/{id}" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Shampoo" }' ``` ``` { "data": { "fields": [], "id": 252, "name": "Shampoo", "parent_id": 220, "type": "product", "description": "", "meta_description": "", "published": true, "access": { "mode": "all", "groups": [] }, "image": "http://localhost:8080/joomla6_ext/images/com_hikashop/upload/demo-cat-252.png", "custom_fields": [], "custom_field_files": [] }, "meta": null, "error": null } ``` ## Delete a category DELETE /categories/**{id}** write since 6.6.0 Deletes a category. The products in it are not deleted; they simply stop being in it, and a product left in no category at all disappears from the shop's listings. ### Path ParameterTypeDescription idrequiredintegerThe category. ### Response expand all FieldTypeDescription idintegerThe category that was deleted. deletedbooleanTrue when the row is gone. ### Errors CodeHTTPMeans not\_found404No such category, or the operator may not delete it. ``` curl -X DELETE "$SHOP/hikashop-api/v1/categories/{id}" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "data": { "id": 287, "deleted": true }, "meta": null, "error": null } ``` ## List the entries of the HikaShop log GET /logs read since 6.8.0 The log of System > Logs, newest first: what payment and shipping methods write when their Debug option is on, and the errors HikaShop meets. The data of an entry is left out; `data_size` says how much there is, and `GET /logs/{id}` returns it. Read a payment problem by finding one entry about the order (`order_id`), then listing its `request`: that gives every line the notification wrote, in order. ### Query ParameterTypeDescription startintegerOffset. Defaults to `0`. limitintegerDefaults to `50`, capped at `200`. sourcestringOnly this source. typestring`payment`, `shipping`, `plugin` or `core`. levelstringThis level and the worse ones: `debug`, `info`, `warning` or `error`. order\_idintegerOnly the entries about this order. requeststringOnly the entries one request wrote. sincestringFrom this date: a Unix timestamp, or a date such as `2026-10-01`. untilstringUp to this date; a bare day such as `2026-10-01` is included. searchstringText in the message, the data, the source, the address or the IP. ### Response a list expand all FieldTypeDescription order\_idintegerThe order it is about, `0` when none. A payment plugin records the order it loaded. idinteger createdintegerUnix timestamp of when it was written. levelstring`debug`, `info`, `warning` or `error`. sourcestringWhat wrote it: a plugin name such as `paypal`, or a part of HikaShop such as `mail`. typestring`payment`, `shipping`, `plugin` or `core`. messagestringThe text of the entry, or the beginning of its data when it only had data. user\_idintegerThe user logged in when it was written, `0` for a guest or a call from a server. ipstringIP address of the request. A payment notification comes from the provider's servers. urlstringAddress of the request, with secrets in its query masked. requeststringId shared by every entry one request wrote; filter on it to read a notification from start to end. data\_sizeintegerBytes of data the entry holds beyond its message, `0` when none. ### Envelope meta FieldTypeDescription startintegerEchoes the offset used. limitintegerEchoes the page size used. totalintegerEntries matching the filters, before paging. ``` curl "$SHOP/hikashop-api/v1/logs?limit=2" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "data": [ { "id": 4, "created": 1792671482, "level": "debug", "source": "ups2", "type": "shipping", "message": "Rate request", "order_id": 0, "user_id": 0, "ip": "203.0.113.7", "url": "cli: seed.php", "request": "6356ff9319045d36", "data_size": 16 }, { "id": 2, "created": 1792671482, "level": "info", "source": "paypal", "type": "payment", "message": "Notification refused: bad signature", "order_id": 1, "user_id": 0, "ip": "203.0.113.7", "url": "cli: seed.php", "request": "6356ff9319045d36", "data_size": 0 } ], "meta": { "start": 0, "limit": 2, "total": 3 }, "error": null } ``` ## Read one entry of the HikaShop log with its data GET /logs/**{id}** read since 6.8.0 One entry with everything it holds. Card numbers and security codes, passwords, keys and tokens were masked when it was written; a gateway's own field names can still slip through, so read the data before passing it on. ### Path ParameterTypeDescription idrequiredintegerThe log entry. ### Response expand all FieldTypeDescription idinteger createdintegerUnix timestamp of when it was written. levelstring`debug`, `info`, `warning` or `error`. sourcestringWhat wrote it: a plugin name such as `paypal`, or a part of HikaShop such as `mail`. typestring`payment`, `shipping`, `plugin` or `core`. messagestringThe text of the entry, or the beginning of its data when it only had data. order\_idintegerThe order it is about, `0` when none. A payment plugin records the order it loaded. user\_idintegerThe user logged in when it was written, `0` for a guest or a call from a server. ipstringIP address of the request. A payment notification comes from the provider's servers. urlstringAddress of the request, with secrets in its query masked. requeststringId shared by every entry one request wrote; filter on it to read a notification from start to end. data\_sizeintegerBytes of data the entry holds beyond its message, `0` when none. dataobject\|array\|stringWhat the entry holds beyond its message: the decoded JSON when it was an array or an object, the text otherwise, an empty string when none. ### Errors CodeHTTPMeans not\_found404No such entry. ``` curl "$SHOP/hikashop-api/v1/logs/4" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "data": { "id": 4, "created": 1792671482, "level": "debug", "source": "ups2", "type": "shipping", "message": "Rate request", "order_id": 0, "user_id": 0, "ip": "203.0.113.7", "url": "cli: seed.php", "request": "6356ff9319045d36", "data_size": 16, "data": "rates" }, "meta": null, "error": null } ``` ## Read one discount or coupon GET /discounts/**{id}** read since 6.6.0 One reduction with every restriction it carries. ### Path ParameterTypeDescription idrequiredintegerThe discount or coupon. ### Response expand all FieldTypeDescription idinteger typestring`discount` 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.modestring`all`, `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.modestring`all`, `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. ### Errors CodeHTTPMeans not\_found404No such discount, or the operator may not see it. ``` curl "$SHOP/hikashop-api/v1/discounts/1" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "data": { "id": 1, "type": "coupon", "code": "APPTEST10", "kind": "flat", "value": 10, "currency_id": 1, "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": null, "error": null } ``` ## Create a discount or a coupon POST /discounts write since 6.6.0 Creates a reduction and answers with it as the shop stored it. `type` decides which kind it is: a `coupon` needs a `code`, a `discount` applies by itself. Either way `value` is required, read according to `kind`. ### Body Any field of a discount. `type` and `value` are required, and a coupon also needs a `code`. The restriction lists take ids, and an empty list means no restriction of that kind. ### Response expand all FieldTypeDescription idinteger typestring`discount` 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.modestring`all`, `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.modestring`all`, `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. ### Errors CodeHTTPMeans code\_required400A coupon needs a code. code\_taken400Another coupon already uses that code. value\_required400A reduction needs a value. not\_found404Not reachable when creating: the same handler serves the update, where it means no such discount. save\_failed500The shop refused to save it. ``` curl -X POST "$SHOP/hikashop-api/v1/discounts" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "type": "coupon", "code": "DOCCAPTURE", "kind": "percent", "value": 10 }' ``` ``` { "data": { "id": 492, "type": "coupon", "code": "DOCCAPTURE", "kind": "percent", "value": 10, "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": null, "error": null } ``` ## Update a discount or a coupon PUT /discounts/**{id}** write since 6.6.0 Changes the fields you send and leaves the rest alone, and answers with the reduction as it now stands. ### Path ParameterTypeDescription idrequiredintegerThe discount or coupon. ### Body Any field of a discount. What you do not send keeps its value. A restriction list you do send replaces the one it had. ### Response expand all FieldTypeDescription idinteger typestring`discount` 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.modestring`all`, `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.modestring`all`, `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. ### Errors CodeHTTPMeans not\_found404No such discount, or the operator may not change it. code\_required400A coupon needs a code, so it cannot be cleared on one. code\_taken400Another coupon already uses that code. value\_required400A reduction needs a value. save\_failed500The shop refused to save it. ``` curl -X PUT "$SHOP/hikashop-api/v1/discounts/1" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "kind": "flat", "value": 10 }' ``` ``` { "data": { "id": 1, "type": "coupon", "code": "APPTEST10", "kind": "flat", "value": 10, "currency_id": 1, "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": null, "error": null } ``` ## Delete a discount or a coupon DELETE /discounts/**{id}** write since 6.6.0 Deletes a reduction. Orders that already used it keep the amount they were given: the discount on an order is a figure, not a pointer at this row. ### Path ParameterTypeDescription idrequiredintegerThe discount or coupon. ### Response expand all FieldTypeDescription deletedbooleanTrue when the row is gone. ### Errors CodeHTTPMeans not\_found404No such discount, or the operator may not delete it. ``` curl -X DELETE "$SHOP/hikashop-api/v1/discounts/{id}" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "data": { "deleted": 493 }, "meta": null, "error": null } ``` ## Create a customer POST /customers write since 6.6.0 Creates a customer from an email address and a name, as a guest: no account, no password, nothing for them to log in with. `POST /customers/{id}/account` turns one into a registered customer afterwards. ### Body FieldTypeDescription emailrequiredstringMust not belong to another customer. namestringTheir display name. ### Response expand all FieldTypeDescription idintegerThe customer that was created. ### Errors CodeHTTPMeans email\_taken400Another customer already has that address. save\_failed500The shop refused to save it. ``` curl -X POST "$SHOP/hikashop-api/v1/customers" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "This email address is being protected from spambots. You need JavaScript enabled to view it.", "name": "Alex Marchand" }' ``` ``` { "data": { "id": 5428 }, "meta": null, "error": null } ``` ## Attach a downloadable file POST /products/**{id}**/files write since 6.6.0 The same as attaching an image, for the files a customer downloads after buying. `free_download` decides whether they have to buy it first. ### Path ParameterTypeDescription idrequiredintegerThe product. ### Body FieldTypeDescription datastringThe bytes, base64 encoded. Give this or `path`. pathstringA file already in the upload folder. namestringThe file name to store it under. descriptionstringA note on the file. accessobjectWho may download it. ### Response expand all FieldTypeDescription idinteger namestring pathstringRelative to the upload folder. urlstringAbsolute, ready to display. orderingintegerWhere it sits among the others; the first image is the one the shop shows. descriptionstringThe alt text for an image, or a note on a file. accessobjectWho may see or download it.modestring`all`, `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. free\_downloadbooleanFiles only: whether it can be downloaded without buying the product. ### Errors CodeHTTPMeans not\_found404No such product, or the operator may not change it. bad\_type400The extension is not one this shop accepts. write\_failed500The upload folder refused the file. ``` curl -X POST "$SHOP/hikashop-api/v1/products/{id}/files" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "data": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwvTGVuZ3RoIDMgMCBSL0ZpbHRlci9GbGF0ZURlY29kZT4+CnN0cmVhbQp4nD3HsQ2AMAxE0T5TXA9IjhOSeAAkKmpLLIAoEAWK2F9wQKK5e/qXcMYKUdE4RSxHTXjuvet3D1CNPqBQZmxbKimw5jJUOJyzcSSJifKPZJa5ffwAAP//AwBQSwMEFAAGAAgAAAAhAA==", "name": "documentation-capture.pdf", "description": "A small file" }' ``` ``` { "data": { "id": 8338, "name": "documentation-capture.pdf", "path": "documentation-capture_2.pdf", "url": "", "ordering": 1, "description": "A small file", "access": { "mode": "all", "groups": [] }, "free_download": false }, "meta": null, "error": null } ``` ## A blank address form GET /customers/**{id}**/addresses read since 6.6.0 The address form of a customer: the shop's own address fields, and the values of the address asked for. Without an address id it is a blank form, which is what you draw to add one. The form comes with the values because a shop decides its own address fields, so build from `fields` rather than assuming a shape. ### Path ParameterTypeDescription idrequiredintegerThe customer. ### Response expand all FieldTypeDescription address\_idintegerThe address this form is for, `0` for a new one. typesstring\[\]Which of `billing` and `shipping` it is used for. defaultstring\|nullWhich kind it is the default for, `null` when it is not a default. fieldsobject\[\]The shop's address fields, in display order.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. valuesobjectThe current values, keyed by field namekey. Empty on a blank form. Keyed by whatever address fields this shop has. country\_namestringThe country spelled out, since the value is a zone namekey. state\_namestringThe state spelled out, empty where the country has none. ### Errors CodeHTTPMeans not\_found404No such customer or address, or the operator may not see them. ``` curl "$SHOP/hikashop-api/v1/customers/{id}/addresses" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "data": { "address_id": 0, "types": [ "billing" ], "default": false, "fields": [ { "namekey": "address_title", "type": "singledropdown", "raw_type": "singledropdown", "label": "Title", "default": "", "required": true, "options": [ { "value": "Mr", "label": "Mr", "label_key": "HIKA_TITLE_MR" }, { "value": "Mrs", "label": "Mrs", "label_key": "HIKA_TITLE_MRS" }, { "value": "Miss", "label": "Miss", "label_key": "HIKA_TITLE_MISS" }, { "value": "Ms", "label": "Ms", "label_key": "HIKA_TITLE_MS" }, "… 1 more, trimmed for the example" ], "multiple": false, "translatable": false, "upload_dir": "", "allowed_extensions": "", "date_format": "" }, { "namekey": "address_firstname", "type": "text", "raw_type": "text", "label": "First name", "default": "", "required": true, "options": [], "multiple": false, "translatable": false, "upload_dir": "", "allowed_extensions": "", "date_format": "" }, { "namekey": "address_lastname", "type": "text", "raw_type": "text", "label": "Last name", "default": "", "required": true, "options": [], "multiple": false, "translatable": false, "upload_dir": "", "allowed_extensions": "", "date_format": "" }, { "namekey": "address_company", "type": "text", "raw_type": "text", "label": "Company", "default": "", "required": false, "options": [], "multiple": false, "translatable": false, "upload_dir": "", "allowed_extensions": "", "date_format": "" }, "… 7 more, trimmed for the example" ], "values": { "address_title": "Mr", "address_firstname": "Alex", "address_lastname": "Marchand", "address_company": "Lilas SARL", "address_street": "12 rue des Lilas", "address_post_code": "44000", "address_city": "Nantes", "address_telephone": "+33 2 00 00 00 00", "address_country": "", "address_state": "", "address_vat": "FR00000000000" }, "country_name": "", "state_name": "" }, "meta": null, "error": null } ``` ## An address with its form GET /customers/**{customerId}**/addresses/**{addressId}** read since 6.6.0 The address form of a customer: the shop's own address fields, and the values of the address asked for. Without an address id it is a blank form, which is what you draw to add one. The form comes with the values because a shop decides its own address fields, so build from `fields` rather than assuming a shape. ### Path ParameterTypeDescription customerIdrequiredintegerThe customer. addressIdrequiredintegerThe address. ### Response expand all FieldTypeDescription address\_idintegerThe address this form is for, `0` for a new one. typesstring\[\]Which of `billing` and `shipping` it is used for. defaultstring\|nullWhich kind it is the default for, `null` when it is not a default. fieldsobject\[\]The shop's address fields, in display order.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. valuesobjectThe current values, keyed by field namekey. Empty on a blank form. Keyed by whatever address fields this shop has. country\_namestringThe country spelled out, since the value is a zone namekey. state\_namestringThe state spelled out, empty where the country has none. ### Errors CodeHTTPMeans not\_found404No such customer or address, or the operator may not see them. ``` curl "$SHOP/hikashop-api/v1/customers/{id}/addresses/{id}" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "data": { "address_id": 23, "types": [ "shipping" ], "default": false, "fields": [ { "namekey": "address_title", "type": "singledropdown", "raw_type": "singledropdown", "label": "Title", "default": "", "required": true, "options": [ { "value": "Mr", "label": "Mr", "label_key": "HIKA_TITLE_MR" }, { "value": "Mrs", "label": "Mrs", "label_key": "HIKA_TITLE_MRS" }, { "value": "Miss", "label": "Miss", "label_key": "HIKA_TITLE_MISS" }, { "value": "Ms", "label": "Ms", "label_key": "HIKA_TITLE_MS" }, "… 1 more, trimmed for the example" ], "multiple": false, "translatable": false, "upload_dir": "", "allowed_extensions": "", "date_format": "" }, { "namekey": "address_firstname", "type": "text", "raw_type": "text", "label": "First name", "default": "", "required": true, "options": [], "multiple": false, "translatable": false, "upload_dir": "", "allowed_extensions": "", "date_format": "" }, { "namekey": "address_lastname", "type": "text", "raw_type": "text", "label": "Last name", "default": "", "required": true, "options": [], "multiple": false, "translatable": false, "upload_dir": "", "allowed_extensions": "", "date_format": "" }, { "namekey": "address_company", "type": "text", "raw_type": "text", "label": "Company", "default": "", "required": false, "options": [], "multiple": false, "translatable": false, "upload_dir": "", "allowed_extensions": "", "date_format": "" }, "… 7 more, trimmed for the example" ], "values": { "address_title": "Mr", "address_firstname": "Alex", "address_lastname": "Marchand", "address_company": "Lilas SARL", "address_street": "12 rue des Lilas", "address_post_code": "44000", "address_city": "Nantes", "address_telephone": "+33 2 00 00 00 00", "address_country": "country_France_73", "address_state": "", "address_vat": "FR00000000000" }, "country_name": "France", "state_name": "" }, "meta": null, "error": null } ``` ## Add an address POST /customers/**{id}**/addresses write since 6.6.0 Writes an address of a customer. Without an address id it creates one; with one it saves that one. `types` says what the address is for, billing or shipping or both, and `default` makes it the default for those. An address is validated by the shop's own field rules, so a missing required field is refused rather than half-saved. ### Path ParameterTypeDescription idrequiredintegerThe customer. ### Body FieldTypeDescription fieldsrequiredobjectKeyed by address field namekey, the same keys the form returned in `values`. typesstring\[\]Which of `billing` and `shipping` this address is for. Defaults to both. defaultbooleanMake it the default for its types. ### Response expand all 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. typestring`registered` 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 address, or the operator may not change them. invalid\_fields400A field was rejected by its own rules. invalid\_address400The address is not one the shop will accept, usually a missing required field. ``` curl -X POST "$SHOP/hikashop-api/v1/customers/{id}/addresses" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "fields": { "address_title": "Mr", "address_firstname": "Alex", "address_lastname": "Marchand", "address_street": "12 rue des Lilas", "address_post_code": "44000", "address_city": "Nantes", "address_telephone": "+33 2 00 00 00 00", "address_country": "country_Albania_2", "address_state": "state_Beratit_274" } }' ``` ``` { "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": 4372, "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": 4371, "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": 4387, "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": 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": 4380, "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": 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)" } }, "… 5 more, trimmed for the example" ], "orders": [ { "id": 2, "number": "TEST-VOTE-1", "status": "confirmed", "created": 1786877040, "total": 100, "currency_id": 1 }, { "id": 18, "number": "U18", "status": "confirmed", "created": 1786358640, "total": 14.99, "currency_id": 1 }, { "id": 20, "number": "X20", "status": "confirmed", "created": 1785840240, "total": 14.99, "currency_id": 1 }, { "id": 16, "number": "S16", "status": "created", "created": 1783345950, "total": 14.99, "currency_id": 1 }, "… 96 more, trimmed for the example" ], "fields": [], "custom_fields": [], "custom_field_files": [] }, "meta": null, "error": null } ``` ## Add an address PUT /customers/**{id}**/addresses write since 6.6.0 Writes an address of a customer. Without an address id it creates one; with one it saves that one. `types` says what the address is for, billing or shipping or both, and `default` makes it the default for those. An address is validated by the shop's own field rules, so a missing required field is refused rather than half-saved. ### Path ParameterTypeDescription idrequiredintegerThe customer. ### Body FieldTypeDescription fieldsrequiredobjectKeyed by address field namekey, the same keys the form returned in `values`. typesstring\[\]Which of `billing` and `shipping` this address is for. Defaults to both. defaultbooleanMake it the default for its types. ### Response expand all 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. typestring`registered` 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 address, or the operator may not change them. invalid\_fields400A field was rejected by its own rules. invalid\_address400The address is not one the shop will accept, usually a missing required field. ``` curl -X PUT "$SHOP/hikashop-api/v1/customers/{id}/addresses" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "fields": { "address_title": "Mr", "address_firstname": "Alex", "address_lastname": "Marchand", "address_street": "12 rue des Lilas", "address_post_code": "44000", "address_city": "Nantes", "address_telephone": "+33 2 00 00 00 00", "address_country": "country_Albania_2", "address_state": "state_Beratit_274" } }' ``` ``` { "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": 4372, "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": 4371, "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": 4388, "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": 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": 4387, "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": 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)" } }, "… 6 more, trimmed for the example" ], "orders": [ { "id": 2, "number": "TEST-VOTE-1", "status": "confirmed", "created": 1786877040, "total": 100, "currency_id": 1 }, { "id": 18, "number": "U18", "status": "confirmed", "created": 1786358640, "total": 14.99, "currency_id": 1 }, { "id": 20, "number": "X20", "status": "confirmed", "created": 1785840240, "total": 14.99, "currency_id": 1 }, { "id": 16, "number": "S16", "status": "created", "created": 1783345950, "total": 14.99, "currency_id": 1 }, "… 96 more, trimmed for the example" ], "fields": [], "custom_fields": [], "custom_field_files": [] }, "meta": null, "error": null } ``` ## Save an address POST /customers/**{customerId}**/addresses/**{addressId}** write since 6.6.0 Writes an address of a customer. Without an address id it creates one; with one it saves that one. `types` says what the address is for, billing or shipping or both, and `default` makes it the default for those. An address is validated by the shop's own field rules, so a missing required field is refused rather than half-saved. ### Path ParameterTypeDescription customerIdrequiredintegerThe customer. addressIdrequiredintegerThe address. ### Body FieldTypeDescription fieldsrequiredobjectKeyed by address field namekey, the same keys the form returned in `values`. typesstring\[\]Which of `billing` and `shipping` this address is for. Defaults to both. defaultbooleanMake it the default for its types. ### Response expand all 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. typestring`registered` 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 address, or the operator may not change them. invalid\_fields400A field was rejected by its own rules. invalid\_address400The address is not one the shop will accept, usually a missing required field. ``` curl -X POST "$SHOP/hikashop-api/v1/customers/{id}/addresses/{id}" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "fields": { "address_title": "Mr", "address_firstname": "Alex", "address_lastname": "Marchand", "address_street": "12 rue des Lilas", "address_post_code": "44000", "address_city": "Nantes", "address_telephone": "+33 2 00 00 00 00", "address_country": "country_Albania_2", "address_state": "state_Beratit_274" } }' ``` ``` { "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": 4372, "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": 4371, "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": 4388, "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": 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": 4387, "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": 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)" } }, "… 6 more, trimmed for the example" ], "orders": [ { "id": 2, "number": "TEST-VOTE-1", "status": "confirmed", "created": 1786877040, "total": 100, "currency_id": 1 }, { "id": 18, "number": "U18", "status": "confirmed", "created": 1786358640, "total": 14.99, "currency_id": 1 }, { "id": 20, "number": "X20", "status": "confirmed", "created": 1785840240, "total": 14.99, "currency_id": 1 }, { "id": 16, "number": "S16", "status": "created", "created": 1783345950, "total": 14.99, "currency_id": 1 }, "… 96 more, trimmed for the example" ], "fields": [], "custom_fields": [], "custom_field_files": [] }, "meta": null, "error": null } ``` ## Save an address PUT /customers/**{customerId}**/addresses/**{addressId}** write since 6.6.0 Writes an address of a customer. Without an address id it creates one; with one it saves that one. `types` says what the address is for, billing or shipping or both, and `default` makes it the default for those. An address is validated by the shop's own field rules, so a missing required field is refused rather than half-saved. ### Path ParameterTypeDescription customerIdrequiredintegerThe customer. addressIdrequiredintegerThe address. ### Body FieldTypeDescription fieldsrequiredobjectKeyed by address field namekey, the same keys the form returned in `values`. typesstring\[\]Which of `billing` and `shipping` this address is for. Defaults to both. defaultbooleanMake it the default for its types. ### Response expand all 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. typestring`registered` 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 address, or the operator may not change them. invalid\_fields400A field was rejected by its own rules. invalid\_address400The address is not one the shop will accept, usually a missing required field. ``` curl -X PUT "$SHOP/hikashop-api/v1/customers/{id}/addresses/{id}" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "fields": { "address_title": "Mr", "address_firstname": "Alex", "address_lastname": "Marchand", "address_street": "12 rue des Lilas", "address_post_code": "44000", "address_city": "Nantes", "address_telephone": "+33 2 00 00 00 00", "address_country": "country_Albania_2", "address_state": "state_Beratit_274" } }' ``` ``` { "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": 4372, "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": 4371, "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": 4388, "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": 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": 4387, "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": 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)" } }, "… 6 more, trimmed for the example" ], "orders": [ { "id": 2, "number": "TEST-VOTE-1", "status": "confirmed", "created": 1786877040, "total": 100, "currency_id": 1 }, { "id": 18, "number": "U18", "status": "confirmed", "created": 1786358640, "total": 14.99, "currency_id": 1 }, { "id": 20, "number": "X20", "status": "confirmed", "created": 1785840240, "total": 14.99, "currency_id": 1 }, { "id": 16, "number": "S16", "status": "created", "created": 1783345950, "total": 14.99, "currency_id": 1 }, "… 96 more, trimmed for the example" ], "fields": [], "custom_fields": [], "custom_field_files": [] }, "meta": null, "error": null } ``` ## Delete an address DELETE /customers/**{id}**/addresses write since 6.6.0 Removes an address from a customer. Orders that used it keep their own copy of it. ### Path ParameterTypeDescription idrequiredintegerThe customer. ### Response expand all 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. typestring`registered` 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 address, or the operator may not change them. ``` curl -X DELETE "$SHOP/hikashop-api/v1/customers/{id}/addresses/{id}" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "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": 4372, "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": 4371, "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": 4388, "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": 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": 4387, "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": 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)" } }, "… 6 more, trimmed for the example" ], "orders": [ { "id": 2, "number": "TEST-VOTE-1", "status": "confirmed", "created": 1786877040, "total": 100, "currency_id": 1 }, { "id": 18, "number": "U18", "status": "confirmed", "created": 1786358640, "total": 14.99, "currency_id": 1 }, { "id": 20, "number": "X20", "status": "confirmed", "created": 1785840240, "total": 14.99, "currency_id": 1 }, { "id": 16, "number": "S16", "status": "created", "created": 1783345950, "total": 14.99, "currency_id": 1 }, "… 96 more, trimmed for the example" ], "fields": [], "custom_fields": [], "custom_field_files": [] }, "meta": null, "error": null } ``` ## Delete an address DELETE /customers/**{customerId}**/addresses/**{addressId}** write since 6.6.0 Removes an address from a customer. Orders that used it keep their own copy of it. ### Path ParameterTypeDescription customerIdrequiredintegerThe customer. addressIdrequiredintegerThe address. ### Response expand all 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. typestring`registered` 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 address, or the operator may not change them. ``` curl -X DELETE "$SHOP/hikashop-api/v1/customers/{id}/addresses/{id}" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "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": 4372, "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": 4371, "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": 4388, "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": 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": 4387, "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": 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)" } }, "… 6 more, trimmed for the example" ], "orders": [ { "id": 2, "number": "TEST-VOTE-1", "status": "confirmed", "created": 1786877040, "total": 100, "currency_id": 1 }, { "id": 18, "number": "U18", "status": "confirmed", "created": 1786358640, "total": 14.99, "currency_id": 1 }, { "id": 20, "number": "X20", "status": "confirmed", "created": 1785840240, "total": 14.99, "currency_id": 1 }, { "id": 16, "number": "S16", "status": "created", "created": 1783345950, "total": 14.99, "currency_id": 1 }, "… 96 more, trimmed for the example" ], "fields": [], "custom_fields": [], "custom_field_files": [] }, "meta": null, "error": null } ``` ## Redeem a pairing code POST /pair public since 6.6.0 Exchanges a single-use code, generated in **System > App Devices** of the shop's backend, for the device's own token. This is the only route that answers without one. The token comes back **once**. Only its hash is stored, so a lost token is re-paired, never recovered. Attempts are rate limited per address. ### Body FieldTypeDescription coderequiredstringThe pairing code as shown in the backend. Case and spacing are normalised, so the grouping dash is optional. device\_namestringWhat to call this device in the device list. Defaults to `Device`. platformstringA free label kept for the listing. Anything that is not a letter, a digit, a dash or an underscore is stripped. ### Response expand all FieldTypeDescription tokenstringSend this as the bearer token from now on. It is not retrievable again. scopesstring\[\]`read`, and `write` when the code granted it. device\_idintegerThe row in the device list, which is what you revoke later. ### Errors CodeHTTPMeans invalid\_request400No code was sent. invalid\_code403The code is unknown, already used, or expired. too\_many\_requests429Too many attempts from this address. ``` curl -X POST "$SHOP/hikashop-api/v1/pair" \ -H "Content-Type: application/json" \ -d '{ "device_name": "Counter tablet", "platform": "android", "code": "9CED9F" }' ``` ``` { "data": { "token": "hk_dev_3f9c1a……", "scopes": [ "read", "write" ], "device_id": 129 }, "meta": null, "error": null } ``` ## List products GET /products read since 6.6.0 The catalogue as the backend sees it, unpublished products included, which is what makes this different from the front end. Variants are not listed on their own. A parent carries `has_variants`, and `GET /products/{id}` returns the variants themselves. ### Query ParameterTypeDescription startintegerOffset into the result set. Defaults to `0`. limitintegerPage size. Defaults to `20` and is capped at `100`. searchstringMatches the product name and the product code. idsstringComma separated product ids, to resolve a known set in one call. category\_idintegerRestrict to one category. ### Response a list expand all FieldTypeDescription idinteger namestring codestringThe SKU. Unique within the shop. quantityinteger`-1` when the product does not track stock, which is not the same as `0`. publishedboolean has\_variantsbooleanAsk `GET /products/{id}` for the variants themselves. imagestring\|nullAbsolute URL of the main image, or `null`. pricenumber\|null`null` when the product has no price row at all. currency\_idintegerA row in the shop's currency table, not an ISO code. custom\_fieldsobjectThe listing values of this product, keyed by field namekey. The keys are whatever this shop has configured, so there is no list to give. `fields` in the envelope says what they are. ### Envelope meta FieldTypeDescription startintegerEchoes the offset used. limitintegerEchoes the page size used. totalintegerRows matching the filter, before paging. This is how you know there is another page. fieldsobject\[\]The custom fields shown on listings, so a client can label the values it just received. ``` curl "$SHOP/hikashop-api/v1/products?limit=2" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "data": [ { "id": 8731, "name": "Anodised Film Camera — 35 mm", "code": "DEMO-0073", "quantity": 79, "published": true, "has_variants": false, "image": "http://localhost:8080/joomla6_ext/images/com_hikashop/upload/demo-0073.png", "price": 71.21, "currency_id": 1, "custom_fields": [] }, { "id": 8816, "name": "Anodised Headphones", "code": "DEMO-0133", "quantity": 14, "published": true, "has_variants": false, "image": "http://localhost:8080/joomla6_ext/images/com_hikashop/upload/demo-0133.png", "price": 317.13, "currency_id": 1, "custom_fields": [] } ], "meta": { "start": 0, "limit": 2, "total": 309, "fields": [] }, "error": null } ``` ## List orders GET /orders read since 6.6.0 The orders the operator may see, newest first. It is the listing the app's order screen is built on, so it carries just enough to draw a row and no more; ask for one order when you need the rest. ### Query ParameterTypeDescription startintegerOffset. Defaults to `0`. limitintegerDefaults to `20`, capped at `100`. searchstringMatches the order number and the customer. statusstringA status namekey, as listed by `GET /statuses`. ### Response a list expand all FieldTypeDescription idintegerThe order id, which is what every other order route takes. numberstringThe order number the customer sees, which is not the id. statusstringA namekey, not a label. `GET /statuses` translates it. createdintegerUnix timestamp. totalnumberWhat the customer owes, tax included, in the order currency. currency\_idintegerThe order keeps the currency it was placed in, which need not be the shop default. customerobjectEnough to name the buyer in a list.namestring emailstring custom\_fieldsobjectThe listing values of your own order fields, keyed by namekey. The keys are whatever this shop has configured; `fields` in the envelope says what they are. ### Envelope meta FieldTypeDescription startintegerEchoes the offset used. limitintegerEchoes the page size used. totalintegerOrders matching the filter, before paging. fieldsobject\[\]The definitions behind `custom_fields`. ``` curl "$SHOP/hikashop-api/v1/orders?limit=2" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "data": [ { "id": 2, "number": "TEST-VOTE-1", "status": "confirmed", "created": 1786877040, "total": 100, "currency_id": 1, "customer": { "name": "Admin", "email": "This email address is being protected from spambots. You need JavaScript enabled to view it." }, "custom_fields": [] }, { "id": 18, "number": "U18", "status": "confirmed", "created": 1786358640, "total": 14.99, "currency_id": 1, "customer": { "name": "Admin", "email": "This email address is being protected from spambots. You need JavaScript enabled to view it." }, "custom_fields": [] } ], "meta": { "start": 0, "limit": 2, "total": 640, "fields": [] }, "error": null } ``` ## Read one order GET /orders/**{id}** read since 6.6.0 The whole order: its lines, its totals, its addresses, its history and your own fields. Money is in the currency the order was placed in, which is not necessarily the shop's. Do not convert it: an order is a record of what was agreed at the time. ### Path ParameterTypeDescription idrequiredintegerThe order id. ### Response expand all FieldTypeDescription idinteger numberstringThe number the customer sees. statusstringA namekey. createdintegerUnix timestamp. modifiedintegerUnix timestamp of the last change. currency\_idintegerThe currency the order was placed in. totalsobjectThe figures. See the shape below.totalnumberWhat the customer owes, tax included. discountnumberThe discount applied, as a positive figure already subtracted. shippingnumberThe shipping charged. paymentnumberThe payment fee charged. taxnumberThe tax within the total, not on top of it. customerobjectWho placed it.namestring emailstring payment\_methodstringHow it was paid, as the shop names it. shipping\_methodstringHow it ships. invoice\_numberstringEmpty until an invoice has been issued. invoice\_createdinteger\|nullUnix timestamp of the invoice. itemsobject\[\]The lines: `id`, `name`, `code`, `quantity`, `price`, `tax` and whether the line can still be edited.idintegerThe line id, which is what `PUT /orders/{id}/products/{lineId}` takes. It is not the product id. namestringThe product as it was named when ordered, which may since have changed. codestringIts SKU at the time. quantityinteger pricenumberUnit price, tax excluded, as agreed at the time. taxnumberTax on the line. editablebooleanFalse once the line can no longer be changed, for instance on a shipped order. billing\_addressobject\|nullThe 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\_addressobject\|nullThe same, for delivery. shipping\_address\_overridebooleanWhether the delivery address was set apart from the billing one. historyobject\[\]What has happened to the order, oldest first.statusstringThe namekey it moved to. createdintegerUnix timestamp. typestringWhat caused it: a payment notification, an operator, the shop itself. reasonstringThe note recorded with the change, when there was one. notifiedbooleanWhether the customer was emailed about it. fieldsobject\[\]The definitions of your own order 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. 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. feesobjectThe `discount`, `shipping` and `payment` amounts, which is what `PUT /orders/{id}/fees` writes. discountobjectIts `amount`, its `tax`, the `tax_namekeys` behind that tax, and the coupon `code` when one was used.amountnumberA positive figure, already subtracted from the total. taxnumberThe tax on it. tax\_namekeysstring\[\]Which tax rates that came from. codestringThe coupon code, empty for a discount applied by hand. shippingobjectThe shipping charge and what carried it.amountnumberTax excluded. taxnumberThe tax on it. tax\_namekeysstring\[\]Which tax rates that came from. methodstringThe plugin that handled it. method\_namestringAs the merchant named it. paymentobjectThe payment fee and what took it.amountnumberTax excluded. taxnumberThe tax on it. tax\_namekeysstring\[\]Which tax rates that came from. methodstringThe plugin that took it. method\_namestringAs the merchant named it. tax\_ratesobject\[\]The rates that made up the tax, each with its namekey and rate, so a total can be explained rather than only shown.namekeystringThe tax rate as the shop names it. ratenumberAs a fraction, so `0.1` is ten percent. sectionsobject\[\]Information other plugins show on this record, each with a `key`, a `title` and `rows` (`label`, `value`, and optionally `url`, `badge` and `ref`). Empty when no plugin adds any; on a customer, core adds their paid downloads. See the guide on adding information and settings. extensionsobject\[\]Settings other plugins keep on this record, in groups (`key`, `title`, `fields`), each field described like a custom field plus its current `value`. Send changes back as `extensions` with the record's save. Empty when no plugin adds any. ``` curl "$SHOP/hikashop-api/v1/orders/{id}" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "data": { "id": 5630, "number": "S5630", "status": "confirmed", "created": 1738143180, "modified": 1790620951, "currency_id": 1, "totals": { "total": 313.92, "discount": 0, "shipping": 6.9, "payment": 0, "tax": 0 }, "customer": { "name": "Admin", "email": "This email address is being protected from spambots. You need JavaScript enabled to view it." }, "payment_method": "paypalcheckout", "shipping_method": "manual", "invoice_number": "B5630", "invoice_created": 1738143180, "items": [ { "id": 20630, "name": "Nordic Design item", "code": "SEED-7-44", "quantity": 1, "price": 307.02, "tax": 0, "editable": true }, { "id": 20642, "name": "Test Product (Vendor 2)", "code": "TEST001", "quantity": 1, "price": 0, "tax": 0, "editable": true } ], "billing_address": null, "shipping_address": null, "shipping_address_override": [], "history": [], "fields": [ { "namekey": "hstestfile1755", "type": "ajaxfile", "raw_type": "ajaxfile", "label": "Test attachment", "default": "", "required": false, "options": [], "multiple": false, "translatable": false, "upload_dir": "", "allowed_extensions": "", "date_format": "" }, { "namekey": "hstestfile1859", "type": "ajaxfile", "raw_type": "ajaxfile", "label": "Test attachment", "default": "", "required": false, "options": [], "multiple": false, "translatable": false, "upload_dir": "", "allowed_extensions": "", "date_format": "" }, { "namekey": "hstestfile26994", "type": "ajaxfile", "raw_type": "ajaxfile", "label": "Test attachment", "default": "", "required": false, "options": [], "multiple": false, "translatable": false, "upload_dir": "", "allowed_extensions": "", "date_format": "" }, { "namekey": "hstestfile28016", "type": "ajaxfile", "raw_type": "ajaxfile", "label": "Test attachment", "default": "", "required": false, "options": [], "multiple": false, "translatable": false, "upload_dir": "", "allowed_extensions": "", "date_format": "" }, "… 1 more, trimmed for the example" ], "custom_fields": { "hstestfile1755": null, "hstestfile1859": null, "hstestfile26994": null, "hstestfile28016": null, "hstestfile27610": null }, "custom_field_files": [], "fees": { "discount": { "amount": 0, "tax": 0, "tax_namekeys": [], "code": "" }, "shipping": { "amount": 6.9, "tax": 0, "tax_namekeys": [], "method": "manual", "method_name": "Vendor 2 only shipping" }, "payment": { "amount": 0, "tax": 0, "tax_namekeys": [], "method": "paypalcheckout", "method_name": "PayPal Checkout Express Test" } }, "tax_rates": [ { "namekey": "apptest_vat10", "rate": 0.1 }, { "namekey": "apptest_vat20", "rate": 0.2 }, { "namekey": "gst", "rate": 0.06 }, { "namekey": "recargo 5,2%", "rate": 0.052 }, "… 1 more, trimmed for the example" ], "sections": [], "extensions": [] }, "meta": null, "error": null } ``` ## Set the order fees PUT /orders/**{id}**/fees write since 6.6.0 Replaces the discount, shipping and payment amounts and re-totals the order, so a client does not have to compute a total itself and risk disagreeing with the shop. What you do not send keeps its current value. ### Path ParameterTypeDescription idrequiredintegerThe order id. ### Body FieldTypeDescription feesrequiredobjectAny of `discount`, `shipping` and `payment`, each an object with at least an `amount`, tax excluded. A discount is a positive figure and is subtracted. ### Response expand all FieldTypeDescription idinteger feesobjectThe discount, shipping and payment amounts of the order. discountobjectIts `amount`, its `tax`, the `tax_namekeys` behind that tax, and the coupon `code` when one was used.amountnumberA positive figure, already subtracted from the total. taxnumberThe tax on it. tax\_namekeysstring\[\]Which tax rates that came from. codestringThe coupon code, empty for a discount applied by hand. shippingobjectThe shipping charge and what carried it.amountnumberTax excluded. taxnumberThe tax on it. tax\_namekeysstring\[\]Which tax rates that came from. methodstringThe plugin that handled it. method\_namestringAs the merchant named it. paymentobjectThe payment fee and what took it.amountnumberTax excluded. taxnumberThe tax on it. tax\_namekeysstring\[\]Which tax rates that came from. methodstringThe plugin that took it. method\_namestringAs the merchant named it. totalsobjectThe order totalled, so a client need not compute it and disagree with the shop.totalnumberWhat the customer owes, tax included. discountnumberThe discount applied, as a positive figure already subtracted. shippingnumberThe shipping charged. paymentnumberThe payment fee charged. taxnumberThe tax within the total, not on top of it. ### Errors CodeHTTPMeans not\_found404No such order, or the operator may not change it. save\_failed500The order could not be saved. ``` curl -X PUT "$SHOP/hikashop-api/v1/orders/{id}/fees" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "fees": { "shipping": { "amount": 4.9 } } }' ``` ``` { "data": { "id": 5630, "fees": { "discount": { "amount": 0, "tax": 0, "tax_namekeys": [], "code": "" }, "shipping": { "amount": 4.9, "tax": 0, "tax_namekeys": [], "method": "manual", "method_name": "Vendor 2 only shipping" }, "payment": { "amount": 0, "tax": 0, "tax_namekeys": [], "method": "paypalcheckout", "method_name": "PayPal Checkout Express Test" } }, "totals": { "total": 311.92, "discount": 0, "shipping": 4.9, "payment": 0, "tax": 0 } }, "meta": null, "error": null } ``` ## An address of an order, with its form GET /orders/**{id}**/address/**{type}** read since 6.6.0 The billing or shipping address of an order, together with the form the shop would use to edit it. The form is sent with the values because a shop decides its own address fields: which exist, which are required, and in what order. Build the form from `fields` rather than assuming a shape, and `PUT` the same keys back. ### Path ParameterTypeDescription idrequiredintegerThe order id. typerequiredstring`billing` or `shipping`. ### Response expand all FieldTypeDescription typestringWhich address this is. address\_idintegerThe address row, `0` when the order has none of that kind. fieldsobject\[\]The shop's address fields, in display order.namekeystringThe key to send the value back under. typestringWhat to render: `text`, `zone`, `singledropdown`, 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 the address without it. optionsobject\[\]The choices, for a field that has them. A country or a state is filled from the zones rather than from here.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. translatablebooleanNot meaningful on an address, where values are the customer's own words. upload\_dirstringUnused on an address field. allowed\_extensionsstringUnused on an address field. date\_formatstringFor a date field, the format it is stored in. valuesobjectThe current values, keyed by field namekey. Keyed by whatever address fields this shop has. country\_namestringThe country spelled out, since the value itself is a zone id. state\_namestringThe state spelled out, empty where the country has none. ### Errors CodeHTTPMeans not\_found404No such order, or the operator may not see it. ``` curl "$SHOP/hikashop-api/v1/orders/{id}/address/billing" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "data": { "type": "billing", "address_id": 19, "fields": [ { "namekey": "address_title", "type": "singledropdown", "raw_type": "singledropdown", "label": "Title", "default": "", "required": true, "options": [ { "value": "Mr", "label": "Mr", "label_key": "HIKA_TITLE_MR" }, { "value": "Mrs", "label": "Mrs", "label_key": "HIKA_TITLE_MRS" }, { "value": "Miss", "label": "Miss", "label_key": "HIKA_TITLE_MISS" }, { "value": "Ms", "label": "Ms", "label_key": "HIKA_TITLE_MS" }, "… 1 more, trimmed for the example" ], "multiple": false, "translatable": false, "upload_dir": "", "allowed_extensions": "", "date_format": "" }, { "namekey": "address_firstname", "type": "text", "raw_type": "text", "label": "First name", "default": "", "required": true, "options": [], "multiple": false, "translatable": false, "upload_dir": "", "allowed_extensions": "", "date_format": "" }, { "namekey": "address_lastname", "type": "text", "raw_type": "text", "label": "Last name", "default": "", "required": true, "options": [], "multiple": false, "translatable": false, "upload_dir": "", "allowed_extensions": "", "date_format": "" }, { "namekey": "address_company", "type": "text", "raw_type": "text", "label": "Company", "default": "", "required": false, "options": [], "multiple": false, "translatable": false, "upload_dir": "", "allowed_extensions": "", "date_format": "" }, "… 7 more, trimmed for the example" ], "values": { "address_title": "Mr", "address_firstname": "Alex", "address_lastname": "Marchand", "address_company": "Lilas SARL", "address_street": "12 rue des Lilas", "address_post_code": "44000", "address_city": "Nantes", "address_telephone": "+33 2 00 00 00 00", "address_country": "", "address_state": "", "address_vat": "FR00000000000" }, "country_name": "", "state_name": "" }, "meta": null, "error": null } ``` ## The coupons that can be applied GET /coupons read since 6.6.0 The shop's published coupons, so an operator can pick one rather than remember a code. Applying it is a separate call, and the shop validates it again there: a coupon listed here can still be refused for this particular order. ### Response a list expand all FieldTypeDescription idinteger codestringWhat the customer would type. This is what you send to apply it. flat\_amountnumberA fixed reduction, `0` when the coupon is a percentage. percent\_amountnumberA percentage reduction, `0` when the coupon is a fixed amount. currency\_idintegerThe currency a flat amount is expressed in. startinteger\|nullUnix timestamp before which it is not valid. endinteger\|nullUnix timestamp after which it expires. quotaintegerHow many times it may be used in total, `0` for no limit. used\_timesintegerHow many times it already has been. minimum\_ordernumberThe order total below which it does not apply, `0` for none. ``` curl "$SHOP/hikashop-api/v1/coupons" \ -H "Authorization: Bearer $TOKEN" ``` ``` { "data": [ { "id": 1, "code": "APPTEST10", "flat_amount": 10, "percent_amount": 0, "currency_id": 1, "start": 0, "end": 0, "quota": 0, "used_times": 0, "minimum_order": 0 }, { "id": 2, "code": "APPTEST20PCT", "flat_amount": 0, "percent_amount": 20, "currency_id": 1, "start": 0, "end": 0, "quota": 0, "used_times": 0, "minimum_order": 0 }, { "id": 432, "code": "E2E1786215715618", "flat_amount": 0, "percent_amount": 12, "currency_id": 0, "start": 0, "end": 0, "quota": 0, "used_times": 0, "minimum_order": 0 }, { "id": 434, "code": "E2E1786215747620", "flat_amount": 0, "percent_amount": 12, "currency_id": 0, "start": 0, "end": 0, "quota": 0, "used_times": 0, "minimum_order": 0 } ], "meta": null, "error": null } ``` ## Change an order's status POST /orders/**{id}**/status write since 6.6.0 Moves the order and, when asked, sends the customer the same notification the backend would have sent. This calls the same code the backend does, so stock, invoices and every plugin listening on a status change behave exactly as they do there. It is not a database update. ### Path ParameterTypeDescription idrequiredintegerThe order id. ### Body FieldTypeDescription statusrequiredstringA status \*\*namekey\*\*, as listed by `GET /statuses`. Not the translated label. notifybooleanSend the customer the notification for the new status. Defaults to `false`. reasonstringRecorded in the order history, and included in the notification when there is one. ### Response expand all FieldTypeDescription idintegerThe order id. statusstringThe namekey the order now has. changedbooleanFalse when the order already had that status. notifiedbooleanWhether the customer was actually emailed, which can be false even when you asked, if the status has no notification configured. ### Errors CodeHTTPMeans invalid\_status400No such status namekey on this shop. not\_found404No such order, or the operator may not see it. save\_failed500The order could not be saved. ``` curl -X POST "$SHOP/hikashop-api/v1/orders/{id}/status" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "status": "confirmed", "notify": false, "reason": "Documentation capture" }' ``` ``` { "data": { "id": 5626, "status": "confirmed", "changed": true, "notified": false }, "meta": null, "error": null } ``` ## [ Customize the display ](/support/documentation/153-customize-the-display) Details Written by: Xavier Category: [Developer area](/support/documentation/hikashop/developer-area) Published: 30 January 2013 Hits: 149052 | - [Description](#description) - [Where to add custom CSS](#where_to_css) - [How to find the CSS to change](#css) - [Responsive Customization](#responsive) - [Changing Text Labels](#labels) - [Layout customization](#layout) - [View Builder](#view_builder) | ![](/images/icon_doc/icon_display_180.png) | |---|---| ### Description This tutorial will explain how to find the elements you want to customize and how to customize them. If you need to change the CSS properties of an element, then you have to follow the CSS Edition part. For additional information about the most common changes please see our FAQ: [Here](/support/faq.html#styl "FAQ CSS") To move an element in the page, or add something in it, follow the Layout customizations part. For additional information about the most common changes please see our FAQ: [Here](/support/faq.html#layo "FAQ Layout") ### Where to add custom CSS There are several ways to add custom CSS to your website. While HikaShop provides its own mechanism, **we recommend using your Joomla template's custom CSS facility** whenever possible. Centralizing all your site-wide styling in one location makes maintenance much easier and ensures consistency. **1. Joomla Template (Recommended)** Most modern Joomla templates provide a dedicated way to add custom CSS without modifying the theme's core files: - **Cassiopeia (Default Joomla Template):** Use the `user.css` file. [View Guide](https://guide.joomla.org/user-manual/templates/templates-cassiopeia-template-customisation) - **Helix Ultimate:** Create a `custom.css` file in the `/css` folder of your template or use the `Custom Code` tab in the Template Options. [View Guide](https://www.joomshaper.com/documentation/helix-framework/helix-ultimate-2/custom-code-css-js-meta) - **Gantry 5:** Create a `custom.scss` file in the `/custom/scss/` folder of your template. [View Guide](https://docs.gantry.org/gantry5/tutorials/adding-a-custom-style-sheet) - **Astroid Framework:** Create a `custom.css` file in the `/css` folder or use the `Custom Code` tab in the Template Options. [View Guide](https://docs.astroidframe.work/user-manual/custom-code) - **T4 Framework:** T4 templates allow adding custom CSS/SCSS through the template settings. [View Guide](https://www.joomlart.com/documentation/t4-framework/css-scss-customization) - **YOOtheme Pro:** For more advanced styling, Child Themes can be used. [View Guide](https://yootheme.com/support/yootheme-pro/joomla/developers-child-themes#less-styles) - **Custom CSS Plugins:** If your template doesn't offer an easy way, you can use a dedicated custom CSS plugin. [View Guide](https://www.joomlashack.com/blog/joomla/custom-css/) **2. HikaShop Configuration** If you prefer to keep HikaShop-specific styles separate or if your template doesn't support custom CSS, you can use the HikaShop settings: In **System > Configuration > Display > CSS**, you can edit the "Styles for frontend" file. Add your custom CSS code at the end of this file. This ensures your custom code overrides the default styles and remains safe during updates. ![add CSS code in HikaShop's configuration page](/images/stories/doc_display_3.png) ### How to find the CSS to change To change the size and the color of an element (like the price on a product listing), you first need to identify the element's distinct class or ID. You can do this using your browser's developer tools (often accessible by pressing **F12**). ![](/images/stories/doc_display_1.png) Right-click on the element you want to customize and choose "Inspect" or "Inspect element". A panel will open displaying the HTML structure. Look for the `class="..."` or `id="..."` attributes of the element. ![add CSS code in HikaShop's configuration page](/images/stories/doc_display_2.png) For instance, the price usually has the class "hikashop\_product\_price". ### Common CSS Examples **1. Change price color and size:** ``` .hikashop_product_price { color: #99cc00; font-size: 18px; } ``` **2. Hide the price:** ``` .hikashop_product_price { display: none; } ``` **3. Customize the "Add to cart" button:** ``` .hikashop_cart_input_button { background-color: #333333; /* Dark background */ color: #ffffff; /* White text */ border-radius: 5px; /* Rounded corners */ border: none; padding: 10px 20px; } .hikashop_cart_input_button:hover { background-color: #555555; /* Lighter background on hover */ } ``` **4. Target a specific module only:** If you want to apply changes only to a specific module, prepend the module's ID. ``` #module_25 .hikashop_product_price { color: #ff0000; } ``` (Replace `#module_25` with the actual ID of your module). To learn more about CSS, you can visit these websites: - - - **Pro-Tip: My CSS is not applied!** If your custom CSS isn't working, it's often due to **CSS Specificity** (priority). Try making your selector more specific by adding a parent ID, for example: `#hikashop_checkout_content .hikashop_product_price { color: red; }`. As a last resort, you can use `!important`. ### Responsive Customization HikaShop is natively responsive, but you might want to adjust the display for specific screen sizes using **CSS Media Queries**. This allows you to hide elements on mobile or change your layout for different devices. **Example: Hide the product description on mobile** ``` @media (max-width: 480px) { .hikashop_product_description_main { display: none; } } ``` **Example: Change font size only on tablets** ``` @media (min-width: 481px) and (max-width: 1024px) { .hikashop_product_name { font-size: 1.5em; } } ``` ### Changing Text Labels (Language Overrides) Customizing the display often involves changing text labels like "Add to cart" or "VAT". Instead of editing HikaShop core files, you should use Language Overrides. This ensures your changes are preserved during updates. For more details on how to do this, please see our [Language Overrides Guide](https://www.hikashop.com/download/languages.html#modify). ### Common HikaShop CSS Classes Here are some of the most common classes you might want to target for customization: | Class Name | Description | |---|---| | `.hikashop_product_name` | The title/name of the product on listings and details. | | `.hikashop_product_price` | The area where the price is displayed. | | `.hikashop_product_description_main` | The main description of the product. | | `.hikashop_cart_input_button` | The main "Add to cart" button. | | `.hikashop_product_stock` | The stock level/availability information. | | `.hikashop_product_image_main` | The main image container for a product. | ### Layout customizations To go further with customization, you can override the view files of HikaShop via the menu Display>Views. We highly recommend that you edit the view files of HikaShop via that menu as explained below and not directly. That way, you won't lose your changes when updating your HikaShop. Note that since Joomla 3, you can also go in the override section of the Joomla template manager to create overrides. Either way, the overrides can be edited on both interfaces as they are compatible between one another. Similarly to when you're using the view override mechanism in HikaShop, when using the template manager, the files are also stored in `templates/[YOUR_TEMPLATE]/html/com_hikashop/`. To know which view you have to edit, just set the ["Display view files"](/support/documentation/54-hikashop-config.html#advanced_main) setting to "all" under the "Advanced" tab of the HikaShop configuration. This will add dashed borders around each view file used with the name of the view file used on the top left corner of the view file. It will have 2 parts separated by a /. The left part will be the view name and the right part will be the file name so you'll be able to easily find what you need to edit. ![](/images/stories/doc_display_4.png) **Note:** Since HikaShop 6.3.0, enabling "Display view files" also adds an edit icon next to the view names on the frontend, allowing for quick access to the view editor. ### View Builder HikaShop includes a **"view builder"** system which allows you to move, swap or delete different elements in most of the frontend views without needing deep HTML or PHP knowledge. When a view supports drag & drop, a "view builder" area will appear on top of the code editor. This editor will dynamically modify the code below as you drag and drop elements. Once finished, just save your changes to validate them. The View Builder experience has been refined with a cleaner interface and auto-scroll support when dragging elements. Developers and integrators will also appreciate a new workflow improvement: when the "Display view files" setting is activated, an edit icon now appears next to the view file names on the frontend. Clicking it opens a popup with the view edit form immediately, saving you from searching for the specific view file in the backend. ![HikaShop View Builder Interface](/images/blog/hikashop-6-3-0/new_view_builder_interface.png) In the edition page, you can also find all the different parts between the HTML comments. <!-- ... --> ![](/images/stories/doc_display_5.png) Now you just have to cut and paste the part for the product name before the product image part. And "voilà" you have moved the name before the picture of the product. **Listing types:** By checking the following tab you'll be able to know which file to edit via "Hikashop->Display->Views" regarding the value of the "Type of layout" and "Type of item layout" options. ![](/images/stories/listing_types2.png) **Product page customization:** By checking the following picture you'll be able to know which file to edit via "Hikashop->Display->Views" regarding what you exactly want to change on product page. ![](/images/stories/Product_customization.jpg) To change the cart module display, you have to edit the view "product / cart". If you want to customize the emails, you have to go in HikaShop > System > Emails, only available in the business edition of HikaShop. If you need more customizations, it requires HTML and probably PHP skills. If you don't have enough knowledge you can learn these programming languages on the web. You can also post a request on the Commercial Jobs section of our forum if you need to find a third party developer to help you personalize HikaShop if you don't know PHP. ## [ Developer documentation ](/support/documentation/62-hikashop-developer-documentation) Details Written by: Administrator Category: [Developer area](/support/documentation/hikashop/developer-area) Published: 10 September 2010 Hits: 242108 Dear developer, HikaShop runs on both Joomla and WordPress. Its plugin system is built on top of each CMS's native extension mechanism, allowing you to extend the shop's functionality with custom plugins. ## HikaShop Developer Documentation HikaShop provides a powerful plugin system. On Joomla, HikaShop plugins are standard Joomla plugins. On WordPress, they are WordPress plugins that register HikaShop event hooks. HikaShop events are triggered when certain actions are performed (order creation, product deletion, etc.). To use these events, you need to create a plugin of the group "hikashop", "hikashoppayment" or "hikashopshipping". This document explains the available events, the HikaShop API, and providing code samples for common tasks. ### Summary - Plugin system - [How to create a HikaShop plugin](#howto) - [Input handling with hikaInput](#input-handling) - [How to create a HikaShop Payment plugin](#howtopayment) - [How to create a HikaShop Shipping plugin](#howtoshipping) - HikaShop API - [Order API](#order) - [Product API](#product) - [Category API](#category) - [Address API](#address) - [Shipping API](#shipping) - [Payment API](#payment) - [UCP (Universal Commerce Protocol)](#ucp) - [WebMCP (AI agents in the browser)](#webmcp) - [Vote API](#vote) - [Cart API](#cart) - [View API](#views) - [Discount/Coupon API](#discount) - [User API](#user) - [Field API](#fields) - [Order Status API](#orderstatus) - [Filter API](#filter) - [Currency and Taxation API](#currency) - [Waitlist API](#waitlist) - [File API](#file) - [Email API](#email) - [Configuration API](#config) - [Massaction API](#massaction) - [Dashboard API](#dashboard) - [Other Events](#other) - [Assets Management](#assets) - [Main Objects](#objects) - [Database Structure](#db) - [PHP code samples](#code) - [Overrides](#override) - [View Overrides](#view-overrides) - [Plugin View Overrides](#plugin-overrides) - [Class Overrides](#class-overrides) - [Javascript events](#js) The first thing you have to do is to create a plugin. The group will be "**hikashop**" unless you create a payment or shipping plugin, in which case it will be "**hikashoppayment**" or "**hikashopshipping**" respectively. **On Joomla**, HikaShop plugins are standard Joomla plugins. We recommend that you first learn how to create Joomla plugins: [Joomla Plugin Development Documentation](https://manual.joomla.org/docs/building-extensions/plugins/basic-content-plugin/) **On WordPress**, HikaShop plugins are standard WordPress plugins. The HikaShop compatibility layer translates WordPress hooks into HikaShop events, so the same plugin code works on both platforms when you extend the `hikashopPlugin` class. ### How to create a HikaShop plugin When you create a plugin for HikaShop, while you can extend `JPlugin` (or `\Joomla\CMS\Plugin\CMSPlugin` on modern Joomla), we highly recommend extending the **`hikashopPlugin`** class. The `hikashopPlugin` class provides a compatibility bridge across Joomla 3, 4, 5, 6 and WordPress, and includes several useful helper methods: - `showPage($name)`: Renders a specific plugin view file, supporting template overrides (e.g., `$this->showPage('thanks')` will look for `yourplugin_thanks.php`). - `listPlugins($name, &$values)`: Helps list all instances of a plugin type. #### Input Handling with `hikaInput` To ensure your plugin works across all Joomla versions and WordPress (where `JRequest` is deprecated and input handling varies), we recommend using the **`hikaInput`** class provided by HikaShop: ``` $input = hikaInput::get(); $myValue = $input->get('my_param', 'default_value', 'string'); ``` **Multiple instances:** You can allow a plugin to have several instances (each with its own configuration) by setting `public $multiple = true;`. You then define the configuration fields in the `public $pluginConfig` array. For each field, you specify a label, a type (e.g., 'boolean', 'category', 'list', 'text'), and optional parameters or default values. This is useful for plugins that need different settings for different scenarios, like the **Shop Close Hours** plugin (`plg_hikashop_shopclosehours`). The `hikashopPlugin` class automatically handles the display and saving of these parameters for each instance. In your plugin, simply create functions matches the names of the events you want to handle. Here is an example using two events: `onBeforeOrderCreate` and `onAfterOrderCreate`. By extending `hikashopPlugin`, the database object `$this->db` is automatically initialized. ``` class plgHikashopName extends hikashopPlugin { function __construct(&$subject, $config){ parent::__construct($subject, $config); } function onBeforeOrderCreate(&$order, &$do){ /* code to be executed before the order is created */ } function onAfterOrderCreate(&$order){ /* code to be executed after the order is created */ } } ``` All events have different parameters. You can find the list of events below. Marc Studer also developed a helpful plugin to see which HikaShop event is triggered on each page: [hikashop\_dump\_events on GitHub](https://github.com/garstud/hikashop_dump_events). #### What your method returns Most events ignore what your method returns, and you change things through the parameters you are given by reference. A few collect the return values instead, and hand the caller the list of everything the listening plugins returned. - Returning `null`, which is what a method with no `return` does, is the same as not listening at all. Both platforms drop it before the list is built, so HikaShop cannot tell the two apart. - To say "I handled this", either return a value the event documents, or set a parameter passed by reference for that purpose. `onHikashopUploadStoreFile` takes the first road and looks for a literal `true` among the returns; `onBeforeVATOnlineCheck` takes the second and gives you a `$processed` to set. - Returning `false` is a real answer and reaches the list. Only `null` disappears. We recommend studying the **HikaShop Email history plugin** (`/plugins/hikashop/email_history/`), as it is one of the simplest examples for understanding the HikaShop plugin structure. Its goal is to store all emails sent to customers in a database table and display them in a list in the admin panel. ### How to create a HikaShop Payment plugin First, we invite you to read the information on the [Payment API](#payment) section. Then, you can go to the [Example Payment Plugin GitHub](https://github.com/hikashop-nicolas/plg_hikashoppayment_example) and look at the files. Each line of the plugin is documented, explaining how a payment plugin should be structured. It's an excellent base if you are a developer but have never integrated a payment gateway before. You can also study the source code of payment plugins included in HikaShop by exploring the `/plugins/hikashoppayment/` folder of your installation. ### How to create a HikaShop Shipping plugin First, we invite you to read the information on the [Shipping API](#shipping) section. Then, you can go to the [Example Shipping Plugin GitHub](https://github.com/hikashop-nicolas/plg_hikashopshipping_example) and look at the files. Each line of the plugin is documented, explaining how a shipping plugin should be structured. It covers advanced topics like multiple packages, custom HTML selection, and automated carrier export. You can also study the source code of shipping plugins included in HikaShop by exploring the `/plugins/hikashopshipping/` folder of your installation. ### Order API Available events for the Order API: > - [onBeforeOrderCreate(&$order, &$do)](#onBeforeOrderCreate) > - [onBeforeOrderUpdate(&$order, &$do)](#onBeforeOrderUpdate) > - [onBeforeOrderDelete(&$elements, &$do)](#onBeforeOrderDelete) > - [onAfterOrderCreate(&$order, &$send\_email)](#onAfterOrderCreate) > - [onAfterOrderConfirm(&$order, &$methods, $method\_id)](#onAfterOrderConfirm) > - [onAfterOrderUpdate(&$order, &$send\_email)](#onAfterOrderUpdate) > - [onAfterOrderDelete($elements)](#onAfterOrderDelete) > - [onAfterInvoiceCreate(&$order)](#onAfterInvoiceCreate) > - [onHistoryDisplay(&$history)](#onHistoryDisplay) > - [onBeforeOrderExport(&$rows, &$this)](#onBeforeOrderExport) > - [onBeforeOrderNumberGenerate(&$data, &$result)](#onBeforeOrderNumberGenerate) > - [onBeforeInvoiceNumberGenerate(&$data, &$result)](#onBeforeInvoiceNumberGenerate) > - [onBeforeOrderProductsUpdate(&$order, &$do)](#onBeforeOrderProductsUpdate) > - [onBeforeOrderPaymentCapture(&$order, $order\_full\_price, &$order\_capture\_price, &$do)](#onBeforeOrderPaymentCapture) > - [onBeforeOrderListing($paramBase, &$extrafilters, &$pageInfo, &$filters, &$tables, &$searchMap, &$select)](#onBeforeOrderListing) > - [onBeforeCalculateProductPriceForQuantityInOrder(&$orderProduct)](#onBeforeCalculateProductPriceForQuantityInOrder) > - [onAfterCalculateProductPriceForQuantityInOrder(&$orderProduct)](#onAfterCalculateProductPriceForQuantityInOrder) > - [onAfterLoadFullOrder(&$order)](#onAfterLoadFullOrder) > - [onAfterOrderListing(&$rows, &$extrafields, $pageInfo)](#onAfterOrderListing) > - [onBeforeModifyOrder(&$order, &$order\_status, &$history, &$email)](#onBeforeModifyOrder) > - [onBeforeCreateRecurringSuborder($order\_id, &$order)](#onBeforeCreateRecurringSuborder) > - [onBeforeOrderExportQuery(&$filters, $paramBase)](#onBeforeOrderExportQuery) > - [onBeforeFrontendOrderListing($paramBase, &$pageInfo, &$filters, &$searchMap)](#onBeforeFrontendOrderListing) > - [onHikashopOrderTrackingDisplay($order)](#onHikashopOrderTrackingDisplay) > - [onHikashopThankYouDisplay(&$order, &$blocks)](#onHikashopThankYouDisplay) Functions are called if they exist; you don't have to define them all. These functions are triggered by HikaShop when an order is saved or deleted. The cron task is only available on commercial versions of HikaShop. #### onBeforeOrderCreate(&$order, &$do) Triggered before a new order is saved. The `$order` object contains the full order data. Setting `$do` to `false` cancels the order creation. - `&$order`: The order object. - `&$do`: A boolean. Set it to `false` to cancel the order creation. #### onBeforeOrderUpdate(&$order, &$do) Triggered before an existing order is updated. The `$order` object contains the updated information. Setting `$do` to `false` cancels the update. - `&$order`: The order object. - `&$do`: A boolean. Set it to `false` to cancel the update. #### onBeforeOrderDelete(&$elements, &$do) Triggered before one or several orders are deleted. `$elements` is an array of order IDs. Setting `$do` to `false` cancels the deletion. - `&$elements`: An array of order IDs to be deleted. - `&$do`: A boolean. Set it to `false` to cancel the deletion. #### onAfterOrderCreate(&$order, &$send\_email) Triggered after an order is successfully created. The `$order` object contains the full order data. Setting `$send_email` to `false` prevents the customer notification email. - `&$order`: The order object. - `&$send_email`: A boolean. Set it to `false` to prevent the customer notification email. #### onAfterOrderConfirm This event belongs to the payment plugin of the method the customer chose. It is documented with the other payment events, under [the Payment API](#onAfterOrderConfirm). #### onAfterOrderUpdate(&$order, &$send\_email) Triggered after an order is updated. The `$order` object contains the updated information. Setting `$send_email` to `false` prevents the status change notification email. - `&$order`: The order object. - `&$send_email`: A boolean. Set it to `false` to prevent the status change notification email. #### onAfterOrderDelete($elements) Triggered after one or several orders are deleted. `$elements` is either a single ID or an array of order IDs. - `$elements`: A single order ID or an array of order IDs. #### onAfterInvoiceCreate(&$order) Triggered after an invoice is generated for an order. This usually happens when the order status changes to "confirmed" or "shipped". #### onAfterLoadFullOrder(&$order) Triggered after an order is fully loaded from the database, including its products, addresses, and history. `$order` is the complete order object. This is a good place to add custom fields or other data to the order object, or to modify the order object before it is used. - `&$order`: The complete order object. #### onBeforeOrderProductsUpdate(&$order, &$do) Triggered before the products of an order are updated in the database (e.g., when editing an order in the backend). - `&$order`: The order object containing the modified `product` array. - `&$do`: A boolean. Set it to `false` to cancel the products update. #### onHistoryDisplay(&$history) Triggered when the history of an order is displayed in the backend. You can use it to modify the `$history` object before display. #### onBeforeOrderExport(&$rows, &$obj) Triggered before orders are exported. `$rows` contains the array of order objects to be exported. #### onBeforeOrderNumberGenerate(&$data, &$result) Triggered during order creation to generate the order number. `$data` contains the order attributes. You can set a custom order number in `$result` to override the default HikaShop format. #### onBeforeInvoiceNumberGenerate(&$data, &$result) Triggered when an invoice number is generated. `$data` contains the order attributes. Set custom text in `$result` to override the default invoice number format. #### onBeforeOrderPaymentCapture(&$order, $order\_full\_price, &$order\_capture\_price, &$do) Triggered before a payment capture is processed (for payment methods supporting authorization/capture). - `&$order`: The order object. - `$order_full_price`: The total amount of the order. - `&$order_capture_price`: The amount to be captured. You can modify this value. - `&$do`: A boolean. Set it to `false` to cancel the capture. #### onBeforeOrderListing($paramBase, &$extrafilters, &$pageInfo, &$filters, &$tables, &$searchMap, &$select) Triggered before running the database query to load orders in the backend. You can modify the query (adding conditions, joins, etc.) or add custom filters to the listing. To add a custom filter, register your plugin in the `$extrafilters` array and implement a `displayFilter` function. ``` class plgHikashopName extends JPlugin { function onBeforeOrderListing($paramBase, &$extrafilters, &$pageInfo, &$filters, &$tables, &$searchMap, &$select) { // Register for extra filter display $extrafilters['my_extra_filter'] = $this; $app = JFactory::getApplication(); $pageInfo->filter->filter_order_published = $app->getUserStateFromRequest($paramBase.".filter_order_published", 'filter_order_published', 1, 'int'); if(!empty($pageInfo->filter->filter_order_published)) { $filters[] = 'b.order_published = ' . (int)$pageInfo->filter->filter_order_published; } } function displayFilter($name, $info) { if($name == 'my_extra_filter') { $values = array( JHTML::_('select.option', '0', JText::_('HIKA_ALL')), JHTML::_('select.option', '1', JText::_('HIKA_PUBLISHED')), JHTML::_('select.option', '-1', JText::_('HIKA_UNPUBLISHED')), ); return JHTML::_('select.genericlist', $values, 'filter_order_published', 'onchange="document.adminForm.submit();"', 'value', 'text', @$info->filter_order_published, 'order_published'); } } } ``` You can refer to the [Orders Product Filter](https://www.hikashop.com/marketplace/product/272-orders-product-filter.html) plugin for a complete example. #### onBeforeCalculateProductPriceForQuantityInOrder(&$orderProduct) Triggered during order creation before calculating the total price of a product in the order. `$orderProduct` contains the product details and its unit price. - `&$orderProduct`: The order product object. #### onAfterCalculateProductPriceForQuantityInOrder(&$orderProduct) Triggered after calculating the total price of a product in the order. You can use it to override the `order_product_total_price` and `order_product_total_price_no_vat` values. - `&$orderProduct`: The order product object. #### onAfterOrderListing(&$rows, &$extrafields, $pageInfo) Triggered once the order listing of your backend has loaded its orders, so that you can add your own column to it. - `&$rows`: The orders being displayed. - `&$extrafields`: The extra columns of the listing. Add yours to display it. - `$pageInfo`: The pagination, the filters and the sort order of the listing. #### onBeforeModifyOrder(&$order, &$order\_status, &$history, &$email) Triggered when the status of an order is about to change, before anything is written. Change the status, the history entry it will record, or the email the customer receives. - `&$order`: The order, carrying the history entry about to be added. - `&$order_status`: The status the order will move to. - `&$history`: The history entry recording the change. - `&$email`: The email about to be sent, or false when none is. #### onBeforeCreateRecurringSuborder($order\_id, &$order) Triggered before a new order is created for the next term of a subscription. Change the order about to be created, or its products, to make the renewal differ from the original. - `$order_id`: The order the subscription started from. - `&$order`: The renewal order about to be created. #### onBeforeOrderExportQuery(&$filters, $paramBase) Triggered when orders are exported from your backend, so that you can restrict what the export contains. - `&$filters`: The WHERE clauses of the export query. - `$paramBase`: The parameter prefix of the listing the export was started from. #### onBeforeFrontendOrderListing($paramBase, &$pageInfo, &$filters, &$searchMap) Triggered before the order history a customer sees on your website is loaded, so that you can change which orders it lists or what the search looks into. - `$paramBase`: The parameter prefix of the listing. - `&$pageInfo`: The pagination, the filters and the sort order. - `&$filters`: The WHERE clauses of the query. - `&$searchMap`: The columns the search box looks into. #### onHikashopOrderTrackingDisplay($order) Triggered on the thank you page displayed once an order is placed. It is where an analytics or conversion tracking plugin outputs its code, with the order available to it. - `$order`: The order that was just placed. `$order->thankyou_first_view` is true on the first display of the page only, false on a reload or when the customer opens it again, so that a purchase is counted once. #### onHikashopThankYouDisplay(&$order, &$blocks) Triggered on the thank you page, before its order summary. A plugin adds a block of its own (downloads, licences, a booking's details...) to `$blocks`. - `&$order`: The order, as loaded by the order class (products, addresses, customer). - `&$blocks`: An array to add to: each block is an array with a `title` (may be empty) and its `html`. A payment plugin gives the page its own part (bank details, where to send a check...) with a `getThankYouContent(&$order)` method, returning the HTML, or an array with `html`, optional `steps` (an array of array(title, text)) and `awaiting_payment` (true while the customer still has to pay). A payment method with that method ends the checkout on the thank you page. A template can word the page for its trade (a stay instead of an order, for example) with a language file of its own, `templates/