Add Custom Billable Products
Admins can manually add products to any billing account to charge for any extra services. Products must be attached to exactly one billing account, there are no general custom products.
Remember, all times are in UTC!
Recurring and One Time
Products can be like subscriptions that have a start and end date, or like one time purchases. The qty_unit
parameter controls how the billing behaves.
qty_unit | Description | start_date parameter | end_date parameter |
---|---|---|---|
pc | One of something, its price is charged once. It will be shown as 1 pc on invoice. | The date when the user receives this product. Cannot be in the previous month. If it's a future date then the product will appear in Current Usage view only after the date has passed. | Value in request can be left empty, it will be ignored and set to the value of start_date . |
h | Hourly charged service. Charge amount will be hours * price . | The date when the product or service started or will start. Hours will be counted from that moment, rounded down to the nearest full hour. Cannot be in the previous month. If it's a future date then the product will appear in Current Usage view only after the date has passed. | Can be left empty if end is not decided yet. This can be set later to stop counting hours, however it cannot be set to past then since past invoices, even the running month hour counting cannot be changed. It can be set to past when creating the product, but it still has to be in the running month, then. Will be effectively rounded up to the nearest full hour, for hour counting purposes. |
API calls
Create Custom Product (admin)
Create a product for a specific billing account.
curl https://<api-hostname>/v1/charging/admin/products \ -H 'apikey: [apikey]' \ -X POST \ -d "description=[descriptive text for the product]" \ -d "billing_account_id=[target billing account]" \ -d "price_per_unit=[fixed point number, price for one unit]" \ -d "qty_unit=[in what units is the product measured]" \ -d "start_date=[starting point for charging, format is YYYY-MM-DDThh:mm:ssZ]" \ -d "end_date=[end point for charging, can be left empty, format is YYYY-MM-DDThh:mm:ssZ]"
Returns product data, most importantly its UUID.
{ "uuid": "ddd8c717-b177-494b-95dd-2a48deff960e", "description": "WordPress maintenance", "start_date": "2020-08-12T14:07:00.000+0000", "end_date": "2020-08-12T14:07:00.000+0000", "billing_account_id": 129639, "user_id": 8, "price_per_unit": 15.00000000, "qty_unit": "pc", "creator_user_id": 28, "created_at": "2020-08-12T14:22:02.409+0000", "updated_at": "2020-08-12T14:22:02.409+0000" }
List Products (admin)
Get a list of all products, optionally filtered by billing account.
curl https://<api-hostname>/v1/charging/admin/products?billing_account_id=[billing_account_id] \ -H 'apikey: [apikey]' \ -X GET
Returns a list of products.
Get Product (admin)
Specify product UUID on path to retrieve a specific product.
curl https://<api-hostname>/v1/charging/admin/products/[uuid] \ -H 'apikey: [apikey]' \ -X GET
Returns a specific product.
Modify Product (admin)
Set product end date to end a subscription type product. End date can also be modified. Do note that setting it to the past has the same effect as setting it to the present moment.
curl https://<api-hostname>/v1/charging/admin/products/[uuid] \ -H 'apikey: [apikey]' \ -X PATCH \ -d "end_date=[end point for charging, format is YYYY-MM-DDThh:mm:ssZ]"
Returns product data.