Set an auto-reload

curl --request POST \
  --url https://bouclay.com/api/v1/customers/{customer}/credit-auto-reloads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "threshold": 5000,
  "amount": 20000,
  "currency": "NGN",
  "paymentMethod": "<string>",
  "expiresAfterMonths": 60,
  "enabled": true
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    threshold: 5000,
    amount: 20000,
    currency: 'NGN',
    paymentMethod: '<string>',
    expiresAfterMonths: 60,
    enabled: true
  })
};

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

payload = {
    "threshold": 5000,
    "amount": 20000,
    "currency": "NGN",
    "paymentMethod": "<string>",
    "expiresAfterMonths": 60,
    "enabled": True
}
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-auto-reloads",
  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([
    'threshold' => 5000,
    'amount' => 20000,
    'currency' => 'NGN',
    'paymentMethod' => '<string>',
    'expiresAfterMonths' => 60,
    'enabled' => true
  ]),
  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": "car_123",
    "object": "credit_auto_reload",
    "customer": {
      "id": "<string>"
    },
    "currency": "NGN",
    "enabled": true,
    "threshold": 5000,
    "amount": 20000,
    "paymentMethod": {
      "id": "<string>"
    },
    "expiresAfterMonths": 123,
    "lastInvoice": {
      "id": "<string>",
      "number": "<string>",
      "status": "open"
    },
    "lastReloadedAt": "2023-11-07T05:31:56Z",
    "disabledReason": "payment_failed",
    "disabledMessage": "<string>",
    "disabledAt": "2023-11-07T05:31:56Z",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  },
  "meta": {
    "requestId": "req_550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "data": {
    "id": "car_123",
    "object": "credit_auto_reload",
    "customer": {
      "id": "<string>"
    },
    "currency": "NGN",
    "enabled": true,
    "threshold": 5000,
    "amount": 20000,
    "paymentMethod": {
      "id": "<string>"
    },
    "expiresAfterMonths": 123,
    "lastInvoice": {
      "id": "<string>",
      "number": "<string>",
      "status": "open"
    },
    "lastReloadedAt": "2023-11-07T05:31:56Z",
    "disabledReason": "payment_failed",
    "disabledMessage": "<string>",
    "disabledAt": "2023-11-07T05:31:56Z",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  },
  "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

Set an auto-reload

“When my credit falls to ₦5,000, buy ₦20,000 with my card.” Sets the customer’s rule in currency, replacing one that is there (200), or creating it (201).

The rule compares projectedAvailable (see the credit balance) with threshold after every movement on the customer’s credit and every usage event. At or below it, it buys amount of prepaid credit the way POST /customers/{id}/credit-purchases does with automatic collection, charged to paymentMethod, or the customer’s default card. One fall buys once: it buys again only after the credit has been back above the threshold, and never while the last top-up’s charge is still unknown. A rule set on while the credit is already at or below the threshold buys at once.

A failed charge voids that top-up, turns the rule off (disabledReason: payment_failed) and emails the customer that automatic top-ups are off, with the credit they have left. Nothing is retried. The rule also turns itself off with no email when there is no card left to charge (no_payment_method) or the purchase is refused before any charge (purchase_refused).

Refused up front when the customer has no saved card, the card is not theirs or is from the other mode, or the amount can’t be sold (below the minimum, or no VAT timing chosen for prepaid credit). Needs credits:write on a restricted key. Emits credit_auto_reload.created or credit_auto_reload.updated.

POST

customers

{customer}

credit-auto-reloads

Set an auto-reload

curl --request POST \
  --url https://bouclay.com/api/v1/customers/{customer}/credit-auto-reloads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "threshold": 5000,
  "amount": 20000,
  "currency": "NGN",
  "paymentMethod": "<string>",
  "expiresAfterMonths": 60,
  "enabled": true
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    threshold: 5000,
    amount: 20000,
    currency: 'NGN',
    paymentMethod: '<string>',
    expiresAfterMonths: 60,
    enabled: true
  })
};

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

payload = {
    "threshold": 5000,
    "amount": 20000,
    "currency": "NGN",
    "paymentMethod": "<string>",
    "expiresAfterMonths": 60,
    "enabled": True
}
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-auto-reloads",
  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([
    'threshold' => 5000,
    'amount' => 20000,
    'currency' => 'NGN',
    'paymentMethod' => '<string>',
    'expiresAfterMonths' => 60,
    'enabled' => true
  ]),
  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": "car_123",
    "object": "credit_auto_reload",
    "customer": {
      "id": "<string>"
    },
    "currency": "NGN",
    "enabled": true,
    "threshold": 5000,
    "amount": 20000,
    "paymentMethod": {
      "id": "<string>"
    },
    "expiresAfterMonths": 123,
    "lastInvoice": {
      "id": "<string>",
      "number": "<string>",
      "status": "open"
    },
    "lastReloadedAt": "2023-11-07T05:31:56Z",
    "disabledReason": "payment_failed",
    "disabledMessage": "<string>",
    "disabledAt": "2023-11-07T05:31:56Z",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  },
  "meta": {
    "requestId": "req_550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "data": {
    "id": "car_123",
    "object": "credit_auto_reload",
    "customer": {
      "id": "<string>"
    },
    "currency": "NGN",
    "enabled": true,
    "threshold": 5000,
    "amount": 20000,
    "paymentMethod": {
      "id": "<string>"
    },
    "expiresAfterMonths": 123,
    "lastInvoice": {
      "id": "<string>",
      "number": "<string>",
      "status": "open"
    },
    "lastReloadedAt": "2023-11-07T05:31:56Z",
    "disabledReason": "payment_failed",
    "disabledMessage": "<string>",
    "disabledAt": "2023-11-07T05:31:56Z",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  },
  "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

threshold

number

required

Buys when the projected credit is at or below this, in major units.

Required range: x >= 0

Example:

5000

amount

number

required

What each top-up costs and the credit it gives, in major units. At least the minimum charge.

Example:

20000

currency

string

Defaults to the customer's.

Example:

"NGN"

paymentMethod

string | null

A saved card of this customer's. Left out or null, their default card when it buys.

expiresAfterMonths

integer | null

How long the credit it buys lasts, from payment. Null never expires.

Required range: 1 <= x <= 120

enabled

boolean

default:true

Response

Auto-reload response.

data

object

required

A customer's auto-reload in one currency: when their projected credit is at or below threshold, it buys amount of prepaid credit on a saved card, once per fall.

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

Set an auto-reload

Authorizations

Headers

Path Parameters

Body

Response