Dispenser Integration

Access to a testing environment is available on request.

The traditional coffee-to-go cup is a significant contributor to waste in Germany, with over 320,000 disposable cups consumed every hour in 2017 (Source). Beyond cups, single-use food containers also generate substantial waste. Relevo addresses this challenge by offering innovative dispensing solutions that operate without the need for staff or supervision, making it easy to provide reusable items where they are needed most. Speak with one of our Relevo packaging experts to find the best solution for your business.

Goals

Relevo's data-driven approach ensures that reusable systems succeed by being convenient for every part of the supply chain. Our dispenser solutions are designed to meet the following goals:

• Dispensers are simple to restock.

• Reusable items are offered at the right place and time.

• No deposit or payment handling required.

• Works in tandem with Return Vending Machines.

Our unique technology enables dispensers to be restocked without requiring a specific stacking order while maintaining precise tracking of individual items. This is achieved through placeholder items linked to the Relevo User ID. Users must scan the QR code on the real item to replace the placeholder in their account, ensuring accurate tracking and incentivizing timely returns.

Requirements

To implement a fully functional reusable dispensing solution, ensure you have the following:

• Relevo integration data

  • Partner Key

  • Location ID(s)

  • Meta Category ID of items

• External QR code scanner on the dispenser

• (Alternative input method for Relevo User ID)

• Release Mechanism (e.g., hatch, box, or holder) tied to verification

• Internet connectivity for simple HTTP API calls

Dispensers can range from simple hatches and boxes to advanced systems that release stackable cups one at a time after Relevo User verification. The design should align with your specific use case.

Process

Tutorial

The capabilities of your dispenser may vary depending on your specific use case, but certain principles should always be followed to ensure a smooth and reliable integration. It is essential to verify the Relevo User ID during every interaction to maintain accurate tracking.

Equally important, no item should be dispensed to a Relevo User without first assigning the correct placeholder category to their account. Placeholder items act as temporary markers in the system and cannot be removed by the Relevo User. They can only be replaced by scanning the QR code on the actual item they receive.

If a Relevo User fails to replace the placeholder with the real item within 14 days (or your custom borrowing period), they will incur a fee. This process encourages users to scan their items promptly, ensuring proper tracking and accountability. By following the steps outlined below, you can implement an efficient and user-friendly system for offering reusable items at the right place and time.

1

Verify the Relevo User ID

API Reference

Verifying the Relevo User ID is mandatory to ensure the user interacting with your dispenser is allowed to and has valid payment information on file. You may allow Relevo Users to either enter their Relevo User ID manually or scan their QR code (prefixed with rlv://).

API Request

Request

// GET Request
// replace <userId> with the scanned Relevo User ID

https://api.relevo-admin.de/api/v1/users/<userId>/status

Headers

Response

API Response

If you receive back a 200 HTTP Status code, then you can proceed with the flow.

2

Assign placeholder item

API Reference

Verifying the Relevo User ID is mandatory to ensure the user interacting with your dispenser is allowed to and has valid payment information on file. You may allow Relevo Users to either enter their Relevo User ID manually or scan their QR code (prefixed with rlv://).

API Request

Request

// PUT Request
// replace <userId> with the previously verified Relevo User ID

https://api.relevo-admin.de/api/v1/users/<userId>/unknown-items

Body

Headers

Response

API Response

If you receive back a 200 HTTP Status code, then you can proceed with the flow.

3

(Assign multiple placeholder items)

API Reference

Should your use-case require you to assign multiple placeholder items at once to a Relevo User, you can do so as well. This is a great option if you offer menus from dispensers. Integrating this option also makes expanding your approach from assigning a single placeholder to multiple ones very easy, since you just have to adjust the transmitted body.

API Request

Request

// PUT Request
// replace <userId> with the previously verified Relevo User ID

https://api.relevo-admin.de/api/v1/users/<userId>/items-categories

Body

Headers

Response

API Response

• Proceed only if your quantity and category appear in the assignedCategories object.

• If errors occur, review the notAssignedCategories object and communicate issues to users.

Placeholder items allow a wide range of applications that are easy to handle for dispenser providers, as well as approachable for users. Let us know if further assistance is needed!