REST API - Article Resource

Introduction

In this part of the documentation you can learn more about the API's article resource. With this resource, it's possible to retrieve, update and delete any article of your shop. We will also have a look at the associated data structures.

General Information

This resource supports the following operations:

Access URL GET GET (List) PUT PUT (Batch) POST DELETE DELETE (Batch)
/api/articles Yes Yes Yes Yes Yes Yes Yes

If you want to access this resource, simply query the following URL:

  • http://my-shop-url/api/articles

Structure

In this part, we will have a look at the data provided by this resource and its structure. You will be guided through all seven different operations separately.

GET

Required Parameters

This API call requires one of the following parameters to be defined:

Identifier Parameter DB column Example call
Article Id id s_articles.id /api/articles/2
Detail Number number s_articles.ordernumber /api/articles/SW10003?useNumberAsId=true
  • useNumberAsId=true - This tells the API to query the article's data by its detail number, instead of its actual identifier. Otherwise, the syntax is just /api/articles/id. It's not possible to provide both parameters at the same time.

Optional Parameters

Optional parameters can be provided:

  • language id or locale (from s_core_locales). If used, the returned info will be provided in the specified language (if available)
  • considerTaxInput: By default, all returned prices are net values. If the boolean considerTaxInput is set to true, gross values will be returned instead.
Identifier Parameter DB column Example call
language id s_core_locales /api/articles/2?language=de_DE
considerTaxInput boolean /api/articles/2?considerTaxInput=true

You can use one or more of these parameters together.

Here is an example of a parametrized URL:

  • http://my-shop-url/api/articles/2?considerTaxInput=true&language=de_DE
  • http://my-shop-url/api/articles/SW10003?useNumberAsId=true&considerTaxInput=true&language=de_DE

Return value

This call will return an array of the model Shopware\Models\Article\Article (s_articles).

The following table shows the fields, types and original objects of this array.

Field Type Original object
id integer (primary key)
mainDetailId integer (foreign key) Detail
supplierId integer (foreign key) Supplier
taxId integer (foreign key) Tax
priceGroupId integer (foreign key) PriceGroup
filterGroupId integer (foreign key) ConfiguratorSet
configuratorSetId integer (foreign key) ConfiguratorSet
name string
description string
descriptionLong string
added date/time
active boolean
pseudoSales integer
highlight boolean
keywords string
metaTitle string
changed date/time
priceGroupActive boolean
lastStock boolean
crossBundleLook boolean
notification boolean
template string
mode integer
availableFrom date/time
availableTo date/time
mainDetail object Detail
tax object Tax
propertyValue object PropertyValue
supplier object Supplier
propertyGroup object PropertyGroup
customerGroups object array CustomerGroup
images object array Image
configuratorSet object ConfiguratorSet
links object array Link
downloads object array Download
categories object array Category
similar object array Similar
related object array Related
details object array Detail
translations object array Translation

GET (List)

Optional Parameters

Optional parameters can be provided:

  • language id or locale (from s_core_locales). If used, the returned info will be provided in the specified language (if available)
  • considerTaxInput: By default, all returned prices are net values. If the boolean considerTaxInput is set to true, gross values will be returned instead.
Identifier Parameter DB column Example call
language id s_core_locales /api/articles/language=de_DE
considerTaxInput boolean /api/articles/considerTaxInput=true

You can use one or more of these parameters together.

Here is an example of a parametrized URL:

  • http://my-shop-url/api/articles/considerTaxInput=true&language=de_DE

Return Value

Field Type Original object
id integer (primary key)
mainDetailId integer (foreign key) Detail
supplierId integer (foreign key) Supplier
taxId integer (foreign key) Tax
priceGroupId integer (foreign key) PriceGroup
filterGroupId integer (foreign key) ConfiguratorSet
configuratorSetId integer (foreign key) ConfiguratorSet
name string
description string
descriptionLong string
added date/time
active boolean
pseudoSales integer
highlight boolean
keywords string
metaTitle string
changed date/time
priceGroupActive boolean
lastStock boolean
crossBundleLook boolean
notification boolean
template string
mode integer
availableFrom date/time
availableTo date/time

POST (create)

Field Type Notice Original Object / Database table
name (required) string
taxId (required) integer (foreign key) Required if no tax object provided s_core_tax.id
tax (required) object Tax
mainDetail (required) object Detail
supplierId (required) integer (foreign key) Required if no supplier object provided s_articles_supplier.id
supplier (required) object Will be created if it does not exist Supplier
priceGroupId integer (foreign key) s_core_pricegroups.id
filterGroupId integer (foreign key) s_filter.id
description string
descriptionLong string
added date/time
active boolean
pseudoSales integer
highlight boolean
keywords string
metaTitle string
changed date/time
priceGroupActive boolean
lastStock boolean
crossBundleLook boolean
notification boolean
template string
mode integer
availableFrom date/time
availableTo date/time
propertyValues object array If provided it requires filterGroupId to be set PropertyValue
customerGroups object array CustomerGroup
images object array Image
configuratorSet object ConfiguratorSet
downloads object array Download
categories object array Category
similar object array Similar
related object array Related
variants object array Detail

PUT (update)

Articles can be identified using the following:

Identifier Parameter DB column Example call
Article Id id s_articles.id /api/articles/2
Detail Number number s_articles.ordernumber /api/articles/SW10003?useNumberAsId=true

The data structure used is similar to the one used for creation (POST request)

DELETE

The article(s) to delete can be defined using the following syntax:

Identifier Parameter DB column Example call
Article Id id s_articles.id /api/articles/2

DELETE (Stack)

In order to delete more than one article at once, it's possible to provide an array of ids to the REST API. Simply pass the array of article ids to the following URL (example)

  • [DELETE] http://my-shop-url/api/articles/

without providing an id as seen in the single DELETE request. As data provide the array of ids you wish to delete.

PUT (Stack)

Updating many articles at once requires an array of article data being provided to the following URL using the PUT request (example):

  • [PUT] http://my-shop-url/api/articles/

Simply provide the same data as described in the create statement.