Shopping List Tutorial

The Shopping List Service allows you to convienently organize the customers frequently purchased items into reusable and manageable shopping lists.

How to create and use a shopping list

Follow these steps to authenticate, impersonate a customer, and manage shopping lists with the Shopping List Service.

1

Get an employee access token

Use the OAuth client credentials flow with a technical client that has shoppinglist.shoppinglist_manage and shoppinglist.shoppinglist_read scopes assigned. This token lets you perform employee operations such as managing lists for any customer.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

curl -L 
  --request POST 
  --url 'https://api.emporix.io/oauth/token' 
  --header 'Content-Type: application/x-www-form-urlencoded' 
  --data 'grant_type=client_credentials&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}&scope=shoppinglist.shoppinglist_manage shoppinglist.shoppinglist_read'

Store the returned access_token to use it in the following steps.

2

Create a shopping list on behalf of a customer

With the employee token, call the Creating a shopping list endpoint and provide the customer ID in the body.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

curl -L 
  --request POST 
  --url 'https://api.emporix.io/shoppinglist/{tenant}/shopping-lists' 
  --header 'Authorization: Bearer {EMPLOYEE_TOKEN}' 
  --header 'Content-Type: application/json' 
  --data '{
    "customerId": "C120043",
    "name": "weekly-delivery",
    "items": [
      {
        "id": 1,
        "productId": "55cdcd91a88ed11babd7ca7e",
        "quantity": 7.1,
        "cuttingOption": "small",
        "servicePackagingOption": "paper",
        "comment": "Handle with care"
      }
    ]
  }'

The response returns the ID of the customer for which the shopping list was created.

3

Log in as a customer

To let a customer manage their own lists, exchange their storefront credentials for a CustomerAccessToken. Use the Logging in a customer endpoint and note the returned bearer token.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

curl -L 
  --request POST 
  --url 'https://api.emporix.io/customer/{tenant}/login' 
  --header 'Content-Type: application/json' 
  --data '{
    "username": "[email protected]",
    "password": "{CUSTOMER_PASSWORD}"
  }'

Tokens issued here only give access to the requesting customer’s resources. You do not need to supply the customerId in the Shopping List requests because it is derived from the token.

4

Create your own shopping list as a customer

Authenticate with the CustomerAccessToken from the previous step and call the shopping list creation endpoint: Creating a shopping list. Skipping the customerId field automatically links the list to the logged-in customer.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

curl -L 
  --request POST 
  --url 'https://api.emporix.io/shoppinglist/{tenant}/shopping-lists' 
  --header 'Authorization: Bearer {CUSTOMER_TOKEN}' 
  --header 'Content-Type: application/json' 
  --data '{
    "name": "holiday-menu",
    "customAttributes": {
      "occasion": "XMAS25"
    },
    "items": [
      {
        "id": 1,
        "productId": "75cdcd91a88ed11babd7ca9i",
        "quantity": 3.5
      },
      {
        "id": 2,
        "productId": "23cdcd91a88ed11babd7ca7y",
        "quantity": 1.25,
        "comment": "Family favorite"
      }
    ]
  }'

Expect a 201 Created response with the assigned customerId.

5

Retrieve all shopping lists

Use the Retrieving a shopping list endpoint to return all the shopping lists.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

curl -L 
  --request GET 
  --url 'https://api.emporix.io/shoppinglist/{tenant}/shopping-lists' 
  --header 'Authorization: Bearer {ACCESS_TOKEN}'

The response is an array where each entry contains the customerId, the list name, and its items.

6

Update a shopping list for a customer

To edit a customer’s list, call the Updating a customer shopping list endpoint. Employees can pass any customerId while customers can only update their own lists (the service infers their ID from the token).

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

curl -L 
  --request PUT 
  --url 'https://api.emporix.io/shoppinglist/{tenant}/shopping-lists/{customerId}?name=holiday-menu' 
  --header 'Authorization: Bearer {ACCESS_TOKEN}' 
  --header 'Content-Type: application/json' 
  --data '{
    "name": "holiday-menu",
    "items": [
      {
        "id": 1,
        "productId": "75cdcd91a88ed11babd7ca9i",
        "quantity": 4,
        "comment": "Need extras"
      },
      {
        "id": 2,
        "productId": "23cdcd91a88ed11babd7ca7y",
        "quantity": 0,
        "comment": "Remove from list"
      }
    ]
  }'

A 204 No Content response confirms the update.