Article

An object representing an article. Please note that the unique identifier is not the same as the article number.

Which articles are accessible depend on such things as administration rights, customer groups and shops in multi-shop systems.

Properties

Property Description
articlegroup The unique identifier of an Articlegroup. If set, the value must also be present in the show-in-article-group array. If not set, showInArticlegroups must be empty.
articleNumber An optional identifier of the article modifiable by an adminstrator. May contain letters, hyphens, numbers and other characters.
articleTemplate The unique identifier of the articleTemplate, if any.
attributes The attributes of the article, based on fields from the article template, as an object, e.g. "Manufacturer" and "Production year".
attachments An array of attachment objects.
baseName The base name that is used when generating a URL for the article, by language. Unless otherwise specified, the base name is generated from name.
choiceOptions An object giving the available ArticleChoiceOptions for all ArticleChoices of the article.
choiceOptionPrices An object giving the prices of choice options by currency, e.g. {"12345678": {"EUR": 29.9, "SEK": 299, "USD": 35.5}}.
choices Which ArticleChoices that can be made when ordering an article.
description Article description by language.
draft Whether the article is a draft. Draft articles are not visible to shop visitors.
ean European Article Number
hidden Whether the article is hidden. Hidden articles are accessible to administrators only.
images A list of URLs to article images.
isBuyable Whether the article can be ordered.
metaDescription Text to be used for the HTML meta element named description, by language.
metaKeywords Text to be used for the HTML meta element named keywords, by language.
name Name of the article, by language.
news Whether the article is a news item.
orderedWithArticles An array of unique identifiers for articles that have been ordered together with the specified article. The array is sorted descendingly by the number of articles ordered and contains only articles ordered within the past three months. This property exists only for articles with the property isBuyable and if the feature has been enabled for the shop.
pageTitle The page title, by language.
presentationOnly Whether the article is view-only and thus cannot be ordered.
price An object containing various price information. See Price below.
priceInquiryRequired If the article is not buyable, but available for price inquiry.
relationLists An array of ArticleRelationList unique identifiers.
showInArticlegroups An array of Articlegroup unique identifiers for all the article groups where the article should be displayed. If this array is non-empty, the value of the articlegroup property must be one of these. If empty, the articlegroup property must not exist.
sku Stock Keeping Unit
stock An object containing various stock information. See Stock below.
type Whether the article is the type of "Standard", "Giftcertificate" or "Subscription".
uid The unique identifier of the article.
unit Abbreviated unit name by language, e.g. {"de": "Stk.", "fr": "pcs", "sv": "st."}.
url URL of the article page, by language.
vatIsIncluded Whether value-added tax is included in the price.
vatRate Value-added tax rate for the article as a decimal number, e.g. 0.12 for 12%.
weight The article weight in grammes, e.g. 1000.
metaProperties An object with extra meta properties not used in Abicart standard themes

Price

These are the properties for the price object.

If the user is an administrator, then the price is that entered originally; otherwise, it is that of the current customer and depends on the customer group or other things that may affect the price visible to a customer.

Property Description
current The current price of the article, by currency. The current price corresponds to the special-offer price, if any; otherwise it corresponds to the regular price. It is also possible to use this property in a filter, like in the examples for list below.
regular The regular price of the article, as opposed to the special-offer price, by currency.
specialOffer The special-offer or sales price of the article, if any, by currency.

For all of the above objects, value-added tax is handled in accordance with the the rules below.

metaProperties

These are the properties of the metaProperties object.

gridName | Alternative name to be used in article grids, by language. gridText | Alternative description to be used in article grids, by language. listName | Alternative name to be used in article lists, by language. listText | Alternative description to be used in article lists, by language. wideName | Alternative name to be used for full wide presentation, by language. wideText | Alternative description to be used for full wide presentation, by language. useGridText | Whether to use alternative texts in article grids. useListText | Whether to use alternative texts in in article lists. useWideText | Whether to use alternative texts for full wide presentation.

For administrators

  • Prices are displayed as when entered, i.e. as they appear in the administration interface, and may be including or excluding VAT.

For non-administrators

  • If the price of the article has been entered including VAT and the session states that prices shall be displayed excluding VAT, then VAT is deducted from the price.
  • If the price of the article has been entered excluding VAT and the session states that prices shall be displayed including VAT, then VAT is added to the price.

For administrators and non-administrators alike, it is always possible to use vatIsIncluded to see whether the prices are including or excluding value-added tax.

Stock

These are the properties for the stock object.

Property Description
hideUnstockedChoices Whether out-of-stock choices should be hidden to visitors.
message Stock balance or out-of-stock message shown to the visitor, by language, e.g. {"en": "In stock: 14", "sv": "Antal i lager: 14"} or {"en": "Temporarily out of stock", "sv": "Tillfälligt slut i lager"}.
stock The total amount of the stock.
show Whether the stock should be shown to visitors.
useStock Whether stock control is being used for the article.

Attachments

These are the properties for an attachment object.

Property Description
title Title of the attachment, by language.
url URL to the attachment.

Example:

{
  "attachments": {
    "title: {
      "en": "My attachment",
      "sv": "Min bifogade fil"
    }
    "url": "http://example.com/my_attachement.zip"
  }
}

Methods

count

Takes a filter object and returns the number of articles found, as an integer.

Parameters

A filter object specifying which articles to count. See Filter objects on the page List selection.

Example

The request below returns the number of articles with a 100 per cent relevance for the search term "kottar".

API Console
Article.count(
  {
    "search": {
      "term": "kottar",
      "relevance": 100
    },
  }
)
Response
553

create

Creates a new article. This is shorthand for set with the uniquer identifier null.

Parameters

Parameter Description
patch An object containing the properties and values to set for the new article.
query A query specifying what to return after article creation has been successful (optional). See Query language.

get

Fetches information about an article. You need the unique identifier of the article. To fetch an article by its article number, use Article.list instead.

Parameters

Parameter Description
uid The unique identifier of an article.
query Which info to return. See Query language.

Example 1

API Console
Article.get(1234567, ["hidden", "name", "weight"])
Response
{
  "hidden": false,
  "name": {
    "en": "Wooden Chaffinch",
    "sv": "Bofink i trä"
  },
  "weight": 1000
}

Example 2

API Console
Article.get(1234568, ["articleNumber", "name", "price"])
Response
{
  "articleNumber": "vase-123",
  "name": {
    "da": "Keramisk vase, rød",
    "en": "Red ceramic vase",
    "nb": "Keramisk vase, rød",
    "sv": "Röd keramikvas"

  },
  "price": {
    "current": {
      "DKK": 365,
      "EUR": 45.95,
      "NOK": 400,
      "SEK": 429
    },
    "regular": {
      "DKK": 565,
      "EUR": 55.95,
      "NOK": 500,
      "SEK": 529
    },
    "specialOffer": {
      "DKK": 365,
      "EUR": 45.95,
      "NOK": 400,
      "SEK": 429
    },
  },
}

getSchema

Fetches the JSON Schema which can be used for client-side validation.

Parameters

The unique identifier of an article or null for a new article.

list

Fetches multiple articles as an array of article objects.

Parameters

Parameter Description
query Which info to return. See Query language.
selection Which articles to list. See List language.

Filters

Apart from filtering on the properties using their JSON pointers, the following filters exist:

  • search (special filter with the operations "term" and "relevance")
  • articleNumber (synonym of "/articleNumber", included for backward compatibility)

These orderings are available:

  • uid
  • articleNumber
  • changed
  • created
  • name
  • numSold
  • price
  • stock
  • relevance (only when there is a filter on "search")

Example 1

The request below lists 4 articles with a 100 per cent relevance for the search term "kottar".

API Console
Article.list(
  ["uid", "name"],
  {
    "filters": {
      "search": {
        "term": "kottar",
        "relevance": 100
      }
    },
    "limit": 4
  }
)
Response
[
  {
    "name": {
      "en": "Dr Rudi whole hops 2012, 100 g",
      "sv": "Dr Rudi kottar 2012, 100 g"
    },
    "uid": 12770469
  },
  {
    "name": {
      "en": "Dr Rudi whole hops 2012, 5x100 g",
      "sv": "Dr Rudi kottar 2012, 5x100 g"
    },
    "uid": 12770474
  },
  {
    "name": {
      "en": "Sovereign whole hops 2012, 100 g",
      "sv": "Sovereign kottar 2012, 100 g"
    },
    "uid": 15707922
  },
  {
    "name": {
      "en": "Sovereign whole hops 2012, 5x100 g",
      "sv": "Sovereign kottar 2012, 5x100 g"
    },
    "uid": 15707934
  }
]

Example 2

The request below returns, as an array of objects, the names in Swedish and prices in SEK for all the articles with a current price of between SEK 42 and 92.

API Console
Article.list(
  {
    "name": "sv",
    "price": "SEK"
  },
  {
    "filters": {
      "/price/current/SEK": {
        "min": 42,
        "max": 92
      }
    }
  }
)
Response
[
  {
    "name": {
      "sv": "Staty i kalksten"
    },
    "price": {
      "SEK": 81
    }
  },
  {
    "name": {
      "sv": "Staty i granit"
    },
    "price": {
      "SEK": 85
    }
  },
  {
    "name": {
      "sv": "Staty i marmor"
    },
    "price": {
      "SEK": 90
    }
  },
]

Example 3

The request below returns, as an array of objects, at most two articles with a current price of USD 10 containing their unique identifiers and names in English.

API Console
Article.list(
  {
    "name": "en",
    "uid": true
  },
  {
    "filters": {
      "/price/current/USD": 10
    },
    "limit": 2
  }
)
Response
[
  {
    "name": {
      "en": "Blue shirt"
    },
    "uid": 54764223
  },
  {
    "name": {
      "en": "Yellow shirt"
    },
    "uid": 35742423
  },
]

set

Creates or updates an article.

Parameters

Parameter Description
uid The unique identifier of an article or null to create a new article.
patch An object containing the properties and values to set for the article.
query A query specifying what to return after a successful set (optional).

Example

API Console
Article.set(123456, {"name": {"en": "Bird", "sv": "Fågel"}}, ["uid", "name"])
Response
{
  "uid": 123456,
  "name": {
    "en": "Bird",
    "sv": "Fågel"
  }
}

normalize

Fetches a normalized version of the patch. Uses the same parameters as set and validate.

While set also normalizes the patch, before storing, normalize only returns the normalized patch. Any properties with numeric values represented as strings are converted to number literals. A normalization error is thrown when we are unable to convert a string to a number literal.

Parameters

Parameter Description
uid The unique identifier of an article or null to create a new article.
patch An object containing the properties and values to normalize.

Example

API Console
Article.normalize(123456, {"weight": "1"})
Response
{
  "uid": 123456,
  "weight" : 1
}

validate

Validates the data to be set. The performed validation is the same as in set; it validates the resulting object and includes all of the required properties. However, nothing is saved.

Parameters

Parameter Description
uid The unique identifier of an existing article or null.
patch An object containing the properties and values to set before validating.

Errors

Error messages are given as an array of validation-error objects, each containing the keys pointer (a property referenced using a JSON Pointer) and message (a readable text in the language of the context).

Returns

If there are no validation errors, then an empty array is returned.

subscribeToStock

When an article is unavailable, often out of stock, this method will allow a visitor to add a subssciption to when an article is back in stock.

Parameters

Parameter Description
uid The unique identifier of an article or null.
email The email address to send the notification to can be set to null if customer is logged in.
language What language to use when sending the notification for back in stock.

Errors

Code Message Description
4100 Stock subscription exists The supplied email or
4101 Article is buyable When trying to subscribe to an buyable article.
4102 Email mismatch The email supplied does not match the logged in user email.
4103 No email supplied If no email is supplied and no customer is logged in.
Response
Article.subscribeToStock(123456, "joe@example.com", sv)

```response {}