Issue a credit note

curl --request POST \
  --url https://bouclay.com/api/v1/invoices/{invoice}/credit-notes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "reason": "Billed 10 seats instead of 8",
  "amount": 1,
  "lines": [
    {
      "invoiceLineId": 123,
      "amount": 1
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    reason: 'Billed 10 seats instead of 8',
    amount: 1,
    lines: [{invoiceLineId: 123, amount: 1}]
  })
};

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

import requests

url = "https://bouclay.com/api/v1/invoices/{invoice}/credit-notes"

payload = {
    "reason": "Billed 10 seats instead of 8",
    "amount": 1,
    "lines": [
        {
            "invoiceLineId": 123,
            "amount": 1
        }
    ]
}
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/invoices/{invoice}/credit-notes",
  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([
    'reason' => 'Billed 10 seats instead of 8',
    'amount' => 1,
    'lines' => [
        [
                'invoiceLineId' => 123,
                'amount' => 1
        ]
    ]
  ]),
  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": "cn_123",
    "number": "7F3KQ2XA-CN-0001",
    "invoice": {
      "id": "<string>",
      "number": "<string>"
    },
    "customer": {
      "id": "<string>"
    },
    "reason": "<string>",
    "destination": "invoice",
    "refund": {
      "id": "<string>"
    },
    "currency": "<string>",
    "subtotal": 1,
    "taxTotal": 1,
    "taxes": [
      {
        "name": "VAT",
        "rate": 7.5,
        "reason": "<string>",
        "inclusive": true,
        "amount": 1
      }
    ],
    "total": 1,
    "sellerTaxId": "<string>",
    "hostedUrl": "<string>",
    "creditNotePdfUrl": "<string>",
    "issuedAt": "2023-11-07T05:31:56Z",
    "createdAt": "2023-11-07T05:31:56Z",
    "lines": [
      {
        "invoiceLineId": 123,
        "description": "<string>",
        "amount": 1,
        "taxAmount": 1,
        "taxRate": 123,
        "taxName": "<string>",
        "taxReason": "<string>",
        "taxInclusive": true,
        "revenueCode": "<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"
  }
}

Credit notes

Issue a credit note

Credits an amount spread over the invoice’s lines in proportion to what is left on each, or named amounts per line (lines, using the invoice lines’ id). Amounts are major units off the line totals, tax included; the tax inside is reversed at the rate the invoice was issued with. Refused on a void or draft invoice, past the invoice’s total, past what is left on a line, and while a charge on the invoice is still processing. An unpaid invoice credited down to nothing is marked paid with no payment, and if it was a subscription’s overdue debt, the subscription is treated as after a write-off. On a paid invoice destination is required: refund sends the money back to the card that paid (it needs refunds:write too), balance keeps it as customer balance that pays their next invoices, and outside records that you paid it back another way. A credit on an invoice the customer balance paid part of gives that part back to the balance first (lowering balanceApplied), and only the rest comes off amountPaid, so a refund only returns what the card paid. When the balance’s part covers the whole credit, a refund is issued as balance and nothing goes to the card.

POST

invoices

{invoice}

credit-notes

Issue a credit note

curl --request POST \
  --url https://bouclay.com/api/v1/invoices/{invoice}/credit-notes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "reason": "Billed 10 seats instead of 8",
  "amount": 1,
  "lines": [
    {
      "invoiceLineId": 123,
      "amount": 1
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    reason: 'Billed 10 seats instead of 8',
    amount: 1,
    lines: [{invoiceLineId: 123, amount: 1}]
  })
};

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

import requests

url = "https://bouclay.com/api/v1/invoices/{invoice}/credit-notes"

payload = {
    "reason": "Billed 10 seats instead of 8",
    "amount": 1,
    "lines": [
        {
            "invoiceLineId": 123,
            "amount": 1
        }
    ]
}
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/invoices/{invoice}/credit-notes",
  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([
    'reason' => 'Billed 10 seats instead of 8',
    'amount' => 1,
    'lines' => [
        [
                'invoiceLineId' => 123,
                'amount' => 1
        ]
    ]
  ]),
  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": "cn_123",
    "number": "7F3KQ2XA-CN-0001",
    "invoice": {
      "id": "<string>",
      "number": "<string>"
    },
    "customer": {
      "id": "<string>"
    },
    "reason": "<string>",
    "destination": "invoice",
    "refund": {
      "id": "<string>"
    },
    "currency": "<string>",
    "subtotal": 1,
    "taxTotal": 1,
    "taxes": [
      {
        "name": "VAT",
        "rate": 7.5,
        "reason": "<string>",
        "inclusive": true,
        "amount": 1
      }
    ],
    "total": 1,
    "sellerTaxId": "<string>",
    "hostedUrl": "<string>",
    "creditNotePdfUrl": "<string>",
    "issuedAt": "2023-11-07T05:31:56Z",
    "createdAt": "2023-11-07T05:31:56Z",
    "lines": [
      {
        "invoiceLineId": 123,
        "description": "<string>",
        "amount": 1,
        "taxAmount": 1,
        "taxRate": 123,
        "taxName": "<string>",
        "taxReason": "<string>",
        "taxInclusive": true,
        "revenueCode": "<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

invoice

string

required

Body

application/json

Give amount or lines, not both.

reason

string

required

Maximum string length: 255

Example:

"Billed 10 seats instead of 8"

destination

enum<string>

invoice (the default on an unpaid invoice) takes the credit off what is owed. On a paid invoice say refund, balance or outside.

Available options:

invoice,

refund,

balance,

outside

amount

number | null

Major currency units. For example, 15000 means NGN 15,000.

Required range: x >= 0

lines

object[]

Minimum array length: 1

Show child attributes

Response

Credit note 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

Issue a credit note

Authorizations

Headers

Path Parameters

Body

Response