CustomerLink API

Overview
Endpoints
Orders
Customers
Brokers
Products
Audit Logs
Product Prices
Product Limits
powered by Stoplight

CustomerLink API

v1.14.1
API Base URL
Test environment for internal client applications:https://iapi-test.merck.com/customer-link/v1
Production environment for internal client applications:https://iapi.merck.com/customer-link/v1
Test environment:https://api-test.merck.com/customer-link/v1
Production environment:https://api.merck.com/customer-link/v1
Security
Basic Auth
  • Base64 encoded string where:
    • Username is your APIKey
    • Password is your Client Secret from Api Portal
  • Format: Username:Password

Basic authentication is a simple authentication scheme built into the HTTP protocol. To use it, send your HTTP requests with an Authorization header that contains the word Basic followed by a space and a base64-encoded string username:password.

Example: Authorization: Basic ZGVtbzpwQDU1dzByZA==

Additional Information

The API allows creating purchase orders and retrieving order status for authorized consuming applications.

API documentation can be viewed as a web page at the root path /. (Also available in yaml or json formats depending on Accept header).

Information about API releases (introduced features and bugfixes) can be viewed as a web page at the releases path /releases or be downloaded as a Markdown file, with Accept: text/md header.

Currently, 3 types of consuming applications are recognized:

  • Direct customers - they are registered within the company system and they can place orders for themselves
  • Broker companies - they are not registered as customers within the company system, but they are authorized to place orders on behalf of existing registered (direct) customers.
  • ReadOnly profile - This profile allows read only access to any customer (orders history/order details/order invoices) from the same sales organization as its own.

Special roles: Additional roles are needed to query Product Prices and Product limits (Please note, these operations are currently available only for DE market). These roles are subject to approval. To request the access, please send an email to cl-api-support@merck.com

All API endpoints in this document are relative. In order to be properly used, they need to be prefixed with the base URL of the API.

For example:

GET /customers/{customerId}

should be translated into:

https://HOSTNAME/customer-link/v1/customers/{customerId}

where HOSTNAME is the hostname of the corresponding API environment.

Direct customers can use the /customers/@me endpoint to retrieve basic information about themselves:

GET https://HOSTNAME/customer-link/v1/customers/@me
200 OK
Content-Type: application/hal+json; charset=utf-8
{
"_links": {
"self": {
"href": "https://iapi.merck.com/customer-link/v1/customers/@me"
}
},
"id": "0000123456",
"name": "CLINICA ABCDE",
"_embedded": {
"billingAddresses": [
...
],
"shippingAddresses": [
...
]
}
}

Broker companies can use the /broker/@me endpoint to retrieve basic information about themselves:

GET https://HOSTNAME/customer-link/v1/brokers/@me
200 OK
Content-Type: application/hal+json; charset=utf-8
{
"name": "Broker company",
"_embedded": {
"customers": [
{
"id": "0000012345",
"_links": {
"self": {
"href": "https://iapi.merck.com/customer-link/v1/customers/0000012345"
}
}
},
{
"id": "0000067890",
"_links": {
"self": {
"href": "https://iapi.merck.com/customer-link/v1/customers/0000067890"
}
}
}
]
}
}

The payload contains the list of customer companies, on behalf of which the broker company is authorized to place orders.

The broker company is also authorized to retrieve basic information about a specific customer from the list:

GET https://HOSTNAME/customer-link/v1/customers/0000012345
200 OK
Content-Type: application/hal+json; charset=utf-8
{
"_links": {
"self": {
"href": "https://iapi.merck.com/customer-link/v1/customers/0000012345"
}
},
"id": "0000012345",
"name": "CLINICA ABCDE",
"_embedded": {
"billingAddresses": [
...
],
"shippingAddresses": [
...
]
}
}

This may be needed particularly when the customer company has more than one shipping or billing address registered. In order to use a non-default address in the order, you need to specify the address ID explicitly. All the billing and shipping address IDs are available within the customer company information.

Both direct customers and broker companies can create purchase orders. The direct customers can place orders for themselves only, while the broker companies can create orders on behalf of all customers, for which they are authorized to do so.

The workflow of creating a new order is as follows:

  1. Send a POST /orders request with all the order data in the payload
  2. In case there are no errors the order will be created and the API will return an empty response with status code 201. The response will also contain a location header with the link to the newly created order.
  3. Follow the link - GET /orders/<ID> to retrieve details and status information about the newly created order.

For example:

POST https://HOSTNAME/customer-link/v1/orders
Content-Type: application/json
{
"customerId": "0000123456",
"shippingAddressId": "0000123456",
"products": [
{
"productId": '1012345',
"quantity": 2
},
{
"ean": '8765432',
"quantity": 7
}
]
}
201 Created
Location: https://HOSTNAME/customer-link/v1/orders/20123456

If the order is created successfully, the response code will be 201 without any payload. The link to the newly created resource will be available in the Location HTTP header:

Location: https://HOSTNAME/customer-link/v1/orders/20123456

In order to retrieve the order status, the consuming application should follow the link:

GET https://HOSTNAME/customer-link/v1/orders/20123456
{
"_links": {
"self": {
"href": "https://iapi.merck.com/customer-link/v1/orders/20123456"
}
},
"id": "20123456",
"deliveryDate": "2021-11-12",
"createTime": "2021-11-12T08:18:40.000Z",
"status": "open",
"shippingStatus": "Not Shipped",
"totalOrderPrice": 2574.88,
"currencyCode": "EUR",
"customerId": "0000124297",
"billToAddress": {
...
},
"shipToAddress": {
...
},
"products": [
{
"productId": '1012345',
"ean": '9876',
"name": "PRODUCT #1 0.5MG 2X21TAB",
"quantity": 2,
"confirmedQuantity": 2,
"unitPrice": 1042.44,
"totalPrice": 2084.88
"batch": "U012961",
"contractNumber": "",
"shippingStatus": "Sent",
"shippingDate": "2021-12-01T22:31:40.000Z"
},
{
"productId": '2012345',
"ean": '8765432',
"name": "PRODUCT #2 50MG DFL",
"quantity": 7,
"confirmedQuantity": 7,
"unitPrice": 70,
"totalPrice": 490
"batch": "U012960",
"contractNumber": "",
"shippingStatus": "Sent",
"shippingDate": "2021-12-01T22:31:40.000Z"
}
]
}

Read Only Profile can use the /customers/{customerId}/orders?orderDate=YYYY-MM-DD endpoint to retrieve same salesOrg customer orders history:

GET https://HOSTNAME/customer-link/v1//customers/50081044/orders?orderDate=2022-03-22
200 OK
Content-Type: application/hal+json; charset=utf-8
{
"totalCount": 1,
"_links": {
"self": {
"href": "https://iapi.merck.com/customer-link/v1/customers/50081044/orders?orderDate=2022-03-22"
}
},
"orders": [
{
"_links": {
"self": {
"href": "https://iapi.merck.com/customer-link/v1/orders/3027214065"
}
},
"orderNumber": "3027214065",
"purchaseOrderNumber": "ZOR-22-03-2022 10:02",
"createTime": "2022-03-22T06:05:28.000Z",
"status": "Completed",
"shippingStatus": "Not Shipped",
"totalOrderPrice": 123.45,
"products": [
{
"productId": "000000000001023929",
"name": "JANUVIA 25MG 2X14FTBL",
"quantity": 1
},
{
"productId": "000000000001034386",
"name": "KEYTRUDA 100MG DFL",
"quantity": 1
}
]
}
]
}

The following common errors may occur on various API endpoints:

CodeTitleDescriptionWhat to do
400Bad RequestBad incoming request from the clientThe server cannot or will not process the request due to something that is perceived to be a client error. This may happen when parameters or payloads are not in the correct formats.
401UnauthorizedUnauthenticated client applicationCheck the error message for more details and verify that the client application credentials are correct.
403ForbiddenThe client application does not have permission to perform the action on the resource. For example, when trying to retrieve other customer's order.Check if all request data are correct.
404Not FoundInvalid resource URL or non-existent record.Check the API documentation for the right URL and make sure that you use the right resource identifier.
405Method Not AllowedThe HTTP method (GET, POST, ...) used for the request is not allowed for the given resource.Check the API documentation for the right HTTP method to use.
429Too Many RequestsThe API has encountered too many requests in a short period of time and it cannot process your request right now.Retry the request after a short period of time.
500Internal Server ErrorGeneral error on the API side.If it happens consistently, contact support.
502Bad GatewayConnection issues within the API infrastructure.If it happens consistently, contact support.
504Gateway TimeoutConnection issues within the API infrastructure.If it happens consistently, contact support.