Welcome to the hummel CONNECT Gateway API.

hummel CONNECT Gateway API provides programmatic access to Product information, Availability and allows partners to create and track Orders.

If you need help or have any questions to the APIs or your specific integration, please create a ticket through our service desk and we will get back to you as soon as possible.

OAuth2 is used for authentication. You should have received a client secret used to request a token and an api key to identify your client.

If you are using the .NET platform you can use the Microsoft.Identity library with:

Tenant ID: 52c7c612-ac6c-420c-88d2-cb752f797d6b
Client ID: 4e46d82c-f238-4e9f-ad63-d0965cad07c8

If not, here is a small recipe:

POST https://login.microsoftonline.com/52c7c612-ac6c-420c-88d2-cb752f797d6b/oauth2/v2.0/token

with form-encoded content:

client_id=4e46d82c-f238-4e9f-ad63-d0965cad07c8&scope=api%3A%2F%2F4e46d82c-f238-4e9f-ad63-d0965cad07c8%2F.default&client_secret=XXX&grant_type=client_credentials

will return a json object with the access_token.

The api key must be sent as a standard HTTP header with the key hml-api-key.

All GET api endpoints are built around sequenceNo, these numbers are ever increasing and will be updated when changes occur. They are also part of the output. While it is also possible to get changes per datetime, it is not recommended as it can lead to missing changes. Results will always be ordered by sequenceNo in ascending order.

The API uses rate limits to ensure each client gets their fair share of the shared resources.

When using sequenceNo you can do 1 request per endpoint every 2 seconds. Bursts are allowed to temporarily exceed this limit but only for shorter periods.

When not using sequenceNo then the limit is 1 request per endpoint every 15 seconds.

If you hit the rate limit, a 429 status code will be returned. Furthermore the RetryAfter header will be filled out to enable proper retries.

The availability API streams what is available per variant no.

Available quantity is what is available right now, while next availabilities is an ordered list of incoming stock available at a later date.

The credit notes API endpoints allows once to fetch either full credit notes with lines or headers and lines individually.

Credit notes can be fetched either by their no or as deltas using sequence no.

The invoices API endpoints allows once to fetch either full invoices with lines or headers and lines individually.

Invoices can be fetched either by their no or as deltas using sequence no.

The items API endpoints can overall be split into two categories: ItemsFull and individual endpoints for each specific part of an item.

ItemsFull is easy to work with because it gives the full tree from item, to color to color sizes and season collections. The flipside is that all this information must be transferred on each change to an item even if only one variant is changed. Because of this, it is also possible to use the APIs like Items or ItemColorSizes to get only those specific changes.

The hierarchy:

• Item
  • Translation
  • Colors
    • Media
    • Composition
    • Color size / variant
      • SeasonCollection
      • Translation
      • Listprice
      • UnitPrice
      • Bullet

Existing products might at some point no longer be available, we want to export this information to external partners so they can handle them properly. To do this we products with DEAD OR BLOCKED item status are exported for 3 months after they enter this status. One must not create new orders on these products.

The orders API endpoints allows customers to place orders and to receive status on these orders.

There are two overall types of orders:

• Normal and Replenishment
• Batch

Normal and replenishment orders are created once and cannot be changed once created. Batch on the other hand allows one to keep adding lines to an open order until it is closed. The order is automatically closed when a new order begins. When this happens is something that agreed between hummel and you. The currently active order returned in the external document no field. As this is automatically assigned for Batch, it should be left blank in input.