Platform Integration

THG Connect Integration Platform is THG’s API solution offering a range of products suited for your business’s needs, this documentation walks you through the steps to start your journey with THG.

Concepts

Console

The THG Connect Console will allow you to setup your organisation and get you started on the platform.

Product

THG APIs provided by the THG Connect Integration Plaform are grouped into products, a product represents a business workflow. APIs within a product are directional, they are designed to be used by either a consumer or a provider (view partnership section for more on consumers and providers);e.g. if entity A is from consumer -> provider, consumers create/modify/delete entity A and the provider consumes the events (see event driven section below) to trigger logic. The consumer in this example would be considered the owner e.g. /<consumer>/v1/entity-a, when the direction is reversed provider -> consumer the owner would be the provider e.g. /<provider>/v1/entity-a

An API is made up of a hierarchy of entities, this hierarchy is represented in the path of the resource, e.g. /<owner>/v1/entity-a/<entity A ID>/entity-b, entity-b entity is a child of entity A, resulting in entity B being created on a entity A resource provided by the entity A ID in the path.

Statuses

A status is a specialised entity which has a set of states, these are designed to represent a status of its parent entity. For example: entity B is a status of entity A, an entity A submitted by a consumer is then approved by provider, resulting in the entity B being state APPROVED or NOT_APPROVED. Each state of status can have its own payload allowing for additional information to be provided alongside a status e.g. why entity A was not approved.

The possible statuses of entity B on entity A can be queried using the post fix /_values e.g. /<owner>/v1/entity-a/<entity A ID>/entity-b/_values, this will return a list of all possible statuses for entity B on entity A. The status of entity B can be queried using /<owner>/v1/entity-a/<entity A ID>/entity-b, this will return the current status of entity B on entity A. The current statuses on entity A will also be visible in the meta section of the entity A resource when queried using the API.

REST API

REpresentational State Transfer (REST) is an architectural style used for building web-based APIs, it follows six principles (read more). All THG APIs on the THG Connect Integration Platform will conform to these REST principles.

Entity Updates

Updates for entities will use PUT and only entities which are mutable will have an update endpoint. PUT is used over PATCH to ensure idempotency, to update an entity the full entity must be send in the body of the request as it overwrites the data which is there.

Filtering & Pagination

Filtering and pagination is available on the GET ALL endpoints. A request without any query parameters will by default return the first page of size 10 with no filter, to provide custom values/cycle through the pages you can provide page[number] (integer) and page[size] (integer) as query parameters, e.g. https://api.developer.thgingenuity.com?page[number]=10&page[size]=100. A page with no entries will return a successful response with an empty list ([]).

Filtering can be applied to a GET ALL request using the filter query parameter, this uses Simple Query Language made up of comparison statements (format: <key><comparison operator><value>, e.g. orderId='123456') joined using conjunction operators (e.g. createdAt>'2024-10-15T13:45:00' and orderId='123456'). Grouping of comparison statements can be done using brackets (()) e.g. https://api.developer.thgingenuity.com?filter=(createdAt>’2024-10-15T13:45:00’ and createdAt<’2024-10-15T16:45:00’) and orderId=‘123456’this will look for order ID123456in a created time range between2024-10-15T13:45:00and2024-10-15T16:45:00, date time formats must conform to this pattern: yyyy-mm-ddThh:mm:ss`.

status is a special keyword in filtering to access the status information of a parent entity (see statuses section above for more on statuses), this can be used in the same way as a normal filter e.g. status.<name of status>='APPROVED' or status.<name of status>='NOT_APPROVED'.

Conjunction Operators:

	Description
AND	AND operator requires both comparison statements to be true
OR	OR operator requires only one comparison statement to be true

Comparison Operators:

	Description
>=	Greater than or equal to
<=	Less than or equal to
!=	Not equal
=	Equal
>	Greater than
<	Less than

Event Driven

Any POST, PUT and DELETE requests made to the THG Connect Integration Platform THG APIs will send out a DataChangedEvent (read more) these events can be consumed using subscriptions (read more).

The above diagram is a simplistic visulisation of the intended event driven approach, a consumer and provider (view partnership section for more on consumers and providers) create/modify resources as part of a product’s workflow these actions generate events which can be consumed by the other members of a partnership triggering event based logic in the consumer/provider’s system.

Response Schema

All responses returned from any API on the THG Connect Integration Platform are application/json and conform to JSON API Specification v1.1.

Platform Invitation

After consulting our solutions experts and choosing a product, you will receive an invitation to the platform. This invitation will create your organisation and give you access to the platform’s tool to manage your products, members and authentication.

Partnership

A partnership on the THG Connect Integration Platform defines a relationship between you and a provider/providers of a product.

There are two primary roles in a partnership: the consumer - an organisation consuming a product - and the provider - an organisation/entity providing a product’s services.

For example for the product A, a possible provider would be THG, THG would be providing the services of the product A. A organisation can then come along and consume product A by partnering with THG, making them the consumer.

Partnerships are created during the onboarding process.

Authentication

All APIs on the THG Connect Integration Platform require Bearer OAuth using JSON Web Tokens (JWT), these tokens come with an expiry time and it is preferred that a single token is used for API calls in the window the token is valid. Tokens are requested using a service account, to setup your first service account log into the platform tool and navigate to the ‘Settings’ page on the left.

Use the ‘Add API Client’ button to navigate to the setup page.

Once all the input boxes are filled in submit the form to create your service account.

The newly created service account will now appear, here you can use the menu on the right of the service account record to view token information.

To request a token you can use the provided HTTP request example, for integration with the token endpoint you will need the token url https://frontier-production.uk.auth0.com/oauth/token, the audience https://api.developer.thgingenuity.com both taken from the HTTP request example; and the client ID and client secret from the information window. All this information will be dependent on the environment of THG Connect Integration Platform you are using, ensure you consult your platform tool for the correct information.

HTTP Request:

curl --location '<authUrl>/oauth/token' \
--header 'Content-Type: application/json' \
--data '{
    "client_id":"<client_id>",
    "client_secret":"<client_secret>",
    "grant_type":"client_credentials",
    "audience":"<apiUrl>"
}'

Response:

{
    "access_token": "<access_token>",
    "expires_in": 86400,
    "token_type": "Bearer"
}

The two main elements of the response for an integration are the access_token this is your JWT used to authenticate you request, it must be sent in the headers 'Authorization': 'Bearer <access_token>' of every request to any API in the THG Connect Integration Platform. The second element is the expires_in this is the lifetime of the token in seconds, after it expires a new token must be requested.

With a partnership and authentication setup you can start using the APIs.

Subscription

For your integration with the platform you may require usage of the Events API, here you can manage you subscriptions to your events. Further information on the structure and types of events click here.

THG Connect Integration Platform offers two methods of consuming your events from your subscription: the first is long polling (preferred method) and the second is webhooks. All subscriptions can be polled default, for webhooks they must be provided in the subscription on creation.

When creating a subscription you provide a unique subscription ID, e.g. testsubscription. Multiple instances/nodes/application can poll the same subscription, with each poll the individual nodes will get different events, distributing the events across nodes. To achieve this each event has a 30 second window after polling where it is hidden from polling, the node which polled the event must confirm the event in this window to prevent the event being polled again. Alternatively, if you require each instance/node/application to recieve all events you can create a subscription for each instance, e.g. testsubscription1, testsubscription2, this will duplicate the events to all subscriptions.

The event resource recieved is uniform across all methods of receiving events (long polling/webhook), this resource wraps an entity with event related information. Event Resource Example:

{
    "id":"Dl4nhH93EOoXaoAxoi/zRuSrQP73XVkhfxOztHmwkYUPQ",
      "type":"DataChangedEvent",
      "attributes":{
         "id":"es_es",
         "type":"thg-commerce:site.label",
         "version":"1",
         "attributes":{
            "labels":{
               "a":"j"
            }
         },
         "links":null,
         "meta":{
            "product":"product-a",
            "reference":"thg:product-a:site.label:thgcommerce@es_es",
            "createdAt":"2025-04-23T10:21:36.126554",
            "updatedAt":"2025-04-23T10:21:36.126554",
            "parent":"product-a:site#d91063ad-8164-419b-8fe5-4368f4416f34",
            "owner":"thgcommerce",
            "creator":"thgcommerce"
         }
      },
      "meta":{
         "receiptHandle":"Dl4nhH93EOoXaoAxoi/zRuSrQP73XVkhfxOztHmwkYUPQ",
         "subscriptionId":"test-sub-id",
         "method":"update"
      }
}

Long Polling

Long polling is a common pattern used for event consumption. It requires the client system to poll (Poll Endpoint Docs) the THG Connect Integration Platform at regular intervals asking for any new events. Events will never be removed from the queue through polling. Once the client system has recieved the event it must confirm the event (Confirm Endpoint Docs) to remove it from the queue.

Webhooks

The webhook pattern notifies a clients system via webhook of any new events. On successfull delivery of the event via webhook the event will be removed from the queue, as a result there is no requirement to confirm the event via the confirm event endpoint. Events are sent using POST request method to the supplied webhook

Members

Within your organisation you may wish that more than one user has the ability to manage: users, authentication and products; to do this you can add a member within the platform tool. Login and navigate to the ‘Settings’ page on the left.

Use the ‘Invite a new member’ button in the to navigate to the setup page.

To setup the new user all that is required is their email; once the form is filled in and submitted a new user is created. The new user will receive an email to register with the platform tool, once they have completed that step they will be able to login and manage the organisation.

Sandbox

NOTE: Sandbox behaviour is not fully defined please contact us for more information if being used

There may be situations where your organisation wishes to test behaviour of the API using test Entities We have provided a Sandbox which has custom behaviour based on what Entities you hit our APIs with. The sandbox behaves the same in all environments and runs alongside your production Entities, meaning you don’t need to worry about setting up a test environment.

For example, there is a Sandbox for the entity A API in the product A which will automatically approve an entity A if its sku equals test_sku. This happens automatically out of the box once you are onboarded onto the sandbox.

To get access to the sandbox, you need to add the sandbox organisation as a provider to whichever product you want to use it for (the sandbox is essentially another organisation on the platform and you can treat it as such). Once added, you will automatically get access to the sandbox behaviour and you can start creating/updating/deleting entities in your testing.

Documents

Certain APIs will require your organisation to upload some documents, such as a pdf file for Hazmat Documentation. We have provided a Document API for this flow which handles upload and referencing.

To upload a document and reference it in an API, you will first need to do a POST request to the Document API with the filename you wish to upload. This will return a Reference String back (i.e. thg:document:example-organisation@4f2929b5-2512-48da-be97-c362cc452dc8) aswel as a custom Presigned-URL which you can upload your document to. You then need to upload your document to this presigned URL by doing a POST request ensuring you have included all the required fields (see examples in Document API reference). Once you have uploaded the actual document to this Presigned-URL, you will be able to reference the document in our other APIs.