Customer Link API

Overview

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

Conventions

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.

Using the API

Direct Customers

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

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.

Creating purchase orders

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:

Send a POST /orders request with all the order data in the payload
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.
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

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
        }
      ]
    }
  ]
}

Common Errors

The following common errors may occur on various API endpoints:

Code	Title	Description	What to do
400	Bad Request	Bad incoming request from the client	The 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.
401	Unauthorized	Unauthenticated client application	Check the error message for more details and verify that the client application credentials are correct.
403	Forbidden	The 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.
404	Not Found	Invalid resource URL or non-existent record.	Check the API documentation for the right URL and make sure that you use the right resource identifier.
405	Method Not Allowed	The 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.
429	Too Many Requests	The 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.
500	Internal Server Error	General error on the API side.	If it happens consistently, contact support.
502	Bad Gateway	Connection issues within the API infrastructure.	If it happens consistently, contact support.
504	Gateway Timeout	Connection issues within the API infrastructure.	If it happens consistently, contact support.

CustomerLink API