Customers

Customers represent individual people that interact and spend money within your organization. Besides storing common contact information, customer objects are also responsible for tracking spending behaviors, metadata, and permissions.

The Customer Object

The associated customer which has been updated

Required attributes

Name
_id
Type
string
Description
The ID of the customer
Name
primaryEmail
Type
string
Description
The primary email of the customer

Optional attributes

Name
company
Type
string
Description
The company of the customer
Name
name
Type
string
Description
The name of the customer collected from first name and last name
Name
prename
Type
string
Description
The first name of the customer
Name
lastname
Type
string
Description
The lastname of the customer
Name
image
Type
string
Description
The image of the customer
Name
number
Type
number
Description
The number of the customer. Need to be unique and incrementing
Name
phone
Type
string
Description
The phone number of the customer
Name
location
Type
object
Description
The location of the customer
Optional nested attributes (8)
Name
street
Type
string
Description
The street of the location
Name
line2
Type
string
Description
The additional address fields of the location
Name
postal
Type
string
Description
The postal of the location
Name
city
Type
string
Description
The city of the location
Name
locale
Type
string
Description
The locale of the location
Name
state
Type
string
Description
The state of the location
Name
center
Type
array<number>
Description
The center of the location
Name
country
Type
string
Description
An ISO-3166-1 Alpha 2 country code of the location
Name
sellerId
Type
string
Description
The ID of the seller of the customer
Name
notes
Type
string
Description
Notes of the customer
Name
extraFields
Type
object
Description
Extra fields of the customer
Name
tags
Type
array<string>
Description
An array of tags
Name
segments
Type
array<string>
Description
An array of segment slugs, read only
Name
blocked
Type
boolean
Description
Whether the customer is blocked
Name
verified
Type
boolean
Description
Whether the customer is verified
Name
identification
Type
array<object>
Description
An array of identification items
Name
_account
Type
object
Description
Account specific information about the customer
Optional nested attributes (4)
Name
verificationToken
Type
string
Description
The verification token will be sent to the customer via email within a verification link, which can be used to verify the account of the customer
Name
passwordResetToken
Type
string
Description
The password reset token will be sent within a password reset link via email, which can be used by the customer to reset its password
Name
limitations
Type
object
Description
Account specific limitations of the customer
Optional nested attributes (1)
Name
nextVerificationMailRequest
Type
string
Description
An ISO timestamp indicating when the next verification mail request can be sent
Name
loginType
Type
enum(password, identityprovider)
Description
The login type of the customer.
Name
meta
Type
object
Description
Custom key-value data. Metadata is useful for storing additional, structured information on an object.
Name
externalId
Type
string
Description
An external identifier of the customer
Name
createdAt
Type
string
Description
An ISO timestamp indicating when the customer was created
Name
updatedAt
Type
string
Description
An ISO timestamp indicating when the customer was updated

Example

{
  "_id": "507f191e810c19729de860ea",
  "primaryEmail": "example@vivenu.com",
  "company": "string",
  "name": "Example Name",
  "prename": "string",
  "lastname": "string",
  "image": "string",
  "number": 10.5,
  "phone": "string",
  "location": {
    "street": "string",
    "line2": "string",
    "postal": "string",
    "city": "string",
    "locale": "string",
    "state": "string",
    "center": [
      10.5
    ],
    "country": "string"
  },
  "sellerId": "507f191e810c19729de860ea",
  "notes": "string",
  "extraFields": {},
  "tags": [
    "string"
  ],
  "segments": [
    "string"
  ],
  "blocked": true,
  "verified": true,
  "identification": [],
  "_account": {
    "verificationToken": "string",
    "passwordResetToken": "string",
    "limitations": {
      "nextVerificationMailRequest": "2030-01-23T23:00:00.123Z"
    },
    "loginType": "password"
  },
  "meta": {},
  "externalId": "507f191e810c19729de860ea",
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z"
}

POST/api/customers

Create Customer

Payload

Required attributes

Name
primaryEmail
Type
string
Description
The primary email of the customer

Optional attributes

Name
company
Type
string
Description
The company of the customer
Name
name
Type
string
Description
The name of the customer collected from first name and last name
Name
prename
Type
string
Description
The first name of the customer
Name
lastname
Type
string
Description
The lastname of the customer
Name
number
Type
number
Description
The number of the customer. Need to be unique and incrementing
Name
image
Type
string
Description
The image of the customer
Name
location
Type
object
Description
The location of the customer
Optional nested attributes (8)
Name
street
Type
string
Description
The street of the location
Name
line2
Type
string
Description
The additional address fields of the location
Name
postal
Type
string
Description
The postal of the location
Name
city
Type
string
Description
The city of the location
Name
locale
Type
string
Description
The locale of the location
Name
state
Type
string
Description
The state of the location
Name
center
Type
array<number>
Description
The center of the location
Name
country
Type
string
Description
An ISO-3166-1 Alpha 2 country code of the location
Name
notes
Type
string
Description
Notes of the customer
Name
extraFields
Type
object
Description
Extra fields of the customer
Name
tags
Type
array<string>
Description
An array of tags
Name
verified
Type
boolean
Description
Whether the customer is verified
Name
meta
Type
object
Description
Custom key-value data. Metadata is useful for storing additional, structured information on an object.
Name
externalId
Type
string
Description
An external identifier of the customer
Name
identification
Type
array<object>
Description
An array of identification items
Name
consents
Type
array<object>
Description
Optional consents provided during creation
Required nested attributes (2)
Name
consentId
Type
string
Description
Name
status
Type
enum(granted, denied)
Description
Name
phone
Type
string
Description
The phone number of the customer
Name
upsert
Type
boolean
Description
If false, reject creation when the email already exists

Request

POST

/api/customers

const response = await fetch('https://vivenu.com/api/customers', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer {token}',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(  {
    "primaryEmail": "example@vivenu.com",
    "company": "string",
    "name": "Example Name",
    "prename": "string",
    "lastname": "string",
    "number": 10.5,
    "image": "string",
    "location": {
      "street": "string",
      "line2": "string",
      "postal": "string",
      "city": "string",
      "locale": "string",
      "state": "string",
      "center": [
        10.5
      ],
      "country": "string"
    },
    "notes": "string",
    "extraFields": {},
    "tags": [
      "string"
    ],
    "verified": true,
    "meta": {},
    "externalId": "507f191e810c19729de860ea",
    "identification": [],
    "consents": [
      {
        "consentId": "507f191e810c19729de860ea",
        "status": "granted"
      }
    ],
    "phone": "string",
    "upsert": true
  }),
})

const data = await response.json()

Response (200)

{
  "_id": "507f191e810c19729de860ea",
  "primaryEmail": "example@vivenu.com",
  "company": "string",
  "name": "Example Name",
  "prename": "string",
  "lastname": "string",
  "image": "string",
  "number": 10.5,
  "phone": "string",
  "location": {
    "street": "string",
    "line2": "string",
    "postal": "string",
    "city": "string",
    "locale": "string",
    "state": "string",
    "center": [
      10.5
    ],
    "country": "string"
  },
  "sellerId": "507f191e810c19729de860ea",
  "notes": "string",
  "extraFields": {},
  "tags": [
    "string"
  ],
  "segments": [
    "string"
  ],
  "blocked": true,
  "verified": true,
  "identification": [],
  "_account": {
    "verificationToken": "string",
    "passwordResetToken": "string",
    "limitations": {
      "nextVerificationMailRequest": "2030-01-23T23:00:00.123Z"
    },
    "loginType": "password"
  },
  "meta": {},
  "externalId": "507f191e810c19729de860ea",
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z"
}

GET/api/customers/:id

Get Customer

Request

GET

/api/customers/:id

const response = await fetch('https://vivenu.com/api/customers/507f191e810c19729de860ea', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer {token}',
  },
})

const data = await response.json()

Response (200)

{
  "_id": "507f191e810c19729de860ea",
  "primaryEmail": "example@vivenu.com",
  "company": "string",
  "name": "Example Name",
  "prename": "string",
  "lastname": "string",
  "image": "string",
  "number": 10.5,
  "phone": "string",
  "location": {
    "street": "string",
    "line2": "string",
    "postal": "string",
    "city": "string",
    "locale": "string",
    "state": "string",
    "center": [
      10.5
    ],
    "country": "string"
  },
  "sellerId": "507f191e810c19729de860ea",
  "notes": "string",
  "extraFields": {},
  "tags": [
    "string"
  ],
  "segments": [
    "string"
  ],
  "blocked": true,
  "verified": true,
  "identification": [],
  "_account": {
    "verificationToken": "string",
    "passwordResetToken": "string",
    "limitations": {
      "nextVerificationMailRequest": "2030-01-23T23:00:00.123Z"
    },
    "loginType": "password"
  },
  "meta": {},
  "externalId": "507f191e810c19729de860ea",
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z"
}

PUT/api/customers/:id

Update Customer

Payload

Optional attributes

Name
company
Type
string
Description
The company of the customer
Name
name
Type
string
Description
The name of the customer collected from first name and last name
Name
image
Type
string
Description
The image of the customer
Name
location
Type
object
Description
The location of the customer
Optional nested attributes (8)
Name
street
Type
string
Description
The street of the location
Name
line2
Type
string
Description
The additional address fields of the location
Name
postal
Type
string
Description
The postal of the location
Name
city
Type
string
Description
The city of the location
Name
locale
Type
string
Description
The locale of the location
Name
state
Type
string
Description
The state of the location
Name
center
Type
array<number>
Description
The center of the location
Name
country
Type
string
Description
An ISO-3166-1 Alpha 2 country code of the location
Name
tags
Type
array<string>
Description
An array of tags
Name
extraFields
Type
object
Description
Extra fields of the customer
Name
verified
Type
boolean
Description
Whether the customer is verified
Name
meta
Type
object
Description
Custom key-value data. Metadata is useful for storing additional, structured information on an object.
Name
externalId
Type
string
Description
An external identifier of the customer
Name
identification
Type
array<object>
Description
An array of identification items
Name
primaryEmail
Type
string
Description
The primary email of the customer
Name
phone
Type
string
Description
The phone number of the customer
Name
prename
Type
string
Description
The first name of the customer
Name
lastname
Type
string
Description
The last name of the customer
Name
notes
Type
string
Description
Notes for the customer
Name
blocked
Type
boolean
Description
Whether the customer is blocked
Name
consents
Type
array<object>
Description
Optional consents to merge into the customer
Required nested attributes (2)
Name
consentId
Type
string
Description
Name
status
Type
enum(granted, denied)
Description

Request

PUT

/api/customers/:id

const response = await fetch('https://vivenu.com/api/customers/507f191e810c19729de860ea', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer {token}',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(  {
    "company": "string",
    "name": "Example Name",
    "image": "string",
    "location": {
      "street": "string",
      "line2": "string",
      "postal": "string",
      "city": "string",
      "locale": "string",
      "state": "string",
      "center": [
        10.5
      ],
      "country": "string"
    },
    "tags": [
      "string"
    ],
    "extraFields": {},
    "verified": true,
    "meta": {},
    "externalId": "507f191e810c19729de860ea",
    "identification": [],
    "primaryEmail": "example@vivenu.com",
    "phone": "string",
    "prename": "string",
    "lastname": "string",
    "notes": "string",
    "blocked": true,
    "consents": [
      {
        "consentId": "507f191e810c19729de860ea",
        "status": "granted"
      }
    ]
  }),
})

const data = await response.json()

Response (200)

{
  "_id": "507f191e810c19729de860ea",
  "primaryEmail": "example@vivenu.com",
  "company": "string",
  "name": "Example Name",
  "prename": "string",
  "lastname": "string",
  "image": "string",
  "number": 10.5,
  "phone": "string",
  "location": {
    "street": "string",
    "line2": "string",
    "postal": "string",
    "city": "string",
    "locale": "string",
    "state": "string",
    "center": [
      10.5
    ],
    "country": "string"
  },
  "sellerId": "507f191e810c19729de860ea",
  "notes": "string",
  "extraFields": {},
  "tags": [
    "string"
  ],
  "segments": [
    "string"
  ],
  "blocked": true,
  "verified": true,
  "identification": [],
  "_account": {
    "verificationToken": "string",
    "passwordResetToken": "string",
    "limitations": {
      "nextVerificationMailRequest": "2030-01-23T23:00:00.123Z"
    },
    "loginType": "password"
  },
  "meta": {},
  "externalId": "507f191e810c19729de860ea",
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z"
}

DELETE/api/customers/:id

Delete Customer

Request

DELETE

/api/customers/:id

const response = await fetch('https://vivenu.com/api/customers/507f191e810c19729de860ea', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer {token}',
  },
})

const data = await response.json()

Response (200)

{
  "_id": "507f191e810c19729de860ea",
  "primaryEmail": "example@vivenu.com",
  "company": "string",
  "name": "Example Name",
  "prename": "string",
  "lastname": "string",
  "image": "string",
  "number": 10.5,
  "phone": "string",
  "location": {
    "street": "string",
    "line2": "string",
    "postal": "string",
    "city": "string",
    "locale": "string",
    "state": "string",
    "center": [
      10.5
    ],
    "country": "string"
  },
  "sellerId": "507f191e810c19729de860ea",
  "notes": "string",
  "extraFields": {},
  "tags": [
    "string"
  ],
  "segments": [
    "string"
  ],
  "blocked": true,
  "verified": true,
  "identification": [],
  "_account": {
    "verificationToken": "string",
    "passwordResetToken": "string",
    "limitations": {
      "nextVerificationMailRequest": "2030-01-23T23:00:00.123Z"
    },
    "loginType": "password"
  },
  "meta": {},
  "externalId": "507f191e810c19729de860ea",
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z"
}

GET/api/customers/rich

Get all Customers

Query parameters

Optional query parameters

Name
name
Type
string
Description
Name
email
Type
string
Description
Name
company
Type
string
Description
Name
tags
Type
string
Description
Name
updatedAt
Type
object
Description
Name
top
Type
integer
Description
Name
skip
Type
integer
Description

Request

GET

/api/customers/rich

const response = await fetch('https://vivenu.com/api/customers/rich?name=Example+Name&email=example%40vivenu.com&company=value&tags=value&updatedAt=2030-01-23T23%3A00%3A00.123Z&top=1&skip=1', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer {token}',
  },
})

const data = await response.json()

Response (200)

{
  "docs": [],
  "total": 1
}

GET/api/customers/:id/balance

Get Customer Balance

Request

GET

/api/customers/:id/balance

const response = await fetch('https://vivenu.com/api/customers/507f191e810c19729de860ea/balance', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer {token}',
  },
})

const data = await response.json()

Response (200)

{
  "_id": "507f191e810c19729de860ea",
  "primaryEmail": "example@vivenu.com",
  "company": "string",
  "name": "Example Name",
  "prename": "string",
  "lastname": "string",
  "image": "string",
  "number": 10.5,
  "phone": "string",
  "location": {
    "street": "string",
    "line2": "string",
    "postal": "string",
    "city": "string",
    "locale": "string",
    "state": "string",
    "center": [
      10.5
    ],
    "country": "string"
  },
  "sellerId": "507f191e810c19729de860ea",
  "notes": "string",
  "extraFields": {},
  "tags": [
    "string"
  ],
  "segments": [
    "string"
  ],
  "blocked": true,
  "verified": true,
  "identification": [],
  "_account": {
    "verificationToken": "string",
    "passwordResetToken": "string",
    "limitations": {
      "nextVerificationMailRequest": "2030-01-23T23:00:00.123Z"
    },
    "loginType": "password"
  },
  "meta": {},
  "externalId": "507f191e810c19729de860ea",
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z"
}

GET/api/customers/tags

Get all Customer tags

Request

GET

/api/customers/tags

const response = await fetch('https://vivenu.com/api/customers/tags', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer {token}',
  },
})

const data = await response.json()

Response (200)

[
  "string"
]

POST/api/customers/:id/account

Create account for Customer

Payload

Optional attributes

Name
suppressEmail
Type
boolean
Description
Whether the email of the customer should be suppressed in the account of the customer

Request

POST

/api/customers/:id/account

const response = await fetch('https://vivenu.com/api/customers/507f191e810c19729de860ea/account', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer {token}',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(  {
    "suppressEmail": true
  }),
})

const data = await response.json()

Response (200)

{
  "_id": "507f191e810c19729de860ea",
  "primaryEmail": "example@vivenu.com",
  "company": "string",
  "name": "Example Name",
  "prename": "string",
  "lastname": "string",
  "image": "string",
  "number": 10.5,
  "phone": "string",
  "location": {
    "street": "string",
    "line2": "string",
    "postal": "string",
    "city": "string",
    "locale": "string",
    "state": "string",
    "center": [
      10.5
    ],
    "country": "string"
  },
  "sellerId": "507f191e810c19729de860ea",
  "notes": "string",
  "extraFields": {},
  "tags": [
    "string"
  ],
  "segments": [
    "string"
  ],
  "blocked": true,
  "verified": true,
  "identification": [],
  "_account": {
    "verificationToken": "string",
    "passwordResetToken": "string",
    "limitations": {
      "nextVerificationMailRequest": "2030-01-23T23:00:00.123Z"
    },
    "loginType": "password"
  },
  "meta": {},
  "externalId": "507f191e810c19729de860ea",
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z"
}

GET/api/customers/me

Get current customer

Request

GET

/api/customers/me

const response = await fetch('https://vivenu.com/api/customers/me', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer {token}',
  },
})

const data = await response.json()

Response (200)

{
  "_id": "507f191e810c19729de860ea",
  "primaryEmail": "example@vivenu.com",
  "company": "string",
  "name": "Example Name",
  "prename": "string",
  "lastname": "string",
  "image": "string",
  "number": 10.5,
  "phone": "string",
  "location": {
    "street": "string",
    "line2": "string",
    "postal": "string",
    "city": "string",
    "locale": "string",
    "state": "string",
    "center": [
      10.5
    ],
    "country": "string"
  },
  "sellerId": "507f191e810c19729de860ea",
  "notes": "string",
  "extraFields": {},
  "tags": [
    "string"
  ],
  "segments": [
    "string"
  ],
  "blocked": true,
  "verified": true,
  "identification": [],
  "_account": {
    "verificationToken": "string",
    "passwordResetToken": "string",
    "limitations": {
      "nextVerificationMailRequest": "2030-01-23T23:00:00.123Z"
    },
    "loginType": "password"
  },
  "meta": {},
  "externalId": "507f191e810c19729de860ea",
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z"
}

GET/api/customers/me/transactions

Get transactions of customer

Query parameters

Optional query parameters

Name
locale
Type
string
Description
Name
subscriptionId
Type
string
Description
Name
checkoutId
Type
string
Description

Request

GET

/api/customers/me/transactions

const response = await fetch('https://vivenu.com/api/customers/me/transactions?locale=value&subscriptionId=507f191e810c19729de860ea&checkoutId=507f191e810c19729de860ea', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer {token}',
  },
})

const data = await response.json()

Response (200)

{
  "transactions": [
    {
      "tid": "507f191e810c19729de860ea",
      "secret": "string",
      "realPrice": 10.5,
      "status": "NEW",
      "eventId": "507f191e810c19729de860ea",
      "tickets": [],
      "products": [],
      "currency": "EUR",
      "vouchers": [
        "string"
      ],
      "redeemedVouchers": {
        "totalRedeemedAmount": 10.5,
        "vouchers": [
          {
            "code": "string",
            "redeemedAmount": 10.5,
            "_id": "507f191e810c19729de860ea"
          }
        ]
      },
      "email": "example@vivenu.com",
      "company": "string",
      "name": "Example Name",
      "prename": "string",
      "lastname": "string",
      "street": "string",
      "line2": "string",
      "postal": "string",
      "city": "string",
      "state": "string",
      "country": "string",
      "createdAt": "2030-01-23T23:00:00.123Z",
      "paymentStatus": "AWAITING",
      "outerCharge": 10.5,
      "paymentMethod": "paypal",
      "preferredLanguage": "de",
      "extraFields": {},
      "underShop": "string",
      "paymentInfoMethod": "string",
      "coupons": [
        "string"
      ]
    }
  ],
  "events": []
}

GET/api/customers/me/shops

Get undershops of customer

Query parameters

Required query parameters

Name
eventId
Type
string
Description

Optional query parameters

Name
locale
Type
string
Description

Request

GET

/api/customers/me/shops

const response = await fetch('https://vivenu.com/api/customers/me/shops?eventId=507f191e810c19729de860ea&locale=value', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer {token}',
  },
})

const data = await response.json()

Response (200)

{
  "shops": [
    {
      "_id": "507f191e810c19729de860ea",
      "name": "Example Name"
    }
  ]
}