Fetch customer credit balance summary by external customer id

curl --request GET \
  --url https://api.withorb.com/v1/customers/external_customer_id/{external_customer_id}/credits/balance \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.withorb.com/v1/customers/external_customer_id/{external_customer_id}/credits/balance"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.withorb.com/v1/customers/external_customer_id/{external_customer_id}/credits/balance', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.withorb.com/v1/customers/external_customer_id/{external_customer_id}/credits/balance",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.withorb.com/v1/customers/external_customer_id/{external_customer_id}/credits/balance"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.withorb.com/v1/customers/external_customer_id/{external_customer_id}/credits/balance")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.withorb.com/v1/customers/external_customer_id/{external_customer_id}/credits/balance")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "currency": "<string>",
  "balance": 123,
  "pending_payment_balance": 123,
  "next_expiry_date": "2023-11-07T05:31:56Z",
  "next_expiry_balance": 123
}

{
  "type": "https://docs.withorb.com/reference/error-responses#400-constraint-violation",
  "status": 400,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#401-authentication-error",
  "status": 401,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#404-feature-not-available",
  "status": 400,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#409-resource-conflict",
  "status": 409,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#413-request-too-large",
  "status": 413,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#429-too-many-requests",
  "status": 429,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#500-internal-server-error",
  "status": 123,
  "detail": "<string>",
  "title": "<string>"
}

Credit

Fetch customer credit balance summary by external customer id

This endpoint returns a customer’s credit balance in a single currency or custom pricing unit: the total available balance, the balance waiting on payment, and the next upcoming expiration.

balance is the sum of balance across the customer’s active credit blocks, as listed by Fetch customer credit balance. Expired, depleted, and voided blocks are not included. Blocks in pending_payment status are totaled in pending_payment_balance instead, and become available once their invoice is paid.

Note that currency defaults to credits if not specified. To use a real world currency, set currency to an ISO 4217 string. A customer with no credits in that currency returns a balance of 0.

GET

customers

external_customer_id

{external_customer_id}

credits

balance

Fetch customer credit balance summary by external customer id

curl --request GET \
  --url https://api.withorb.com/v1/customers/external_customer_id/{external_customer_id}/credits/balance \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.withorb.com/v1/customers/external_customer_id/{external_customer_id}/credits/balance"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.withorb.com/v1/customers/external_customer_id/{external_customer_id}/credits/balance', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.withorb.com/v1/customers/external_customer_id/{external_customer_id}/credits/balance",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.withorb.com/v1/customers/external_customer_id/{external_customer_id}/credits/balance"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.withorb.com/v1/customers/external_customer_id/{external_customer_id}/credits/balance")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.withorb.com/v1/customers/external_customer_id/{external_customer_id}/credits/balance")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "currency": "<string>",
  "balance": 123,
  "pending_payment_balance": 123,
  "next_expiry_date": "2023-11-07T05:31:56Z",
  "next_expiry_balance": 123
}

{
  "type": "https://docs.withorb.com/reference/error-responses#400-constraint-violation",
  "status": 400,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#401-authentication-error",
  "status": 401,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#404-feature-not-available",
  "status": 400,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#409-resource-conflict",
  "status": 409,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#413-request-too-large",
  "status": 413,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#429-too-many-requests",
  "status": 429,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#500-internal-server-error",
  "status": 123,
  "detail": "<string>",
  "title": "<string>"
}

Authorizations

Authorization

string

header

required

API Keys can be issued in the Orb's web application.

Path Parameters

external_customer_id

string | null

required

Query Parameters

currency

string | null

The ledger currency or custom pricing unit to use.

Response

currency

string | null

required

The currency or custom pricing unit the balances are denominated in. Null when no currency is passed and the customer has no credit ledger, in which case every balance is 0.

balance

number

required

The customer's available credit balance: the sum of balance across their active credit blocks.

pending_payment_balance

number

required

The total balance of credit blocks in pending_payment status. Not included in balance until the invoice that funds them is paid.

next_expiry_date

string<date-time> | null

required

The earliest expiry_date among active credit blocks. Null if none of them expire.

next_expiry_balance

number | null

required

The balance that expires on next_expiry_date. Null if next_expiry_date is null.

API documentation

Webhooks

Alert

Coupon

Credit

Credit note

Customer

Dimensional Price Group

Event

Invoice

Item

LicenseType

License

Metric

Availability

Plan

Price

Subscription Change

Subscription

Price interval

Webhook endpoint

Fetch customer credit balance summary by external customer id

Authorizations

Path Parameters

Query Parameters

Response