OpenAPI Specification
openapi: 3.0.0
info:
title: Xata API Keys Billing API
description: Xata API
version: '1.0'
contact:
name: help@xata.io
servers:
- url: https://api.xata.tech
description: Xata API
tags:
- name: Billing
description: Internal organization billing operations
x-displayName: Billing
paths:
/organizations/{organizationID}/billing/checkout-session:
post:
operationId: createBillingCheckoutSession
summary: Create a billing checkout session
description: Creates a Stripe checkout session used to activate card billing for an organization.
parameters:
- $ref: '#/components/parameters/OrganizationIDParam'
responses:
'200':
description: Billing checkout session created
content:
application/json:
schema:
$ref: '#/components/schemas/BillingCheckoutSessionResponse'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/AuthError'
'403':
$ref: '#/components/responses/AuthError'
5XX:
description: Unexpected Error
security:
- xata:
- org:write
tags:
- Billing
x-excluded: true
/organizations/{organizationID}/billing/payment-method-session:
post:
operationId: createBillingPaymentMethodSession
summary: Create a billing payment method session
description: Creates a Stripe setup-mode checkout session used to add or update an organization payment method.
parameters:
- $ref: '#/components/parameters/OrganizationIDParam'
responses:
'200':
description: Billing payment method session created
content:
application/json:
schema:
$ref: '#/components/schemas/BillingPaymentMethodSessionResponse'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/AuthError'
'403':
$ref: '#/components/responses/AuthError'
5XX:
description: Unexpected Error
security:
- xata:
- org:write
tags:
- Billing
x-excluded: true
/organizations/{organizationID}/billing/customer:
get:
operationId: getBillingCustomer
summary: Get billing customer details
description: Retrieves billing customer details for the specified organization.
parameters:
- $ref: '#/components/parameters/OrganizationIDParam'
responses:
'200':
description: Billing customer details
content:
application/json:
schema:
$ref: '#/components/schemas/BillingCustomerResponse'
'401':
$ref: '#/components/responses/AuthError'
'403':
$ref: '#/components/responses/AuthError'
'404':
$ref: '#/components/responses/SimpleError'
5XX:
description: Unexpected Error
security:
- xata:
- org:read
tags:
- Billing
x-excluded: true
patch:
operationId: updateBillingCustomer
summary: Update billing customer details
description: Updates billing customer details for the specified organization.
parameters:
- $ref: '#/components/parameters/OrganizationIDParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateBillingCustomerRequest'
responses:
'200':
description: Billing customer updated
content:
application/json:
schema:
$ref: '#/components/schemas/BillingCustomerResponse'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/AuthError'
'403':
$ref: '#/components/responses/AuthError'
'404':
$ref: '#/components/responses/SimpleError'
5XX:
description: Unexpected Error
security:
- xata:
- org:write
tags:
- Billing
x-excluded: true
/organizations/{organizationID}/billing/invoices:
get:
operationId: getBillingInvoices
summary: List billing invoices
description: Retrieves billing invoices for the specified organization.
parameters:
- $ref: '#/components/parameters/OrganizationIDParam'
- name: cursor
in: query
description: Pagination cursor from a previous response
schema:
type: string
- name: limit
in: query
description: Number of invoices to fetch
schema:
type: integer
default: 20
maximum: 100
minimum: 1
responses:
'200':
description: Billing invoices
content:
application/json:
schema:
$ref: '#/components/schemas/BillingInvoicesResponse'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/AuthError'
'403':
$ref: '#/components/responses/AuthError'
'404':
$ref: '#/components/responses/SimpleError'
5XX:
description: Unexpected Error
security:
- xata:
- org:read
tags:
- Billing
x-excluded: true
/organizations/{organizationID}/billing/invoices/upcoming:
get:
operationId: getBillingUpcomingInvoice
summary: Get upcoming billing invoice
description: Retrieves the upcoming billing invoice for the specified organization's active subscription. Organizations are expected to have at most one active subscription.
parameters:
- $ref: '#/components/parameters/OrganizationIDParam'
responses:
'200':
description: Upcoming billing invoice
content:
application/json:
schema:
$ref: '#/components/schemas/BillingUpcomingInvoiceResponse'
'401':
$ref: '#/components/responses/AuthError'
'403':
$ref: '#/components/responses/AuthError'
'404':
$ref: '#/components/responses/SimpleError'
5XX:
description: Unexpected Error
security:
- xata:
- org:read
tags:
- Billing
x-excluded: true
components:
schemas:
BillingCreditDetails:
type: object
properties:
total_lifetime_credits:
type: number
format: double
last_expiry:
type: string
format: date-time
nullable: true
last_expiry_with_balance:
type: string
format: date-time
nullable: true
active_credits:
description: Credits with active status, a reached effective date, positive balance, and no past expiry.
type: array
items:
$ref: '#/components/schemas/BillingCredit'
last_active_credit_expiry:
type: string
format: date-time
nullable: true
total_active_credits:
type: number
format: double
days_until_last_active_credit_expiry:
description: Days until the last active credit expiry, or null when there is no future active credit expiry.
type: integer
nullable: true
days_until_last_expiry_with_balance:
description: Days until the last positive-balance credit expiry, or null when there is no future positive-balance credit expiry.
type: integer
nullable: true
required:
- total_lifetime_credits
- last_expiry
- last_expiry_with_balance
- active_credits
- last_active_credit_expiry
- total_active_credits
- days_until_last_active_credit_expiry
- days_until_last_expiry_with_balance
UpdateBillingCustomerRequest:
type: object
properties:
billing_email:
type: string
format: email
required:
- billing_email
PaginationMetadata:
type: object
properties:
has_more:
type: boolean
next_cursor:
type: string
nullable: true
required:
- has_more
- next_cursor
BillingInvoicesResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/BillingInvoice'
pagination_metadata:
$ref: '#/components/schemas/PaginationMetadata'
required:
- data
- pagination_metadata
BillingCustomerResponse:
type: object
properties:
billing_email:
type: string
format: email
has_payment_method:
description: True when the customer has a valid Stripe default card payment method.
type: boolean
default_payment_method:
description: The Stripe default card payment method, when one is configured and retrievable.
allOf:
- $ref: '#/components/schemas/BillingPaymentMethod'
nullable: true
credits:
type: array
items:
$ref: '#/components/schemas/BillingCredit'
credit_details:
$ref: '#/components/schemas/BillingCreditDetails'
required:
- billing_email
- has_payment_method
- default_payment_method
- credits
- credit_details
BillingInvoice:
type: object
properties:
id:
type: string
invoice_number:
type: string
amount_due:
description: Decimal amount due.
type: number
format: double
currency:
type: string
invoice_date:
type: string
format: date-time
status:
type: string
enum:
- draft
- issued
- paid
- void
- synced
invoice_pdf:
type: string
nullable: true
required:
- id
- invoice_number
- amount_due
- currency
- invoice_date
- status
- invoice_pdf
BillingPaymentMethodSessionResponse:
type: object
properties:
url:
description: Stripe payment method session URL
type: string
format: uri
required:
- url
OrganizationID:
title: OrganizationID
type: string
pattern: '[a-zA-Z0-9_-~:]+'
x-oapi-codegen-extra-tags:
validate: identifier
BillingCheckoutSessionResponse:
type: object
properties:
url:
description: Stripe checkout session URL
type: string
format: uri
required:
- url
BillingPaymentMethodCard:
type: object
properties:
brand:
type: string
last4:
type: string
expiry_month:
type: integer
expiry_year:
type: integer
required:
- brand
- last4
- expiry_month
- expiry_year
BillingPaymentMethod:
type: object
properties:
card:
$ref: '#/components/schemas/BillingPaymentMethodCard'
required:
- card
BillingUpcomingInvoiceResponse:
type: object
properties:
created_at:
type: string
format: date-time
amount_due:
description: Decimal amount due.
type: number
format: double
currency:
type: string
target_date:
type: string
format: date-time
subtotal:
description: Decimal subtotal.
type: number
format: double
total:
description: Decimal total.
type: number
format: double
hosted_invoice_url:
type: string
format: uri
nullable: true
required:
- created_at
- amount_due
- currency
- target_date
- subtotal
- total
- hosted_invoice_url
BillingCredit:
type: object
properties:
id:
type: string
balance:
description: Remaining credit balance.
type: number
format: double
effective_date:
description: Date when the credit becomes usable.
type: string
format: date-time
expiry_date:
description: Date when the credit expires, or null for credits that do not expire.
type: string
format: date-time
nullable: true
maximum_initial_balance:
description: Initial credit balance before any usage.
type: number
format: double
status:
type: string
enum:
- active
- pending_payment
required:
- id
- balance
- effective_date
- expiry_date
- maximum_initial_balance
- status
responses:
AuthError:
description: Error returned when authentication or authorization fails
content:
application/json:
schema:
type: object
properties:
id:
description: Error identifier for tracking and debugging
type: string
message:
description: Human-readable error message explaining the issue
type: string
example:
message: invalid API key
required:
- message
BadRequestError:
description: Error returned when the request is malformed or contains invalid parameters
content:
application/json:
schema:
type: object
properties:
id:
description: Error identifier for tracking and debugging
type: string
message:
description: Human-readable error message explaining the issue
type: string
required:
- message
SimpleError:
description: Generic error response
content:
application/json:
schema:
type: object
properties:
id:
description: Error identifier for tracking and debugging
type: string
message:
description: Human-readable error message explaining the issue
type: string
required:
- message
parameters:
OrganizationIDParam:
name: organizationID
in: path
required: true
schema:
$ref: '#/components/schemas/OrganizationID'
description: Unique identifier for a specific organization
securitySchemes:
oidc:
type: openIdConnect
openIdConnectUrl: https://auth.xata.io/realms/xata/.well-known/openid-configuration
apiKey:
type: apiKey
in: header
name: Authorization
description: 'API key authentication using Bearer token format: Bearer <api_key>'
xata:
type: oauth2
flows:
implicit:
authorizationUrl: https://auth.xata.io/realms/xata/protocol/openid-connect/auth
scopes:
org:read: Read organization information
org:write: Create and modify organizations
keys:read: Read API keys
keys:write: Create and manage API keys
project:read: Read project information
project:write: Create and modify projects
branch:read: Read branch information
branch:write: Create and modify branches
metrics:read: Read metrics data
logs:read: Read logs data
credentials:read: Read credentials
credentials:write: Rotate credentials
marketplace:write: Register with cloud marketplaces
branchConnectionString:
type: apiKey
in: header
name: Connection-String
description: Branch PostgreSQL connection string (`postgres://user:pass@{branch}.{region}.xata.tech/db`), including the embedded password. The hostname selects the target branch, region, and endpoint type (the `-rw`/`-ro` suffix, see `EndpointType`), and must match the request host. Obtain it from the Xata dashboard or the control-plane API. This is the only credential the gateway accepts; the control-plane API key (Bearer token) is rejected here. For the WebSocket endpoint (`GET /v2`) the same connection string is conveyed via the PostgreSQL startup message instead of this header.
externalDocs:
url: https://xata.io/docs/api
x-tagGroups:
- name: Authentication API
tags:
- Organizations
- Users
- API Keys
- Marketplace
- Billing
- Webhooks
- name: Gateway API
tags:
- Gateway
- name: Projects API
tags:
- Projects Webhooks
- Projects
- Branches
- GitHub App
- Metrics
- Logs