Quick Start Guide: Get your Merchant ID

This optional tutorial presents a short “Hello World” exercise to introduce the basics of making calls to the zDirect API. We will obtain an access token and use it to authenticate a call to get your Merchant Identifier. Merchant IDs are required for many zDirect API calls.

The main steps are:

  1. Create a temporary app in the zDirect Portal
  2. Use the app’s client ID and client secret to request an access token
  3. Use the access token to request your Merchant ID
  4. Clean up

httpie

We will use the command-line tool httpie to make calls to the zDirect REST API. If you have not already installed httpie, see Testing with httpie for more information.

Sandbox

We will make calls in the sandbox environment, so you do not need to worry about affecting production data. You can easily recognize sandbox calls because they use https://api-sandbox.merchants.zalando.com as their base URL. For more information, see Sandbox Testing.

1. Create a temporary app in the zDirect Portal

In this step, we will create a temporary app in the zDirect Portal in order to generate authentication credentials. A client ID and client secret are automatically generated whenever you create an app in the zDirect Portal.

No actual application code is necessary.

To create an app:

  1. Navigate to the Applications section of the zDirect Portal.
  2. Click Create a New App.
  3. Fill in the Name and Description fields with any value you like, such as "Sample App" and "This entry is used for sandbox testing only."
  4. Select any values from the Fashion Partner and Merchants pulldown menus. Later, we will retrieve the Merchant IDs of whichever Merchant or Merchants you select here.
  5. Click Create Application in the lower-right.
  6. When prompted, click Create to confirm app creation.

You should now see your app listed in the "Applications" section.

Note that the app is set to sandbox mode. All new apps are set to sandbox mode by default. Leave the app in sandbox mode.

For more information on creating and managing apps, see Creating and Managing Apps in our zDirect Portal guide.

2. Use the app’s credentials to request an Access Token

In this step, we will send a typical access token request, using the credentials for the temporary app we created above.

Warning

The client ID and client secret are used to protect your account from unauthorized access. Do not send them through insecure channels such as email or chat, and do not save them in unencrypted files.

  1. If you are not already on the Applications section of the zDirect Portal, go there now.
  2. Click on your app to select it.
  3. Under “Credentials”, you will find the app’s client ID and client secret. Note that you can easily copy them to your clipboard with the buttons to the right.
  4. Send the following httpie command with your terminal. Be sure to use your actual client ID and client secret instead of the placeholders shown.
http \
-a $CLIENT_ID:$CLIENT_SECRET \
--form POST \
https://api-sandbox.merchants.zalando.com\
/auth/token \
grant_type=client_credentials \
scope=access_token_only

You will receive an HTTP 200 response similar to this:

HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 3054
Content-Type: application/json
Date: Tue, 30 Oct 2018 12:46:30 GMT

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJxSXJSLUZkdm5vcms2RktjcV9nNDFUa3p4VC16dk8welRyUHFUM0tMem9zIn0.eyJqdGkiOiI4MzFkZDQ5My1kY2UxLTRjNDMtYTQxMC1kMmZiNmU4ZDY4ZGUiLCJleHAiOjE1NDA5MTA3OTAsIm5iZiI6MCwiaWF0IjoxNTQwOTAzNTkwLCJpc3MiOiJodHRwczovL21lcmNoYW50LWlhbS5kZWZhdWx0LnN2Yy5jbHVzdGVyLmxvY2FsL2F1dGgvcmVhbG1zL21lcmNoYW50LXBsYXRmb3JtIiwiYXVkIjoidGVzdC1ub24taW50ZXJhY3RpdmUiLCJzdWIiOiIwN2I1M2VkYy02Mjc4LTQ3NjQtODA0MS1jYzNiYjBjZWI5MmQiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJ0ZXN0LW5vbi1pbnRlcmFjdGl2ZSIsImF1dGhfdGltZSI6MCwic2Vzc2lvbl9zdGF0ZSI6IjljNjIyYWExLTU0ZGYtNGRkNC04ZGFjLTQyMWVjODBhZjIwMyIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOltdLCJyZXNvdXJjZV9hY2Nlc3MiOnsidGVzdC1ub24taW50ZXJhY3RpdmUiOnsicm9sZXMiOlsidW1hX3Byb3RlY3Rpb24iXX0sInRlc3QtcmVzb3VyY2UiOnsicm9sZXMiOlsicmVhZCIsIndyaXRlIl19LCJ6ZnMiOnsicm9sZXMiOlsiaXRlbS1xdWFudGl0aWVzL3JlYWQiXX0sIm9yZGVycyI6eyJyb2xlcyI6WyJyZWFkIiwid3JpdGUiXX0sImFydGljbGVzIjp7InJvbGVzIjpbImVhbi9yZWFkIiwic3RvY2svcmVhZCIsInN0b2NrL3dyaXRlIiwicHJpY2Uvd3JpdGUiXX19LCJzY29wZSI6IiIsImNsaWVudElkIjoidGVzdC1ub24taW50ZXJhY3RpdmUiLCJicGlkcyI6IjE5ZTNiZGMwLTQ0MDItNGMzNC04OWE2LWI3OTgyNDQyMDc5MSwxNjcwYTc5OC04MzUyLTQwNWYtOWE4Yy05MTJjNjU4ODE5NmIsMDAwMDAwMDAtMDAwMC0xMDAwLWEwMDAtMDAwMDAwMDAwMDAxIn0.jZ4tM3gTgSJh1XVb8sZvzLmNFATSM7lKOjYgQtm9IXVCVwRFDr7YJc4tfvnYAmmqAYgClPtIiWnKfEykfApv_CuNXqEBsw88gL-ROw9cfK5fKuRLXmNVOLb4Iy1Qrvm4Rk2t1Pem5HClM3Zw345INlNrNPQPlaRMioyw9ORmW0K-a90CLPiGnZo1Qb6F2n7zpOSTuF-p-6kaqLQs8ixFkFqRaoj3pyt5OkOlgnZ0a_8T8F8ZohBak6iLkyJaAHAE_aKLVq3GmM_Pis4ieCts33QdRR0pWg0drrdGUDXtgGYaDebULaHP0niZb0yNd0Fl3F8HCpuVNfdMtFaIvqW-OA",
    "expires_in": 7200,
    "not-before-policy": 0,
    "scope": "access_token_only",
    "session_state": "9c622aa1-54df-4dd4-8dac-421ec80af203",
    "token_type": "bearer"
}

For more information on authentication, see Authentication in the Developer's Guide.

Troubleshooting

  • If you receive an error or are prompted for a password when you make this call, make sure that you separated your client ID and client secret with a colon :, and that you did not include the dollar signs.
  • Access credential requests in the sandbox environment are rate limited to one request per minute. If you make an incorrect request, you need to wait one minute before submitting your next call.

3. Use the access token to request your Merchant ID

Send the following httpie command with your terminal. Be sure to use your actual access token instead of the placeholders shown.

http -v \
https://api-sandbox.merchants.zalando.com/auth/me \
"Authorization:Bearer $YOUR_ACCESS_TOKEN"

A successful call will return HTTP 200 reply similar to the following example:

HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 412
Content-Type: application/json
Date: Thu, 01 Nov 2018 11:39:34 GMT

{
    "bpids": [
        "ab77162d-f83d-4a7b-e279-a4c03b9c4ad4"
    ],
    "client_id": "8a2333d7ae8ba156ef223fa43adb4",
    "groups": [],
    "scopes": [
        "products/stock/read",
        "products/stock/write",
        "zfs/item-quantities/read",
        "orders/read",
        "orders/write",
        "sandbox"
    ]
}

The Merchant ID or IDs associated with the access token you used to issue this request are returned as values for bpids (short for 'Business Partner IDs", another term for Merchant ID).

Troubleshooting

  • Be sure to enclose the Authorization:Bearer value in double quotes ("Authorization: Bearer ${TOKEN}") as shown in the sample.
  • Don't forget that access tokens expire. If the access token expires, repeat the previous step to generate a new one.

4. Clean up

Once you have completed this tutorial, be sure to delete any notes you made that contain your client ID and client secret. This will help prevent unauthorized access.

You may wish to delete your temporary app from the zDirect Portal if you do not plan to use its credentials for additional testing. To delete your temporary app:

  1. Navigate to the Applications section of the zDirect Portal.
  2. If you mouse-over the far right of the table row that lists your temporary app, you will see three vertical dots appear. Click them to open a context menu.
  3. Click Delete App.
  4. When asked for verification, provide your email address and click Delete in the lower-right.
Contact Support