Xero App Store API – Subscription and metered billing management.
Base URL: https://api.xero.com/appstore/2.0/
Grant type: Client Credentials (machine-to-machine, no user required).
Available in: AU, NZ, UK.
Authentication
Unlike other Xero APIs, the App Store API uses the Client Credentials grant.
Call client_credentials_token/0 to get a token — no user authorization required.
{:ok, token} = Xero.AppStore.client_credentials_token()
{:ok, subs} = Xero.AppStore.list_subscriptions(token)Subscription Statuses
"ACTIVE"— Subscription is active"CANCELED"— Subscription has been cancelled"TRIALING"— In trial period"PAST_DUE"— Payment overdue"INCOMPLETE"— Awaiting initial payment
Metered Billing
For usage-based pricing, call create_usage_record/4 after each billable event.
Usage is aggregated per billing period.
{:ok, _} = Xero.AppStore.create_usage_record(token, subscription_id, plan_id, %{
"quantity" => 5.0,
"timestamp" => "2024-01-15T12:00:00Z",
"productId" => "api-calls",
"priceId" => "per-1000-calls"
})Summary
Functions
Obtains a Client Credentials access token for the App Store API.
Creates a usage record for metered billing.
Retrieves a single subscription by ID.
Gets a specific usage record by ID.
Lists all subscriptions for your app (all tenants that have subscribed).
Lists usage records for a subscription plan.
Functions
@spec client_credentials_token() :: {:ok, Xero.Auth.Token.t()} | {:error, Xero.Error.t()}
Obtains a Client Credentials access token for the App Store API.
This does not require a user to authorize — it uses the app's
client_id and client_secret directly.
The token scope is marketplace.billing.
@spec create_usage_record(Xero.Auth.Token.t(), String.t(), String.t(), map()) :: {:ok, map()} | {:error, Xero.Error.t()}
Creates a usage record for metered billing.
Required fields
"quantity"— Number of units consumed (float)"timestamp"— ISO 8601 UTC timestamp of usage"productId"— ID of the metered product from your pricing config"priceId"— ID of the price from your pricing config
@spec get_subscription(Xero.Auth.Token.t(), String.t()) :: {:ok, map()} | {:error, Xero.Error.t()}
Retrieves a single subscription by ID.
@spec get_usage_record(Xero.Auth.Token.t(), String.t(), String.t(), String.t()) :: {:ok, map()} | {:error, Xero.Error.t()}
Gets a specific usage record by ID.
@spec list_subscriptions(Xero.Auth.Token.t()) :: {:ok, map()} | {:error, Xero.Error.t()}
Lists all subscriptions for your app (all tenants that have subscribed).
@spec list_usage_records(Xero.Auth.Token.t(), String.t(), String.t(), keyword()) :: {:ok, map()} | {:error, Xero.Error.t()}
Lists usage records for a subscription plan.