Host to Host Integration

Integrate FlexiBill directly into your business application or website using the API. Use this approach to programmatically create bills, register subscriptions, and manage billing without going through the dashboard.

Features & Benefits

🔗 Full Programmatic Control

Create bills and subscriptions directly from your application backend — ideal for customer onboarding flows that are fully integrated into your system.

📤 Multi-Channel Delivery via API

Deliver invoices to customers via Email and/or WhatsApp in a single API call, without any additional configuration on the dashboard.

🔁 Recurring and One-Time Support

The API supports both one-time bill creation and recurring billing with flexible cycle configuration.

How It Works

Step 1	Step 2	Step 3
Register and activate FlexiBill	Integrate the API into your application backend	Call the endpoint to create a bill or subscription — FlexiBill delivers the invoice to the customer automatically

API Reference

All API requests must include valid authentication headers. See the Authentication tab below.

Authentication

All API requests require the following headers:

Header	Description
Client-Id	Your merchant Client ID from the DOKU Dashboard
Request-Id	A unique UUID per request
Request-Timestamp	UTC timestamp in ISO 8601 format
Signature	HMAC-SHA256 signature for request authentication

Example headers:

Client-Id: BRN-0228-1748939308074
Request-Id: 69e22f33-e7f3-49b9-9302-f0df1f6059b9
Request-Timestamp: 2025-06-16T03:32:26Z
Signature: HMACSHA256=WNdiEPJEZAW1vLthXygOkzMuCEadiEVK0saLjtFRqqs=

👉 Learn more about how to generate signature

Generate Bill

Create Subscription

Use Cases

ISP

Customer POV

Use Case Details

Description An internet service provider wants to integrate FlexiBill billing into their customer activation portal — when a customer activates a package, the system automatically creates a subscription and sends the first invoice. Solution Integrate the Create Subscription API into the activation portal backend. When a customer selects a package and submits, the system calls the FlexiBill API to create the subscription and deliver the first invoice programmatically. How It Works Customer selects package in portal → backend calls Create Subscription API → FlexiBill creates subscription and delivers first invoice → billing runs automatically each cycle. Features Used Create Subscription API, Generate Bill API, Webhook

SaaS

Merchant & Customer Experience

Merchant View

Merchants (developers) integrate the API into their system backend:

• Use the Sandbox endpoint for development and testing

• Switch to the Production endpoint after testing is complete

• Monitor bills and subscriptions created via API in the DOKU Dashboard just like any other billing

Customer View

The customer experience is identical to dashboard-initiated billing:

• Receives invoice via Email or WhatsApp

• Pays via the payment link

• Receives receipt after successful payment

Terms & Conditions

• Merchant must be registered with a corporate business account on DOKU Dashboard

• Business must be KYB verified before using the production API

• All requests must use HTTPS and include valid authentication headers

FAQ

What is the difference between the Sandbox and Production endpoints?

The Sandbox endpoint is used for development and testing — no real transactions are processed and no invoices are delivered to actual customers. The Production endpoint processes live transactions and delivers real invoices. Always develop and test in Sandbox first, then switch the base URL to Production when going live. Your Client-Id and Client-Secret are different between environments — use the correct credentials for each.

Do bills and subscriptions created via API appear in the DOKU Dashboard?

Yes. All bills and subscriptions created via the API are immediately visible in the DOKU Dashboard — under Subscription and Billing → Bill and Subscription and Billing → Subscription respectively — and are manageable the same way as records created through the dashboard.

How do I obtain my Client-Id and generate the Signature?

Your Client-Id is available in the DOKU Dashboard under the Integrations menu. The Signature is an HMAC-SHA256 hash generated from your Client-Secret and a canonical request string composed of the request headers and body. Full instructions for signature generation are available in the DOKU API documentation.

The collection, plan, or coupon code I am passing is returning a validation error. What should I check?

All entity codes (collection_code, plans[].code, taxes[].code, coupons[].code) must be pre-registered in the DOKU Dashboard before they can be referenced via the API. There is no API endpoint to create these entities programmatically. Check the following in order:

1. The entity exists in the dashboard under the correct menu path

2. The code string is an exact match — these values are case-sensitive

3. For plans: the plan belongs to the collection specified in collection_code

4. For coupons: the coupon is active, within its validity period, and has available stock

5. For taxes: the tax is associated with the collection specified in collection_code

How should I calculate `total_amount` before submitting the Create Subscription request?

Calculate total_amount using the following order:

Plan price(s) × qty → Coupon discount deducted → Subtotal → Tax rate applied on subtotal → total_amount

The value you send must match the server-calculated total exactly. A mismatch will return a INVALID_REQUEST error with field: total_amount. Verify the registered plan price, coupon discount value (flat or percentage), and tax rate in the dashboard before computing.

Can I pass both `subscription_code` and `auto_generate_id: true` in the same request?

Yes, but the subscription_code takes precedence. When subscription_code is present, the system uses that value and ignores auto_generate_id. Only omit subscription_code entirely when you want the system to auto-generate one. The generated code is not returned in the response body — look it up in the dashboard or via webhook if you need it.

What happens if I submit a Create Subscription request with a `start_date` in the past?

The request will return an INVALID_REQUEST error with field: plan_schedule.start_date. The start_date must be greater than or equal to the request timestamp. Past dates are not accepted. If you need the subscription to start immediately, set start_date to the current UTC time.

My Generate Bill request returned `state: INVOICE_ERROR`. What should I do?

INVOICE_ERROR means the invoice was created but delivery to the customer failed — the most common cause is insufficient deposit balance in your DOKU merchant account. Top up your deposit balance from the DOKU Dashboard. Once balance is restored, the system will automatically retry delivery. You can also monitor the current state of the invoice from the dashboard under Subscription and Billing → Bill.

How do I handle duplicate requests safely for Generate Bill?

The bill_identifier field acts as an idempotency key — the same identifier cannot be used twice within a merchant account. If your request times out or you are unsure whether it was processed, do not immediately retry with the same bill_identifier. First query the bill's status via the dashboard or inquiry endpoint to confirm whether the original request succeeded. Only generate a new bill (with a new identifier) if you have confirmed the original was not processed.

What is the difference between Generate Bill and Create Subscription for recurring billing?

Both support recurring billing, but they serve different purposes:

Generate Bill (RECURRING) — You define the schedule and the system handles recurring invoice issuance. The billing configuration (amount, cycle, customer) is passed directly in the API call with no dependency on dashboard-configured entities. Use this for custom, ad-hoc, or dynamically-calculated billing where amounts may vary per cycle.

Create Subscription — The subscription is bound to a pre-registered Collection and Plan. Pricing, billing cycle, tax, and coupon are all defined in the dashboard. Use this for structured product/service offerings where the plan configuration is reusable and managed centrally.

How do I know when a customer has paid their invoice?

Set up a Webhook to receive real-time payment notifications. When a customer completes payment, FlexiBill sends a PAID event to your configured webhook endpoint with the invoice number and payment details. You can also poll the bill status from the dashboard. → Webhook

Can I cancel or modify a subscription created via the API?

Subscriptions created via the API can be viewed and managed from the DOKU Dashboard. Cancellation is performed from the dashboard — there is no dedicated cancel subscription API endpoint. Plan, collection, and schedule fields cannot be changed after a subscription is created. To change the plan for a customer, cancel the existing subscription from the dashboard and create a new one via the API with the updated configuration.