Sign in

v1

latestOpenAPI 3.1.02026-07-265817860.8 KB
entities

Updates an existing entity and returns the refreshed entity object.

Use this to change entity billing controls or other mutable entity fields after the entity has already been created.

post/v1/entities.update

Headers

x-api-versionstring required

Request body

customer_idstring

The ID of the customer that owns the entity.

entity_idstring required

The ID of the entity.

Example request

{
  "customer_id": "cus_123",
  "entity_id": "seat_42",
  "billing_controls": {
    "spend_limits": [
      {
        "feature_id": "messages",
        "enabled": true,
        "limit_type": "usage_percentage",
        "overage_limit": 120
      }
    ]
  }
}

Response

OK

idstring nullable required

The unique identifier of the entity

namestring nullable required

The name of the entity

customer_idstring nullable

The customer ID this entity belongs to

feature_idstring nullable

The feature ID this entity belongs to

created_atnumber required

Unix timestamp when the entity was created

env'sandbox' | 'live' required

The environment (sandbox/live)

balancesobject required
flagsobject required

Example response

{
  "id": "seat_42",
  "name": "Seat 42",
  "customer_id": "cus_123",
  "feature_id": "seats",
  "created_at": 1771409161016,
  "env": "sandbox",
  "subscriptions": [
    {
      "plan_id": "pro_plan",
      "auto_enable": true,
      "add_on": false,
      "status": "active",
      "past_due": false,
      "canceled_at": null,
      "expires_at": null,
      "trial_ends_at": null,
      "started_at": 1771431921437,
      "current_period_start": 1771431921437,
      "current_period_end": 1771999921437,
      "quantity": 1
    }
  ],
  "purchases": [],
  "balances": {
    "messages": {
      "feature_id": "messages",
      "granted": 100,
      "remaining": 72,
      "usage": 28,
      "unlimited": false,
      "overage_allowed": false,
      "max_purchase": null,
      "next_reset_at": 1773851121437,
      "breakdown": [
        {
          "id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
          "plan_id": "pro_plan",
          "included_grant": 100,
          "prepaid_grant": 0,
          "remaining": 72,
          "usage": 28,
          "unlimited": false,
          "reset": {
            "interval": "month",
            "resets_at": 1773851121437
          },
          "price": null,
          "expires_at": null
        }
      ]
    }
  },
  "invoices": []
}