Get Customer State

GET

customers

{id}

state

Python

from polar.v2027_01 import Polar

polar = Polar("polar_oat_xxx")

response = polar.customers.get_state(
    '00000000-0000-4000-8000-000000000000',
)
print(response)

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

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

const response = await polar.customers.getState(
  "00000000-0000-4000-8000-000000000000",
);
console.log(response);

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.polar.sh/v1/customers/{id}/state', 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/{id}/state",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.polar.sh/v1/customers/{id}/state"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.polar.sh/v1/customers/{id}/state")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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",
  "active_subscriptions": [
    {
      "id": "e5149aae-e521-42b9-b24c-abb3d71eea2e",
      "created_at": "2026-01-01T00:00:00.000000Z",
      "modified_at": "2026-01-01T00:00:00.000000Z",
      "metadata": {},
      "status": "active",
      "amount": 1000,
      "currency": "usd",
      "recurring_interval": "day",
      "current_period_start": "2025-02-03T13:37:00Z",
      "current_period_end": "2025-03-03T13:37:00Z",
      "trial_start": "2025-02-03T13:37:00Z",
      "trial_end": "2025-03-03T13:37:00Z",
      "cancel_at_period_end": false,
      "canceled_at": null,
      "started_at": "2025-01-03T13:37:00Z",
      "ends_at": null,
      "product_id": "d8dd2de1-21b7-4a41-8bc3-ce909c0cfe23",
      "discount_id": null,
      "seats": null,
      "units": null,
      "meters": [
        {
          "created_at": "2026-01-01T00:00:00.000000Z",
          "modified_at": "2026-01-01T00:00:00.000000Z",
          "id": "<string>",
          "consumed_units": 25,
          "credited_units": 100,
          "amount": 0,
          "meter_id": "d498a884-e2cd-4d3e-8002-f536468a8b22"
        }
      ],
      "custom_field_data": {}
    }
  ],
  "granted_benefits": [
    {
      "id": "d322132c-a9d0-4e0d-b8d3-d81ad021a3a9",
      "created_at": "2026-01-01T00:00:00.000000Z",
      "modified_at": "2026-01-01T00:00:00.000000Z",
      "granted_at": "2025-01-03T13:37:00Z",
      "benefit_id": "397a17aa-15cf-4cb4-9333-18040203cf98",
      "benefit_type": "custom",
      "benefit_metadata": {
        "key": "value"
      },
      "properties": {
        "account_id": "<string>",
        "guild_id": "<string>",
        "role_id": "<string>",
        "granted_account_id": "<string>"
      }
    }
  ],
  "active_meters": [
    {
      "id": "<string>",
      "created_at": "2026-01-01T00:00:00.000000Z",
      "modified_at": "2026-01-01T00:00:00.000000Z",
      "meter_id": "d498a884-e2cd-4d3e-8002-f536468a8b22",
      "consumed_units": 25,
      "credited_units": 100,
      "balance": 75
    }
  ],
  "external_id": "usr_1337",
  "locale": "<string>",
  "default_payment_method_id": "<string>"
}

{
  "error": "ResourceNotFound",
  "detail": "<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:read

pat

customers:write

pat

customers:read

oat

customers:write

oat

Path Parameters

string<uuid4>

required

The customer ID.

Response

Successful Response

CustomerStateIndividual
CustomerStateTeam

A customer along with additional state information:

Active subscriptions
Granted benefits
Active meters

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"

active_subscriptions

CustomerStateSubscription · object[]

required

The customer's active subscriptions.

Show child attributes

granted_benefits

CustomerStateBenefitGrant · object[]

required

The customer's active benefit grants.

Show child attributes

active_meters

CustomerStateMeter · object[]

required

The customer's active meters.

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"

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.get_state(
    '00000000-0000-4000-8000-000000000000',
)
print(response)

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

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

const response = await polar.customers.getState(
  "00000000-0000-4000-8000-000000000000",
);
console.log(response);

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.polar.sh/v1/customers/{id}/state', 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/{id}/state",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.polar.sh/v1/customers/{id}/state"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.polar.sh/v1/customers/{id}/state")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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",
  "active_subscriptions": [
    {
      "id": "e5149aae-e521-42b9-b24c-abb3d71eea2e",
      "created_at": "2026-01-01T00:00:00.000000Z",
      "modified_at": "2026-01-01T00:00:00.000000Z",
      "metadata": {},
      "status": "active",
      "amount": 1000,
      "currency": "usd",
      "recurring_interval": "day",
      "current_period_start": "2025-02-03T13:37:00Z",
      "current_period_end": "2025-03-03T13:37:00Z",
      "trial_start": "2025-02-03T13:37:00Z",
      "trial_end": "2025-03-03T13:37:00Z",
      "cancel_at_period_end": false,
      "canceled_at": null,
      "started_at": "2025-01-03T13:37:00Z",
      "ends_at": null,
      "product_id": "d8dd2de1-21b7-4a41-8bc3-ce909c0cfe23",
      "discount_id": null,
      "seats": null,
      "units": null,
      "meters": [
        {
          "created_at": "2026-01-01T00:00:00.000000Z",
          "modified_at": "2026-01-01T00:00:00.000000Z",
          "id": "<string>",
          "consumed_units": 25,
          "credited_units": 100,
          "amount": 0,
          "meter_id": "d498a884-e2cd-4d3e-8002-f536468a8b22"
        }
      ],
      "custom_field_data": {}
    }
  ],
  "granted_benefits": [
    {
      "id": "d322132c-a9d0-4e0d-b8d3-d81ad021a3a9",
      "created_at": "2026-01-01T00:00:00.000000Z",
      "modified_at": "2026-01-01T00:00:00.000000Z",
      "granted_at": "2025-01-03T13:37:00Z",
      "benefit_id": "397a17aa-15cf-4cb4-9333-18040203cf98",
      "benefit_type": "custom",
      "benefit_metadata": {
        "key": "value"
      },
      "properties": {
        "account_id": "<string>",
        "guild_id": "<string>",
        "role_id": "<string>",
        "granted_account_id": "<string>"
      }
    }
  ],
  "active_meters": [
    {
      "id": "<string>",
      "created_at": "2026-01-01T00:00:00.000000Z",
      "modified_at": "2026-01-01T00:00:00.000000Z",
      "meter_id": "d498a884-e2cd-4d3e-8002-f536468a8b22",
      "consumed_units": 25,
      "credited_units": 100,
      "balance": 75
    }
  ],
  "external_id": "usr_1337",
  "locale": "<string>",
  "default_payment_method_id": "<string>"
}

{
  "error": "ResourceNotFound",
  "detail": "<string>"
}

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

General

Core API

Customer Portal API

Webhook Events

Integrations

Get Customer State

Authorizations

Scopes

Path Parameters

Response