Abicart API

# Article

An object representing an article.

info

Please note that the unique identifier is not the same as the article number.

info

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

# Properties

Property Type Description
uid integer The unique identifier of the article.
created string Date and time when the article was created.
changed string Date and time when the article was last changed.
articleNumber string An optional identifier of the article modifiable by an adminstrator. May contain letters, hyphens, numbers and other characters.
name object Name of the article, by language.
description object Article description by language.
introductionText object Article introduction text, by language.
freeFreight boolean Whether the article has free freight.
isBulky boolean Whether the article is bulky.
price Price An object containing various price information.
pricing array An array of pricing tiers for the article, each defined by a minimum quantity (qtyFloor) and associated price information. Each pricing object contains regular price (regular) and special offer price (specialOffer), both inclusive and exclusive of VAT. See Pricing for more details.
url object URL of the article page, by language.
baseName object 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.
stock Stock An object containing various stock information.
draft boolean Whether the article is a draft. Draft articles are not visible to shop visitors.
hidden boolean Whether the article is hidden. Hidden articles are accessible to administrators only.
isBuyable boolean Whether the article can be ordered.
deliveryInfo object Information about delivery, by language.
images array A list of URLs to article images.
articleTemplate integer The unique identifier of the articleTemplate, if any.
attributes object The attributes of the article, based on fields from the article template, as an object, e.g. "Manufacturer" and "Production year".
sortedAttributes array The articles attributes in order.
choiceSchema object The choices, as a JSON Schema, to make when adding this article to a cart, by language.
variants Variants A list of variations, each with what defines it and what properties it overrides.
articlegroup integer 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.
showInArticlegroups array 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.
weight number The article weight in grammes, e.g. 1000.
textAfterCheckout object Additional text shown to the customer after checkout.
vatRate number Value-added tax rate for the article as a decimal number, e.g. 0.12 for 12%.
hasChoices boolean Whether the article has choices.
choices array Which ArticleChoices that can be made when ordering an article.
choiceOptions object An object giving the available ArticleChoiceOptions for all ArticleChoices of the article.
choiceOptionPrices object An object giving the prices of choice options by currency, e.g. {"12345678": {"EUR": 29.9, "SEK": 299, "USD": 35.5}}.
presentationOnly boolean Whether the article is view-only and thus cannot be ordered.
news boolean Whether the article is a news item.
ean string European Article Number
sku string Stock Keeping Unit
pageTitle object The page title, by language.
metaDescription object Text to be used for the HTML meta element named description, by language.
metaKeywords object Text to be used for the HTML meta element named keywords, by language.
vatIsIncluded boolean Whether value-added tax is included in the price.
orderedWithArticles array 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.
attachments Attachments An array of objects.
type string Whether the article is the type of "Standard", "Giftcertificate", "Subscription", "Service" or "Package".
relationLists array An array of ArticleRelationList unique identifiers.
customerGroupVariants object Properties overridden by a customer group, by customer group uid.
subshopVariants object Properties overridden on shops in a shop system, by webshop uid.
outOfStockMessage object Message for when the article is out of stock, by language.
priceInquiryRequired boolean If the article is not buyable, but available for price inquiry.
unit object Abbreviated unit name by language, e.g. {"de": "Stk.", "fr": "pcs", "sv": "st."}.

# Price

These are the properties for the price object.

info

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 Type Description
current object 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 object The regular price of the article, as opposed to the special-offer price, by currency.
purchasePrice object The articles's purchase price, if any, by currency.
specialOffer object 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.

# 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.

info

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.

# Pricing

This property represents tiered pricing for the article. Each tier is defined by a minimum quantity (qtyFloor) and associated price information. The pricing information includes both a regular price (regular) and a special offer price (specialOffer), both inclusive and exclusive of VAT.

# Properties of a Pricing Object

Each object in the pricing array has the following properties:

Property Type Description
qtyFloor number The minimum quantity from which the specified price is valid.
regular object An object containing the price of the article at the specified quantity, both exclusive (exVat) and inclusive of VAT (incVat).
specialOffer object An object containing the special offer price of the article at the specified quantity, both exclusive (exVat) and inclusive of VAT (incVat).

# Example of a Pricing Object

"pricing": [
  {
    "qtyFloor": 0,
    "regular": {
      "exVat": {
        "USD": 15.18
      },
      "incVat": {
        "USD": 18.98
      }
    },
    "specialOffer": {
      "exVat": {
        "USD": 12
      },
      "incVat": {
        "USD": 15
      }
    }
  },
  // Additional pricing tiers...
]


::: info-icon
Tiered pricing is used to offer discounts based on quantity purchases, allowing customers to receive a lower price per article when buying in larger quantities.
:::

::: warning-icon
Note that the pricing property is only available when tiered prices have been defined for the article.
:::




### Stock
These are the properties for the stock object.

Property             | Type    | Description
---------------------|---------|-------------
show                 | boolean | Whether the stock should be shown to visitors.
useStock             | boolean | Whether stock control is being used for the article.
stock                | number  | The total amount of the stock.
hideUnstocked        | boolean | If the article should be hidden when out of stock.
hideUnstockedChoices | boolean | Whether out-of-stock choices should be hidden to visitors.
allowUnstockedOrder  | boolean | If the article should be possible to order when out of stock.
stockpile            | string  | Name of storage location
message              | object  | 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"}`.

### Variant
These are the properties for a variant object.

Property  | Type    | Description
----------|---------|-------------
uid       | integer | The unique identifier of the article variant.
definedBy | object  | What defines this article variant.
overrides | object  | Which properties this variant overrides.

### Attachment
These are the properties for an attachment object.

Property | Type   | Description
---------|--------|-------------
title    | object | Title of the attachment, by language.
url      | string | URL to the attachment.

#### Example:
```JSON
{
  "attachments": {
    "title": {
      "en": "My attachment",
      "sv": "Min bifogade fil"
    },
    "url": "https://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".

Article.count({
  "search": {
    "term": "kottar",
    "relevance": 100
  }
})

# create

Creates a new article. This is shorthand for set with the unique 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

Article.get(1234567, [
  "hidden",
  "name",
  "weight"
])

# Example 2

Article.get(1234568, [
  "articleNumber",
  "name",
  "price"
])

# 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:

Filter Description
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".

Article.list([
  "uid",
  "name"
], {
  "filters": {
    "search": {
      "term": "kottar",
      "relevance": 100
    }
  },
  "limit": 4
})

# 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.

Article.list({
  "name": "sv",
  "price": "SEK"
}, {
  "filters": {
    "/price/current/SEK": {
      "min": 42,
      "max": 92
    }
  }
})

# 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.

Article.list({
  "name": "en",
  "uid": true
}, {
  "filters": {
    "/price/current/USD": 10
  },
  "limit": 2
})

# 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

Article.normalize(123456, {
  "weight": "1"
})

A way to search for articles by a search term with our index. Only returns an array of article uid's, with no other data attached.

# Parameters

Parameter Description
term The search term to use when searching.
limit The number of article uid's to return at maximum (optional).
offset Where to begin searching in the index (optional).

# Example

Article.search("kottar", 5, 0)

# 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). See Query language.

# Example

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

# 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.

# Example

Article.subscribeToStock(123456, "john.doe@example.com", "sv")

# 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.