Get a customer's credit balance

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

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

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

import requests

url = "https://bouclay.com/api/v1/customers/{customer}/credit-balance"

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

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

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://bouclay.com/api/v1/customers/{customer}/credit-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;
}

{
  "data": [
    {
      "object": "credit_balance",
      "currency": "NGN",
      "available": 1,
      "balance": 123,
      "pending": 1,
      "unbilled": 1,
      "held": 1,
      "projectedAvailable": 1,
      "projectedShortfall": 1,
      "grants": [
        {
          "id": "cg_123",
          "object": "credit_grant",
          "customer": {
            "id": "<string>"
          },
          "kind": "promotional",
          "status": "pending_payment",
          "vatTiming": "at_purchase",
          "tax": {
            "category": "standard",
            "rate": 7.5,
            "inclusive": true
          },
          "denomination": {
            "kind": "money",
            "code": "NGN"
          },
          "currency": "NGN",
          "amount": 2000,
          "remaining": 1500,
          "expiresAt": "2023-11-07T05:31:56Z",
          "expired": true,
          "reason": "<string>",
          "invoice": {
            "id": "<string>",
            "number": "<string>"
          },
          "customData": {},
          "activatedAt": "2023-11-07T05:31:56Z",
          "createdAt": "2023-11-07T05:31:56Z",
          "transactions": [
            {
              "type": "grant",
              "amount": 123,
              "invoice": {
                "id": "<string>",
                "number": "<string>"
              },
              "invoiceLineId": 123,
              "creditNote": {
                "id": "<string>",
                "number": "<string>"
              },
              "reason": "<string>",
              "createdAt": "2023-11-07T05:31:56Z"
            }
          ]
        }
      ]
    }
  ],
  "meta": {
    "requestId": "req_550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "hasMore": true,
      "previous": "<string>",
      "next": "<string>"
    }
  }
}

{
  "error": {
    "type": "request_error",
    "code": "authentication_failed",
    "detail": "<string>",
    "errors": [
      {
        "field": "<string>",
        "message": "<string>"
      }
    ]
  },
  "meta": {
    "requestId": "req_550e8400-e29b-41d4-a716-446655440000"
  }
}

Credits

Get a customer's credit balance

What this customer has left to spend, one entry per currency they have ever held a balance in. Derived from the same ledger an invoice spends, so available is what the next invoice in that currency will take before charging the rest.

A new invoice spends the balance after tax and records it as balanceApplied. Card verification charges and payment-link checkouts never spend it. Voiding an invoice gives back what it spent.

An automatic charge below the minimum (the card gateway’s own floor, or the merchant’s higher minimum) is never sent. The invoice is marked paid and its amount becomes debt on the balance: balance goes negative and available stays at 0. The next invoice in that currency collects it, with a negative balanceApplied that adds to its amountDue.

Promotional credit lots that are active, unexpired and not yet spent are listed in grants and counted in available. The next invoice spends them before tax (soonest expiry first, then promotional before prepaid, then oldest), so they lower its VAT like a discount and show as grantApplied. A lot only pays invoices in its own currency.

Prepaid credit taxed when bought (vatTiming: at_purchase) is spent before tax in the same order, but only on lines taxed the way its top-up was (the same tax category and rate, in the lot’s tax): an exempt, zero-rated or export line, or one after a rate change, is billed normally. A lot bought at a price with VAT included is shown in that price’s terms in amount, remaining and available, so 10,000 bought with VAT inside reads 10,000 and covers 10,000 of usage priced the same way.

Prepaid credit taxed when used (vatTiming: at_redemption) is spent after tax, like cash, in balanceApplied: lots expiring soonest first, then those that never expire, then the money balance last. A top-up awaiting payment shows in pending, never in available.

unbilled counts usage so far in the customer’s open periods against the credit: what the invoices at their period ends would draw if the usage stopped now, priced the way those invoices will be. projectedAvailable is what would be left, the number to compare with zero before serving a request, and projectedShortfall what those invoices would still collect. Usage is only as fresh as what you have sent, and stopping at zero is your call.

held is what open holds would take, priced on top of that usage (POST /customers/{id}/credit-holds), and comes off projectedAvailable too. To stop a customer exactly when their credit runs out, reserve before each request instead of reading this: a hold is refused when the credit can’t cover it.

Needs the credits:read scope on a restricted key.

GET

customers

{customer}

credit-balance

Get a customer's credit balance

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

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

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

import requests

url = "https://bouclay.com/api/v1/customers/{customer}/credit-balance"

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

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

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://bouclay.com/api/v1/customers/{customer}/credit-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;
}

{
  "data": [
    {
      "object": "credit_balance",
      "currency": "NGN",
      "available": 1,
      "balance": 123,
      "pending": 1,
      "unbilled": 1,
      "held": 1,
      "projectedAvailable": 1,
      "projectedShortfall": 1,
      "grants": [
        {
          "id": "cg_123",
          "object": "credit_grant",
          "customer": {
            "id": "<string>"
          },
          "kind": "promotional",
          "status": "pending_payment",
          "vatTiming": "at_purchase",
          "tax": {
            "category": "standard",
            "rate": 7.5,
            "inclusive": true
          },
          "denomination": {
            "kind": "money",
            "code": "NGN"
          },
          "currency": "NGN",
          "amount": 2000,
          "remaining": 1500,
          "expiresAt": "2023-11-07T05:31:56Z",
          "expired": true,
          "reason": "<string>",
          "invoice": {
            "id": "<string>",
            "number": "<string>"
          },
          "customData": {},
          "activatedAt": "2023-11-07T05:31:56Z",
          "createdAt": "2023-11-07T05:31:56Z",
          "transactions": [
            {
              "type": "grant",
              "amount": 123,
              "invoice": {
                "id": "<string>",
                "number": "<string>"
              },
              "invoiceLineId": 123,
              "creditNote": {
                "id": "<string>",
                "number": "<string>"
              },
              "reason": "<string>",
              "createdAt": "2023-11-07T05:31:56Z"
            }
          ]
        }
      ]
    }
  ],
  "meta": {
    "requestId": "req_550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "hasMore": true,
      "previous": "<string>",
      "next": "<string>"
    }
  }
}

{
  "error": {
    "type": "request_error",
    "code": "authentication_failed",
    "detail": "<string>",
    "errors": [
      {
        "field": "<string>",
        "message": "<string>"
      }
    ]
  },
  "meta": {
    "requestId": "req_550e8400-e29b-41d4-a716-446655440000"
  }
}

Authorizations

Authorization

string

header

required

Use a Bouclay secret key (sk_test_..., sk_live_...) or restricted key (rk_test_..., rk_live_...).

A secret key can call every endpoint. A restricted key can only call the endpoints its scopes cover. A scope is {resource}:{access}, for example customers:read or refunds:write, and write includes read. GET requests need read access and everything else needs write, except POST /subscriptions/{id}/items/{item}/preview, which only needs subscriptions:read. A request outside the key's scopes gets 403 permission_denied naming the missing scope, and its Idempotency-Key is not used up.

Resource	Endpoints	Access
`customers`	customers, their addresses and payment methods	read, write
`entitlements`	`/customers/{id}/entitlements`	read
`credits`	`/customers/{id}/credit-balance`, credit purchases, credit grants, auto-reloads, credit holds (committing one records its usage)	read, write
`catalog`	products, plans, prices	read, write
`meters`	meters	read, write
`usage`	meter events, `/customers/{id}/usage`	read, write
`discounts`	discounts	read
`subscriptions`	subscriptions	read, write
`invoices`	invoices	read, write
`credit_notes`	credit notes, `POST /invoices/{id}/credit-notes` (a refund to the card also needs `refunds:write`)	read, write
`payments`	payments	read
`refunds`	refunds, `POST /payments/{id}/refunds`, chargebacks and their outcome	read, write
`checkout_sessions`	checkout sessions	read, write
`portal_sessions`	portal sessions	write
`events`	events	read
`webhook_endpoints`	webhook endpoints	read, write
`metrics`	metrics	read

Publishable keys (pk_...) are rejected by server-side API endpoints. A key's mode scopes what it can see and charge: a test key can never reach a live card.

Path Parameters

customer

string

required

Response

Credit balance list response.

data

object[]

required

Show child attributes

Overview

Customers

Customer addresses

Entitlements

Credits

Usage

Payment methods

Catalog

Meters

Discounts

Subscriptions

Metrics

Invoices

Credit notes

Payments

Refunds

Chargebacks

Events

Checkout sessions

Portal sessions

Payment links

Webhook endpoints

Get a customer's credit balance

Authorizations

Path Parameters

Response