Get customers

GET

customers

curl --request GET \
  --url https://api.hyperline.co/v1/customers \
  --header 'Authorization: Bearer <token>'

{
  "meta": {
    "total": 1,
    "taken": 1,
    "skipped": 0
  },
  "data": [
    {
      "id": "cus_Typ0px2W0aiEtl",
      "name": "Acme",
      "type": "corporate",
      "status": "active",
      "currency": "EUR",
      "country": "FR",
      "vat_number": "FR123456789",
      "vat_number_valid": true,
      "vat_rate_custom": 123,
      "language": "fr",
      "timezone": "Europe/Paris",
      "external_id": "<string>",
      "properties": {},
      "custom_properties": {},
      "billing_address": {
        "name": "Acme",
        "line1": "5 rue de Paradis",
        "line2": "<string>",
        "city": "Paris",
        "zip": "75010",
        "state": "<string>",
        "country": "FR"
      },
      "billing_email": "billing@acme.com",
      "invoice_emails": [
        "accounting@acme.com"
      ],
      "invoicing_entity_id": "ive_484dn4U48E",
      "invoice_reminders_enabled": true,
      "price_book_id": "prib_613_WbVIZ1329e",
      "available_payment_methods": [
        "card",
        "direct_debit"
      ],
      "current_payment_method_type": "card",
      "current_payment_method_id": "pm_UTclbc1US8GzCe",
      "custom_payment_delay": 30,
      "subscriptions": [
        {
          "id": "sub_0kIc7jrF7gV00V",
          "status": "active",
          "current_period_started_at": "2024-10-12T07:00:01.860Z",
          "current_period_ends_at": "2024-11-12T07:00:01.860Z",
          "plan_id": "plan_34hdd843hReh",
          "checkout_session_id": "che_949djdj39RJj"
        }
      ],
      "created_at": "2024-10-12T07:00:01.860Z",
      "updated_at": "2024-10-12T07:00:01.860Z",
      "deleted_at": "2024-10-13T02:00:00.000Z"
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

take

number | null

default:50

Required range: 0 <= x <= 100

skip

number | null

default:0

Required range: x >= 0

string

id__not

string

id__isNull

string

id__isNotNull

string

id__equals

string

id__contains

string

id__startsWith

string

id__endWith

string

name

string

name__not

string

name__isNull

string

name__isNotNull

string

name__equals

string

name__contains

string

name__startsWith

string

name__endWith

string

type

string

type__not

string

type__isNull

string

type__isNotNull

string

type__equals

string

type__contains

string

type__startsWith

string

type__endWith

string

status

Available options:

all,

active,

inactive,

imported,

archived

status__in

Available options:

all,

active,

inactive,

imported,

archived

currency

string

currency__not

string

currency__isNull

string

currency__isNotNull

string

currency__equals

string

currency__contains

string

currency__startsWith

string

currency__endWith

string

country

string

country__not

string

country__isNull

string

country__isNotNull

string

country__equals

string

country__contains

string

country__startsWith

string

country__endWith

string

vat_number

string

vat_number__not

string

vat_number__isNull

string

vat_number__isNotNull

string

vat_number__equals

string

vat_number__contains

string

vat_number__startsWith

string

vat_number__endWith

string

external_id

string

external_id__not

string

external_id__isNull

string

external_id__isNotNull

string

external_id__equals

string

external_id__contains

string

external_id__startsWith

string

external_id__endWith

string

billing_email

string

billing_email__not

string

billing_email__isNull

string

billing_email__isNotNull

string

billing_email__equals

string

billing_email__contains

string

billing_email__startsWith

string

billing_email__endWith

string

subscription_status

Available options:

active,

pending,

cancelled,

paused,

trialing,

errored,

draft,

none

subscription_status__in

Available options:

active,

pending,

cancelled,

paused,

trialing,

errored,

draft,

none

invoicing_entity_id

string

invoicing_entity_id__not

string

invoicing_entity_id__isNull

string

invoicing_entity_id__isNotNull

string

invoicing_entity_id__equals

string

invoicing_entity_id__contains

string

invoicing_entity_id__startsWith

string

invoicing_entity_id__endWith

string

custom_properties

string

created_at

string

created_at__not

string

created_at__isNull

string

created_at__isNotNull

string

created_at__equals

string

created_at__lt

string

created_at__lte

string

created_at__gt

string

created_at__gte

string

updated_at

string

updated_at__not

string

updated_at__isNull

string

updated_at__isNotNull

string

updated_at__equals

string

updated_at__lt

string

updated_at__lte

string

updated_at__gt

string

updated_at__gte

string

payment_method_type

Available options:

card,

direct_debit,

direct_debit_ach,

direct_debit_bacs,

transfer,

external,

missing

payment_method_type__in

Available options:

card,

direct_debit,

direct_debit_ach,

direct_debit_bacs,

transfer,

external,

missing

Response

200 - application/json

meta

object

required

data

object[]

required

List of Customer.

data.id

string

required

Customer ID.

Example:

"cus_Typ0px2W0aiEtl"

data.name

string

required

Customer name.

Example:

"Acme"

data.type

enum<string> | null

required

Customer type.

corporate: The customer is a business entity.
person: The customer is a natural person.
automatically_created: The customer was automatically imported (e.g. from a data loader). This value cannot be used when creating/editing.

Available options:

corporate,

person,

automatically_created

Example:

"corporate"

data.status

enum<string>

required

Customer status.

Available options:

active,

archived

Example:

"active"

data.currency

enum<string>

required

Currency code. See ISO 4217.

Available options:

EUR,

AED,

AFN,

XCD,

ALL,

AMD,

AOA,

ARS,

USD,

AUD,

AWG,

AZN,

BAM,

BBD,

BDT,

XOF,

BGN,

BHD,

BIF,

BMD,

BND,

BOB,

BRL,

BSD,

BTN,

NOK,

BWP,

BYR,

BZD,

CAD,

CDF,

XAF,

CHF,

NZD,

CLP,

CNY,

COP,

CRC,

CUP,

CVE,

ANG,

CZK,

DJF,

DKK,

DOP,

DZD,

EGP,

MAD,

ERN,

ETB,

FJD,

FKP,

GBP,

GEL,

GHS,

GIP,

GMD,

GNF,

GTQ,

GYD,

HKD,

HNL,

HRK,

HTG,

HUF,

IDR,

ILS,

INR,

IQD,

IRR,

ISK,

JMD,

JOD,

JPY,

KES,

KGS,

KHR,

KMF,

KPW,

KRW,

KWD,

KYD,

KZT,

LAK,

LBP,

LKR,

LRD,

LSL,

LYD,

MDL,

MGA,

MKD,

MMK,

MNT,

MOP,

MRO,

MUR,

MVR,

MWK,

MXN,

MYR,

MZN,

NAD,

XPF,

NGN,

NIO,

NPR,

OMR,

PAB,

PEN,

PGK,

PHP,

PKR,

PLN,

PYG,

QAR,

RON,

RSD,

RUB,

RWF,

SAR,

SBD,

SCR,

SDG,

SEK,

SGD,

SHP,

SLL,

SOS,

SRD,

SSP,

STD,

SYP,

SZL,

THB,

TJS,

TMT,

TND,

TOP,

TRY,

TTD,

TWD,

TZS,

UAH,

UGX,

UYU,

UZS,

VEF,

VND,

VUV,

WST,

YER,

ZAR,

ZMW,

ZWL

Example:

"EUR"

data.country

enum<string> | null

required

Two-letter country code in ISO format. See ISO 3166 Alpha 2.

Available options:

AD,

AE,

AF,

AG,

AI,

AL,

AM,

AO,

AQ,

AR,

AS,

AT,

AU,

AW,

AX,

AZ,

BA,

BB,

BD,

BE,

BF,

BG,

BH,

BI,

BJ,

BL,

BM,

BN,

BO,

BQ,

BR,

BS,

BT,

BV,

BW,

BY,

BZ,

CA,

CC,

CD,

CF,

CG,

CH,

CI,

CK,

CL,

CM,

CN,

CO,

CR,

CU,

CV,

CW,

CX,

CY,

CZ,

DE,

DJ,

DK,

DM,

DO,

DZ,

EC,

EE,

EG,

EH,

ER,

ES,

ET,

FI,

FJ,

FK,

FM,

FO,

FR,

GA,

GB,

GD,

GE,

GF,

GG,

GH,

GI,

GL,

GM,

GN,

GP,

GQ,

GR,

GS,

GT,

GU,

GW,

GY,

HK,

HM,

HN,

HR,

HT,

HU,

IC,

ID,

IE,

IL,

IM,

IN,

IO,

IQ,

IR,

IS,

IT,

JE,

JM,

JO,

JP,

KE,

KG,

KH,

KI,

KM,

KN,

KP,

KR,

KW,

KY,

KZ,

LA,

LB,

LC,

LI,

LK,

LR,

LS,

LT,

LU,

LV,

LY,

MA,

MC,

MD,

ME,

MF,

MG,

MH,

MK,

ML,

MM,

MN,

MO,

MP,

MQ,

MR,

MS,

MT,

MU,

MV,

MW,

MX,

MY,

MZ,

NA,

NC,

NE,

NF,

NG,

NI,

NL,

NO,

NP,

NR,

NU,

NZ,

OM,

PA,

PE,

PF,

PG,

PH,

PK,

PL,

PM,

PN,

PR,

PS,

PT,

PT-20,

PT-30,

PW,

PY,

QA,

RE,

RO,

RS,

RU,

RW,

SA,

SB,

SC,

SD,

SE,

SG,

SH,

SI,

SJ,

SK,

SL,

SM,

SN,

SO,

SR,

SS,

ST,

SV,

SX,

SY,

SZ,

TC,

TD,

TF,

TG,

TH,

TJ,

TK,

TL,

TM,

TN,

TO,

TR,

TT,

TV,

TW,

TZ,

UA,

UG,

UM,

US,

UY,

UZ,

VA,

VC,

VE,

VG,

VI,

VN,

VU,

WF,

WS,

XK,

YE,

YT,

ZA,

ZM,

ZW

Example:

"FR"

data.vat_number

string | null

required

Customer tax ID.

Example:

"FR123456789"

data.vat_number_valid

boolean

required

Indicates customer's tax ID validity.

Example:

true

data.vat_rate_custom

number | null

required

Customer custom tax rate. If not defined, the rate will be automatically determined based on the customer's country, your country, and applicable legal requirements.

data.language

enum<string> | null

required

Language used for invoices, emails, and hosted pages.

Available options:

fr,

en,

de,

it,

nl,

es,

pt,

pl

Example:

"fr"

data.timezone

enum<string> | null

required

Customer timezone.

Available options:

Pacific/Niue,

Pacific/Midway,

Pacific/Pago_Pago,

Pacific/Rarotonga,

Pacific/Honolulu,

Pacific/Tahiti,

Pacific/Marquesas,

Pacific/Gambier,

America/Adak,

America/Anchorage,

Pacific/Pitcairn,

America/Hermosillo,

America/Phoenix,

America/Los_Angeles,

America/Tijuana,

America/Vancouver,

America/Whitehorse,

America/Belize,

America/Guatemala,

America/Managua,

America/Mexico_City,

America/Costa_Rica,

America/El_Salvador,

America/Regina,

America/Tegucigalpa,

Pacific/Easter,

Pacific/Galapagos,

America/Edmonton,

America/Ciudad_Juarez,

America/Denver,

America/Rio_Branco,

America/Chicago,

America/Matamoros,

America/Winnipeg,

America/Bogota,

America/Atikokan,

America/Cancun,

America/Cayman,

America/Jamaica,

America/Panama,

America/Guayaquil,

America/Lima,

America/Manaus,

America/St_Kitts,

America/Blanc-Sablon,

America/Montserrat,

America/Barbados,

America/St_Lucia,

America/Port_of_Spain,

America/Martinique,

America/St_Barthelemy,

America/St_Vincent,

America/Kralendijk,

America/Guadeloupe,

America/Marigot,

America/Aruba,

America/Lower_Princes,

America/Tortola,

America/Dominica,

America/St_Thomas,

America/Grenada,

America/Antigua,

America/Puerto_Rico,

America/Santo_Domingo,

America/Anguilla,

America/Curacao,

America/La_Paz,

America/Santiago,

America/Havana,

America/Grand_Turk,

America/Nassau,

America/New_York,

America/Port-au-Prince,

America/Toronto,

America/Guyana,

America/Asuncion,

America/Caracas,

America/Argentina/Buenos_Aires,

America/Halifax,

Atlantic/Bermuda,

America/Thule,

America/Sao_Paulo,

Antarctica/Palmer,

America/Punta_Arenas,

Atlantic/Stanley,

America/Cayenne,

America/Paramaribo,

America/Montevideo,

America/St_Johns,

America/Noronha,

Atlantic/South_Georgia,

America/Miquelon,

Atlantic/Cape_Verde,

America/Scoresbysund,

America/Nuuk,

Atlantic/Azores,

Etc/UTC,

Africa/Abidjan,

Africa/Bamako,

Africa/Bissau,

Africa/Conakry,

Africa/Dakar,

America/Danmarkshavn,

Africa/Freetown,

Atlantic/St_Helena,

Africa/Accra,

Africa/Lome,

Africa/Monrovia,

Africa/Nouakchott,

Africa/Ouagadougou,

Atlantic/Reykjavik,

Africa/Sao_Tome,

Africa/Banjul,

Africa/Algiers,

Africa/Tunis,

Europe/Isle_of_Man,

Europe/Dublin,

Europe/London,

Europe/Jersey,

Europe/Guernsey,

Africa/Bangui,

Africa/Malabo,

Africa/Brazzaville,

Africa/Porto-Novo,

Africa/Douala,

Africa/Kinshasa,

Africa/Lagos,

Africa/Libreville,

Africa/Luanda,

Africa/Ndjamena,

Africa/Niamey,

Africa/Casablanca,

Africa/El_Aaiun,

Atlantic/Canary,

Europe/Lisbon,

Atlantic/Faroe,

Africa/Bujumbura,

Africa/Gaborone,

Africa/Harare,

Africa/Juba,

Africa/Khartoum,

Africa/Kigali,

Africa/Blantyre,

Africa/Lubumbashi,

Africa/Lusaka,

Africa/Maputo,

Africa/Windhoek,

Europe/Amsterdam,

Europe/Andorra,

Europe/Belgrade,

Europe/Berlin,

Europe/Bratislava,

Europe/Brussels,

Europe/Budapest,

Europe/Copenhagen,

Europe/Gibraltar,

Europe/Ljubljana,

Arctic/Longyearbyen,

Europe/Luxembourg,

Europe/Madrid,

Europe/Monaco,

Europe/Oslo,

Europe/Paris,

Europe/Podgorica,

Europe/Prague,

Europe/Rome,

Europe/San_Marino,

Europe/Malta,

Europe/Sarajevo,

Europe/Skopje,

Europe/Stockholm,

Europe/Tirane,

Europe/Vaduz,

Europe/Vatican,

Europe/Vienna,

Europe/Warsaw,

Europe/Zagreb,

Europe/Zurich,

Africa/Cairo,

Europe/Kaliningrad,

Africa/Tripoli,

Antarctica/Troll,

Africa/Johannesburg,

Africa/Mbabane,

Africa/Maseru,

Asia/Kuwait,

Asia/Bahrain,

Asia/Baghdad,

Asia/Qatar,

Asia/Riyadh,

Asia/Aden,

Asia/Amman,

Asia/Damascus,

Africa/Addis_Ababa,

Indian/Antananarivo,

Africa/Asmara,

Africa/Dar_es_Salaam,

Africa/Djibouti,

Africa/Kampala,

Indian/Mayotte,

Africa/Mogadishu,

Indian/Comoro,

Africa/Nairobi,

Europe/Athens,

Asia/Beirut,

Europe/Bucharest,

Europe/Chisinau,

Asia/Hebron,

Europe/Helsinki,

Europe/Kyiv,

Europe/Mariehamn,

Asia/Nicosia,

Europe/Riga,

Europe/Sofia,

Europe/Tallinn,

Europe/Vilnius,

Asia/Jerusalem,

Europe/Minsk,

Europe/Moscow,

Europe/Simferopol,

Antarctica/Syowa,

Europe/Istanbul,

Asia/Tehran,

Asia/Yerevan,

Asia/Baku,

Asia/Tbilisi,

Asia/Dubai,

Asia/Muscat,

Indian/Mauritius,

Indian/Reunion,

Europe/Samara,

Indian/Mahe,

Asia/Kabul,

Asia/Almaty,

Indian/Kerguelen,

Indian/Maldives,

Antarctica/Mawson,

Asia/Karachi,

Asia/Dushanbe,

Asia/Ashgabat,

Asia/Tashkent,

Antarctica/Vostok,

Asia/Aqtobe,

Asia/Yekaterinburg,

Asia/Colombo,

Asia/Kolkata,

Asia/Kathmandu,

Asia/Dhaka,

Asia/Thimphu,

Asia/Urumqi,

Indian/Chagos,

Asia/Bishkek,

Asia/Omsk,

Indian/Cocos,

Asia/Yangon,

Indian/Christmas,

Antarctica/Davis,

Asia/Hovd,

Asia/Bangkok,

Asia/Ho_Chi_Minh,

Asia/Phnom_Penh,

Asia/Vientiane,

Asia/Novosibirsk,

Asia/Jakarta,

Australia/Perth,

Asia/Brunei,

Antarctica/Casey,

Asia/Makassar,

Asia/Macau,

Asia/Shanghai,

Asia/Hong_Kong,

Asia/Irkutsk,

Asia/Kuala_Lumpur,

Asia/Manila,

Asia/Singapore,

Asia/Taipei,

Asia/Ulaanbaatar,

Australia/Eucla,

Asia/Dili,

Asia/Jayapura,

Asia/Tokyo,

Asia/Pyongyang,

Asia/Seoul,

Pacific/Palau,

Asia/Chita,

Australia/Adelaide,

Australia/Darwin,

Australia/Brisbane,

Australia/Sydney,

Pacific/Guam,

Pacific/Saipan,

Pacific/Chuuk,

Antarctica/DumontDUrville,

Pacific/Port_Moresby,

Asia/Vladivostok,

Australia/Lord_Howe,

Pacific/Bougainville,

Pacific/Kosrae,

Pacific/Noumea,

Pacific/Norfolk,

Asia/Sakhalin,

Pacific/Guadalcanal,

Pacific/Efate,

Pacific/Fiji,

Pacific/Tarawa,

Pacific/Majuro,

Pacific/Nauru,

Pacific/Auckland,

Antarctica/McMurdo,

Asia/Kamchatka,

Pacific/Funafuti,

Pacific/Wake,

Pacific/Wallis,

Pacific/Chatham,

Pacific/Apia,

Pacific/Kanton,

Pacific/Fakaofo,

Pacific/Tongatapu,

Pacific/Kiritimati

Example:

"Europe/Paris"

data.external_id

string | null

required

ID of the customer in your system. This helps matching your customer with the one on Hyperline.

data.properties

object | null

required

Key/value pairs to store any information you find useful.

data.custom_properties

object | null

required

A list of key value with the ID or the name of the custom property as the key and the custom property value as value.

data.billing_address

object

required

Customer billing address.

data.billing_email

string | null

required

Email to which all communications will be sent.

Example:

"billing@acme.com"

data.invoice_emails

string[]

required

Emails to which invoices will be sent (e.g. payer, finance team, accounting firm). If not defined, invoices will be sent to the billing_email; otherwise, they won't be sent to the billing_email.

Example:

["accounting@acme.com"]

data.invoicing_entity_id

string

required

ID of the invoicing entity this customer will be attached to.

Example:

"ive_484dn4U48E"

data.invoice_reminders_enabled

required

Indicates if invoice reminders are enabled for the customer.

data.price_book_id

string | null

required

Default price book ID assigned to the customer.

Example:

"prib_613_WbVIZ1329e"

data.available_payment_methods

enum<string>[]

required

List of payment methods you allow your customer to pay with. You customer will be able to select one of them in their portal page and those will be the default options when creating a checkout session.

Available options:

card,

direct_debit,

direct_debit_ach,

direct_debit_bacs,

transfer,

transfer_automated

Example:

["card", "direct_debit"]

data.current_payment_method_type

enum<string> | null

required

Default payment method type used to pay subscriptions and one-off invoices.

Available options:

card,

direct_debit,

direct_debit_ach,

direct_debit_bacs,

transfer,

transfer_automated,

external

Example:

"card"

data.current_payment_method_id

string | null

required

ID of the default payment method of the customer. Only applies to card and direct debit.

Example:

"pm_UTclbc1US8GzCe"

data.custom_payment_delay

number | null

required

Custom payment delay. If not defined, the default one defined on the related invoicing entity will be used.

Example:

30

data.subscriptions

object[]

required

data.created_at

string

required

Customer creation date. UTC date time string in the ISO 8601 format.

Example:

"2024-10-12T07:00:01.860Z"

data.updated_at

string

required

Customer last edition date. UTC date time string in the ISO 8601 format.

Example:

"2024-10-12T07:00:01.860Z"

data.deleted_at

string | null

required

UTC date time string in the ISO 8601 format.

Example:

"2024-10-13T02:00:00.000Z"

Was this page helpful?

Delete custom property Get customer

curl --request GET \
  --url https://api.hyperline.co/v1/customers \
  --header 'Authorization: Bearer <token>'

{
  "meta": {
    "total": 1,
    "taken": 1,
    "skipped": 0
  },
  "data": [
    {
      "id": "cus_Typ0px2W0aiEtl",
      "name": "Acme",
      "type": "corporate",
      "status": "active",
      "currency": "EUR",
      "country": "FR",
      "vat_number": "FR123456789",
      "vat_number_valid": true,
      "vat_rate_custom": 123,
      "language": "fr",
      "timezone": "Europe/Paris",
      "external_id": "<string>",
      "properties": {},
      "custom_properties": {},
      "billing_address": {
        "name": "Acme",
        "line1": "5 rue de Paradis",
        "line2": "<string>",
        "city": "Paris",
        "zip": "75010",
        "state": "<string>",
        "country": "FR"
      },
      "billing_email": "billing@acme.com",
      "invoice_emails": [
        "accounting@acme.com"
      ],
      "invoicing_entity_id": "ive_484dn4U48E",
      "invoice_reminders_enabled": true,
      "price_book_id": "prib_613_WbVIZ1329e",
      "available_payment_methods": [
        "card",
        "direct_debit"
      ],
      "current_payment_method_type": "card",
      "current_payment_method_id": "pm_UTclbc1US8GzCe",
      "custom_payment_delay": 30,
      "subscriptions": [
        {
          "id": "sub_0kIc7jrF7gV00V",
          "status": "active",
          "current_period_started_at": "2024-10-12T07:00:01.860Z",
          "current_period_ends_at": "2024-11-12T07:00:01.860Z",
          "plan_id": "plan_34hdd843hReh",
          "checkout_session_id": "che_949djdj39RJj"
        }
      ],
      "created_at": "2024-10-12T07:00:01.860Z",
      "updated_at": "2024-10-12T07:00:01.860Z",
      "deleted_at": "2024-10-13T02:00:00.000Z"
    }
  ]
}

API documentation

Integrations

Analytics

Billable events

Companies

Coupons

Custom properties

Customers

Customers > Credits

Customers > Payment methods

Integrations

Invoices

Invoices > Transactions

Invoicing entities

OAuth2

Organisations

Payments

Plans

Price configurations

Products

Quotes

Subscriptions

Taxes

Third-party apps

Wallets

Webhooks

Authorizations

Query Parameters

Response