HomeEngagementContentDiscoveryOther Resources
API Reference

GraphQL Commerce API guides

Introduction

This page explains how to use the GraphQL Commerce API with your Bloomreach Content account and your frontend application(s).

GraphQL Commerce URLs

The GraphQL Commerce is available at the following URLs:

Staging Environmenthttps://graphql-commerce-preprod.bloomreach.io
Production Environmenthttps://graphql-commerce.bloomreach.io

Additionally, any requests to the GraphQL Server should include the br-acct-env request header. The value should match your Bloomreach Content account name, defined as part of the Bloomreach Content instance URL https://[account_name].bloomreach.io.

If you are not using these URLs in both staging and production, please make sure to update your configurations as explained in the following paragraphs.

Back end

Please execute the following steps:

  • Create a new development project
  • Associate the desired channel
  • Move to the Site Development project
  • Open the development project created in a previous step
  • Edit the graphql_baseurl channel property value to desired instance (e.g. https://graphql-commerce.bloomreach.io for production)
  • Create a new channel property called graphqlTenantName: ideally it is hidden
  • Fill the graphqlTenantName property value with your Bloomreach Content account name: that is defined as part of the Bloomreach Content URL https://[account_name].bloomreach.io

Please repeat the steps above for all the Content channels dealing with the GraphQL Commerce.

Front end

If your front-end implementation uses the Commerce React Components library, then:

  • Make sure that your front-end implementations use the latest version of the library
  • Add (or edit) the accountEnvId parameter to any occurrence of the CommerceConnectorProvider React component, like the following:
<CommerceConnectorProvider
   graphqlServiceUrl={graphqlServiceUrl}
   ...
   accountEnvId="[account_name]"
 >
 …
 </CommerceConnectorProvider>

If your front-end does not use the Commerce React Components library, please make sure to update your GraphQL client(s), in order to inject the requested header.

Once both the front-end and back-end changes have been tested, execute the following steps in this order:

  • Deploy the new front-end changes
  • Merge your project to the core branch

General configuration options

The following configuration options are available. If you wish to make a change, please submit a support request with the names of the properties and your preferred values.

Property Name (* required field)DescriptionDefault Value
APOLLO_INTROSPECTIONIf set to 'true', the Apollo Server Introspection technique is enabled to provide detailed information about a GraphQL API's schema.'false'
APOLLO_PLAYGROUNDIf set to 'true', the Apollo Server GraphQL Playground, the in-browser IDE for GraphQL development and workflow, is enabled to provide developers with features such as theme change, automatic schema reloading, HTTP headers configuration, query history and GraphQL subscription support.'false'
CORS_ORIGINThe allowed origin which wants to access the GraphQL Commerce as a Cross-Origin Resource Sharing target.
If this is not set or set to an empty string, then the GraphQL Commerce allows access to the clients sending a valid 'Origin' request header.
If set to '*', then the GraphQL Commerce allows access to any clients.
If set to a specific URL (e.g, https://www.example.com), then the GraphQL Commerce allows access only to the clients which are originated from the URL.
TOKEN_REFRESH_ENABLEDIf set to 'true', the Refreshing Access Token request against Access Management is enabled on the GraphQL Commerce. This option has been disabled by default since v14.3.0.
DEFAULT_CONNECTOR_IDGraphQL Commerce reads the Commerce Connector ID from the HTTP request header named 'connector'. If the GraphQL client does not provide a valid Commerce Connector ID value, then this variable is used instead.'brsm'
DEFAULT_LANGUAGEThe default language code for the client.'en'
DEFAULT_COUNTRYThe default country code for the client.'US'
DEFAULT_CURRENCYThe default currency code for the client.'USD'
RESPONSE_TIME_HEADER_ENABLEDIf set to 'true', the internal response time in milliseconds measured in the GraphQL Commerce is passed in the X-Response-Time response header.

Bloomreach Discovery and commerce back-end platform connection settings and connector IDs

Bloomreach Discovery and the following commerce back-end platforms are supported (differentiated by their unique identifier to be specified in the connector request header):

📘

Note

The Discovery connector is configured by default, while the other connectors are configured only on request (see below).

How to request configuration changes?

Please use our support channel to request configuration changes, including properties name and value(s).