Reconcile charges - Chenvoya API documentation

Use task billing to check the reservation, debits, refunds and amount due of every task.

Each task has a bill: a summary and a series of permanent billing events. The summary answers how much the task charged in total; the events show how the money moved.

Read the bill

curl --request GET "${CHENVOYA_BASE_URL}/v1/video/tasks/${TASK_ID}/billing" \
  --header "Authorization: Bearer ${CHENVOYA_API_KEY}"

import urllib.request
import urllib.parse
import json
import os
import sys
import re
import uuid

key = os.environ["CHENVOYA_API_KEY"].strip()
if not key or re.search(r"[\x00-\x1f\x7f-\x9f]", key):
    sys.exit("Set CHENVOYA_API_KEY to a non-empty value without control characters")
base = os.environ["CHENVOYA_BASE_URL"].rstrip("/")
headers = {"Authorization": "Bearer " + key}
TASK_ID = os.environ["TASK_ID"]
path = "/v1/video/tasks/{task_id}/billing".replace("{task_id}", urllib.parse.quote(TASK_ID, safe=""))
request = urllib.request.Request(base + path, data=None, headers=headers, method="GET")
try:
    with urllib.request.urlopen(request) as response:
        print(response.read().decode("utf-8"))
except urllib.request.HTTPError as error:
    print(error.read().decode("utf-8"))
    sys.exit(1)

// Needs Node.js 20 or later; save it as a .mjs file and run it.
const key = process.env.CHENVOYA_API_KEY?.trim();
if (!key || /[\x00-\x1f\x7f-\x9f]/.test(key)) {
  console.error("Set CHENVOYA_API_KEY to a non-empty value without control characters");
  process.exit(1);
}
const base = process.env.CHENVOYA_BASE_URL;
if (!base) throw new Error("Set CHENVOYA_BASE_URL");
const headers = {Authorization: `Bearer ${key}`};
const TASK_ID = process.env.TASK_ID;
if (!TASK_ID) throw new Error("Set TASK_ID");
const path = "/v1/video/tasks/{task_id}/billing".replace("{task_id}", encodeURIComponent(TASK_ID));
const response = await fetch(base.replace(/\/$/, "") + path, {method: "GET", headers, body: undefined});
console.log(await response.text());
if (!response.ok) process.exitCode = 1;

package main

import (
	"fmt"
	"io"
	"net/http"
	"net/url"
	"os"
	"regexp"
	"strings"
)

func main() {
	key := strings.TrimSpace(os.Getenv("CHENVOYA_API_KEY"))
	if key == "" || regexp.MustCompile(`[\x00-\x1f\x7f-\x9f]`).MatchString(key) {
		fail("Set CHENVOYA_API_KEY to a non-empty value without control characters")
	}
	base := strings.TrimRight(os.Getenv("CHENVOYA_BASE_URL"), "/")
	if base == "" {
		fail("Set CHENVOYA_BASE_URL")
	}
	taskID := os.Getenv("TASK_ID")
	if taskID == "" {
		fail("Set TASK_ID")
	}
	path := strings.Replace("/v1/video/tasks/{task_id}/billing", "{task_id}", url.PathEscape(taskID), 1)
	request, err := http.NewRequest("GET", base+path, nil)
	if err != nil {
		fail(err.Error())
	}
	request.Header.Set("Authorization", "Bearer "+key)
	response, err := http.DefaultClient.Do(request)
	if err != nil {
		fail(err.Error())
	}
	text, err := io.ReadAll(response.Body)
	response.Body.Close()
	if err != nil {
		fail(err.Error())
	}
	fmt.Println(string(text))
	if response.StatusCode < 200 || response.StatusCode > 299 {
		os.Exit(1)
	}
}

func fail(message string) {
	fmt.Fprintln(os.Stderr, message)
	os.Exit(1)
}

The summary covers the whole task and never turns into a subtotal of the event page. Page through events with cursor and page_size; the last page has a null next_cursor.

Summary fields

Field	Meaning
`reserved_amount`	Amount reserved for the task.
`charged_amount`	Charge recorded for the task.
`funding_debit_amount`	Amount actually debited from your balance.
`funding_refund_amount`	Amount actually returned to your balance.
`outstanding_receivable`	Amount due that has not been collected.
`final_actual_cost`	Final charge; `null` until settlement is final.

Billing events

Every movement of money is an event, such as hold_created for a new reservation, charge_captured for a charge and hold_released for a released reservation. Creating, increasing, reducing or releasing a reservation by itself is not a debit, refund or change in the amount due; read the amount fields. Every event type is on Statuses and reasons.

When billing needs review

The usage of a few tasks needs review. Their settlement_status is reconciliation_required, final_actual_cost is null, and reconciliation gives the reason reason_code, the missing meters missing_meters and whether you need to act in customer_action_required. After the review the settlement becomes settled or settled_with_receivable.

Correlation IDs

request_id and billing_correlation_id stay the same across the task, its bill and its events, so you can match your orders with our bills.

Next steps

How billing worksFunds for the upper bound are reserved at creation and settled on actual usage; failed and cancelled tasks are free.Read task billingRetrieve the whole-task billing summary and one ordered page of permanent billing events.Statuses and reasonsEvery value of the task, delivery, settlement, asset and billing fields.