> ## Documentation Index > Fetch the complete documentation index at: https://docs.beinfi.com/llms.txt > Use this file to discover all available pages before exploring further. # Get customer state > In one read: the enrollment, the balance of each meter, live subscriptions (with their items) and current-period usage. Use it to render the customer's panel or to decide, before serving a request, whether they still have balance. `customerID` here is the enrollment ID, not the customer ID. ## OpenAPI ````yaml /api-reference/openapi.en.json get /customers/{customerID}/state openapi: 3.1.0 info: title: Infi API version: 0.0.1 description: > The Infi REST API: catalog, customers, usage metering, subscriptions, invoices, payments and checkout. **Authentication.** Send your secret key as `Authorization: Bearer sk_test_…` (sandbox) or `sk_live_…` (production). The key prefix selects the environment. Checkout routes (`/pay/*`) and `/public/*` take no key: they run in the payer's browser. **Idempotency.** Every request that changes data requires an `Idempotency-Key` header. A retry with the same key returns the original response instead of running again. **Amounts.** Money and quantities travel as decimal strings (`"150.00"`, `"0.0001"`), never as floating-point numbers. **Errors.** The body carries `error_code` (stable, branch on it), `message` (for humans) and `tracer_id` (send it to support). Rate-limit and idempotency errors are nested under `error`, with `code` and `request_id`. servers: - url: https://api-sandbox.beinfi.com description: Sandbox - url: https://api.beinfi.com description: Production security: - bearerAuth: [] tags: - name: Catalog - name: Customers - name: Metering - name: Subscriptions - name: Invoices - name: Payments - name: Checkout - name: Coupons - name: Billing - name: Account - name: Webhooks - name: Test account - name: Rail - name: Storefronts paths: /customers/{customerID}/state: parameters: - $ref: '#/components/parameters/EnrollmentIDInPath' get: tags: - Customers summary: Get customer state description: > In one read: the enrollment, the balance of each meter, live subscriptions (with their items) and current-period usage. Use it to render the customer's panel or to decide, before serving a request, whether they still have balance. `customerID` here is the enrollment ID, not the customer ID. operationId: getCustomerState responses: '200': content: application/json: schema: $ref: '#/components/schemas/CustomerState' description: Customer state. '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' components: parameters: EnrollmentIDInPath: name: customerID in: path required: true schema: type: string format: uuid description: ID of the customer's enrollment in the product (not the customer ID). schemas: CustomerState: type: object required: - customer - balances - subscriptions - usage properties: customer: $ref: '#/components/schemas/ProductCustomer' description: The enrollment. balances: type: array items: $ref: '#/components/schemas/WalletBalance' description: One balance per meter. subscriptions: type: array items: $ref: '#/components/schemas/Subscription' description: Live subscriptions, with their items. usage: $ref: '#/components/schemas/UsageReport' description: Current-period usage. description: >- The customer's state in one read: the enrollment, each meter's balance, live subscriptions and current-period usage. ProductCustomer: type: object properties: id: type: string format: uuid description: Enrollment ID. This is the one billing and usage calls expect. customerId: type: string format: uuid description: Customer ID. Do not use it for billing and usage calls; use `id`. productId: type: string format: uuid externalId: type: string description: The customer's id in your own system. name: type: - string - 'null' email: type: - string - 'null' taxId: type: - string - 'null' description: CPF or CNPJ. pspRef: type: - string - 'null' description: >- The customer's reference with the payment processor, when there is one. metadata: type: object additionalProperties: true description: The free-form data sent at enrollment. creditAlertSent: type: boolean description: >- Whether the low-balance alert has already been sent for this enrollment. createdAt: type: string format: date-time description: >- An enrollment: this customer in this product. The `id` is the enrollment ID that subscriptions, invoices, usage and balances reference. WalletBalance: type: object properties: meter: type: string description: Meter key. balance: type: string description: Current balance, as a decimal string. Can be negative. total: type: string description: Total ever credited to this meter. Subscription: type: object properties: id: type: string format: uuid customerId: type: string format: uuid description: Enrollment ID. productVersionId: type: string format: uuid description: >- The product version subscribed to. It sets the price billed, even if the product changes later. status: type: string enum: - trialing - active - past_due - paused - canceled billingCycle: type: string enum: - weekly - monthly - annual collectionMethod: type: string enum: - charge_automatically - send_invoice description: >- `charge_automatically` charges on its own; `send_invoice` sends the invoice for the customer to pay. billingMode: type: string enum: - arrears - advance description: '`advance` bills at the start of the period; `arrears`, at the end.' anchor: type: string format: date-time description: Reference date the billing periods are counted from. nextBillingDate: type: - string - 'null' format: date-time description: Next billing date. startedAt: type: string format: date-time canceledAt: type: - string - 'null' format: date-time items: type: array items: $ref: '#/components/schemas/SubscriptionItem' description: What the subscription bills or grants. UsageReport: type: object required: - customerId - from - to - meters properties: customerId: type: string format: uuid description: Enrollment ID. from: type: string format: date-time description: Window start. to: type: string format: date-time description: Window end. meters: type: array items: $ref: '#/components/schemas/MeterUsage' description: One total per meter. description: An enrollment's usage totals per meter over a time window. Error: type: object required: - message - error_code - tracer_id properties: message: type: string description: Human-readable sentence. error_code: $ref: '#/components/schemas/ErrorCode' description: Stable error code. Branch on it. tracer_id: type: string description: Request id. Include it when contacting support. description: >- The standard error body. It is flat (no `error` wrapper) and the trace id is `tracer_id`. NotFoundError: type: object required: - message - error_code - tracer_id - resource properties: message: type: string error_code: $ref: '#/components/schemas/ErrorCode' tracer_id: type: string resource: type: string SubscriptionItem: type: object properties: id: type: string format: uuid kind: type: string enum: - recurring_fee - credit_grant - metered_usage - prepaid_usage description: >- `recurring_fee` is the fixed recurring fee; `credit_grant`, credits granted each cycle; `metered_usage`, usage billed afterwards; `prepaid_usage`, usage paid upfront. timing: type: - string - 'null' enum: - advance - arrears - null description: '`advance` bills at the start of the period; `arrears`, at the end.' productVersionId: type: string format: uuid description: The product version the item comes from. createdAt: type: string format: date-time canceledAt: type: - string - 'null' format: date-time MeterUsage: type: object required: - meterId - meter - unit - totalValue - eventCount properties: meterId: type: string format: uuid meter: type: string description: Meter key. unit: type: string description: The meter's unit. totalValue: type: string description: Quantity summed over the window, as a decimal string. eventCount: type: integer description: How many events were recorded. totalAmount: type: - string - 'null' description: >- Money value of that quantity at the applicable price. Null when the meter has no price. currency: type: - string - 'null' description: Currency of `totalAmount`. ErrorCode: type: string examples: - internal_error - validation_failed - bad_request - unauthorized - forbidden - not_found - conflict - rate_limited description: >- Stable error code. The list is open: besides the generic codes, each area defines its own (`coupon_expired`, `insufficient_balance`, `version_not_draft`, `idempotency_key_reused`…). Handle a code you do not recognize by its HTTP status and show `message`; do not fail parsing the response. responses: Unauthorized: content: application/json: schema: $ref: '#/components/schemas/Error' description: Missing or invalid API key. NotFound: content: application/json: schema: $ref: '#/components/schemas/NotFoundError' description: Resource not found. securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your account's secret key: `Authorization: Bearer sk_test_…` or `sk_live_…`. Server-side only. ````