productStream

• product created

• product property updated

  • attribute value

  • product added or removed from a category

  • template assignment

  • status changed

  • a variant has been added or removed

  • grouped product has been added or removed

• product added to a segment

• variable product variant added to a segment

• grouping product grouped product added to a segment

• product related in product relation attribute added to a segment

attributeStream

• attribute created

• attribute property updated

  • name

  • metadata

  • option added, modified, or removed from an attribute

  • unit attribute unit

  • price attribute currency

  • textarea attribute richEdit property

categoryStream

• category created

• category property updated

  • name

  • attribute value

categoryTreeStream

• category tree created

• category tree property updated

  • name

  • category tree structure

multimediaStream

• multimedia created

• multimedia property updated

  • name

  • folder assignment

Single resource

Returns resource identified by the unique inedntifier

• product(sku: "simple_product") {…} - sku(Sku) for product

• attribute(code: "attribute_code") {...} - code(AttributeCode) for the attribute

Streams

*Stream (paginable)

Streams allow fetching the collection of resources.

Streams are designed specifically for integrations - once you create a new resource or edit existing ones, a resource is automatically transferred to the end of the stream - a given resource at a given moment is available in the stream only once. The stream gives you the power of importing resources in time without worrying about dealing with nitty-gritty details like edition date etc. As an example, we do have a product stream with the following SKUs [1, 2, 3 {endCursor}]. Once product 2 gets updated the stream will look like the following [1, 3 {endCursorFromInitialState}, 2]. Once you'd add product 4 again the stream would look like [1, 3 {endCursorFromInitialState}, 2, 4]. Thanks to using this powerful design of the cursor approach and our providing method you are sure you don't miss a resource once fetching continuously unlike it's risky on classic paginal collections.

• productStream(first: 1, after: “cursor”) {…}

Lists

*List (paginable)

Lists allow fetching the collection(list) of the resources.

The list should always be fetched and updated entirely at once. The list represents finite resources not growing in time.

• languageList(first: 1, after: "cursor") {…}

• Product.attributeList

Collections

Usually available from other resources levels i.e. bindings of the variable product

• VariableProduct.bindings

Every API resource is presented in the current state at the moment of fetching.

All paginable collections are based on the Relay standard. According to it every Edge of the graph next to the information of the resource(node) contains a cursor that allows fetching the next resource from the collection.

General

• 128f9cb0-28bd-4843-a570-d2bd4671c495 The resource is referenced from other resources.

• e78b3ed7-db49-4e81-9f29-ecc2985072f4 Currency is not supported.

• 79876042-fe47-4035-ba10-ce07706433fd Template with given TemplateCode does not exist.

• 4b5f8783-1273-4ddb-8e05-e0ecf685d924 Unit with given UnitName does not exist.

• 9ff3fdc4-b214-49db-8718-39c315e33d45 Too short input value.

• d94b19cc-114f-4f44-9cc4-4138e80a87b9 Too long input value.

• c1051bb4-d103-4f74-8988-acbcafc7fdc3 The input value cannot be blank.

• ea4e51d1-3342-48bd-87f1-9e672cd90cad The numeric value is too low.

• 1a9da513-2640-4f84-9b6a-4d99dcddc628 Value is not a valid date format.

• d6d40d78-bf28-4773-8c0d-4411be1e8fa6 Translation language is not active.

• 756b1212-697c-468d-a9ad-50dd783bb169 Too many elements in a collection.

• 491b2811-7e4d-49f7-adbe-a42622031f1c Language has to be passed when setting a value for local scope Attribute.

• 786446ad-32b8-40a9-9bb5-e5445196ffd5 Value is not unique for the given attribute.

• a16b966e-e884-4075-9de7-4720cad1022a Value does not match Regex.

• aa82dbed-9098-4d4b-af22-3a0dde5d47bb Multimedia extension is not acceptable.

• e47e5afd-c7ef-4a5d-bb3e-0076269951d4 Value contains banned words.

• 25db6569-d15d-41a2-a32d-61b67308d285 Attribute code has to represent a unique attribute.

Attribute

• 4a9205b6-8f3c-4e85-960d-9835aaa1e9ab Attribute with given AttributeCode does not exist.

• 62adb4f9-217d-4d9e-b117-0a30b4b33f3b Attribute with given AttributeCode exists already.

• 25f77355-4443-4850-b8cd-7d3ec7ef5a7a Attribute already has Option with given OptionCode.

• bc1a2fc6-4910-4e47-a3aa-1fdbcd2d364b Attribute does not contain Option with given OptionCode.

• 50084892-e811-4358-820e-f005917f769b Attribute with given AttributeCode is not valid according to context.

• 72e93c59-575a-4062-914b-5e143f2810f0 Attribute metadata limit exceeded.

• ea5e8ce4-8ab7-442d-87ca-db500cad7be2 Attribute metadata payload keys duplicates.

• 7cc10e50-3d49-43c6-a847-3b8363f9ed83 Invalid attribute scope.

Category

• 6d2e1555-7d1b-47a7-8d2d-47ea2e33bfe6 Category with given CategoryCode does not exist.

• ef49c353-7fec-4f5a-beb7-47d392606a15 Category with given CategoryCode exists already.

• b2943d95-24e6-4b0c-9f09-f86ea635d8cb Categories do not have Attribute enabled in configuration.

• c18fa865-07a5-4fcb-a6af-8c44b5c643bd Attribute is used in Category as value.

Multimedia

• d62579bf-6fde-4396-9f12-bc71d6394746 Multimedia exists already within MultimediaPath.

• eabcf146-a4e7-425c-999f-9e04a6c8a988 Multimedia with given MultimediaPath does not exist.

• 9670b62d-5db8-4de8-81bd-7d6119625df0 Multimedia file should be an image.

• df8637af-d466-48c6-a59d-e7126250a654 Multimedia file uploaded is too large.

• dd4722d6-9371-42a2-9c35-87b2a03009e7 Multimedia file uploaded extension is not supported.

• 9465e18e-be76-46e8-ab9f-1db22426ab06 Multimedia file is corrupted and its extension does not match MIME type.

• ef0dd12b-f075-4bbb-8535-4f299452cf30 Multimedia with the given extension in MultimediaName does not match the Multimedia file MIME type.

• d64f83eb-32ae-48f6-a46d-ffa4fcba6ee3 MultimediaFolder with given MultimediaFolderPath does not exist.

• 54c25a35-59da-4215-aa61-997bb80d303f MultimediaFolder with given MultimediaFolderPath exists already.

Product

• bb87ccb2-0433-40d9-976d-f4f388299840 Product relation cannot reference self.

• a339fa44-2bf8-48df-84a5-ad83a4ba74be Product type is invalid.

• 01b70d39-8e58-4406-a1c8-f63d84f29af6 Product with given Sku does not exist.

• c63cc7a9-1298-4520-a5ad-6c0a9c478a00 Product with given Sku exists already.

• 7e270f10-73b7-4b82-991f-80bda5bc70a3 VariableProduct needs to have bindings in order to add variants.

• d3209a3d-23a5-4c53-bf6b-4b72cd42d376 Product cannot be added as a VariableProduct variant as do not have the required attributes.

• 18b2cb49-313d-4251-96bd-e031351a95b8 VariableProduct has variants already and its binding attributes cannot be changed.

• 3b96fc99-792e-4698-aee1-a3d95ad97b05 Product attribute value is a bond to VariableProduct and cannot be changed.

• 0786e099-07ce-4b4e-bf92-d04442c130e5 Another Product is bonded to VariableProduct with the same set of value of binding attributes.

• bfff5187-1ac6-45f8-8516-7d59ab030c09 Cannot remove attribute value as it's a binding attribute.

• 72b36b5b-5c2f-44c6-85f3-ecadc04ea1b3 Product is already a Variant.

• 6406a966-10e9-4096-abfd-bf6764909fd2 Product does not have given child.

AttributeScope

Represents the behavior of language translation of Attribute values.

Values:

LOCAL

Value translation is set individually in every language.

GLOBAL

Value translation is the same in every language.

TwoWayRelation

Represents the behavior of language translation of Attribute values.

Determines the behavior of ProductRelationAttribute value.

Values:

None

Do not modify related products.

New

Set backward relations to the modified product only in its newly related products. Already related products remain unmodified.

All

Set backward relations to the modified product in all its related products.

GroupedProductProduct

Represents a product grouped in GroupingProduct.

Types:

• SimpleProduct

• VariableProduct

GraphQL API requires to be authenticated in order to process requests.

In order to obtain access to API resources, an API key is required to be sent along with the appropriate GraphQL query as an HTTP header - X-API-KEY.

Mutations

By default, the API key grants you access to queries, meaning you can only read data. If mutations(write) access is required you need to specify write access on key creation.

Limiting products catalog with segments

A regular API key provides you with access to the entire product catalog. It is also possible to limit that by assigning a segment while creating the key. If assigned the consumer will only have access to the products available in the specific segment. This also means that, if write access is granted, you'll be able only to modify the data of products available within the segment.

The only exception from that is when the product is created in batch request with further mutations - though possibly not yet part of the segment since you are the creator of it you can modify its data within this request.

You can also assign a category to the newly created product in the same query.

This is how you can query GraphQL API on product attributes by SKU

The entire GraphQL schema is available to fetch from the API itself. It's called introspection.

As with every other query, introspection of the Ergonode API requires authentication.

The simplest way to discover the GraphQL API is to use supporting HTTP clients like Insomnia. On one hand, they do support scoping through documentation schema, and on the other provide autocomplete functionality which makes writing queries really straightforward.

Alternatively, in order to obtain the full types definition download the schema

or just query the API:

{
  __schema {
    queryType {
      name
    }
    mutationType {
      name
    }
    subscriptionType {
      name
    }
    types {
      ...FullType 
    }
    directives {
      name
      description
      locations
      args {
        ...InputValue 
      }
    }
  }
}
fragment FullType on __Type {
  kind
  name
  description
  fields(includeDeprecated: true) {
    name
    description
    args {
      ...InputValue 
    } 
    type {
      ...TypeRef
    }
    isDeprecated
    deprecationReason
  }
  inputFields {
    ...InputValue
  }
  interfaces {
    ...TypeRef
  }
  enumValues(includeDeprecated: true) {
    name
    description
    isDeprecated
    deprecationReason
  }
  possibleTypes {
    ...TypeRef 
  }
}
fragment InputValue on __InputValue {
  name
  description
  type {
    ...TypeRef 
  }
  defaultValue
}
fragment TypeRef on __Type {
  kind
  name
  ofType {
    kind
    name
    ofType {
      kind
      name
      ofType {
        kind
        name
        ofType
        {
          kind
          name
          ofType {
            kind
            name
            ofType {
              kind
              name
              ofType {
                kind
                name
              }
            }
          }
        }
      }
    }
  }
}

Types reference:

• Queries

• Mutations

• Objects

• Interfaces

• Scalars

• Input objects

• Enums

• Unions

Example in PHP8

Example in Python3

At Ergonode we strive to make your integration process as fluent as possible but from time to time we discover a flaw in the design of the schema or introduce a really cool new feature that is impossible to be provided in a fully-compatible non-breaking way.

In such a situation, we will always aim to not break your integration with the new release and provide you with a transition period of approximately 3-months to adjust your consumer. Every such change shall be communicated in the following list.

2023-08-23

Breaking change scheduled for 04-2024

• MultiSelectAttribute.options is going to be removed

• SelectAttribute.options is going to be removed

2023-05-08

Breaking change scheduled for 09-2023

• MultimediaCreateInput.folderName is going to be removed

• Mutation.multimediaSetFolder is going to be removed

2022-09-26

Breaking changes scheduled for 02-2023

• AttributeValue.valueTranslations is going to be removed

2022-08-09

Breaking changes scheduled for 12-2022

• Attribute.label is going to be removed

• Option.label is going to be removed

• OptionInput.label is going to be removed

• Mutation.attributeSetLabel is going to be removed

• label field is going to be removed from Attribute create mutation input objects

  • AttributeCreateDateInput

  • AttributeCreateFileInput

  • AttributeCreateGalleryInput

  • AttributeCreateImageInput

  • AttributeCreateMultiSelectInput

  • AttributeCreateNumericInput

  • AttributeCreatePriceInput

  • AttributeCreateProductRelationInput

  • AttributeCreateSelectInput

  • AttributeCreateTextareaInput

  • AttributeCreateTextInput

  • AttributeCreateUnitInput

2022-06-09

Breaking changes scheduled for 10-2022

• GroupingProduct.childList is going to be removed

• Template.name is going to be removed

• Template.defaultLabel is going to be removed

2022-05-04

Breaking changes scheduled for 08-2022

• TranslatedAttributeValue.inherited is going to be removed

• Query.languageTreeLeafList is going to be removed

2022-03-15

Breaking change scheduled for 07-2022

• Attribute.hint is going to be removed

• Attribute.placeholder is going to be removed

• Mutation.attributeSetHint is going to be removed

• Mutation.attributeSetPlaceholder is going to be removed

• placeholder and hint fields are going to be removed from Attribute create mutation input objects

  • AttributeCreateDateInput

  • AttributeCreateFileInput

  • AttributeCreateGalleryInput

  • AttributeCreateImageInput

  • AttributeCreateMultiSelectInput

  • AttributeCreateNumericInput

  • AttributeCreatePriceInput

  • AttributeCreateProductRelationInput

  • AttributeCreateSelectInput

  • AttributeCreateTextareaInput

  • AttributeCreateTextInput

  • AttributeCreateUnitInput

2022-01-31

Breaking change scheduled for 05-2022

• Option.attribute is going to be removed

2022-01-18

Breaking change scheduled for 05-2022

• AttributeValue.value is going to be removed

• AttributeValue.code is going to be removed

Note: the following examples are based on the API Stream integration concept - if you are not yet familiar with it check an overview of the Query types to understand the approach.

A simple example of integrating categories into the system from scratch:

Fetch the first page of the Category stream

{
  categoryStream(first: 1) {
    pageInfo {
      endCursor
      hasNextPage
    }
    edges {
      node {
        code
        name {
          value
          language
        }
      }
      cursor
    }
  }
}

example response:

{
  "data": {
    "categoryStream": {
      "pageInfo": {
        "endCursor": "YXJyYXljb25uZWN0aW9uOjQ5",
        "hasNextPage": true
      },
      "edges": [
        {
          "node": {
            "code": "category_name_clothing",
            "name": [
              {
                "value": "Clothing",
                "language": "en_GB"
              },
              {
                "value": "Odzież",
                "language": "pl_PL"
              }
            ]
          },
          "cursor": "YXJyYXljb25uZWN0aW9uOjQ5"
        }
      ]
    }
  }
}

Fetch the next page of the Category stream

Since we received information that the next page exists data.categoryStream.pageInfo.hasNextPage=true we should request the next resource. The query is very similar to the previous one except we are passing the appropriate cursor with the request:

{
  categoryStream(first: 1, after: "YXJyYXljb25uZWN0aW9uOjQ5") {
    ...
}

example response:

{
  "data": {
    "categoryStream": {
      "pageInfo": {
        "endCursor": "YXJyYXljb25uZWN0aW9uOjUw",
        "hasNextPage": false
      }
      ...
    }
  }
}

we do know that there is no next page, therefore, there is nothing to fetch at the very moment. We can retry the next request(for the retrieved cursor) with i.e., an increased interval not to waste resources.

A more complex example of integrating categories

Alternatively in some systems, we will want only to fetch the identifier of the resource using some sort of queueing system in order to distribute the consumption processes. In that case, we can just fetch our resource ID (code in the case of categories) and the PageInfo object:

{
  categoryStream(first: 1) {
    pageInfo {
      endCursor
      hasNextPage
    }
    edges {
      node {
        code
      }
    }
  }
}

and fetch it in the separate consuming process via a single resource query:

{
  category(code: "category_name_clothing") {
    name {
      value
      language
    }
    code
  }
}

The rest of the process looks the same for the paginating over the stream.

Queries in GraphQL are created by opening curly brackets.

{

}

If we have more than one query, we need to name them and specify that this is the query, we do it as follows.

query queryName {

}

An example of a simple query that will return the value of "pageInfo" from the "productStream" branch, and from there provide the value of "endCursor". Additionally, from the "productStream" branch, it will return the value "totalCount". Think of it as a tree, a branch, and a leaf. To get information from a leaf, you must first reach it by going through all the steps one by one. Each subsequent indentation must be called using the next curly bracket. Until it's closed, we are constantly working within the same space.

For better understanding, I've stretched the code below to reflect these indents.

query queryName {
                productStream {
                                pageInfo {
                                                endCursor
                                }
                                totalCount
                }
}

The query can also use arguments. The list of available parameters can be found in the API schema(documentation). Here, we will use the "first" argument.

Without using this argument, the system would return all the data it finds, here we want to limit ourselves to the first 2 results.

query queryName {
  productStream (first: 2) {
    pageInfo {
      endCursor
    }
    totalCount
  }
}

It is also possible, to refer to the same place with several arguments, in this example we wanted to get the first 2 results and the then results after something.

query queryName {
  productStream(first: 2) {
    pageInfo {
      endCursor
    }
    totalCount
  }
  productStream(after: "YXJyYXljb25uZWN0aW9uOjM0Mw==") {
    pageInfo {
      endCursor
    }
    totalCount
  }
}

However, the above query will not work without a slight modification. If to a given object we refer more than once, we must use aliases. Below I used two aliases: "firstTwo" and "dataAfter". Remember to use a colon after the alias.

query queryName {
  firstTwo: productStream(first: 2) {
    pageInfo {
      endCursor
    }
    totalCount
  }
  dataAfter: productStream(after: "YXJyYXljb25uZWN0aW9uOjM0Mw==") {
    pageInfo {
      endCursor
    }
    totalCount
  }
}

query x {
  productStream {
    pageInfo {
      endCursor
    }
  }
}

Note that in the query (the previous one, not the one about available cursors) we call the same "totalCount" data 2 times unnecessarily. We can simplify this by using fragments.

The following query will return us exactly the same data as the previous one.

Of course, if I'm querying only one thing, there's no point in throwing it into a fragment.

However, if there were more objects or the query was more complicated, fragments allow us to optimize it.

query queryName {
  firstTwo: productStream(first: 2) {
    pageInfo {
      endCursor
    }
    ...fragmentName
  }
  dataAfter: productStream(after: "YXJyYXljb25uZWN0aW9uOjM0Mw==") {
    pageInfo {
      endCursor
    }
    ...fragmentName
  }
}

fragment fragmentName on ProductConnection {
  totalCount
}

In GraphQL it is also possible to use variables, variables are usually passed on by programming languages, but for the sake of completeness, I will show you how to use them.

Before the first curly bracket, I open a round bracket and define ( with the $ sign ) a variable named x in it, then I make a colon and a space and define the type of the variable, in this example, it will be Int (Integer). I could be done here, but I still would like to define a default value, so I put an equals sign followed by "2".

Then in the place where the variable should be passed I simply call it bt $x:

query queryName ($x: Int = 2) {
  firstTwo: productStream(first: $x) {
    pageInfo {
      endCursor
    }
    ...fragmentName
  }
  dataAfter: productStream(after: "YXJyYXljb25uZWN0aW9uOjM0Mw==") {
    pageInfo {
      endCursor
    }
    ...fragmentName
  }
}

fragment fragmentName on ProductConnection {
  totalCount
}

Queries can also use directives. In other words, conditional statements.

I'm going to add a second variable to my query named condition and set its type to Boolean, with the default value true.

Then after pageInfo I placed @include(if: $condition) directive.

query queryName ($x: Int = 2, $condition: Boolean = true) {
  firstTwo: productStream(first: $x) {
    pageInfo @include(if: $condition) {
      endCursor
    }
    ...fragmentName
  }
  dataAfter: productStream(after: "YXJyYXljb25uZWN0aW9uOjM0Mw==") {
    pageInfo {
      endCursor
    }
    ...fragmentName
  }
}

fragment fragmentName on ProductConnection {
  totalCount
}

Since I have previously set the default value of the $condition variable to true, the condition will be met and the data will show up, but if I change it to false, the data will not.

query queryName ($x: Int = 2, $condition: Boolean = true) {
  firstTwo: productStream(first: $x) {
    pageInfo @include(if: $condition) {
      endCursor
    }
    ...fragmentName
  }
  dataAfter: productStream(after: "YXJyYXljb25uZWN0aW9uOjM0Mw==") {
    pageInfo {
      endCursor
    }
    ...fragmentName
  }
}

fragment fragmentName on ProductConnection {
  totalCount
}

mutation {
  productCreateSimple(
    input: { sku: "SKU_test2", templateCode: "Tshirts"}
  ) {
    __typename
  }
}

You can also assign a category to the newly created product in the same query.

mutation {
  productCreateSimple(
    input: { sku: "SKU_test2", templateCode: "Tshirts", categoryCodes: "DELL" }
  ) {
    __typename
  }
}

API mutations are designed to be very small and atomic on purpose - thanks to that design, you don't have to prefetch data to send it back to the server and worry only about the actual change you want to perform.

On the other hand, occasionally your intention is to create or change resources with data that a single mutation does not handle. GraphQL comes in handy here - thanks to its design you can batch mutations(and queries) which means that multiple operations can be performed in one, single request - this not only makes it easier to make updates but also speeds up operations.

mutation {
  create: productCreateSimple(input: {sku: "new_product", templateCode: "template"}) {
    __typename
  }
  assignDescription: productAddAttributeValueTranslationsTextarea(
    input: {
      sku: "new_product"
      attributeCode: "description"
      translations: [{ value: "Long description", language: "en_GB" }]
    }
  ) {
    __typename
  }
  assignShortDescription: productAddAttributeValueTranslationsTextarea(
    input: {
      sku: "new_product"
      attributeCode: "short_description"
      translations: [{ value: "Short description", language: "en_GB" }]
    }
  ) {
    __typename
  }
}

attribute

Finds an Attribute.

Returns: Attribute

Arguments:

attributeDeletedStream

Provides a stream of deleted attribute codes.

Returns: AttributeDeletedConnection

Arguments:

attributeOptionList

Provides a list of attribute options.

Returns: OptionConnection

Arguments:

attributeStream

Provides a stream of attributes.

Returns: AttributeConnection

Arguments:

category

Finds a Category.

Returns: Category

Arguments:

categoryAttributeList

Provides a list of attributes allowed to be used in a category.

Returns: AttributeConnection

Arguments:

categoryDeletedStream

Provides a stream of deleted category codes.

Returns: CategoryDeletedConnection

Arguments:

categoryStream

Provides a stream of categories.

Returns: CategoryConnection

Arguments:

categoryTree

Finds a CategoryTree.

Returns: CategoryTree

Arguments:

categoryTreeDeletedStream

Provides a stream of deleted category tree codes.

Returns: CategoryTreeDeletedConnection

Arguments:

categoryTreeStream

Provides a stream of category trees.

Returns: CategoryTreeConnection

Arguments:

languageList

Provides a list of active languages.

Returns: LanguageConnection

Arguments:

multimedia

Finds a Multimedia.

Returns: Multimedia

Arguments:

multimediaFolder

Finds a MultimediaFolder.

Returns: MultimediaFolder

Arguments:

multimediaFolderList

Provides a list of multimedia folders.

Returns: MultimediaFolderConnection

Arguments:

multimediaStream

Provides a stream of multimedia.

Returns: MultimediaConnection

Arguments:

product

Finds a Product.

Returns: Product

Arguments:

productByUniqueAttribute

Finds a Product by unique attribute value.

Returns: Product

Arguments:

productDeletedStream

Provides a stream of deleted product SKUs.

Returns: ProductDeletedConnection

Arguments:

productStream

Provides a stream of products.

Returns: ProductConnection

Arguments:

productVariantParent

Finds a parent VariableProduct identified by variant Sku.

Returns: VariableProduct

Arguments:

section

Finds a Section.

Returns: Section

Arguments:

sectionList

Provides a list of sections.

Returns: SectionConnection

Arguments:

template

Finds a Template.

Returns: Template

Arguments:

templateList

Provides a list of templates.

Returns: TemplateConnection

Arguments:

2024-11-21

• Query.productVariantParent added

• Product.status added

• Mutation.productSetStatus added

2024-10-16

• Query.productByUniqueAttribute added

2024-07-15

• ProductAddAttributeValueTranslationsProductRelationInput.twoWayRelation added

2024-06-25

• Mutation.multimediaFolderDelete added

• Query.attributeOptionList added

2024-04-16

• MultiSelectAttribute.options removed

• SelectAttribute.options removed

2024-01-25

• OptionAttribute.optionList argument codes added

• Template.sectionList added

• Query.section added

• Query.sectionList added

• Query.template added

2023-12-20

• OptionAttribute interface added

• SelectAttribute implements OptionAttribute

• MultiSelectAttribute implements OptionAttribute

• OptionAttribute.customFields added

• Option.customFields added

• Mutation.attributeOptionAddCustomFieldImage added

• Mutation.attributeOptionAddCustomFieldText added

• Mutation.attributeOptionAddCustomFieldTextarea added

• Mutation.attributeOptionAddCustomFieldTextareaRTE added

• Mutation.attributeOptionAddOptionCustomFieldValueTranslationsImage added

• Mutation.attributeOptionAddOptionCustomFieldValueTranslationsText added

• Mutation.attributeOptionAddOptionCustomFieldValueTranslationsTextarea added

• Mutation.attributeOptionAddOptionCustomFieldValueTranslationsTextareaRTE added

• Mutation.attributeOptionDeleteCustomField added

• Mutation.attributeOptionDeleteOptionCustomFieldValueTranslations added

2023-09-07

• Query.multimediaFolder added

• MultimediaFolderCreateInput.createFolderPath added

• MultimediaCreateInput.folderName removed

• Mutation.multimediaSetFolder removed

2023-08-23

• MultiSelectAttribute.optionList added

• MultiSelectAttribute.options becomes deprecated. Use MultiSelectAttribute.optionList instead

• SelectAttribute.optionList added

• SelectAttribute.options becomes deprecated. Use SelectAttribute.optionList instead

• Mutation.attributeMultiSelectAddOption added

• Mutation.attributeMultiSelectDeleteOption added

• Mutation.attributeMultiSelectSetOptionName added

• Mutation.attributeSelectAddOption added

• Mutation.attributeSelectDeleteOption added

• Mutation.attributeSelectSetOptionName added

• Mutation.multimediaReplace added

2023-07-25

• Query.multimedia added

2023-05-08

• MultimediaFolder.path added

• Mutation.multimediaMove added

• Mutation.multimediaFolderCreate added

• MultimediaCreateInput.folderPath added

• MultimediaCreateInput.folderName becomes deprecated. If passed together with folderPath this argument becomes disregarded

• Mutation.multimediaSetFolder becomes deprecated

2023-04-17

• MultiSelectAttributeValueTranslation.translatedValue added

• SelectAttributeValueTranslation.translatedValue added

2023-02-28

• AttributeValue.valueTranslations removed

• TextareaAttributeValueTranslation.rawValue added

2023-02-22

• Attribute.metadata added

• Mutation.attributeAddMetadata added

• Mutation.attributeDeleteMetadata added

2023-02-14

• Mutation.multimediaSetFolder added

2022-12-21

• Query.categoryAttributeList added

• Mutation.categoryAttributeAddAttribute added

• Mutation.categoryAttributeRemoveAttribute added

2022-12-07

• Mutation.attributeSetLabel removed

• OptionInput.label removed

• Option.label removed

• Attribute.label removed

• label removed from Attribute create mutation input objects

  • AttributeCreateDateInput

  • AttributeCreateFileInput

  • AttributeCreateGalleryInput

  • AttributeCreateImageInput

  • AttributeCreateMultiSelectInput

  • AttributeCreateNumericInput

  • AttributeCreatePriceInput

  • AttributeCreateProductRelationInput

  • AttributeCreateSelectInput

  • AttributeCreateTextareaInput

  • AttributeCreateTextInput

  • AttributeCreateUnitInput

2022-11-09

• Category.attributeList added

• Mutation.categoryDeleteAttributeValueTranslations added

• Mutation.categoryAddAttributeValueTranslationsText added

• Mutation.categoryAddAttributeValueTranslationsTextarea added

• Mutation.categoryAddAttributeValueTranslationsNumeric added

• Mutation.categoryAddAttributeValueTranslationsPrice added

• Mutation.categoryAddAttributeValueTranslationsUnit added

• Mutation.categoryAddAttributeValueTranslationsImage added

• Mutation.categoryAddAttributeValueTranslationsGallery added

• Mutation.categoryAddAttributeValueTranslationsFile added

• Mutation.categoryAddAttributeValueTranslationsProductRelation added

• Mutation.categoryAddAttributeValueTranslationsDate added

• Mutation.categoryAddAttributeValueTranslationsSelect added

• Mutation.categoryAddAttributeValueTranslationsMultiSelect added

• GroupingProduct.childList removed

• Template.name removed

• Template.defaultLabel removed

2022-10-19

• MultimediaCreateInput.folderName added

2022-09-26

• AttributeValue.translations added - represents the translation value type per Attribute type. MultiSelectAttributeValue and SelectAttributeValue instead of simple OptionCode provides entire Option

• AttributeValue.valueTranslations becomes deprecated

• AttributeValue implementations per Attribute type added

2022-08-11

• TranslatedAttributeValue.inherited removed

• Query.languageTreeLeafList removed

2022-08-09

• Template.attributeList added

• Query.templateList added

• Attribute.name added - represents the same value as Attribute.label field

• Attribute.label becomes deprecated

• Option.name added - represents the same value as Option.label field

• Option.label becomes deprecated

• OptionInput.name added

  • if passed together with label field it takes precedence

• Mutation.attributeSetName added

• Mutation.attributeSetLabel becomes deprecated

• name field added in Attribute create mutation input objects. It replaces label field. If passed together with it name takes precedence

  • AttributeCreateDateInput

  • AttributeCreateFileInput

  • AttributeCreateGalleryInput

  • AttributeCreateImageInput

  • AttributeCreateMultiSelectInput

  • AttributeCreateNumericInput

  • AttributeCreatePriceInput

  • AttributeCreateProductRelationInput

  • AttributeCreateSelectInput

  • AttributeCreateTextareaInput

  • AttributeCreateTextInput

  • AttributeCreateUnitInput

2022-08-01

• Attribute.hint removed

• Attribute.placeholder removed

• Mutation.attributeSetHint removed

• Mutation.attributeSetPlaceholder removed

• placeholder and hint fields removed from Attribute create mutation input objects

  • AttributeCreateDateInput

  • AttributeCreateFileInput

  • AttributeCreateGalleryInput

  • AttributeCreateImageInput

  • AttributeCreateMultiSelectInput

  • AttributeCreateNumericInput

  • AttributeCreatePriceInput

  • AttributeCreateProductRelationInput

  • AttributeCreateSelectInput

  • AttributeCreateTextareaInput

  • AttributeCreateTextInput

  • AttributeCreateUnitInput

2022-07-14

• Multimedia.title added

• Mutation.multimediaSetTitle added

2022-06-09

• ProductGroupingAddChildInput.quantity added

• Mutation.productGroupingSetChildQuantity added

• GroupingProduct.childrenList added

• GroupingProduct.childList becomes deprecated

• Template.name becomes deprecated

• Template.defaultLabel becomes deprecated

2022-05-10

• AttributeValue.code removed

• AttributeValue.value removed

• Option.attribute removed

2022-05-04

• TranslatedAttributeValue.inherited becomes deprecated

• Query.languageTree becomes deprecated

• Query.languageList added

• language field becomes nullable for(valid for global attributes only)

  • DateValueTranslationInput

  • FileValueTranslationInput

  • GalleryValueTranslationInput

  • ImageValueTranslationInput

  • MultiSelectValueTranslationInput

  • NumericValueTranslationInput

  • PriceValueTranslationInput

  • ProductRelationValueTranslationInput

  • SelectValueTranslationInput

  • TextareaValueTranslationInput

  • TextValueTranslationInput

  • UnitValueTranslationInput

2022-03-15

• Attribute.hint becomes deprecated

• Attribute.placeholder becomes deprecated

• Mutation.attributeSetHint becomes deprecated

• Mutation.attributeSetPlaceholder becomes deprecated

2022-01-31

• Option.attribute becomes deprecated

2022-01-18

• AttributeValue.valueTranslations added

• AttributeValue.value becomes deprecated

2022-01-04

• Mutation schema has been added to the API. For a full list of mutations available use an introspection

  • every existing API key has preserved its read access but did not receive write access. In order to obtain write access create a new key with it

Attribute

An attribute represents a type of value that can be assigned to a product.

Fields:

Implemented by:

• DateAttribute

• FileAttribute

• GalleryAttribute

• ImageAttribute

• MultiSelectAttribute

• NumericAttribute

• OptionAttribute

• PriceAttribute

• ProductRelationAttribute

• SelectAttribute

• TextareaAttribute

• TextAttribute

• UnitAttribute

AttributeValue

Represents a value defining a specific attribute.

Fields:

Implemented by:

• DateAttributeValue

• FileAttributeValue

• GalleryAttributeValue

• ImageAttributeValue

• MultiSelectAttributeValue

• NumericAttributeValue

• PriceAttributeValue

• ProductRelationAttributeValue

• SelectAttributeValue

• TextareaAttributeValue

• TextAttributeValue

• UnitAttributeValue

AttributeValueTranslation

Represents a translated attribute value for language.

Fields:

Implemented by:

• DateAttributeValueTranslation

• FileAttributeValueTranslation

• GalleryAttributeValueTranslation

• ImageAttributeValueTranslation

• MultiSelectAttributeValueTranslation

• NumericAttributeValueTranslation

• PriceAttributeValueTranslation

• ProductRelationAttributeValueTranslation

• SelectAttributeValueTranslation

• TextareaAttributeValueTranslation

• TextAttributeValueTranslation

• UnitAttributeValueTranslation

CustomField

A custom field represents a type of value that can be assigned to an attribute option.

Fields:

Implemented by:

• ImageCustomField

• TextareaCustomField

• TextareaRTECustomField

• TextCustomField

CustomFieldTranslatedValue

Represents a value defining a specific CustomField in specific language only.

Fields:

Implemented by:

• ImageCustomFieldTranslatedValue

• TextareaCustomFieldTranslatedValue

• TextareaRTECustomFieldTranslatedValue

• TextCustomFieldTranslatedValue

CustomFieldValue

Represents a value defining a specific CustomField.

Fields:

Implemented by:

• ImageCustomFieldValue

• TextareaCustomFieldValue

• TextareaRTECustomFieldValue

• TextCustomFieldValue

CustomFieldValueTranslation

Represents a translated custom field value for language.

Fields:

Implemented by:

• ImageCustomFieldValueTranslation

• TextareaCustomFieldValueTranslation

• TextareaRTECustomFieldValueTranslation

• TextCustomFieldValueTranslation

OptionAttribute

An attribute with a predefined set of values(options).

Implements:

• Attribute

Fields:

Implemented by:

• MultiSelectAttribute

• SelectAttribute

Product

Fields:

Implemented by:

• GroupingProduct

• SimpleProduct

• VariableProduct

This is an example of how you can get values of specific attributes in specific languages of a specific product using pagination.

Please keep in mind that this is just an example and more data can be pulled. How to deal with other attribute types can be seen in the fragment AttributeValue here.

query getAttValues {
    product(sku: "0123456789") {
        # SKU of a single product to get data from
        sku
        createdAt
        editedAt
        template {
            code
        }
        attributeList(
            first: 10 # nuber of entries to return in a single page (max response time is 60s)
            after: "YXJyYXljb25uZWN0aW9uOjA=" # endCursor from the response to get rest of the data if "hasNextPage": true
            codes: [
                # attributes to get values from
                "name"
                "color"
                "short_description"
                "price_local_eur"
                "galeria_zdjec"
            ]
        ) {
            ... on AttributeValueConnection {
                pageInfo {
                    hasNextPage
                    endCursor
                }
                edges {
                    node {
                        ... on PriceAttributeValue {
                            priceAttribute: attribute {
                                # currency might be useful in the price context
                                currency
                            }
                            priceAttributeValue: translations(
                                languages: ["en_GB", "pl_PL"]
                            ) {
                                language
                                value
                            }
                        }
                        ... on SelectAttributeValue {
                            SelectAttributeValue: translations(
                                languages: ["en_GB", "pl_PL"]
                            ) {
                                language
                                translatedValue {
                                    ...OptionTranslatedValue
                                }
                            }
                        }
                        ... on TextAttributeValue {
                            attribute {
                                name(languages: ["en_GB", "pl_PL"]) {
                                    language
                                    value
                                }
                            }
                            TextAttributeValue: translations(
                                languages: ["en_GB", "pl_PL"]
                            ) {
                                language
                                value
                            }
                        }
                        ... on TextareaAttributeValue {
                            attribute {
                                name(languages: ["en_GB", "pl_PL"]) {
                                    language
                                    value
                                }
                            }
                            TextareaAttributeValue: translations(
                                languages: ["en_GB", "pl_PL"]
                            ) {
                                language
                                value
                            }
                        }
                        ... on GalleryAttributeValue {
                            GalleryAttributeValue: translations {
                                language
                                value {
                                    ...Multimedia
                                }
                            }
                        }
                    }
                }
            }
        }
        __typename
    }
}

fragment Multimedia on Multimedia {
    path
    name
    extension
    mime
    sizeInBytes: size
    alt(languages: ["en_GB", "pl_PL"]) {
        language
        value
    }
    title(languages: ["en_GB", "pl_PL"]) {
        language
        value
    }
}
fragment OptionTranslatedValue on OptionTranslatedValue {
    code
    name
}