Retrieve customer billing state

POST

/v1/customers/retrieve_billing_state

const url = 'https://api.strent.dev/v1/customers/retrieve_billing_state';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"stripe_customer_id":"cus_123"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.strent.dev/v1/customers/retrieve_billing_state \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "stripe_customer_id": "cus_123" }'

Returns detailed subscription, item, and schedule state for billing pages and inspection. Each subscription reports grants_access. This operation is outside the hot-path performance class and returns 200 even when the customer has never been refreshed, with last_refreshed_at: null.

This read-only POST operation is side-effect-free and semantically safe to retry, but clients should not retry automatically by default.

Authorizations

projectApiKey

Request Body^required

application/json

object

stripe_customer_id

required

string

<= 255 characters /^cus_[^\s]+$/

Example

{
  "stripe_customer_id": "cus_123"
}

Responses

200

Detailed billing state; last_refreshed_at is null when the customer has never been refreshed.

application/json

object

stripe_customer_id

required

string

<= 255 characters /^cus_[^\s]+$/

last_refreshed_at

required

Any of:

string
null

string format: date-time

subscriptions

required

Array<object>

object

required

string

>= 1 characters

status

required

string

>= 1 characters

grants_access

required

boolean

trial_end

required

Any of:

string
null

string format: date-time

cancellation

required

Any of:

object
null

object

effective_at

required

Any of:

string
null

string format: date-time

pending_change

required

Any of:

object
null

object

effective_at

required

Any of:

string
null

string format: date-time

items

required

Array<object>

object

price

required

object

required

string

>= 1 characters

lookup_key

required

string | null

nickname

required

string | null

product

required

object

required

string

>= 1 characters

name

required

string | null

currency

required

string

>= 1 characters

unit_amount

required

Stripe’s amount in the currency’s minor unit, for arithmetic. Null for tiered or decimal-only prices.

integer | null

unit_amount_display

required

The same amount as an exact decimal string in whole currency units, such as “19.99” for usd 1999 or “2000” for jpy 2000. It has no currency symbol or locale separators: format it with Intl.NumberFormat and currency. Null exactly when unit_amount is null.

string | null

/^[0-9]+(\.[0-9]+)?$/

recurring

required

Any of:

object
null

object

interval

required

Allowed values: day week month year

interval_count

required

integer

>= 1

quantity

required

Any of:

integer
null

integer

current_period_end

required

Any of:

string
null

string format: date-time

start_date

required

Any of:

string
null

string format: date-time

items

required

Array<object>

object

required

string

>= 1 characters

price

required

object

required

string

>= 1 characters

lookup_key

required

string | null

nickname

required

string | null

product

required

object

required

string

>= 1 characters

name

required

string | null

currency

required

string

>= 1 characters

unit_amount

required

Stripe’s amount in the currency’s minor unit, for arithmetic. Null for tiered or decimal-only prices.

integer | null

unit_amount_display

required

string | null

/^[0-9]+(\.[0-9]+)?$/

recurring

required

Any of:

object
null

object

interval

required

Allowed values: day week month year

interval_count

required

integer

>= 1

quantity

required

Any of:

integer
null

integer

current_period_start

required

Any of:

string
null

string format: date-time

current_period_end

required

Any of:

string
null

string format: date-time

Example

{
  "stripe_customer_id": "cus_123",
  "last_refreshed_at": "2026-08-14T09:30:00.000Z",
  "subscriptions": []
}

400

The request body is invalid.

application/json

object

error

required

object

code

required

string

Allowed values: VALIDATION_FAILED

message

required

string

requestId

required

string

details

object

key

additional properties

any

Example

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The request body is invalid.",
    "requestId": "req_123"
  }
}

401

The Authorization header or project API key is invalid.

application/json

object

error

required

object

code

required

string

Allowed values: INVALID_AUTH_HEADER API_KEY_INVALID

message

required

string

requestId

required

string

details

object

key

additional properties

any

Example

{
  "error": {
    "code": "INVALID_AUTH_HEADER",
    "message": "The Authorization header or project API key is invalid.",
    "requestId": "req_123"
  }
}

403

The project API key has been revoked.

application/json

object

error

required

object

code

required

string

Allowed values: API_KEY_REVOKED

message

required

string

requestId

required

string

details

object

key

additional properties

any

Example

{
  "error": {
    "code": "API_KEY_REVOKED",
    "message": "The project API key has been revoked.",
    "requestId": "req_123"
  }
}

413

The request body is too large.

application/json

object

error

required

object

code

required

string

Allowed values: VALIDATION_FAILED

message

required

string

requestId

required

string

details

object

key

additional properties

any

Example

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The request body is too large.",
    "requestId": "req_123"
  }
}

415

The request failed.

application/json

object

error

required

object

code

required

string

Allowed values: VALIDATION_FAILED

message

required

string

requestId

required

string

details

object

key

additional properties

any

Example

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The request failed.",
    "requestId": "req_123"
  }
}

429

The project or pre-authentication rate limit was exceeded.

application/json

object

error

required

object

code

required

string

Allowed values: RATE_LIMIT_EXCEEDED

message

required

string

requestId

required

string

details

object

key

additional properties

any

Example

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "The project or pre-authentication rate limit was exceeded.",
    "requestId": "req_123"
  }
}

Headers

Retry-After

number

Seconds before another request is advised.

500

Strent could not complete the request.

application/json

object

error

required

object

code

required

string

Allowed values: INTERNAL_ERROR

message

required

string

requestId

required

string

details

object

key

additional properties

any

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Strent could not complete the request.",
    "requestId": "req_123"
  }
}

Retrieve customer billing state

Authorizations

Request Bodyrequired

Example

Responses

200

Example

400

Example

401

Example

403

Example

413

Example

415

Example

429

Example

Headers

500

Example

Request Body^required