Getting Started

Create a scoped API key in Connections to call the supported Agent API. The generated reference below lists the active operations. Legacy OAuth2 examples apply only to clients that are already provisioned.

External Gateway origin

https://api.billixi.com

This is the public Gateway origin in the production Nginx configuration. Set BILLIXI_API_BASE_URL to your own public Gateway origin when self-hosting. The site's /api/gateway path is a browser BFF route, not the external Agent API base URL.

Authentication

Connection keys authorize only the operations in the generated Agent API contract, with your current account and workspace permissions still enforced. Public catalog operations need no key. Existing OAuth2 clients use the separate legacy examples below.

  1. Create a connection and choose only the capabilities your tool needs
  2. Save the one-time API key on your server; it cannot be retrieved later
  3. Find an enabled operation and request example in the Agent API reference below
  4. Send the key as Authorization: Bearer <API_KEY> to the public Gateway

Webhooks

Receive signed HTTPS events for eligible product, payment, affiliate, support, and delivery changes.

Configure personal endpoints in Connections → Webhooks.

Security notes (quick)

Treat API keys and webhook signing secrets like passwords: store them on your server, never ship them to browsers, rotate if exposed, and grant only needed capabilities.

Error Handling

Use the downloadable Agent OpenAPI schema for each operation's responses. Invalid keys return 401, missing grants return 403, quota limits return 429, and dependency failures can return 503. Legacy Payment and Workspace APIs may use this `ApiResponse` envelope: 

{
  "success": false,
  "data": null,
  "errors": [
    { "message": "Human-readable error message", "code": "OptionalCode" }
  ],
  "meta": null
}

Connect your agent

Choose your app and follow its setup steps.

https://api.billixi.com/mcp

App availability depends on your plan, version and organization settings.

Agent API reference

The public contract lists the operations enabled for an opaque connection key. Anonymous catalog endpoints are marked Public. Connection and webhook management require a human session.

Manage connections and test requestsWebhook reference

Loading API reference…

Testing and contract download

Use the OpenAPI contract to inspect the supported paths, parameters, request bodies and responses for your integration.

Download OpenAPI JSON

API keys and permissions

Agent connections

Create a named, expiring connection in Account settings → Connections. The opaque API key is shown once. Grant only the capabilities needed, store the key server side, and rotate or revoke it from the same page. Current user and workspace permissions still apply. 

BILLIXI_API_BASE_URL=https://api.billixi.com
BILLIXI_API_KEY=bxk_…
Authorization: Bearer <BILLIXI_API_KEY>

Agent keys cannot manage connections or webhook destinations. Checkout and other money flows can return a human continuation; an API response is not an approval or completed payment. See the generated contract and request examples below.

Legacy integrations reference

The OAuth2, Payment and Workspace sections below are retained for already-provisioned clients. New Agent API integrations should use named connections and the generated operation contract above.

OAuth2 Overview

This legacy guide is for already-provisioned OAuth2 clients. It does not provide a self-service client creation path. Request only the scopes assigned to that client, such as payment:read or workspaces:read.

Getting Access Token

If you already have a provisioned OAuth2 client, POST its credentials to the token endpoint to request an access token.

Request

POST https://auth.billixi.com/oauth2/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
client_id=YOUR_CLIENT_ID
client_secret=YOUR_CLIENT_SECRET
scope=payment:read workspaces:read

Response 

{
  "access_token": "eyJhbGc...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Code Examples 

// Get OAuth2 token using Client Credentials flow
const response = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'payment:read workspaces:read'
  })
});
if (!response.ok) throw new Error(`Token request failed: ${response.status}`);

const { access_token } = await response.json();

// Use access_token in Authorization header: Bearer {access_token}

Token Refresh

Use the token response's expires_in value. When the token expires, request another with the same provisioned client credentials; this flow has no separate refresh token.

Workflows

Use the connection context for workspace identity, then grant only the capabilities a workflow needs. Mutations that create or change resources need endpoint-specific idempotency and revision checks; human approval remains required where the contract says so.

  • Support: create a ticket with an idempotency key, replay an uncertain request with the same key and body, then use the returned revision for a reply.
  • Seller draft: create and update with the returned revision; upload through the supported chunk flow and submit for review. Submission does not mean publication.
  • Buyer access: read owned orders and entitlements; request delivery only for an active entitlement. Checkout responses can require a human continuation.

Webhook receiver workflow

Errors and rate limits

The operation reference shows response codes and descriptions from the generated contract. Common outcomes include 401 invalid/expired/revoked key, 403 missing capability/current permission, 404 hidden ownership, 409 conflict, 412 stale revision, 428 missing precondition, 429 rate limit, and 503 unavailable owner/dependency.

Honor Retry-After when returned. Connection quota is shared across services and endpoint limits may be stricter. A tester timeout does not cancel a request already accepted by the Gateway.

Idempotency and concurrency

A network timeout leaves the outcome unknown. Retry only documented idempotent operations with the same key and byte-equivalent request. Use If-Match with the latest ETag for revision-protected writes; a 412 requires reading current state. Do not repeat financial or provider effects just because a response was lost.

Payment API (legacy catalog)

Legacy reference for existing OAuth2 clients and public catalog calls. Availability depends on the deployed public Gateway and assigned scopes. Connection-key operations are listed only in the generated Agent API reference above.

GET
/api/v1/payment/workspaces/{workspaceId}/products

List workspace products (owner + promoted)

OAuth2payment:read

Parameters

workspaceId
Required
uuid

Workspace ID

relationship
string

all | owner | promoted

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'payment:read',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const workspaceId = 'YOUR_WORKSPACE_ID';
const relationship = 'all';
let path = '/api/v1/payment/workspaces/{workspaceId}/products';
path = path.replace('{workspaceId}', encodeURIComponent(workspaceId));
const url = new URL(path, 'https://api.billixi.com');
url.searchParams.set('relationship', relationship);

// Make API request
const response = await fetch(url, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
GET
/api/v1/payment/workspaces/{workspaceId}/products/capabilities

Workspace product capabilities (seller vs promoter)

OAuth2payment:read

Parameters

workspaceId
Required
uuid

Workspace ID

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'payment:read',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const workspaceId = 'YOUR_WORKSPACE_ID';
let path = '/api/v1/payment/workspaces/{workspaceId}/products/capabilities';
path = path.replace('{workspaceId}', encodeURIComponent(workspaceId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
GET
/api/v1/payment/workspaces/{workspaceId}/catalog/products

List catalog products (seller)

OAuth2payment:read

Parameters

workspaceId
Required
uuid

Workspace ID

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'payment:read',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const workspaceId = 'YOUR_WORKSPACE_ID';
let path = '/api/v1/payment/workspaces/{workspaceId}/catalog/products';
path = path.replace('{workspaceId}', encodeURIComponent(workspaceId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
GET
/api/v1/payment/workspaces/{workspaceId}/catalog/products/{productId}

Get catalog product by ID

OAuth2payment:read

Parameters

workspaceId
Required
uuid

Workspace ID

productId
Required
uuid

Product ID

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'payment:read',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const workspaceId = 'YOUR_WORKSPACE_ID';
const productId = 'YOUR_PRODUCT_ID';
let path = '/api/v1/payment/workspaces/{workspaceId}/catalog/products/{productId}';
path = path.replace('{workspaceId}', encodeURIComponent(workspaceId));
path = path.replace('{productId}', encodeURIComponent(productId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
POST
/api/v1/payment/workspaces/{workspaceId}/catalog/products

Create catalog product (requires payment:write scope)

OAuth2payment:write

Parameters

workspaceId
Required
uuid

Workspace ID

Request Body 

{
  "name": "Digital course",
  "shortDescription": "Short summary for the store",
  "fullDescription": "Full product description",
  "digitalSubtype": 2,
  "basePrice": 29.99,
  "network": 1,
  "affiliateFeePercentage": 20,
  "affiliateEnabled": true,
  "publishToStore": false,
  "seoTitle": null,
  "seoDescription": null,
  "variants": []
}

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'payment:write',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const workspaceId = 'YOUR_WORKSPACE_ID';
let path = '/api/v1/payment/workspaces/{workspaceId}/catalog/products';
path = path.replace('{workspaceId}', encodeURIComponent(workspaceId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${access_token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Digital course",
    "shortDescription": "Short summary for the store",
    "fullDescription": "Full product description",
    "digitalSubtype": 2,
    "basePrice": 29.99,
    "network": 1,
    "affiliateFeePercentage": 20,
    "affiliateEnabled": true,
    "publishToStore": false,
    "seoTitle": null,
    "seoDescription": null,
    "variants": []
}),
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
PUT
/api/v1/payment/workspaces/{workspaceId}/catalog/products/{productId}

Update catalog product (full replacement; include every variant and SEO field you want to keep)

OAuth2payment:write

Parameters

workspaceId
Required
uuid

Workspace ID

productId
Required
uuid

Product ID

Request Body 

{
  "name": "Digital course",
  "shortDescription": "Updated short summary",
  "fullDescription": "Updated full product description",
  "digitalSubtype": 2,
  "basePrice": 29.99,
  "network": 1,
  "affiliateFeePercentage": 20,
  "affiliateEnabled": true,
  "publishToStore": false,
  "seoTitle": null,
  "seoDescription": null,
  "variants": []
}

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'payment:write',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const workspaceId = 'YOUR_WORKSPACE_ID';
const productId = 'YOUR_PRODUCT_ID';
let path = '/api/v1/payment/workspaces/{workspaceId}/catalog/products/{productId}';
path = path.replace('{workspaceId}', encodeURIComponent(workspaceId));
path = path.replace('{productId}', encodeURIComponent(productId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${access_token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Digital course",
    "shortDescription": "Updated short summary",
    "fullDescription": "Updated full product description",
    "digitalSubtype": 2,
    "basePrice": 29.99,
    "network": 1,
    "affiliateFeePercentage": 20,
    "affiliateEnabled": true,
    "publishToStore": false,
    "seoTitle": null,
    "seoDescription": null,
    "variants": []
}),
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
POST
/api/v1/payment/workspaces/{workspaceId}/catalog/products/{productId}/submit-for-review

Submit the current product version for moderation; this never publishes directly

OAuth2payment:write

Parameters

workspaceId
Required
uuid

Workspace ID

productId
Required
uuid

Product ID

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'payment:write',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const workspaceId = 'YOUR_WORKSPACE_ID';
const productId = 'YOUR_PRODUCT_ID';
let path = '/api/v1/payment/workspaces/{workspaceId}/catalog/products/{productId}/submit-for-review';
path = path.replace('{workspaceId}', encodeURIComponent(workspaceId));
path = path.replace('{productId}', encodeURIComponent(productId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
POST
/api/v1/payment/workspaces/{workspaceId}/catalog/products/{productId}/hide

Hide a live product while preserving its current moderation approval

OAuth2payment:write

Parameters

workspaceId
Required
uuid

Workspace ID

productId
Required
uuid

Product ID

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'payment:write',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const workspaceId = 'YOUR_WORKSPACE_ID';
const productId = 'YOUR_PRODUCT_ID';
let path = '/api/v1/payment/workspaces/{workspaceId}/catalog/products/{productId}/hide';
path = path.replace('{workspaceId}', encodeURIComponent(workspaceId));
path = path.replace('{productId}', encodeURIComponent(productId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
POST
/api/v1/payment/workspaces/{workspaceId}/catalog/products/{productId}/unhide

Make a seller-hidden product live only when its exact current version is approved

OAuth2payment:write

Parameters

workspaceId
Required
uuid

Workspace ID

productId
Required
uuid

Product ID

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'payment:write',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const workspaceId = 'YOUR_WORKSPACE_ID';
const productId = 'YOUR_PRODUCT_ID';
let path = '/api/v1/payment/workspaces/{workspaceId}/catalog/products/{productId}/unhide';
path = path.replace('{workspaceId}', encodeURIComponent(workspaceId));
path = path.replace('{productId}', encodeURIComponent(productId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
GET
/api/v1/payment/workspaces/{workspaceId}/payment-links

List payment links

OAuth2payment:read

Parameters

workspaceId
Required
uuid

Workspace ID

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'payment:read',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const workspaceId = 'YOUR_WORKSPACE_ID';
let path = '/api/v1/payment/workspaces/{workspaceId}/payment-links';
path = path.replace('{workspaceId}', encodeURIComponent(workspaceId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
GET
/api/v1/payment/workspaces/{workspaceId}/payment-links/{paymentLinkId}

Get payment link by ID

OAuth2payment:read

Parameters

workspaceId
Required
uuid

Workspace ID

paymentLinkId
Required
uuid

Payment link ID

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'payment:read',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const workspaceId = 'YOUR_WORKSPACE_ID';
const paymentLinkId = 'YOUR_PAYMENT_LINK_ID';
let path = '/api/v1/payment/workspaces/{workspaceId}/payment-links/{paymentLinkId}';
path = path.replace('{workspaceId}', encodeURIComponent(workspaceId));
path = path.replace('{paymentLinkId}', encodeURIComponent(paymentLinkId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
POST
/api/v1/payment/workspaces/{workspaceId}/payment-links/{paymentLinkId}/affiliate-link

Create affiliate (child) payment link

OAuth2payment:write

Parameters

workspaceId
Required
uuid

Workspace ID

paymentLinkId
Required
uuid

Canonical payment link ID

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'payment:write',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const workspaceId = 'YOUR_WORKSPACE_ID';
const paymentLinkId = 'YOUR_PAYMENT_LINK_ID';
let path = '/api/v1/payment/workspaces/{workspaceId}/payment-links/{paymentLinkId}/affiliate-link';
path = path.replace('{workspaceId}', encodeURIComponent(workspaceId));
path = path.replace('{paymentLinkId}', encodeURIComponent(paymentLinkId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
GET
/api/v1/payment/catalog/public/products

List public store products (marketplace)

Public

Parameters

search
string

Search query

sort
string

newest | commission | price_asc | price_desc | popular

kind
string

digital | physical | service

affiliateOnly
boolean

Only affiliate-enabled listings

page
number

Page number

pageSize
number

Page size (max 100)

Code example 

// Replace path and query values below with values from your authorized account.
let path = '/api/v1/payment/catalog/public/products';
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'GET',
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
GET
/api/v1/payment/catalog/public/marketplace/stats

Public marketplace stats (product counts, purchases)

Public

Code example 

// Replace path and query values below with values from your authorized account.
let path = '/api/v1/payment/catalog/public/marketplace/stats';
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'GET',
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
GET
/api/v1/payment/catalog/public/marketplace/activity

Anonymized recent marketplace activity feed

Public

Parameters

limit
number

Max items (1-50)

Code example 

// Replace path and query values below with values from your authorized account.
let path = '/api/v1/payment/catalog/public/marketplace/activity';
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'GET',
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
GET
/api/v1/payment/catalog/public/marketplace/top-promoters

Anonymized affiliate earnings leaderboard

Public

Parameters

limit
number

Max promoters (1-25)

period
string

7d | 30d | 90d

Code example 

// Replace path and query values below with values from your authorized account.
const period = '30d';
let path = '/api/v1/payment/catalog/public/marketplace/top-promoters';
const url = new URL(path, 'https://api.billixi.com');
url.searchParams.set('period', period);

// Make API request
const response = await fetch(url, {
  method: 'GET',
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
GET
/api/v1/payment/catalog/public/products/{slug}

Get public store product details by slug

Public

Parameters

slug
Required
string

Product slug

Code example 

// Replace path and query values below with values from your authorized account.
const slug = 'YOUR_SLUG';
let path = '/api/v1/payment/catalog/public/products/{slug}';
path = path.replace('{slug}', encodeURIComponent(slug));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'GET',
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
GET
/api/v1/payment/catalog/public/sellers/{slug}

Get the current public seller profile and store branding by handle

Public

Parameters

slug
Required
string

Current public store handle

Code example 

// Replace path and query values below with values from your authorized account.
const slug = 'YOUR_SLUG';
let path = '/api/v1/payment/catalog/public/sellers/{slug}';
path = path.replace('{slug}', encodeURIComponent(slug));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'GET',
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
GET
/api/v1/payment/catalog/public/memberships/{slug}

Get public membership listing by slug

Public

Parameters

slug
Required
string

Membership slug

Code example 

// Replace path and query values below with values from your authorized account.
const slug = 'YOUR_SLUG';
let path = '/api/v1/payment/catalog/public/memberships/{slug}';
path = path.replace('{slug}', encodeURIComponent(slug));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'GET',
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
GET
/api/v1/payment/catalog/public/licenses/{slug}

Get public license listing by slug

Public

Parameters

slug
Required
string

License slug

Code example 

// Replace path and query values below with values from your authorized account.
const slug = 'YOUR_SLUG';
let path = '/api/v1/payment/catalog/public/licenses/{slug}';
path = path.replace('{slug}', encodeURIComponent(slug));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'GET',
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
GET
/api/v1/payment/workspaces/{workspaceId}/analytics/promote/pulse

Promoter analytics pulse

OAuth2payment:read

Parameters

workspaceId
Required
uuid

Workspace ID

period
string

7d | 30d | 90d

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'payment:read',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const workspaceId = 'YOUR_WORKSPACE_ID';
let path = '/api/v1/payment/workspaces/{workspaceId}/analytics/promote/pulse';
path = path.replace('{workspaceId}', encodeURIComponent(workspaceId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
GET
/api/v1/payment/me/library

Buyer library — purchased products (account-scoped, not workspace)

OAuth2

Parameters

status
string

all | ready | in_progress

page
integer

Page number

pageSize
integer

Page size

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const status = 'ready';
const page = '1';
const pageSize = '24';
let path = '/api/v1/payment/me/library';
const url = new URL(path, 'https://api.billixi.com');
url.searchParams.set('status', status);
url.searchParams.set('page', page);
url.searchParams.set('pageSize', pageSize);

// Make API request
const response = await fetch(url, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
GET
/api/v1/payment/me/orders/{intentId}

Buyer order detail with timeline (entitlement owner only)

OAuth2

Parameters

intentId
Required
uuid

Payment intent ID

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const intentId = 'YOUR_INTENT_ID';
let path = '/api/v1/payment/me/orders/{intentId}';
path = path.replace('{intentId}', encodeURIComponent(intentId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
POST
/api/v1/payment/me/orders/{intentId}/download-url

Issue short-lived signed download URL for an active entitlement

OAuth2

Parameters

intentId
Required
uuid

Payment intent ID

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const intentId = 'YOUR_INTENT_ID';
let path = '/api/v1/payment/me/orders/{intentId}/download-url';
path = path.replace('{intentId}', encodeURIComponent(intentId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());

Workspace API (legacy catalog)

Legacy reference for existing OAuth2 clients. Availability depends on the deployed public Gateway and assigned scopes. Use Connections for personal webhooks and scoped API keys.

GET
/api/v1/workspace/workspaces/slug-availability

Check whether a public store page name can be selected

OAuth2workspaces:read

Parameters

slug
Required
string

Normalized public page name (Unicode letters and digits supported)

workspaceId
uuid

Owned workspace; its current handle and its own reserved handles are available to it

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'workspaces:read',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const slug = 'YOUR_SLUG';
let path = '/api/v1/workspace/workspaces/slug-availability';
const url = new URL(path, 'https://api.billixi.com');
url.searchParams.set('slug', slug);

// Make API request
const response = await fetch(url, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
GET
/api/v1/workspace/workspaces

List workspaces

OAuth2workspaces:read

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'workspaces:read',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
let path = '/api/v1/workspace/workspaces';
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
GET
/api/v1/workspace/workspaces/{workspaceId}

Get workspace by ID

OAuth2workspaces:read

Parameters

workspaceId
Required
uuid

The workspace ID

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'workspaces:read',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const workspaceId = 'YOUR_WORKSPACE_ID';
let path = '/api/v1/workspace/workspaces/{workspaceId}';
path = path.replace('{workspaceId}', encodeURIComponent(workspaceId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
POST
/api/v1/workspace/workspaces

Create workspace

OAuth2

Request Body 

{
  "name": "My New Workspace",
  "slug": "my-new-workspace",
  "description": "Workspace description",
  "ownerDisplayName": "John Doe",
  "ownerEmail": "john@example.com"
}

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'workspaces:read',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
let path = '/api/v1/workspace/workspaces';
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${access_token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "My New Workspace",
    "slug": "my-new-workspace",
    "description": "Workspace description",
    "ownerDisplayName": "John Doe",
    "ownerEmail": "john@example.com"
}),
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
PUT
/api/v1/workspace/workspaces/{workspaceId}

Update workspace

OAuth2workspaces:write

Parameters

workspaceId
Required
uuid

The workspace ID

Request Body 

{
  "name": "Updated Workspace Name",
  "slug": "updated-slug",
  "description": "Updated description"
}

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'workspaces:write',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const workspaceId = 'YOUR_WORKSPACE_ID';
let path = '/api/v1/workspace/workspaces/{workspaceId}';
path = path.replace('{workspaceId}', encodeURIComponent(workspaceId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${access_token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Updated Workspace Name",
    "slug": "updated-slug",
    "description": "Updated description"
}),
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
DELETE
/api/v1/workspace/workspaces/{workspaceId}

Delete workspace

OAuth2workspaces:write

Parameters

workspaceId
Required
uuid

The workspace ID to delete

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'workspaces:write',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const workspaceId = 'YOUR_WORKSPACE_ID';
let path = '/api/v1/workspace/workspaces/{workspaceId}';
path = path.replace('{workspaceId}', encodeURIComponent(workspaceId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
GET
/api/v1/workspace/workspaces/{workspaceId}/preferences/appearance

Get appearance preferences

OAuth2workspaces:read

Parameters

workspaceId
Required
uuid

The workspace ID

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'workspaces:read',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const workspaceId = 'YOUR_WORKSPACE_ID';
let path = '/api/v1/workspace/workspaces/{workspaceId}/preferences/appearance';
path = path.replace('{workspaceId}', encodeURIComponent(workspaceId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
PUT
/api/v1/workspace/workspaces/{workspaceId}/preferences/appearance

Update appearance preferences

OAuth2workspaces:write

Parameters

workspaceId
Required
uuid

The workspace ID

Request Body 

{
  "primaryColor": "green",
  "accentColor": "teal",
  "fontFamily": "inter",
  "theme": "light",
  "borderRadius": "md",
  "animationSpeed": "normal",
  "logoUrl": "",
  "faviconUrl": ""
}

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'workspaces:write',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const workspaceId = 'YOUR_WORKSPACE_ID';
let path = '/api/v1/workspace/workspaces/{workspaceId}/preferences/appearance';
path = path.replace('{workspaceId}', encodeURIComponent(workspaceId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${access_token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "primaryColor": "green",
    "accentColor": "teal",
    "fontFamily": "inter",
    "theme": "light",
    "borderRadius": "md",
    "animationSpeed": "normal",
    "logoUrl": "",
    "faviconUrl": ""
}),
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
GET
/api/v1/workspace/workspaces/{workspaceId}/preferences/team

List team members

OAuth2workspaces:read

Parameters

workspaceId
Required
uuid

The workspace ID

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'workspaces:read',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const workspaceId = 'YOUR_WORKSPACE_ID';
let path = '/api/v1/workspace/workspaces/{workspaceId}/preferences/team';
path = path.replace('{workspaceId}', encodeURIComponent(workspaceId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
PUT
/api/v1/workspace/workspaces/{workspaceId}/preferences/team

Update team preferences

OAuth2workspaces:write

Parameters

workspaceId
Required
uuid

The workspace ID

Request Body 

{
  "allowInvites": true,
  "requireTwoFactor": false,
  "allowedDomains": [
    "example.com"
  ]
}

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'workspaces:write',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const workspaceId = 'YOUR_WORKSPACE_ID';
let path = '/api/v1/workspace/workspaces/{workspaceId}/preferences/team';
path = path.replace('{workspaceId}', encodeURIComponent(workspaceId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${access_token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "allowInvites": true,
    "requireTwoFactor": false,
    "allowedDomains": [
        "example.com"
    ]
}),
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
POST
/api/v1/workspace/workspaces/{workspaceId}/members

Invite member

OAuth2workspaces:write

Parameters

workspaceId
Required
uuid

The workspace ID

Request Body 

{
  "email": "user@example.com",
  "displayName": "Jane Doe",
  "avatarUrl": null,
  "role": "member"
}

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'workspaces:write',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const workspaceId = 'YOUR_WORKSPACE_ID';
let path = '/api/v1/workspace/workspaces/{workspaceId}/members';
path = path.replace('{workspaceId}', encodeURIComponent(workspaceId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${access_token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "email": "user@example.com",
    "displayName": "Jane Doe",
    "avatarUrl": null,
    "role": "member"
}),
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
PUT
/api/v1/workspace/workspaces/{workspaceId}/members/{memberId}

Update member role & grants

OAuth2workspaces:write

Parameters

workspaceId
Required
uuid

The workspace ID

memberId
Required
uuid

Member ID

Request Body 

{
  "role": "admin",
  "moduleRoles": [],
  "customGrants": []
}

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'workspaces:write',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const workspaceId = 'YOUR_WORKSPACE_ID';
const memberId = 'YOUR_MEMBER_ID';
let path = '/api/v1/workspace/workspaces/{workspaceId}/members/{memberId}';
path = path.replace('{workspaceId}', encodeURIComponent(workspaceId));
path = path.replace('{memberId}', encodeURIComponent(memberId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${access_token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "role": "admin",
    "moduleRoles": [],
    "customGrants": []
}),
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
PUT
/api/v1/workspace/workspaces/{workspaceId}/members/{memberId}/status

Update member status

OAuth2workspaces:write

Parameters

workspaceId
Required
uuid

The workspace ID

memberId
Required
uuid

Member ID

Request Body 

{
  "status": "active"
}

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'workspaces:write',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const workspaceId = 'YOUR_WORKSPACE_ID';
const memberId = 'YOUR_MEMBER_ID';
let path = '/api/v1/workspace/workspaces/{workspaceId}/members/{memberId}/status';
path = path.replace('{workspaceId}', encodeURIComponent(workspaceId));
path = path.replace('{memberId}', encodeURIComponent(memberId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${access_token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "status": "active"
}),
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
DELETE
/api/v1/workspace/workspaces/{workspaceId}/members/{memberId}

Remove member

OAuth2workspaces:write

Parameters

workspaceId
Required
uuid

The workspace ID

memberId
Required
uuid

Member ID

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'workspaces:write',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const workspaceId = 'YOUR_WORKSPACE_ID';
const memberId = 'YOUR_MEMBER_ID';
let path = '/api/v1/workspace/workspaces/{workspaceId}/members/{memberId}';
path = path.replace('{workspaceId}', encodeURIComponent(workspaceId));
path = path.replace('{memberId}', encodeURIComponent(memberId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
GET
/api/v1/workspace/workspaces/{workspaceId}/preferences/notification-settings

Get notification settings

OAuth2workspaces:read

Parameters

workspaceId
Required
uuid

The workspace ID

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'workspaces:read',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const workspaceId = 'YOUR_WORKSPACE_ID';
let path = '/api/v1/workspace/workspaces/{workspaceId}/preferences/notification-settings';
path = path.replace('{workspaceId}', encodeURIComponent(workspaceId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
PUT
/api/v1/workspace/workspaces/{workspaceId}/preferences/notification-settings

Update notification settings

OAuth2workspaces:write

Parameters

workspaceId
Required
uuid

The workspace ID

Request Body 

{
  "email": {
    "enabled": true
  }
}

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'workspaces:write',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const workspaceId = 'YOUR_WORKSPACE_ID';
let path = '/api/v1/workspace/workspaces/{workspaceId}/preferences/notification-settings';
path = path.replace('{workspaceId}', encodeURIComponent(workspaceId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${access_token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "email": {
        "enabled": true
    }
}),
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
GET
/api/v1/workspace/workspaces/permissions

List permission catalog

OAuth2permissions:read

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'permissions:read',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
let path = '/api/v1/workspace/workspaces/permissions';
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
GET
/api/v1/workspace/workspaces/{workspaceId}/permissions

Get role permissions for workspace

OAuth2permissions:read

Parameters

workspaceId
Required
uuid

The workspace ID

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'permissions:read',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const workspaceId = 'YOUR_WORKSPACE_ID';
let path = '/api/v1/workspace/workspaces/{workspaceId}/permissions';
path = path.replace('{workspaceId}', encodeURIComponent(workspaceId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
PUT
/api/v1/workspace/workspaces/{workspaceId}/permissions

Update role permissions for workspace

OAuth2permissions:write

Parameters

workspaceId
Required
uuid

The workspace ID

Request Body 

{
  "mappings": [
    {
      "role": 2,
      "permission": 9,
      "allowed": true
    }
  ]
}

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'permissions:write',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const workspaceId = 'YOUR_WORKSPACE_ID';
let path = '/api/v1/workspace/workspaces/{workspaceId}/permissions';
path = path.replace('{workspaceId}', encodeURIComponent(workspaceId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${access_token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "mappings": [
        {
            "role": 2,
            "permission": 9,
            "allowed": true
        }
    ]
}),
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
POST
/api/v1/workspace/workspaces/{workspaceId}/logo

Upload a JPEG, PNG, GIF, or WebP workspace logo as multipart/form-data (file; requires Workspace.UpdateGeneral permission; max 5 MiB)

OAuth2

Parameters

workspaceId
Required
uuid

The workspace ID

Request Body 

{
  "file": "JPEG, PNG, GIF, or WebP image file (max 5 MiB)"
}

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'workspaces:read',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const workspaceId = 'YOUR_WORKSPACE_ID';
let path = '/api/v1/workspace/workspaces/{workspaceId}/logo';
path = path.replace('{workspaceId}', encodeURIComponent(workspaceId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
  body: (() => {
    const form = new FormData();
    const input = document.querySelector('#store-image');
    if (!(input instanceof HTMLInputElement) || !input.files?.[0]) throw new Error('Choose an image first');
    form.append('file', input.files[0]);
    return form;
  })(),
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
DELETE
/api/v1/workspace/workspaces/{workspaceId}/logo

Delete the workspace logo (requires Workspace.UpdateGeneral permission)

OAuth2

Parameters

workspaceId
Required
uuid

The workspace ID

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'workspaces:read',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const workspaceId = 'YOUR_WORKSPACE_ID';
let path = '/api/v1/workspace/workspaces/{workspaceId}/logo';
path = path.replace('{workspaceId}', encodeURIComponent(workspaceId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
POST
/api/v1/workspace/workspaces/{workspaceId}/banner

Upload a JPEG, PNG, GIF, or WebP public store banner as multipart/form-data (file; requires Workspace.UpdateGeneral permission; max 5 MiB)

OAuth2

Parameters

workspaceId
Required
uuid

The workspace ID

Request Body 

{
  "file": "JPEG, PNG, GIF, or WebP image file (max 5 MiB)"
}

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'workspaces:read',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const workspaceId = 'YOUR_WORKSPACE_ID';
let path = '/api/v1/workspace/workspaces/{workspaceId}/banner';
path = path.replace('{workspaceId}', encodeURIComponent(workspaceId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
  body: (() => {
    const form = new FormData();
    const input = document.querySelector('#store-image');
    if (!(input instanceof HTMLInputElement) || !input.files?.[0]) throw new Error('Choose an image first');
    form.append('file', input.files[0]);
    return form;
  })(),
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
DELETE
/api/v1/workspace/workspaces/{workspaceId}/banner

Delete the public store banner (requires Workspace.UpdateGeneral permission)

OAuth2

Parameters

workspaceId
Required
uuid

The workspace ID

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'workspaces:read',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const workspaceId = 'YOUR_WORKSPACE_ID';
let path = '/api/v1/workspace/workspaces/{workspaceId}/banner';
path = path.replace('{workspaceId}', encodeURIComponent(workspaceId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
GET
/api/v1/workspace/invitations/validate

Validate invitation token (public)

Public

Parameters

token
Required
string

Invitation token

Code example 

// Replace path and query values below with values from your authorized account.
const token = 'YOUR_TOKEN';
let path = '/api/v1/workspace/invitations/validate';
const url = new URL(path, 'https://api.billixi.com');
url.searchParams.set('token', token);

// Make API request
const response = await fetch(url, {
  method: 'GET',
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
POST
/api/v1/workspace/invitations/accept

Accept invitation (public)

Public

Request Body 

{
  "token": "invitation_token"
}

Code example 

// Replace path and query values below with values from your authorized account.
let path = '/api/v1/workspace/invitations/accept';
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "token": "invitation_token"
}),
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
POST
/api/v1/workspace/invitations/decline

Decline invitation (public)

Public

Request Body 

{
  "token": "invitation_token"
}

Code example 

// Replace path and query values below with values from your authorized account.
let path = '/api/v1/workspace/invitations/decline';
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "token": "invitation_token"
}),
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());
POST
/api/v1/workspace/invitations/workspaces/{workspaceId}/members/{memberId}/resend

Resend invitation

OAuth2

Parameters

workspaceId
Required
uuid

The workspace ID

memberId
Required
uuid

Member ID

Code example 

// Get OAuth2 token
const tokenResponse = await fetch('https://auth.billixi.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    scope: 'workspaces:read',
  })
});
if (!tokenResponse.ok) throw new Error(`Token request failed: ${tokenResponse.status}`);
const { access_token } = await tokenResponse.json();

// Replace path and query values below with values from your authorized account.
const workspaceId = 'YOUR_WORKSPACE_ID';
const memberId = 'YOUR_MEMBER_ID';
let path = '/api/v1/workspace/invitations/workspaces/{workspaceId}/members/{memberId}/resend';
path = path.replace('{workspaceId}', encodeURIComponent(workspaceId));
path = path.replace('{memberId}', encodeURIComponent(memberId));
const url = new URL(path, 'https://api.billixi.com');

// Make API request
const response = await fetch(url, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
});
if (!response.ok) throw new Error(`API request failed: ${response.status} ${await response.text()}`);

console.log(await response.text());