FAQ

What kind of Commerce Platforms are supported?

The GraphQL Commerce reads the 'connector' request header from the clients to invoke the specific Commerce Connector implementation modules by the specified Connector ID. See Configure GraphQL Commerce for all available Connector IDs.

How does the authentication/authorization work?

Every request to the GraphQL Commerce should provide an access token, and the GraphQL Commerce handles and validates the authentication and authorization through its internal Access Manager components. See Access Management for further detail.

How are date/time values handled in the GraphQL Commerce?

In the GraphQL schema of the GraphQL Commerce, every date/time data field is defined as an ISO 8601 formatted string type, supporting formats like the following:

For example, the Order type in the GraphQL Schema is defined like the following:

"Purchase order abstraction"
  type Order {
    "The identifier of this purchase order"
    id: String!
    "The creation date of this order in ISO 8601 date format"
    creationDate: String!
    "...SNIP..."
  }

The creationDate field value will be an ISO 8601 formatted string in the response, so applications are supposed to parse the date/time value properly whenever necessary.

When an application wants to mutate an entity through the GraphQL Commerce, it has to format any date/time field value to a string properly. For example, the mutation to update the customer detail requires an argument of the following type:

"The customer detail input data used when updating the customer's detail information"
  input CustomerDetailInput {
    "The E-Mail address of the customer"
    email: String!
    "...SNIP..."
    "The customer's date of birth in ISO 8601 date format"
    dateOfBirth: String
  }

The dateOfBirth field value is expected to be an ISO 8601 formatted string, so applications are expected to format the date input value properly (for example, "1999-05-25").

How can I pass the faceting and filtering parameters to brSM API calls?

The API of Bloomreach Search & Merchandising supports the faceting and filtering parameter, fp. See the Faceting and filtering page for detail.

In order to pass the faceting and filtering parameter when making a GraphQL query request, you need to specify QueryHintInput.facetFieldFilters input argument.

For example, the following input will make a brSM API call with a URL like ...&fq=color: "red" OR "purple"&fq=size: "10".

query {
  findItemsByKeyword(text: "", limit: 200,
    queryHint:{
      facetFieldFilters: [
        { id: "color", values: ["red","purple"] },
        { id: "size", values: ["10"] }
      ]
    }
  ) {
    //...
    items {
      //...
    }
  }
}

How can I append or override request parameters for brSM API calls?

By default, GraphQL queries on the GraphQL Commerce against Bloomreach Search and Merchandising generates the backend API call URLs automatically to fulfill the requests. However, it also supports appending or overrriding any request parameters through QueryHintInput.params GraphQL query input argument.

For example, if you want to add the segement parameter and override the ref_url parameter when invoking brSM API URLs, then you can specify the QueryHintInput.params like the following example:

query {
  findItemsByKeyword(text: "", limit: 200,
    queryHint:{
      params: [
        { name: "segment", values: ["customer_tier:Premium"] },
        { name: "ref_url", values: ["http://www.example.com"] }
      ]
    }
  ) {
    //...
    items {
      //...
    }
  }
}

How can I include extra custom fields from the brSM API response?

By default, GraphQL queries on the GraphQL Commerce against Bloomreach Discovery extracts the fields defined in the GraphQL Schema automatically.

However, it also supports the optional configurations to include any extra custom fields by the BRSM_CUSTOM_ATTR_FIELDS and BRSM_CUSTOM_VARIANT_ATTR_FIELDS environment variables. See the Bloomreach Discovery Connector Configuration page for detail.

Furthermore, you can override the optional configurations by specifying QueryHintInput.customAttrFields and QueryHintInput.customVariantAttrFields when making GraphQL queries. For example, the following GraphQL query will make the response include the custom fields in the product item level, "brand" and "score", and the custom fields in the product variant level, "color_code":

query {
  findItemsByKeyword(text: "", limit: 200,
    queryHint: {
      customAttrFields: ["brand","score"],
      customVariantAttrFields: ["color_code"],
    }
  ) {
    //...
    items {
      //...
    }
  }
}

How to sort products search result?

The GraphQL Commerce supports the sort/order by fields functionality while triggering operations like products search. Queries like findItemsByKeyword accept a sortFields parameter where to specify a list of product fields - separated by a comma - used for sorting. As an example, the sortField param may accept values like "field1,field2,-field3", meaning order by field1 and field2 ascending and field3 descending. Below you can find a very basic example, where the result is supposed to be sorted by purchasePrice (ascending order).

query {
  findItemsByKeyword(text: "", limit: 200, sortFields: "purchasePrice") {
    //...
    items {
      //...
    }
  }
}

Please note that the sorting behavior may differ based on the commerce backend connector implementation. As an example, sorting by multiple fields may not be supported in some of the external commerce backend. In that case, the commerce backend connector may use only the first entry of the sortFields param.

Please also note that the sortFields specified in the GraphQL query are "mapped" internally to the commerce backend fields. As an example, in the case of the Bloomreach Discovery connector, the purchasePrice is mapped automatically to the sale_price field. In case a field is not mapped internally, the specified field name is used.