Give promotional credit

curl --request POST \
  --url https://bouclay.com/api/v1/credit-grants \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "customerId": "ctm_123",
  "amount": 2000,
  "reason": "Launch promotion",
  "currency": "NGN",
  "expiresAt": "2023-11-07T05:31:56Z",
  "customData": {}
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customerId: 'ctm_123',
    amount: 2000,
    reason: 'Launch promotion',
    currency: 'NGN',
    expiresAt: '2023-11-07T05:31:56Z',
    customData: {}
  })
};

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

import requests

url = "https://bouclay.com/api/v1/credit-grants"

payload = {
    "customerId": "ctm_123",
    "amount": 2000,
    "reason": "Launch promotion",
    "currency": "NGN",
    "expiresAt": "2023-11-07T05:31:56Z",
    "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/credit-grants",
  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([
    'customerId' => 'ctm_123',
    'amount' => 2000,
    'reason' => 'Launch promotion',
    'currency' => 'NGN',
    'expiresAt' => '2023-11-07T05:31:56Z',
    '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": "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"
  }
}

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

Give promotional credit

Gives a customer promotional credit, paid for from your own margin. It is active at once and the customer’s next invoices in its currency spend it before tax, so it lowers the VAT like a discount: ₦12,000 of usage with ₦2,000 of credit is ₦10,000 + ₦750 VAT. currency defaults to the customer’s. Credit someone paid for is prepaid credit, not this. Card verification charges and payment-link checkouts never spend it. Voiding an invoice gives back what it spent. A credit note can’t give it back, since credit notes are capped at what the line charged. Needs credits:write on a restricted key. Emits credit_grant.created.

POST

credit-grants

curl --request POST \
  --url https://bouclay.com/api/v1/credit-grants \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "customerId": "ctm_123",
  "amount": 2000,
  "reason": "Launch promotion",
  "currency": "NGN",
  "expiresAt": "2023-11-07T05:31:56Z",
  "customData": {}
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customerId: 'ctm_123',
    amount: 2000,
    reason: 'Launch promotion',
    currency: 'NGN',
    expiresAt: '2023-11-07T05:31:56Z',
    customData: {}
  })
};

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

import requests

url = "https://bouclay.com/api/v1/credit-grants"

payload = {
    "customerId": "ctm_123",
    "amount": 2000,
    "reason": "Launch promotion",
    "currency": "NGN",
    "expiresAt": "2023-11-07T05:31:56Z",
    "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/credit-grants",
  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([
    'customerId' => 'ctm_123',
    'amount' => 2000,
    'reason' => 'Launch promotion',
    'currency' => 'NGN',
    'expiresAt' => '2023-11-07T05:31:56Z',
    '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": "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"
  }
}

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

Body

application/json

customerId

string

required

Example:

"ctm_123"

amount

number

required

Major units of currency.

Example:

2000

reason

string

required

Maximum string length: 255

Example:

"Launch promotion"

currency

string

Example:

"NGN"

expiresAt

string<date-time> | null

In the future. Leave out for credit that never expires.

customData

object | null

Response

Credit grant response.

data

object

required

A lot of granted credit. What is left on it is the sum of its movements, so remaining is what the next invoice can spend.

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

Give promotional credit

Authorizations

Headers

Body

Response