I. Integration Setup

• Do you have a staging/testing environment available?

  Our staging environment is currently not available. Your requests to https://platform.tier-staging.io/v1 will not get any responses.

• Do you have any forecast on when the staging environment will be back again?

  At this point, there is no confirmed timeline until when the staging environment will be available. Hence, please use the production environment for testing the integration.

• Can we connect our staging environment to TIER’s production environment?

  You can use our production environment for tests by using our test scooters, but please only use this for manual testing, and never for automated tests.

• How can we perform test rides?

  As our staging environment is currently not available, we kindly ask you to use our production environment in order to execute tests. A test vehicle is made available, in order to access it, please call the vehicle ID and set the customerStartLocation as the name of the respective city (depends on test vehicle). Please note that in order to successfully create a rental, the vehicle state should be set as ACTIVE, if this is not the case please get in touch with your point of contact at TIER in order to change it. In order to not get charged for the rentals, we kindly ask you to:

  • Stick to only one test vehicle
  • Not run the rentals over 30 seconds

• What test vehicles are available for partners?

  e-scooter (Berlin): 121069

  e-Moped (Munich): 511072

• Can we expand the 30 seconds limit for free test rides?

  Expanding the 30sec limit for test rides is unfortunately not possible.

• Can we get our own test vehicle?

  If you’d like to get access to a dedicated test vehicle for the setup period of the integration, please get in touch with your point of contact at TIER.

• How/Where can we get access to TIER’s brand assets and graphics needed for the integration?

  Our design kit with all relevant assets, visuals and logos can be found here in our API documentation.

• Which API documentation version should be used? V1 or V2?

  Version 1 is our stable API that will continue to work in the future. Please use Version 2 only if you plan to use multi-modality, e.g. to integrate other vehicles than our e-scooters. Version 2 already supports other vehicles like eMopeds. Will will inform you in time when v2 is fully ready on all endpoints. Up until then, please keep using version 1.

• How often do you rotate API keys? Will you inform us upfront in case you do?

  We will reach out to you in advance when we rotate an API key. In the future we want to transition to an OAuth flow and use JWTs instead.

II. Search & Ride

1) Start Rental

• Are booked scooters returned via the same interface as freely available scooters?

  Each vehicle has the isRentable flag. If set to true this vehicle is currently available. By default, only vehicles that have isRentable set to true will be returned from the /vehicle list endpoint. See more information here. However, when requesting individual vehicles from the detail endpoint, all vehicles can be requested, no matter if they have isRentable set to true or not.

• At what battery level switches a vehicle state to INACTIVE or MAINTENANCE?

  This is triggered at 20% in most cities, except:

  • Triggered at 15% in Grenoble, Bordeaux, and St. Gallen (with large capacity ES400A batteries)
  • If the vehicle has a rental running, it will be at 13% for OKAI_ES400B models and 8% for others unless it’s paused for battery swap.
  • E-bikes at 15%

• In the TIER app I see a button that allows me to ring the bell of a scooter, whereas in the API I see an endpoint to make a scooter flash. Is this one and the same thing? Does the scooter ring when I send out a request to flash?

  Scooter ringing and flashing is connected. The flash endpoint should also activate the ring function of the scooter. The behaviour that you see when you “ring the bell” from the TIER app is exactly what you get when you call the flash endpoint. The scooter will always flash, and it will produce a sound depending on other factors (like the hour of the day).

• The TIER API returns the battery level of the scooter, but not the estimated distance that the scooter can cover given its current battery level. Is there a way to calculate this? I can see in the TIER app that you’re displaying estimated range as opposed to battery level.

  We calculate the estimated range of the scooter with the following formula for e-scooters: range = battery 0.22. We will update this calculation over time, so it could be not 100% accurate in the future, though.

• How short does the ride need to be to be free? and can you have many short/free rides in a row?

  Every ride under 30 seconds of duration is considered failed and it’s not charged. It can happen any number of times in a row.

• For which vehicles do you need to verify the driver’s licenses?

  Currently for e-mopeds only, except for the UK, where this is also mandatory for e-scooters.

2) During Rental

• I understand that the scooter rental will end automatically after 120 minutes, but will we get a notice or something or do we have to orchestrate a new call?

  No, currently you will not be notified when the rental ends. You would need to poll the rental/ endpoint to find out the current state of the rental.

• What happens if the phone turns off during a ride?

  The ride continues normally. If you turn your phone on again and open the app, you go back to the “in-ride” view. You need to end the ride from the app. We also have an automation that ends the rides in case of 30 minutes of inactivity, this would apply in all cases.

• What happens if you lose internet connection while riding. Can you stop the ride yourself?

  The ride continues even if you lose internet connection in your phone. You need to end the ride from the app with an internet connection though. Otherwise the ride continues until an automations ends it.

• What happens if you close the app and open it again while riding?

  When you open the app, it checks if you have a current ride, and if so you go back to the “in-ride” view of the existing ride.

• What happens if you don’t have enough money to start a ride?

  In the TIER app, if you don’t have enough funds to cover the pre-auth cost, the ride does not start, you see an error message. But in the case of your integration, payments are managed on your side, so this is for you to implement as you see fit. We do not check or execute payments for you.

• What happens when the scooter runs out of battery?

  There is an automation that ends the ride if scooter battery gets under a certain threshold (8%)

• What is the longest ride possible?

  The maximum ride duration for scooters are 2 hours, for mopeds 4 hours. The 1 hour limit is applied only for Dubai, Lyon and Paris.

• Is it possible to pause the ride in OBA / no-parking zones?

  Pause is possible outside of the business zone but not in no-parking zones (e.g. in cities with MPZ, you cannot pause unless you are in a MPZ).

• Are the limited speed zones displayed in the partner app via the API? Is the customer notified?

  Yes, the limited speed zones can be displayed in your app, but currently no notifications will be sent. This is something you’d have to implement on your side.

• What happens after 120 min?

  The rental will end and the user has to start a new ride. The scooters slow down gracefully and riders have a chance to pull over.

• Pause functionality: Will this “pause” phase be billed?

  Yes, all active ride durations will be included in the billing. The pause duration has the same pricing as active running state billing at the moment. User initiated pause state is also not separately reflected in the invoice yet.

• Can I ride from one business area to another one?

  Yes, this is possible, but vehicle speed may be reduced.

3) End Rental

• How to act if the ride ends on the TIER side? How often do we need to pull the ride state during the ride?

  Partners should test if this is the case and if yes, implement “pulling ride state” while in-ride every 30 seconds.

• Regarding Rental start and stop, there are parameters customerStartLocation and customerEndLocation that are marked as optional in the documentation. What are these parameters used for and how is the data processed and stored?

  The customerStartLocation and customerEndLocation are used to validate the positioning of the scooters. Since the GPS signal reception of the scooters isn’t as good as most consumer headsets, we use that information to augment the location accuracy. This is especially helpful when the user needs to park the scooter in a very small area. See here for more information.

• Will the TIER App automatically switch the rental to the ended/paused state for partners as well?

  All automations that exist for TIER are the same for all partners. When we end a rental after 60 minutes, this is also the case for our partners. You need to poll the state of the rental to get an update. (We’re working on an event driven system to alleviate that).

• We were thinking to start using force_stop for deferred stops (cases when we sent a stop request, but had a timeout, so we are not sure that rental ended), would it be fine from your end?

  If you end a rental in under 30 seconds, it counts as PROBLEM_STARTING_RIDE and will not cost anything. So if you detect a problem in under 30 seconds, you may use the force switch to end the rental without any cost.

• What about the cases when the customer was able to successfully start the rental, drive for some time then try to stop it in an area with bad connectivity, so we face timeout on stop and due to bad GPS connection TIER thinks it’s outside the business zone / mandatory parking zone?

  Most of the time we want the customer to return to the business area/parking zone to end the rental there, so they should not be able to end the rental outside the business area. For our own customers, we charge a fee for the scooter to be left outside the business area. This fee is not yet applied to partner customers though. Therefore, as a workaround, I would recommend only using force end rental if the user tried to end the rental multiple times in your app. This could incentivise the customer to try to reposition the vehicle before ending the ride. We need to make sure that your integration does not create too many problems with scooters outside the business area/parking zone as we have to collect them all.

• If the user stops the ride outside of the business area without locking the vehicle, will the vehicle automatically end the trip according to the maximum trip length? Will the customer then be charged a relocation fee?

  Yes, the rental will then automatically end after 60 minutes. For now, no additional charges (e.g. relocation fee) will apply in partner applications.

• After what time do we automatically end a ride?

  Every ride is automatically ended after 120 minutes for eScooters and eBikes, 240min for eMopeds. Exceptions: there is a 1hr max ride duration in Paris/Lyon/Dubai for fraud prevention If a vehicle is not moved, we end the ride after 30 minutes.

III. Parking & Compliance

• Which cities have mandatory parking?

  UK: London, York France: Paris, Bordeaux, Grenoble, Lyon, Saint-Quentin-en-Yvelines, Roubaix Netherlands: Utrecht Germany: Leipzig Switzerland: St Gallen Norway: Bergen (partial), Baerum Slovakia: Bratislava Austria: Korneuburg

• Is it possible to end a ride outside of the business area in partner apps?

  It is not possible to end rentals outside of the BA in partners apps as of today. If a user does not end the rental outside of the BA, either your CS can force end the rental via the API endpoint or the vehicle will be automatically locked after 60 min. In the TIER app, we offer our customers the possibility to charge them a “relocation fee” which enables them to park the vehicle outside of the business area. However our API does not currently provide this functionality. We will inform you once this is changing so it can be implemented on your side as well.

• What is the margin of error within the MPZ / business area? Given that there may be poor GPS coverage in some places.

  You are right, there is a margin of error due to the GPS of the vehicle which is not always 100% accurate. Hence, sending the customerEndLocation is highly recommended (but not mandatory). Oftentimes the GPS signal of the customer handset is much more accurate than the GPS location of the vehicle. Sending the customerEndLocation, therefore, helps a lot for ending rides inside small zones, such as at the edge of the business area or in mandatory parking zones. This feature is for now only enabled for France, but we expect to roll it out globally in the upcoming months. You can find more information here.

• What size are zone buffers and why do we need them?

  As GPS is not super precise, we need to cut Riders some slack, so they can still operate our vehicles and end their rides, even though our GPS is not too accurate.

  Standard values

  • for Mandatory Parking Zones: 35m
  • for No Parking Zones: 0m
  • for Business Area borders: 50m

  The following logic we use to end rides:

  • If CPS (Fantasmo) is provided, then the buffer is 2m, phone GPS and IoT GPS are ignored.
  • If Phone GPS is provided, the buffer is 35m in Utrecht, IoT GPS is ignored
  • Buffers are applied to the border of the polygon, not to the center of the MPZ
  • the Phone GPS is only being used when the customer is closer to the vehicle than 100m.

• Parking locations: I wonder why you have points in your app for these parking locations but provide polygons to us via API?

  The parking locations in MPZ markets are often marked on the streets. The points just highlight where these marked parking zones are. Since our GPS signal is oftentimes not 100% accurate, we’re using parking zones internally to give some leeway for the GPS parking position. The parking zones can be considered an internal workaround, or an implementation detail.

• Is the Fantasmo parking feature available via the API?

  Currently not. We’re still figuring out how to onboard all of our partners to use the feature. We’ll keep you posted.

IV. Pricing, Payment & Invoicing

1) Pre-authorisation

• How does the pre-auth work for partners? Are there any requirements from the TIER side that the partner needs to take into account?

  As the payment (and the associated payment risk) will be handled by the partner, we always leave this up to the partner to decide. In the TIER app, we do pre-authorisation before every ride, the exact amount can vary by country. We are happy to share our learnings and insights if needed.

• How will the start ride flow look like if we implement the pre-authorisation on our side?

  Once the pre-authorisation is executed successfully and the sum is reserved by PSP, our system is notified and the vehicle will be unlocked.

• Is the vehicle reserved / blocked to other users during the pre-auth check?

  No, unfortunately there is no reservation of the vehicle before any rental.

2) Invoicing

• Can TIER send the invoice to our customers?

  Yes this is possible. We can send the invoice directly to your customers, however the standard approach is that you issue the invoice yourself. More information can be found here.

• Could you explain the flag dontInvoice in the response end rental/get rental?

  dontInvoice is used by Customer Care, if the rental should not be considered as a “service rendered”, for example in case of accidental unlocks. Then the rental ends without invoice creation, and consequently, no payment. That means that dontInvoice can be true in some cases. The rentals will never receive an invoice, and we will not collect payments for them.

• Does the flag dontInvoice apply to rentals shorter than 30 seconds?

  dontInvoice does not apply to <30s rentals, they still get invoiced, but with a 0-amount charge. While dontInvoice rentals do not count as service rendered, short rentals do count as such, but for reasons of goodwill we do not charge for them.

3) Refunds

• What does the refund process look like?

  Please always contact our customer support team via support@tier.app and get their approval before you issue any refunds to the users. If a customer is entitled to get a refund (fully or partly)and this has been approved by TIER CS, you can perform the refund (transferring the revenue back to the customer). The TIER customer support also marks the refund in the TIER database. The last step can also be automated if the partner uses these endpoints to (partially) refund amounts.

• How likely are refund events?

  Refunds are relatively rare. For partner integrations, we have a global refund rate of around 0.8%.

4) Miscellaneous

• Is the time rounded up to calculate the price? E.g. would 5 min and 36 sec count as 6 minutes?

  Yes, it will be rounded up.

• There are two ways to get a price for a ride: for a zone (/v1/pricing) and for a vehicle (/v2/pricing). Do you recommend using the /v2/ one?

  For now, please use V1. Per-vehicle pricing is the future-proof version for pricing, but as of now both work.

• Is it correct that it is not possible for a vehicle to have a price different from the one specified for the zone that vehicle is in? In other words, if we know a price for a zone all vehicles in that zone are guaranteed to have that same price?

  Currently all vehicles in the same zone will have the same price. But we want to change that in the future, that’s why there is an endpoint that allows getting the price individually per vehicle. We will notify you in advance once we make such a change.

• Is there an API endpoint to get “Get the pricing information for a vehicle” when a vehicle is being identified by its code and not ID?

  No, the vehicle code can possibly change and is not the primary key to look-up a vehicle. Therefore you need to use the vehicle id and not the code to lookup the pricing too.

• Are there any additional claims/fees that we would charge the customer from partner apps? (e.g. relocation fee, damaged scooter, bad parking, etc.)

  No, at the moment these additional fees do not apply for partners. We will inform you in advance if this will change.

• What VAT rate does TIER use? Is VAT included in cost.totalAmount?

  The price is incl VAT. More details can be found in the invoice section in our API documentation.

• Is it technically possible to deeply integrate TIER service, while TIER continues taking care of the payment processes?

  At the moment this is not possible, as it would be too much effort on both sides.

V. Data Security

• Can we create new customers in the TIER platform?

  This depends on what the partner wants. Our standard approach is to not receive any new customers (performing rides via shadow account), but we can create customers in the TIER platform as well.

• What (personal) data is being shared between the Partner and TIER for every rental?

  Only the External Customer ID is needed, name and email is optional for invoicing. Some partners send us the email address and name for invoicing purposes. A joint controllership agreement will need to be signed for such use cases. See here for more information.

• Are the TIER User-IDs unique?

  All internal User-Ids are completely unique. That means there can never be any overlap of user IDs no matter if they come from a partner or if they are internal to TIER. However the external ids of partners are not validated and just treated as random payload.

• Are we able to block certain users with the current “shadow account” setting for starting rentals?

  Our CS team is able to block users via the user ID, as long as we receive an email address fro the partner. We can currently not block the user based on the partner customer ID.

• Do you ever fully delete user accounts on your side, when we don’t use the specific endpoint for it? E.g. in case we submit a cancellation of contract (or in any other cases?)? And if so, when do you delete the accounts?

  We are fully GDPR compliant: The data will either be deleted upon request or after a fixed retention period since the last user activity. We only keep data related to financial transactions, such as invoices (that also relate to the user, but cannot be deleted, as law requires us to keep them for 5 years)

VI. E-Mopeds

• Who takes care of the driver’s license verification process?

  Our partners are fully in charge of implementing this.

• Will the helmet and helmet box always be present in e-moped? Currently I see examples where these attributes are false.

  The fields hasHelmetBox and hasHelmet in the API response are always false for e-mopeds and should be ignored. E-mopeds have a compartment to hold a helmet, but not an attached box with an IoT component. There is no sensor to detect if the helmet is inside. So we can not know if the helmet is there, and we can not return it via API.

• Would it be a problem if we also sent hasValidDriverLicence = true not only for e-mopeds, but also for e-scooters?

  hasValidDriverLicence is ignored if the vehicle is a scooter, so it’s fine if you send it.

• Moped: If a vehicle gets locked due to inactivity and then gets unlocked via Resume endpoint, what happens when successive Resume endpoint is called again?

  It will send another unlock command to the vehicle. So it can be used for cases where state is not changed but the vehicle is locked.

• Is there a detection to check that the user has returned the helmet in the eMoped?

  No, this is currently not possible.

• Is the user allowed to end their E-Moped journey while their rental is paused?

  Yes, this is possible.

VII. Miscellaneous

• GET Customer. Ist the customer ID to pass the internal or external ID? (TIER ID or Partner ID)

  It is the TIER ID. Unfortunately no, it’s not possible to query customers by externalCustomerId.

• How unique are the TIER vehicle codes?

  The vehicle codes are unique on a global level, not just per city/country.

• Is the vehicle code a number or a string?

  The vehicle code is a number from 5 to 6 digits currently

• How will we be informed when the TIER services are being shut down due to weather conditions?

  Currently there is no automation in place to inform partners for such an event. We are working on an automated solution for this in the future and will inform you once this is available.

• Is the helmet feature (for e-scooters) available via the API?

  Currently this functionality is not available via our API. We will inform you once this is possible.

• Is the energy network available via the API?

  Currently this functionality is not available via our API. We will inform you once this is possible.

• Can you share voucher codes via API so they can be redeemed in the partner app?

  No this is not possible today.

• Do you have a 24/7 on-call number in case of technical issues and emergencies?

  +493056838693. Note that this is not for any kind of support (for development or otherwise): Calling this number will wake people up at night and send them multiple alerts throughout the day, so please make sure only to use it in case of emergencies, and also only when you are 100% certain the issue could not possibly lie on your side.

• Do you also provide GBFS data?

  Yes, we do. If you want to find out more, please get in touch with your point of contact at TIER.