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.

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

The API is available at /api/graphql/ URL path of your instance.

API returns data in JSON format.

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

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.

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

GroupedProductProduct

Represents a product grouped in GroupingProduct.

Types:

• SimpleProduct

• VariableProduct

AttributeCode

Represents a lowercased, alphanumerical, and _ textual Attribute identifier of 1-128 chars in length. It cannot be id or start with esa_.

Boolean

Represents true or false.

CategoryCode

Represents a lowercased, alphanumerical, and _ textual Category identifier of 1-128 chars in length.

CategoryTreeCode

Represents a textual CategoryTree identifier of 1-128 chars in length.

Currency

Represents a currency code in ISO 4217 format. Example: PLN.

CustomFieldCode

Represents a lowercased, alphanumerical, and _ textual CustomField identifier in a single OptionAttribute context of 1-128 chars in length.

DateFormat

Represents a date formatted in one of the: yyyy-MM-dd, yy-MM-dd, dd.MM.yy, dd.MM.yyyy, MM/dd/yy, MM/dd/yyyy, MMMM dd, yyyy, dd MMMM yyyy, dd MMM yyyy

DateTime

Represents an ISO 8601 date. Example: 2021-04-09T17:25:26+00:00

Float

Represents signed double-precision fractional values as specified by IEEE 754.

Int

Represents non-fractional signed whole numeric values.

Language

Represents a 5 chars LCID language code. Example: pl_PL.

MetadatumKey

Represents an alphanumeric and _ Metadatum key of 1-128 chars in length.

MultimediaFolderName

Represents an alphanumeric, \, - and _ textual MultimediaFolder name of 1-255 chars in length.

MultimediaFolderPath

Represents a textual combination of MultimediaFolderName scalars joined with / MultimediaFolder identifier pointing to its exact location.

MultimediaName

Represents a not containing / textual Multimedia name of 1-128 chars in length.

MultimediaPath

Represents a textual combination of MultimediaFolderPath, and MultimediaName joined with / Multimedia identifier pointing to its exact location.

OptionCode

Represents a textual Option identifier in a single Attribute context of 1-128 chars in length.

SectionCode

Represents a textual Section identifier of 3-32 chars in length.

Sku

Represents a textual Product identifier of 1-255 chars in length.

StatusCode

Represents a textual ProductStatus identifier of 1-128 chars in length.

String

Represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

TemplateCode

Represents a textual Template identifier of 3-32 chars in length.

UnitName

Represents a textual Unit name of 1-255 chars in length.

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.

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: