Documentation

API reference

Customers

Customers are the people who order from you.

Base URL: https://apiv2.venuerun.com/merchants/:merchantId/customers

text

GET    /merchants/:merchantId/customers
POST   /merchants/:merchantId/customers
GET    /merchants/:merchantId/customers/:customerId
POST   /merchants/:merchantId/customers/:customerId
PATCH  /merchants/:merchantId/customers/:customerId
DELETE /merchants/:merchantId/customers/:customerId

The customer object

Field	Type	Description
`id`	`string` (read-only)	Unique identifier, assigned by VenueRun.
`createdAt`	`string` (read-only)	When it was created (ISO 8601).
`updatedAt`	`string` (read-only)	When it last changed (ISO 8601).
`firstName`	`string`	Defaults to `""`.
`lastName`	`string`	Defaults to `""`.
`email`	`string \| ""`	Defaults to `""`.
`phone`	`string`	Defaults to `""`.
`testMode`	`boolean`	Defaults to `false`.

json

{
  "id": "vWUExowomFhOCXtHnd0D",
  "firstName": "Test",
  "lastName": "A1B2C3",
  "email": "test-a1b2c3@example.com",
  "phone": "5555550123",
  "metadata": [],
  "testMode": true,
  "createdAt": "2026-01-15T12:00:00.000Z",
  "updatedAt": "2026-01-15T12:00:00.000Z"
}

List customers

GET /merchants/:merchantId/customers

javascript

const merchantId = process.env.VENUERUN_MERCHANT_ID;
const response = await fetch(`https://apiv2.venuerun.com/merchants/${merchantId}/customers`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.VENUERUN_API_KEY}`,
  },
});

Response:

json

{
  "testMode": true,
  "length": 1,
  "data": [
    {
      "id": "vWUExowomFhOCXtHnd0D",
      "firstName": "Test",
      "lastName": "A1B2C3",
      "email": "test-a1b2c3@example.com",
      "phone": "5555550123",
      "metadata": [],
      "testMode": true,
      "createdAt": "2026-01-15T12:00:00.000Z",
      "updatedAt": "2026-01-15T12:00:00.000Z"
    }
  ]
}

Create a customer

POST /merchants/:merchantId/customers

Required attributes

None.

Optional attributes

Field	Type	Description
`firstName`	`string`	Defaults to `""`.
`lastName`	`string`	Defaults to `""`.
`email`	`string \| ""`	Defaults to `""`.
`phone`	`string`	Defaults to `""`.
`testMode`	`boolean`	Defaults to `false`.

javascript

const merchantId = process.env.VENUERUN_MERCHANT_ID;
const response = await fetch(`https://apiv2.venuerun.com/merchants/${merchantId}/customers`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VENUERUN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "firstName": "Test",
    "lastName": "A1B2C3",
    "email": "test-a1b2c3@example.com",
    "phone": "5555550123",
    "testMode": true
  }),
});

Response:

json

{
  "id": "rU3sIWRZVrIwZ1TYzYf7",
  "firstName": "Test",
  "lastName": "A1B2C3",
  "email": "test-a1b2c3@example.com",
  "phone": "5555550123",
  "metadata": [],
  "testMode": true,
  "createdAt": "2026-01-15T12:00:00.000Z",
  "updatedAt": "2026-01-15T12:00:00.000Z"
}

Retrieve a customer

GET /merchants/:merchantId/customers/:customerId

javascript

const merchantId = process.env.VENUERUN_MERCHANT_ID;
const response = await fetch(`https://apiv2.venuerun.com/merchants/${merchantId}/customers/nWZayxunrPXlvmav8Sxs`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.VENUERUN_API_KEY}`,
  },
});

Response:

json

{
  "id": "nWZayxunrPXlvmav8Sxs",
  "firstName": "Test",
  "lastName": "A1B2C3",
  "email": "test-a1b2c3@example.com",
  "phone": "5555550123",
  "metadata": [],
  "testMode": true,
  "createdAt": "2026-01-15T12:00:00.000Z",
  "updatedAt": "2026-01-15T12:00:00.000Z"
}

Update a customer (POST alias)

POST /merchants/:merchantId/customers/:customerId

Send only the fields you are changing — every attribute is optional.

javascript

const merchantId = process.env.VENUERUN_MERCHANT_ID;
const response = await fetch(`https://apiv2.venuerun.com/merchants/${merchantId}/customers/VONdRtILTz1hwsWhnlGD`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VENUERUN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "phone": "5555559999"
  }),
});

Response:

json

{
  "id": "VONdRtILTz1hwsWhnlGD",
  "firstName": "Test",
  "lastName": "A1B2C3",
  "email": "test-a1b2c3@example.com",
  "phone": "5555559999",
  "metadata": [],
  "testMode": true,
  "createdAt": "2026-01-15T12:00:00.000Z",
  "updatedAt": "2026-01-15T12:00:00.000Z"
}

Update a customer

PATCH /merchants/:merchantId/customers/:customerId

Send only the fields you are changing — every attribute is optional.

javascript

const merchantId = process.env.VENUERUN_MERCHANT_ID;
const response = await fetch(`https://apiv2.venuerun.com/merchants/${merchantId}/customers/ly2raY7myH3XtkHvxxxz`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.VENUERUN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "firstName": "Renamed"
  }),
});

Response:

json

{
  "id": "ly2raY7myH3XtkHvxxxz",
  "firstName": "Renamed",
  "lastName": "A1B2C3",
  "email": "test-a1b2c3@example.com",
  "phone": "5555550123",
  "metadata": [],
  "testMode": true,
  "createdAt": "2026-01-15T12:00:00.000Z",
  "updatedAt": "2026-01-15T12:00:00.000Z"
}

Delete a customer

DELETE /merchants/:merchantId/customers/:customerId

javascript

const merchantId = process.env.VENUERUN_MERCHANT_ID;
const response = await fetch(`https://apiv2.venuerun.com/merchants/${merchantId}/customers/Hbn6KlB4RU2mXuOvPIIP`, {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.VENUERUN_API_KEY}`,
  },
});

Response:

json

{
  "id": "Hbn6KlB4RU2mXuOvPIIP",
  "object": {
    "id": "Hbn6KlB4RU2mXuOvPIIP",
    "firstName": "Renamed",
    "lastName": "A1B2C3",
    "email": "test-a1b2c3@example.com",
    "phone": "5555550123",
    "metadata": [],
    "testMode": true,
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z"
  },
  "message": "Customer deleted",
  "deleted": true
}

Errors

Every error answers with a message. A request that fails validation is a 400:

json

{
  "message": "An API key in test mode cannot create a live mode customer."
}