MOmonei
Customers

Create Customer

Changed on

Creates a customer.

Every field is optional — a customer with no details at all is valid, and useful if you only want somewhere to attach saved payment methods.

Pass the returned id as customerId when you create a payment or a subscription to link it to this buyer.

What linking does:

  • A payment saved with generatePaymentToken stores its payment method under this customer
  • The customer's details are copied onto the payment at the time it is made. Editing the customer later never rewrites a payment that already happened
  • A subscription gains renewal failover across the customer's other saved payment methods

Best practices:

  • Create the customer once, when the buyer first registers with you, and reuse the id
  • Use metadata to store your own user identifier, so you can match your records to MONEI's
post/customers

Request

Request body

emailstring

The customer's email address.

namestring

The customer's full name or business name.

phonestring

The customer's phone number in E.164 format.

metadataMetadata

A set of key-value pairs that you can attach to a resource. This can be useful for storing additional information about the resource in a structured format.

Example request

{
  "email": "john.doe@example.com",
  "name": "John Doe",
  "phone": "+34666666666",
  "billingDetails": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "address": {
      "country": "ES",
      "city": "Málaga",
      "line1": "Fake Street 123",
      "zip": "1234",
      "state": "Málaga"
    }
  },
  "shippingDetails": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "address": {
      "country": "ES",
      "city": "Málaga",
      "line1": "Fake Street 123",
      "zip": "1234",
      "state": "Málaga"
    }
  },
  "metadata": {
    "systemId": "12345"
  }
}

Response

A customer object

idstring uuid required

Unique identifier for the customer.

emailstring

The customer's email address.

namestring

The customer's full name or business name.

phonestring

The customer's phone number in E.164 format.

metadataMetadata

A set of key-value pairs that you can attach to a resource. This can be useful for storing additional information about the resource in a structured format.

defaultTokenIdstring

The payment method charged when a payment sets useDefaultPaymentMethod.

MONEI fills this only while it is empty: the first reusable payment method the customer saves becomes the default, and a value you set here is kept. Deleting that payment method clears the field, so the next reusable one the customer saves becomes the new default. It must be the ID of a payment method this customer already owns, and one that can be reused for future payments.

createdAtstring date-time

Time at which the resource was created.

updatedAtstring date-time

Time at which the resource was last updated.

Example response

{
  "id": "a4e1d1dd-e0c2-4f7a-a2b1-2b0f1f9b6b1e",
  "email": "john.doe@example.com",
  "name": "John Doe",
  "phone": "+34666666666",
  "billingDetails": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "address": {
      "country": "ES",
      "city": "Málaga",
      "line1": "Fake Street 123",
      "zip": "1234",
      "state": "Málaga"
    }
  },
  "shippingDetails": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "address": {
      "country": "ES",
      "city": "Málaga",
      "line1": "Fake Street 123",
      "zip": "1234",
      "state": "Málaga"
    }
  },
  "metadata": {
    "systemId": "12345"
  },
  "defaultTokenId": "7cc38b08ff471ccd313ad62b23b9f362b107560b",
  "createdAt": "2026-09-21T10:25:52.000Z",
  "updatedAt": "2026-09-21T10:25:52.000Z"
}

Changes