Link Search Menu Expand Document

Create customer

HTTP Request

POST https://platform.tier-services.io/v1/customer

Post Data

Field Content Note
firstName James Optional. This is used for invoicing.
lastName Brown Optional. This is used for invoicing.
email hello@tier.app Optional. This is used for sending invoice PDFs
externalCustomerId partnerId Mandatory. Sending your customer is needed for correct attribution. Internally it is a VARCHAR(255), so you can put in any string here. 
curl "https://platform.tier-services.io/v1/customer"
  -X POST
  -H "x-api-key: TIER API KEY"
  -d '{
    "firstName": "James",
    "lastName": "Brown",
    "email": "james@brown.com",
    "externalCustomerId": "Your customer id"
  }'
Click to expand JSON data response 
    {
      "data": {
        "id": "3232505a-62a5-4e80-b93e-9f013bc2e1e0",
        "type": "customer",
        "attributes": {
          "firstName": "James",
          "lastName": "Brown",
          "email": "james@brown.com",
          "externalCustomerId": "Your customer id"
        }
      }
    }

Update customer

HTTP Request

PATCH https://platform.tier-services.io/v1/customer/:customerId

PATCH Data

See POST Data

curl "https://platform.tier-services.io/v1/customer/:customerId"
  -X PATCH
  -H "x-api-key: TIER API KEY"
  -d '{
    "firstName": "James",
    "lastName": "Brown",
    "email": "james@brown.com",
    "externalCustomerId": "Your customer id"
  }'

Delete customer

This anonymizes the data according to GDPR law. Customers can delete themselves using the JWT token. Partners can delete all customers they have created

HTTP Request

DELETE https://platform.tier-services.io/v1/customer

curl "https://platform.tier-services.io/v1/customer/3232505a-62a5-4e80-b93e-9f013bc2e1e0"
  -X DELETE
  -H "x-api-key: TIER API KEY"

curl "https://platform.tier-services.io/v1/customer"
  -X DELETE
  -H "X-Firebase-Auth: Bearer JWT"

Get customer

The customer endpoint is using JWT for authentication

HTTP Request

GET https://platform.tier-services.io/v1/customer/<customer-id>

curl "https://platform.tier-services.io/v1/customer/<customer-id>"
  -H "x-api-key: TIER API KEY"
Click to expand JSON data response 
    {
      "data": {
        "id": "3232505a-62a5-4e80-b93e-9f013bc2e1e0",
        "type": "customer",
        "attributes": {
          "firstName": "James",
          "lastName": "Brown",
          "email": "james@brown.com",
          "externalCustomerId": "Your customer id"
        }
      }
    }

Get Customer Free Rides

This customer endpoint is using JWT for authentication and the pagination is JSON-API spec compliant.

HTTP Request

GET https://platform.tier-services.io/v1/customer/free-ride

curl "https://platform.tier-services.io/v1/customer/free-ride" 
  -H "X-Firebase-Auth: Bearer JWT"
Click to expand JSON data response 
    {
      "data": [{
        "type": "freeride",
        "attributes": {
          "freeUnlock": true,
          "freeMinutes": 10,
          "usedFor": 0
        }
      }],
      "meta": {
        "pagination": {
          "page": 1,
          "pages": 1,
          "count": 1
        }
      },
      "links": {
        "first": "",
        "last": "",
        "next": null,
        "prev": null
      }
    }

Get current rental of a customer

This endpoint can be used to get the current rental of a customer by customer id.

💡 Note: You can only use the TIER customer UUID and not the externalCustomerId for looking up rentals.

The externalCustomerId is not validated on our side and is only for your convenience. We do not assure uniqueness and therefore also do not allow lookups based on this id.

HTTP Request

GET https://platform.tier-services.io/v1/customer/<customer-id>/current-rental

curl "https://platform.tier-services.io/v1/customer/0c00faf3-3923-4fe4-a2c1-88b4c2268a2c/current-rental" 
  -H "x-api-key: TIER API KEY"
Click to expand JSON data response 
    {
        "data": {
            "type": "current-rental",
            "id": "4a35a1bd-fa1a-4b56-ab8d-4b93a2f7534b",
            "attributes": {
                "rideDurationMin": 83,
                "pauseDurationMin": 0,
                "cost": {
                    "unlock": {
                        "amount": "1.00",
                        "currency": "EUR"
                    },
                    "ride": {
                        "amount": "0.00",
                        "currency": "EUR"
                    },
                    "pause": {
                        "amount": "0.00",
                        "currency": "EUR"
                    },
                    "total": {
                        "amount": "0.00",
                        "currency": "EUR"
                    }
                },
                "state": "RUNNING",
                "startedAt": "2019-08-10T15:57:39Z",
                "customerStartLocation": null,
                "customerEndLocation": null,
                "vehicleStartLocation": {
                    "lat": 52.513656,
                    "lng": 13.296032
                },
                "vehicle": {
                    "vehicleId": "8c0b2bd6-889a-49f3-8464-3f597ac387a2",
                    "vehicleCode": 119970
                },
                "stateHistory": [
                    {
                        "createdAt": "2019-08-10T15:57:39.680734Z",
                        "state": "RUNNING"
                    },
                ]
            },
        }
    }

Customer-Specific error codes

The Tier API can respond with the following customer specific error codes:

Error Codes

Error Code Meaning Code
400 Malformed email and missing firebaseId ValidationError

Please find the specific responses in the shell.

The command to create a customer

curl "https://platform.tier-services.io/v1/customer"
  -X POST
  -H "x-api-key: TIER API KEY"
  -d '{
    "email": "malformed-email",
    "firstName": "John",
    "lastName": "Doe",
    "locale": "es_ES"
  }'
  • returns a JSON structured like this if the email is malformed and the externalCustomerId is missing. Click â–¶ button
Click to expand JSON data response 
    {
      "errors": [
        {
          "code": "ValidationError",
          "title": "Enter a valid email address.",
          "status": "400"
        },
        {
          "code": "ValidationError",
          "title": "Missing required field externalCustomerId.",
          "status": "400"
        }
      ]
    }

The command to get the current rental of a customer

curl "https://platform.tier-services.io/v1/customer/0c00faf3-3923-4fe4-a2c1-88b4c2268a2c/current-rental" 
  -H "x-api-key: TIER API KEY"
  • returns a JSON structured like this if there is no running rental for that customer
Click to expand JSON data response 
      {
          "errors": [
              {
                  "source": {
                      "pointer": "/data"
                  },
                  "status": "404",
                  "title": "No running rental found",
                  "code": "RentalNotFound"
              }
          ]
      }