Read Customer State

Intent

Reads the customer state without changing it.

When to call it

Call this after your application has received or stored the identifier for the customer state.

Access boundary

Authorize the request with a token that carries customers:read or customers:write.

Successful result

A successful request returns 200. The response schema below defines the body your integration receives.

Operational notes

Get a customer state by ID.

The customer state includes information about the customer’s active subscriptions and benefits.

It’s the ideal endpoint to use when you need to get a full overview of a customer’s status.

Scopes: customers:read customers:write

GET

customers

{id}

state

Read Customer State

curl --request GET \
  --url https://api.getruba.com/v1/customers/{id}/state \
  --header 'Authorization: Bearer <token>'

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

fetch('https://api.getruba.com/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.getruba.com/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.getruba.com/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.getruba.com/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": "2023-11-07T05:31:56Z",
  "modified_at": "2023-11-07T05:31:56Z",
  "metadata": {},
  "email": "customer@example.com",
  "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": "2023-11-07T05:31:56Z",
  "avatar_url": "https://example.com/avatar.png",
  "active_subscriptions": [
    {
      "id": "e5149aae-e521-42b9-b24c-abb3d71eea2e",
      "created_at": "2023-11-07T05:31:56Z",
      "modified_at": "2023-11-07T05:31:56Z",
      "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,
      "meters": [
        {
          "created_at": "2023-11-07T05:31:56Z",
          "modified_at": "2023-11-07T05:31:56Z",
          "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": "2023-11-07T05:31:56Z",
      "modified_at": "2023-11-07T05:31:56Z",
      "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": "2023-11-07T05:31:56Z",
      "modified_at": "2023-11-07T05:31:56Z",
      "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 an Organization Access Token from your organization's settings.

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

The time Ruba created this record.

modified_at

string<date-time> | null

required

The time this record last changed.

metadata

object

required

Show child attributes

string

required

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

Example:

"customer@example.com"

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.

avatar_url

string | null

required

Example:

"https://example.com/avatar.png"

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.

Read Customer State

curl --request GET \
  --url https://api.getruba.com/v1/customers/{id}/state \
  --header 'Authorization: Bearer <token>'

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

fetch('https://api.getruba.com/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.getruba.com/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.getruba.com/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.getruba.com/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": "2023-11-07T05:31:56Z",
  "modified_at": "2023-11-07T05:31:56Z",
  "metadata": {},
  "email": "customer@example.com",
  "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": "2023-11-07T05:31:56Z",
  "avatar_url": "https://example.com/avatar.png",
  "active_subscriptions": [
    {
      "id": "e5149aae-e521-42b9-b24c-abb3d71eea2e",
      "created_at": "2023-11-07T05:31:56Z",
      "modified_at": "2023-11-07T05:31:56Z",
      "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,
      "meters": [
        {
          "created_at": "2023-11-07T05:31:56Z",
          "modified_at": "2023-11-07T05:31:56Z",
          "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": "2023-11-07T05:31:56Z",
      "modified_at": "2023-11-07T05:31:56Z",
      "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": "2023-11-07T05:31:56Z",
      "modified_at": "2023-11-07T05:31:56Z",
      "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": {}
    }
  ]
}

Read This First

Create a Sale

Collect and Reconcile

Manage Recurring Revenue

Model Customer Access

Power the Customer Portal

Configure the Platform

React to State Changes

Read Customer State

Intent

When to call it

Access boundary

Successful result

Operational notes

Authorizations

Path Parameters

Response