# About the Billable Items API

The billable items feature allows Wix users to manage custom billable products and services that can be added to invoices that are sent to customers for payment. 

The Billable Items API enables you to create, update, and organize billable items to streamline a site's billing process and integrate with Wix's business management platform.

This functionality enables you to quickly add custom items to invoices and send them out for payment, without the need to install any apps made by Wix.

With the Billable Items API, you can:

- Create and manage billable items for products or services with detailed information.
- Organize items with tags for better categorization and filtering.
- Set pricing and tax information for accurate billing using tax groups.
- Add images to visually represent items using the Wix Media Manager.
- Query and filter items based on various criteria including price, name, and tags.
- Perform bulk operations to efficiently update multiple items at once.
- Receive real-time notifications when items are created, updated, or deleted, by listening for events.

## About billable items

A billable item represents a billable product or service that can be added to an invoice. Billable items include details like:

- Name and description.
- Price information.
- Tax group associations.
- Visual representation (images).
- Custom metadata through extended fields.
- Organizational tags.

> **Note**: Any billable product or service added to a site through an app made by Wix (Wix Stores, Wix Bookings, and so on), is automatically available to be used in invoices and therefore there is no need to integrate these with the Billable Items API. This API is only intended for custom items that aren't managed by an app made by Wix.


## Before you begin

- Tax group IDs reference the [Wix eCommerce tax groups](fallback::https://dev.wix.com/docs/sdk/backend-modules/ecom/tax-groups/introduction) and must be valid existing tax groups.
- Image uploads must be handled through the [Wix Media Manager](fallback::https://dev.wix.com/docs/sdk/backend-modules/media/introduction) before referencing them in billable items.

## Use cases
- [Export billable items to an external accounting system or inventory management system](fallback::https://dev.wix.com/docs/sdk/backend-modules/get-paid/billable-items/sample-flows#export-billable-items-to-an-external-accounting-system-or-inventory-management-system)
- [Create a custom pricing page with categorized services](fallback::https://dev.wix.com/docs/sdk/backend-modules/get-paid/billable-items/sample-flows#create-a-custom-pricing-page-with-categorized-services)
- [Bulk update pricing with seasonal discounts](fallback::https://dev.wix.com/docs/sdk/backend-modules/get-paid/billable-items/sample-flows#bulk-update-pricing-with-seasonal-discounts)


## Terminology

- **Billable item**: A billable product or service that can be added to invoices, containing details like name, description, price, and tax information.
- **Tax group**: A reference to tax rules that determine how taxes are categorized. See the [Tax Groups API](fallback::https://dev.wix.com/docs/sdk/backend-modules/ecom/tax-groups/introduction) for more information.

# Sample Use Cases and Flows

This article shares some possible use cases you can support,
as well as a sample flow that could support each use case.
This can be a helpful jumping off point as you plan your implementation.

## Export billable items to an external accounting system or inventory management system

Keep an external accounting system synchronized with Wix billable items.

To implement this integration:

1. Perform an initial data load by calling [Query Billable Items](fallback::https://dev.wix.com/docs/sdk/backend-modules/get-paid/billable-items/query-billable-items) with pagination to retrieve all existing items.

2. Map and upload the billable items to the external system:
   - `name` → Product/Service name
   - `description` → Product/Service description
   - `price` → Base price
   - `taxGroupId` → Tax category (if supported)

3. Store the current timestamp for future synchronization.

4. Set up a scheduled job to periodically check for new or updated items by calling [Query Billable Items](fallback::https://dev.wix.com/docs/sdk/backend-modules/get-paid/billable-items/query-billable-items) with a filter for items created or updated since the last sync.

5. Allow site administrators to configure the synchronization frequency through your app settings.

## Create a custom pricing page with categorized services

Create a structured pricing page that organizes services into categories using tags.

To implement this feature:

1. Create tags for your service categories using the Tags API (For example, "consulting", "training", or "support").

2. Create billable items for each service with appropriate category tags by calling [Create Billable Item](fallback::https://dev.wix.com/docs/sdk/backend-modules/get-paid/billable-items/create-billable-item).

3. Query BillableItems by tag to display them in the appropriate category sections using [Query Billable Items](fallback::https://dev.wix.com/docs/sdk/backend-modules/get-paid/billable-items/query-billable-items) with a filter for specific tags.

4. Display the items on your custom pricing page, organized by category and sorted by price.

5. When prices change, call [Update Billable Item](fallback::https://dev.wix.com/docs/sdk/backend-modules/get-paid/billable-items/update-billable-item) to update the pricing information.

## Bulk update pricing with seasonal discounts

Apply seasonal discounts to multiple services at once using bulk update functionality.

To implement this feature:

1. Query all billable items that should receive the discount by calling [Query Billable Items](fallback::https://dev.wix.com/docs/sdk/backend-modules/get-paid/billable-items/query-billable-items) with a filter for items tagged as "seasonal-eligible".

2. Calculate the discounted price for each item (e.g., 20% off).

3. Call [Bulk Update Billable Items](fallback::https://dev.wix.com/docs/sdk/backend-modules/get-paid/billable-items/bulk-update-billable-items) to update all prices at once, including the item ID, current revision, and new price for each item.

4. Handle potential errors in the response by checking the `bulkActionMetadata` for success and failure counts, and implement appropriate error handling for specific error codes.

5. When the seasonal discount ends, repeat the process to restore original prices.

Coding Examples

Sled Tests

Go Headless

Build Apps

Client

API Preview

Ricos

Develop Websites

REST

Velo

Picasso

GraphQL (Alpha)

bulkUpdateBillableItems( )