Frequently asked questions

Is v4 backwards compatible with previous versions?

No. V4 introduced breaking changes to reflect updates in the logical structure of product information and to address technical and usability issues in earlier versions. You cannot use v3 request formats or endpoints with v4.

V1 and V2 are fully deprecated and no longer available — both the API endpoints and their documentation have been removed. V3 is still operational but is in maintenance mode; its documentation is available at platform.medipim.be/docs/api/v3. All new integrations should use v4.

How to handle API requests of 100/min?

See Throttling & quotas for strategies on staying within rate limits and performing bulk imports.

How to deal with product status?

You can use a filter in the body of the API request to select only active products. Inactive products are typically being phased out — there will likely be no stock left for them.

{
  "status": "active"
}

In what format are prices returned?

Prices are always returned in the base denomination (the lowest unit of the currency) to avoid rounding errors. Divide the returned value by 100 to get the actual amount.

For example, an API response of 820 for a price field means €8.20.

How to request a large set of data?

Products are returned through a newline-delimited response stream, appearing line by line. This allows for immediate processing instead of waiting for the entire response.

• Use the stream endpoint for large data sets.
• Use the query endpoint with pagination for testing or smaller sets.

Acquiring all information through a single API call is feasible, but the response will be substantial. We strongly advise processing the data promptly to avoid buffering delays.

Why are my image requests being blocked?

Product images (packshots, productshots, etc.) are served from a CDN that requires a valid User-Agent header on every request. This header tells the CDN which application is making the request, and is used to enforce rate limits, prevent unauthorized scraping, and optimize content delivery.

If your image requests return errors or empty responses, check that you are sending a descriptive User-Agent header. Generic or empty values (e.g., "Mozilla/5.0", "curl/7.x", or "-") may be rejected.

Recommended format:

User-Agent: YourAppName/Version (contact@yourdomain.com)

For example:

User-Agent: MyPharmacyApp/2.1 (dev@mypharmacy.be)

Which product fields can I request through the API?

Products in Medipim can have many fields — names, descriptions, identifiers, images, dietary restrictions, and more. The set of available fields depends on your organization's subscription and the platform region.

Use the get-product-fields endpoint to retrieve the full list of product fields available to you. You can then use these field names with the hasContent filter to query only products that have a specific field populated — see the HasContentFilter in the query-products endpoint documentation for usage details.

Can I use the ean identifier as a unique product identifier?

Although EAN was intended as a cross-country unique product code, duplicates do exist in practice. If you need a truly unique code for a product, use the Medipim product ID.

Which product identifiers are enforced as unique?

The following identifiers are enforced as unique on the Belgium platform — no two products can share the same value for any of these codes:

Field name	Description
cnk	CNK
eanGtin8	EAN/GTIN-8
eanGtin12	EAN/GTIN-12
eanGtin13	EAN/GTIN-13
eanGtin14	EAN/GTIN-14

If a product is saved with a value that already exists for one of these fields, the API will reject it. Note that the ean field (the legacy multi-value EAN field) is not enforced as unique — use the specific EAN/GTIN variant fields instead.

For a guaranteed unique reference for every product regardless of identifier codes, use the Medipim product ID (id).

What is a product's 'public page'?

For each product, the API returns a meta.publicPageUrl field containing a URL to a standalone HTML page hosted by Medipim. This page is designed for end-consumers and patients — it does not redirect to the Medipim platform and does not require authentication.

The page renders the following product information (all scoped to the public target group):

• Product photo — the main image for the selected language
• General information — product name, brand, and a general description
• Main fields — identifiers (EAN, CNK), dietary restrictions, etc.
• Secondary fields — active ingredients, galenic shape, dosage form, and (when applicable) a link to a replacement product
• Descriptions — usage, composition, side effects, warnings, and other consumer-facing descriptions
• Patient leaflet — a "Read leaflet" link when a PIL (Patient Information Leaflet) is available
• Supply alerts — when a product has supply problems or has been taken off the market, the page shows a notice and lists alternative products from the same therapeutic group

Professional or scientific data is not included.

URL structure and validity

The URL has the form https://products.medipim.be/{encoded-product-id}-{unique-identifier} and is valid for 6 months. After expiry, a new identifier is generated automatically — always use the latest URL from the API response rather than caching it long-term.

Language selection

Append a locale query parameter to request the page in a specific language:

https://products.medipim.be/...?locale=fr

If no locale is provided, the page defaults to the primary content language for the platform region. On the Belgian platform, the page also shows a language switcher for Dutch and French.

Use cases

• Embedding in a QR code on packaging or shelf labels
• Sharing a product link with patients or consumers
• Displaying product information on pharmacy touchscreens or kiosks

How do I keep my product data in sync?

Most integrations start with a full import and then periodically fetch only what has changed. Here's the general approach:

1. Initial sync — use the stream endpoint to pull the full product catalog (see Throttling & quotas for why streaming is recommended). Store the products locally and save the current timestamp.
2. Periodic sync — use the updatedSince filter on the product query or stream endpoint to fetch only products that have changed since your last sync. After each sync, update your saved timestamp.

The updatedSince filter accepts a timestamp and returns all products that have been created or modified since that point in time.

How do I sync product images and media?

Product responses include the linked media items for each product, so if you're syncing full product data, you already have the media URLs.

If you only need images for a selection of products (e.g. you manage your own product data but want packshots from Medipim), you can query the media items directly using the media query or media stream endpoint. These endpoints support filters such as product (to scope media to specific products) and type (to select only images, PDFs, etc.).

To keep media in sync over time, the media endpoints also support the updatedSince filter — the same approach as for products:

1. Initial sync — fetch all relevant media items and save the current timestamp.
2. Periodic sync — use updatedSince to fetch only new or changed media since your last sync.

When processing media updates, compare the new URL with the one you have stored. If a media item you previously synced is no longer present in the response, remove it from your local records.