Hold credit for a request

curl --request POST \
  --url https://bouclay.com/api/v1/customers/{customer}/credit-holds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "usage": [
    {
      "eventName": "tokens",
      "value": 4000
    }
  ],
  "currency": "NGN",
  "expiresIn": 3600,
  "reference": "req_8f2a",
  "customData": {}
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    usage: [{eventName: 'tokens', value: 4000}],
    currency: 'NGN',
    expiresIn: 3600,
    reference: 'req_8f2a',
    customData: {}
  })
};

fetch('https://bouclay.com/api/v1/customers/{customer}/credit-holds', 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-holds"

payload = {
    "usage": [
        {
            "eventName": "tokens",
            "value": 4000
        }
    ],
    "currency": "NGN",
    "expiresIn": 3600,
    "reference": "req_8f2a",
    "customData": {}
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://bouclay.com/api/v1/customers/{customer}/credit-holds",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'usage' => [
        [
                'eventName' => 'tokens',
                'value' => 4000
        ]
    ],
    'currency' => 'NGN',
    'expiresIn' => 3600,
    'reference' => 'req_8f2a',
    'customData' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

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

curl_close($curl);

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

{
  "data": {
    "id": "hold_123",
    "object": "credit_hold",
    "customer": {
      "id": "<string>"
    },
    "status": "held",
    "currency": "NGN",
    "amount": 123,
    "usage": [
      {
        "eventName": "<string>",
        "value": 123,
        "committed": 123
      }
    ],
    "reference": "<string>",
    "customData": {},
    "expiresAt": "2023-11-07T05:31:56Z",
    "settledAt": "2023-11-07T05:31:56Z",
    "createdAt": "2023-11-07T05:31:56Z"
  },
  "meta": {
    "requestId": "req_550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "insufficient_credit",
    "detail": "The customer has NGN 700.00 of credit available, and this usage needs NGN 800.00.",
    "currency": "NGN",
    "available": 700,
    "needed": 800
  },
  "meta": {}
}

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

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

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

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

Credits

Hold credit for a request

Early access. Not yet turned on for every account: until it is, this answers 404 not_found. Build against it now and ask us to turn it on.

Reserves the usage a request is expected to use against the customer’s prepaid credit, before you do the work. Use it to stop a customer exactly when their credit runs out: if the credit can’t cover the hold, it is refused with 402 insufficient_credit, saying what is available and what the hold needed, and nothing is reserved. A hold that would go past a spending cap that stops billing (behavior: cap) is refused with 409 spending_cap_reached: that usage would never be billed.

The hold is priced as usage, on top of the usage you have already sent this period and every other open hold, the way the period’s invoice will price it: tiers, the subscription’s discount, VAT, and which credit pays first. amount is what it takes from the credit. Two holds placed at the same moment never share the same credit.

Holds work on meters that sum their values (meter_not_summed otherwise), billed by one of the customer’s active subscriptions (meter_not_billed). When the meters are billed in two currencies, pass currency. When the work ends, commit what it used or release the hold. A hold that is neither expires after expiresIn seconds and its credit is free again. Needs credits:write on a restricted key.

POST

customers

{customer}

credit-holds

Hold credit for a request

curl --request POST \
  --url https://bouclay.com/api/v1/customers/{customer}/credit-holds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "usage": [
    {
      "eventName": "tokens",
      "value": 4000
    }
  ],
  "currency": "NGN",
  "expiresIn": 3600,
  "reference": "req_8f2a",
  "customData": {}
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    usage: [{eventName: 'tokens', value: 4000}],
    currency: 'NGN',
    expiresIn: 3600,
    reference: 'req_8f2a',
    customData: {}
  })
};

fetch('https://bouclay.com/api/v1/customers/{customer}/credit-holds', 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-holds"

payload = {
    "usage": [
        {
            "eventName": "tokens",
            "value": 4000
        }
    ],
    "currency": "NGN",
    "expiresIn": 3600,
    "reference": "req_8f2a",
    "customData": {}
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://bouclay.com/api/v1/customers/{customer}/credit-holds",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'usage' => [
        [
                'eventName' => 'tokens',
                'value' => 4000
        ]
    ],
    'currency' => 'NGN',
    'expiresIn' => 3600,
    'reference' => 'req_8f2a',
    'customData' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

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

curl_close($curl);

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

{
  "data": {
    "id": "hold_123",
    "object": "credit_hold",
    "customer": {
      "id": "<string>"
    },
    "status": "held",
    "currency": "NGN",
    "amount": 123,
    "usage": [
      {
        "eventName": "<string>",
        "value": 123,
        "committed": 123
      }
    ],
    "reference": "<string>",
    "customData": {},
    "expiresAt": "2023-11-07T05:31:56Z",
    "settledAt": "2023-11-07T05:31:56Z",
    "createdAt": "2023-11-07T05:31:56Z"
  },
  "meta": {
    "requestId": "req_550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "insufficient_credit",
    "detail": "The customer has NGN 700.00 of credit available, and this usage needs NGN 800.00.",
    "currency": "NGN",
    "available": 700,
    "needed": 800
  },
  "meta": {}
}

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

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

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

{
  "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.

Headers

Idempotency-Key

string

required

Required for POST and PATCH requests. Replays identical method + path + body requests and rejects mismatched re-use.

Required string length: 1 - 255

Path Parameters

customer

string

required

Body

application/json

usage

object[]

required

Required array length: 1 - 20 elements

Show child attributes

currency

string

Example:

"NGN"

expiresIn

integer

default:3600

Seconds until the hold expires if not committed or released.

Required range: 60 <= x <= 604800

reference

string | null

Your own id for the request, for your records.

Maximum string length: 255

Example:

"req_8f2a"

customData

object | null

Response

Credit hold response.

data

object

required

Usage reserved against a customer's prepaid credit before a request, then committed or released.

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

Hold credit for a request

Authorizations

Headers

Path Parameters

Body

Response