Bonzai Business API

Welcome to the documentation for the Bonzai API, the programming interface for our content creator-focused platform.

Notice: API in Beta Version

Please be aware that the Bonzai API is currently in its beta version. We welcome your feedback and suggestions to improve its functionality and user experience. For any comments or useful remarks, feel free to reach out to us at [e-mail]. Your input is invaluable in helping us refine and enhance the API.

API access

Access to the Bonzai API is exclusively reserved for Bonzai Pro members.

Authentication System

The Bonzai API utilizes a bearer token authentication system to ensure secure access to its services. The token must be included in the Authorization header of every request made to the API.

Obtaining Your Token

To obtain your API token, simply visit: https://www.bonzai.pro/user/profile and then navigate to "Manage API Tokens".

---

Product Invitation

This route enables Pro members to grant their customers access to products without needing to go through the Bonzai checkout process.

Pro members can activate products seamlessly for promotional offers or when using external checkout systems, diversifying sales and marketing strategies beyond the Bonzai checkout process.

Grant access to a product

POST https://www.bonzai.pro/api/v1/products/{product_uuid}/invite

This endpoint grants access to a product by requiring an email. If the email matches a Bonzai user, it grants direct access. Otherwise, it sends an email invitation with a one-click link to create and activate the account.

You can find the product_uuid in any product-related URL: https://www.bonzai.pro/products/xBgq3Z3J

Path Parameters

Name	Type	Description
product_uuid	String	Can be found in any product-related URL.

Request Body

Name	Type	Description
email*	String	Must be a valid email address.
name	String	Useful when the Bonzai user doesn't exist. If only an email is provided, we assume the name from the email's prefix (before the @)
code	String	Can be used to revoke specific access or a set of accesses. Multiple invitations can share the same code.

200: OK Return an access object.

400: Bad Request Invalid request

Understanding code parameter

The code parameter plays a crucial role in managing access to your products. This parameter empowers you to grant or revoke access efficiently.

Granting Access

When you use the Bonzai API to grant access to a product, you can include the code parameter. This allows you to assign a code to the granted access, ensuring precise control.

Revoking Access

Conversely, when you need to revoke access to a product, you can provide the associated code parameter. This action removes access not only for the individual who initiated it but for all individuals who share the same code.

Two Usage Scenarios

1. Individualized Codes: You have the option to assign a distinct code to each individual, enabling personalized access control, such as managing individual subscriptions. You might use a Stripe subscription ID, an email address any internal ID you have if your workflow.

2. Shared Codes: Alternatively, you can utilize the same code for multiple users. This is particularly useful when offering time-limited free promotions or other scenarios where several individuals should have access using the same code.

By grasping the significance of the code parameter in the Bonzai API, you gain the flexibility to adapt your access control strategy to various use cases and business models seamlessly.

Product Revocation

This route enables Pro members to revoke their customers product access.

This functionality is particularly useful in scenarios such as when a subscription is no longer active, or when a limited-time offer concludes, allowing Pro members to manage their product offerings effectively and responsively.

Revoke access to a product

POST https://www.bonzai.pro/api/v1/products/{product_uuid}/revoke

This endpoint revokes access to a product.

You can revoke access using applicable filters such as access id, user_id, email, or code.

You must provide at least one valid filter.

Query Parameters

Name	Type	Description
product_uuid*	String	Can be found in any product-related URL.

Request Body

Name	Type	Description
user_id	String	As provided in the invite request response
email	String	Only search for invited members (not Bonzai user yet). Not recommended to use.
code	String	The same invite code you provided using the invite route.

200: OK A set of revoked access ids

400: Bad Request Invalid request

Create a custom product checkout

POST https://www.bonzai.pro/api/v1/products/{product_uuid}/checkout

This endpoint creates a custom checkout session for a given product, allowing you to set price, currency, VAT options, and payment mode (one-off or subscription). The response returns the unique order_id and a checkout_url where the customer can complete the payment.

Query Parameters

Name	Type	Description
product_uuid*	String	Can be found in any product-related URL.

Request Body

Name	Type	Required?	Description
amount	Float	yes	The price to be charged for this checkout session.
currency	String	yes	Currency code of the transaction. Available values: EUR or USD
is_vat_incl	Boolean	no	Defines whether the amount already includes VAT. Defaults to true.
mode	String	no	Payment mode. Can be one_off for a single payment or subscription for recurring billing. Defaults to one_off.
interval	String	no	Interval for subscriptions. Valid values: monthly, yearly. Only applies if mode=subscription.
metadata	Array	no	A custom key/value array that can be passed with the session. It will be attached to the order and returned both through the order retrieval endpoint and via webhooks.
email	String	no	Prefills the customer’s email address in the checkout form to simplify the flow and avoid retyping.
title	String	no	Replaces the default product list display with a custom title string.
redirect_url	String	no	The URL where the customer will be redirected after checkout, for both success and cancel outcomes.

The API will return a JSON response depending on the outcome of the request.

If the request is invalid (for example, missing or wrong parameters), you will receive a validation error response such as:

{
    "message": "The currency field is required.",
    "errors": {
        "currency": [
            "The currency field is required."
        ]
    }
}

If the request succeeds, the response will contain the newly created order details:

{
    "order_id": 34855,
    "checkout_url": "https://pay.bonzai.pro/manage/spa_34694qpxpvdu?expires=1756216156&signature=6c7ac54ae5962e298167ef8b7a68d61f8e95fcfe47e8dc937336e69bae062c7b"
}

It is recommended to store the order_id in your system, as it can be used later to reconcile and link incoming webhook events with the correct order.

Retrieve an order

GET https://www.bonzai.pro/api/v1/orders/{order_id}

Query Parameters

Name	Type	Description
order_id*	String

The API will return a JSON response:

{
    "id": 12345,
    "price_id": 5844,
    "amount_excl_vat": "20",
    "currency": "EUR",
    "mode": "one_off",
    "interval": null,
    "intent_status": "completed",
    "subscription_status": null,
    "subscription_ends_at": null,
    "has_access": true,
    "metadata":null,
    "product": {
        "id": 199,
        "name": "Super Product"
    },
    "accesses": [
        {
            "id": 90330,
            "created_at": "2025-08-26T11:37:59.000000Z",
            "updated_at": "2025-08-26T11:37:59.000000Z",
            "deleted_at": null
        }
    ]
}

About this return:

• price_id will be null if the order was created through a custom checkout flow.

• has_access indicates whether the client currently has access to the product:

  • For one-off purchases, it confirms that the payment was successful and not refunded.

  • For subscriptions, it stays true until the current billing period ends, even if the user has cancelled. Once the subscription fully expires, it becomes false.

• Accesses are separate from orders. Each time an order is paid, a new access record is created.

  • If the order is refunded or the subscription has fully ended, the access is revoked (deleted_at is set).

  • If the user later regains access, a new access object will be created.