Create Customer

POST

customers

Python

from polar.v2027_01 import Polar

polar = Polar("polar_oat_xxx")

response = polar.customers.create(
    external_id='usr_1337',
    type='individual',
    email='[email protected]',
)
print(response)

import { createPolar } from "@polar-sh/sdk/2027-01";

const polar = createPolar({
  accessToken: "polar_oat_xxx",
});

const response = await polar.customers.create(
  {
    "external_id": "usr_1337",
    "type": "individual",
    "email": "[email protected]"
  },
);
console.log(response);

curl --request POST \
  --url https://api.polar.sh/v1/customers/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "[email protected]",
  "metadata": {},
  "external_id": "usr_1337",
  "name": "John Doe",
  "billing_address": {
    "country": "US",
    "line1": "<string>",
    "line2": "<string>",
    "postal_code": "<string>",
    "city": "<string>",
    "state": "<string>"
  },
  "tax_id": "<string>",
  "locale": "en",
  "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737",
  "owner": {
    "email": "[email protected]",
    "name": "Jane Doe",
    "external_id": "usr_1337"
  },
  "type": "individual"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    email: '[email protected]',
    metadata: {},
    external_id: 'usr_1337',
    name: 'John Doe',
    billing_address: {
      country: 'US',
      line1: '<string>',
      line2: '<string>',
      postal_code: '<string>',
      city: '<string>',
      state: '<string>'
    },
    tax_id: '<string>',
    locale: 'en',
    organization_id: '1dbfc517-0bbf-4301-9ba8-555ca42b9737',
    owner: {email: '[email protected]', name: 'Jane Doe', external_id: 'usr_1337'},
    type: 'individual'
  })
};

fetch('https://api.polar.sh/v1/customers/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.polar.sh/v1/customers/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'email' => '[email protected]',
    'metadata' => [
        
    ],
    'external_id' => 'usr_1337',
    'name' => 'John Doe',
    'billing_address' => [
        'country' => 'US',
        'line1' => '<string>',
        'line2' => '<string>',
        'postal_code' => '<string>',
        'city' => '<string>',
        'state' => '<string>'
    ],
    'tax_id' => '<string>',
    'locale' => 'en',
    'organization_id' => '1dbfc517-0bbf-4301-9ba8-555ca42b9737',
    'owner' => [
        'email' => '[email protected]',
        'name' => 'Jane Doe',
        'external_id' => 'usr_1337'
    ],
    'type' => 'individual'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.polar.sh/v1/customers/"

	payload := strings.NewReader("{\n  \"email\": \"[email protected]\",\n  \"metadata\": {},\n  \"external_id\": \"usr_1337\",\n  \"name\": \"John Doe\",\n  \"billing_address\": {\n    \"country\": \"US\",\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\"\n  },\n  \"tax_id\": \"<string>\",\n  \"locale\": \"en\",\n  \"organization_id\": \"1dbfc517-0bbf-4301-9ba8-555ca42b9737\",\n  \"owner\": {\n    \"email\": \"[email protected]\",\n    \"name\": \"Jane Doe\",\n    \"external_id\": \"usr_1337\"\n  },\n  \"type\": \"individual\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.polar.sh/v1/customers/")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"email\": \"[email protected]\",\n  \"metadata\": {},\n  \"external_id\": \"usr_1337\",\n  \"name\": \"John Doe\",\n  \"billing_address\": {\n    \"country\": \"US\",\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\"\n  },\n  \"tax_id\": \"<string>\",\n  \"locale\": \"en\",\n  \"organization_id\": \"1dbfc517-0bbf-4301-9ba8-555ca42b9737\",\n  \"owner\": {\n    \"email\": \"[email protected]\",\n    \"name\": \"Jane Doe\",\n    \"external_id\": \"usr_1337\"\n  },\n  \"type\": \"individual\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.polar.sh/v1/customers/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"email\": \"[email protected]\",\n  \"metadata\": {},\n  \"external_id\": \"usr_1337\",\n  \"name\": \"John Doe\",\n  \"billing_address\": {\n    \"country\": \"US\",\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\"\n  },\n  \"tax_id\": \"<string>\",\n  \"locale\": \"en\",\n  \"organization_id\": \"1dbfc517-0bbf-4301-9ba8-555ca42b9737\",\n  \"owner\": {\n    \"email\": \"[email protected]\",\n    \"name\": \"Jane Doe\",\n    \"external_id\": \"usr_1337\"\n  },\n  \"type\": \"individual\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "992fae2a-2a17-4b7a-8d9e-e287cf90131b",
  "created_at": "2026-01-01T00:00:00.000000Z",
  "modified_at": "2026-01-01T00:00:00.000000Z",
  "metadata": {},
  "email": "[email protected]",
  "email_verified": true,
  "type": "individual",
  "name": "John Doe",
  "billing_name": "John Doe",
  "billing_address": {
    "country": "US",
    "line1": "<string>",
    "line2": "<string>",
    "postal_code": "<string>",
    "city": "<string>",
    "state": "<string>"
  },
  "tax_id": {
    "[0]": "<string>"
  },
  "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737",
  "deleted_at": "2026-01-01T00:00:00.000000Z",
  "first_user_event_at": "2026-01-01T00:00:00.000000Z",
  "avatar_url": "https://www.gravatar.com/avatar/xxx?d=404",
  "external_id": "usr_1337",
  "locale": "<string>",
  "default_payment_method_id": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Authorizations

Authorization

string

header

required

You can generate a Personal Access Token from your settings.

Scopes

customers:write

pat

customers:write

oat

Body

application/json

CustomerIndividualCreate
CustomerTeamCreate

string<email>

required

The email address of the customer. This must be unique within the organization.

Example:

"[email protected]"

metadata

Metadata · object

Key-value object allowing you to store additional information.

The key must be a string with a maximum length of 40 characters. The value must be either:

A string with a maximum length of 500 characters
An integer
A floating-point number
A boolean

You can store up to 50 key-value pairs.

Show child attributes

external_id

string | null

The ID of the customer in your system. This must be unique within the organization. Once set, it can't be updated.

Example:

"usr_1337"

name

string | null

The name of the customer.

Maximum string length: 256

Example:

"John Doe"

billing_address

AddressInput · object | null

Show child attributes

tax_id

string | null

locale

string | null

Locale of the customer, given as an IETF BCP 47 language tag, e.g. en, en-US or en-GB-oxendict. If null or unsupported, the locale will default to en.

Example:

"en"

organization_id

string<uuid4> | null

The organization ID.

Example:

"1dbfc517-0bbf-4301-9ba8-555ca42b9737"

owner

MemberOwnerCreate · object | null

Optional owner member to create with the customer. If not provided, an owner member will be automatically created using the customer's email and name.

Show child attributes

type

string

default:individual

Allowed value: "individual"

Response

Customer created.

CustomerIndividual
CustomerTeam

A customer in an organization.

string<uuid4>

required

The ID of the customer.

Example:

"992fae2a-2a17-4b7a-8d9e-e287cf90131b"

created_at

string<date-time>

required

Creation timestamp of the object.

Example:

"2026-01-01T00:00:00.000000Z"

modified_at

string<date-time> | null

required

Last modification timestamp of the object.

Example:

"2026-01-01T00:00:00.000000Z"

metadata

object

required

Show child attributes

string

required

The email address of the customer. This must be unique within the organization.

Example:

"[email protected]"

email_verified

boolean

required

Whether the customer email address is verified. The address is automatically verified when the customer accesses the customer portal using their email address.

Example:

true

type

string

required

The type of customer.

Allowed value: "individual"

Example:

"individual"

name

string | null

required

The name of the customer.

Example:

"John Doe"

billing_name

string | null

required

The name that should appear on the customer's invoices. Falls back to the customer name when not explicitly set.

Example:

"John Doe"

billing_address

Address · object | null

required

Show child attributes

tax_id

Tax Id · object | null

required

Show child attributes

organization_id

string<uuid4>

required

The ID of the organization owning the customer.

Example:

"1dbfc517-0bbf-4301-9ba8-555ca42b9737"

deleted_at

string<date-time> | null

required

Timestamp for when the customer was soft deleted.

Example:

"2026-01-01T00:00:00.000000Z"

first_user_event_at

string<date-time> | null

required

Timestamp of the first event ingested for this customer. Can predate created_at, and is null if no event was ever ingested.

Example:

"2026-01-01T00:00:00.000000Z"

avatar_url

string | null

required

Example:

"https://www.gravatar.com/avatar/xxx?d=404"

external_id

string | null

The ID of the customer in your system. This must be unique within the organization. Once set, it can't be updated.

Example:

"usr_1337"

locale

string | null

default_payment_method_id

string<uuid4> | null

The ID of the customer's default payment method, if any. Use the payment methods endpoint to retrieve its details.

⌘I

Python

from polar.v2027_01 import Polar

polar = Polar("polar_oat_xxx")

response = polar.customers.create(
    external_id='usr_1337',
    type='individual',
    email='[email protected]',
)
print(response)

import { createPolar } from "@polar-sh/sdk/2027-01";

const polar = createPolar({
  accessToken: "polar_oat_xxx",
});

const response = await polar.customers.create(
  {
    "external_id": "usr_1337",
    "type": "individual",
    "email": "[email protected]"
  },
);
console.log(response);

curl --request POST \
  --url https://api.polar.sh/v1/customers/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "[email protected]",
  "metadata": {},
  "external_id": "usr_1337",
  "name": "John Doe",
  "billing_address": {
    "country": "US",
    "line1": "<string>",
    "line2": "<string>",
    "postal_code": "<string>",
    "city": "<string>",
    "state": "<string>"
  },
  "tax_id": "<string>",
  "locale": "en",
  "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737",
  "owner": {
    "email": "[email protected]",
    "name": "Jane Doe",
    "external_id": "usr_1337"
  },
  "type": "individual"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    email: '[email protected]',
    metadata: {},
    external_id: 'usr_1337',
    name: 'John Doe',
    billing_address: {
      country: 'US',
      line1: '<string>',
      line2: '<string>',
      postal_code: '<string>',
      city: '<string>',
      state: '<string>'
    },
    tax_id: '<string>',
    locale: 'en',
    organization_id: '1dbfc517-0bbf-4301-9ba8-555ca42b9737',
    owner: {email: '[email protected]', name: 'Jane Doe', external_id: 'usr_1337'},
    type: 'individual'
  })
};

fetch('https://api.polar.sh/v1/customers/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.polar.sh/v1/customers/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'email' => '[email protected]',
    'metadata' => [
        
    ],
    'external_id' => 'usr_1337',
    'name' => 'John Doe',
    'billing_address' => [
        'country' => 'US',
        'line1' => '<string>',
        'line2' => '<string>',
        'postal_code' => '<string>',
        'city' => '<string>',
        'state' => '<string>'
    ],
    'tax_id' => '<string>',
    'locale' => 'en',
    'organization_id' => '1dbfc517-0bbf-4301-9ba8-555ca42b9737',
    'owner' => [
        'email' => '[email protected]',
        'name' => 'Jane Doe',
        'external_id' => 'usr_1337'
    ],
    'type' => 'individual'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.polar.sh/v1/customers/"

	payload := strings.NewReader("{\n  \"email\": \"[email protected]\",\n  \"metadata\": {},\n  \"external_id\": \"usr_1337\",\n  \"name\": \"John Doe\",\n  \"billing_address\": {\n    \"country\": \"US\",\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\"\n  },\n  \"tax_id\": \"<string>\",\n  \"locale\": \"en\",\n  \"organization_id\": \"1dbfc517-0bbf-4301-9ba8-555ca42b9737\",\n  \"owner\": {\n    \"email\": \"[email protected]\",\n    \"name\": \"Jane Doe\",\n    \"external_id\": \"usr_1337\"\n  },\n  \"type\": \"individual\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.polar.sh/v1/customers/")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"email\": \"[email protected]\",\n  \"metadata\": {},\n  \"external_id\": \"usr_1337\",\n  \"name\": \"John Doe\",\n  \"billing_address\": {\n    \"country\": \"US\",\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\"\n  },\n  \"tax_id\": \"<string>\",\n  \"locale\": \"en\",\n  \"organization_id\": \"1dbfc517-0bbf-4301-9ba8-555ca42b9737\",\n  \"owner\": {\n    \"email\": \"[email protected]\",\n    \"name\": \"Jane Doe\",\n    \"external_id\": \"usr_1337\"\n  },\n  \"type\": \"individual\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.polar.sh/v1/customers/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"email\": \"[email protected]\",\n  \"metadata\": {},\n  \"external_id\": \"usr_1337\",\n  \"name\": \"John Doe\",\n  \"billing_address\": {\n    \"country\": \"US\",\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\"\n  },\n  \"tax_id\": \"<string>\",\n  \"locale\": \"en\",\n  \"organization_id\": \"1dbfc517-0bbf-4301-9ba8-555ca42b9737\",\n  \"owner\": {\n    \"email\": \"[email protected]\",\n    \"name\": \"Jane Doe\",\n    \"external_id\": \"usr_1337\"\n  },\n  \"type\": \"individual\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "992fae2a-2a17-4b7a-8d9e-e287cf90131b",
  "created_at": "2026-01-01T00:00:00.000000Z",
  "modified_at": "2026-01-01T00:00:00.000000Z",
  "metadata": {},
  "email": "[email protected]",
  "email_verified": true,
  "type": "individual",
  "name": "John Doe",
  "billing_name": "John Doe",
  "billing_address": {
    "country": "US",
    "line1": "<string>",
    "line2": "<string>",
    "postal_code": "<string>",
    "city": "<string>",
    "state": "<string>"
  },
  "tax_id": {
    "[0]": "<string>"
  },
  "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737",
  "deleted_at": "2026-01-01T00:00:00.000000Z",
  "first_user_event_at": "2026-01-01T00:00:00.000000Z",
  "avatar_url": "https://www.gravatar.com/avatar/xxx?d=404",
  "external_id": "usr_1337",
  "locale": "<string>",
  "default_payment_method_id": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

General

Core API

Customer Portal API

Webhook Events

Integrations

Create Customer

Authorizations

Scopes

Body

Response