Credit Notes

Create a credit note

Creates a credit note in draft status. Optionally link it to an invoice. Linked paid invoices are supported, and pre-payment credit notes are supported for Alguna-managed invoices in issued or overdue. Add line items to specify the credited amounts, then apply the credit note to finalize it. Alternatively, set apply to create and apply the credit note in one call — the same synchronous flow as calling apply-credit-note on a draft. Applying alone does not return funds; send refund as well to refund the customer, which requires a linked invoice that is paid. If applying fails, the credit note is left in draft and the error identifies it so it can be applied separately.

POST

credit-notes

curl --request POST \
  --url https://api.alguna.io/credit-notes \
  --header 'Alguna-Version: <alguna-version>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "apply": false,
  "billing_period_end": "2026-04-01T00:00:00Z",
  "billing_period_start": "2026-03-01T00:00:00Z",
  "customer_id": "cust_01H1VECT",
  "description": "Overcharge credit for March",
  "invoice_id": "inv_01H1VECT",
  "line_items": [
    {
      "description": "Platform usage credit",
      "quantity": "1",
      "unit_price": "100.00",
      "invoice_line_item_id": "ili_01H1VECT",
      "product_id": "prod_01H1VECT"
    }
  ],
  "refund": {
    "destination": "original_payment"
  }
}
'

import requests

url = "https://api.alguna.io/credit-notes"

payload = {
    "apply": False,
    "billing_period_end": "2026-04-01T00:00:00Z",
    "billing_period_start": "2026-03-01T00:00:00Z",
    "customer_id": "cust_01H1VECT",
    "description": "Overcharge credit for March",
    "invoice_id": "inv_01H1VECT",
    "line_items": [
        {
            "description": "Platform usage credit",
            "quantity": "1",
            "unit_price": "100.00",
            "invoice_line_item_id": "ili_01H1VECT",
            "product_id": "prod_01H1VECT"
        }
    ],
    "refund": { "destination": "original_payment" }
}
headers = {
    "Alguna-Version": "<alguna-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Alguna-Version': '<alguna-version>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    apply: false,
    billing_period_end: '2026-04-01T00:00:00Z',
    billing_period_start: '2026-03-01T00:00:00Z',
    customer_id: 'cust_01H1VECT',
    description: 'Overcharge credit for March',
    invoice_id: 'inv_01H1VECT',
    line_items: [
      {
        description: 'Platform usage credit',
        quantity: '1',
        unit_price: '100.00',
        invoice_line_item_id: 'ili_01H1VECT',
        product_id: 'prod_01H1VECT'
      }
    ],
    refund: {destination: 'original_payment'}
  })
};

fetch('https://api.alguna.io/credit-notes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.alguna.io/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([
    'apply' => false,
    'billing_period_end' => '2026-04-01T00:00:00Z',
    'billing_period_start' => '2026-03-01T00:00:00Z',
    'customer_id' => 'cust_01H1VECT',
    'description' => 'Overcharge credit for March',
    'invoice_id' => 'inv_01H1VECT',
    'line_items' => [
        [
                'description' => 'Platform usage credit',
                'quantity' => '1',
                'unit_price' => '100.00',
                'invoice_line_item_id' => 'ili_01H1VECT',
                'product_id' => 'prod_01H1VECT'
        ]
    ],
    'refund' => [
        'destination' => 'original_payment'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Alguna-Version: <alguna-version>",
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.alguna.io/credit-notes"

	payload := strings.NewReader("{\n  \"apply\": false,\n  \"billing_period_end\": \"2026-04-01T00:00:00Z\",\n  \"billing_period_start\": \"2026-03-01T00:00:00Z\",\n  \"customer_id\": \"cust_01H1VECT\",\n  \"description\": \"Overcharge credit for March\",\n  \"invoice_id\": \"inv_01H1VECT\",\n  \"line_items\": [\n    {\n      \"description\": \"Platform usage credit\",\n      \"quantity\": \"1\",\n      \"unit_price\": \"100.00\",\n      \"invoice_line_item_id\": \"ili_01H1VECT\",\n      \"product_id\": \"prod_01H1VECT\"\n    }\n  ],\n  \"refund\": {\n    \"destination\": \"original_payment\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Alguna-Version", "<alguna-version>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.alguna.io/credit-notes")
  .header("Alguna-Version", "<alguna-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"apply\": false,\n  \"billing_period_end\": \"2026-04-01T00:00:00Z\",\n  \"billing_period_start\": \"2026-03-01T00:00:00Z\",\n  \"customer_id\": \"cust_01H1VECT\",\n  \"description\": \"Overcharge credit for March\",\n  \"invoice_id\": \"inv_01H1VECT\",\n  \"line_items\": [\n    {\n      \"description\": \"Platform usage credit\",\n      \"quantity\": \"1\",\n      \"unit_price\": \"100.00\",\n      \"invoice_line_item_id\": \"ili_01H1VECT\",\n      \"product_id\": \"prod_01H1VECT\"\n    }\n  ],\n  \"refund\": {\n    \"destination\": \"original_payment\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.alguna.io/credit-notes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Alguna-Version"] = '<alguna-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"apply\": false,\n  \"billing_period_end\": \"2026-04-01T00:00:00Z\",\n  \"billing_period_start\": \"2026-03-01T00:00:00Z\",\n  \"customer_id\": \"cust_01H1VECT\",\n  \"description\": \"Overcharge credit for March\",\n  \"invoice_id\": \"inv_01H1VECT\",\n  \"line_items\": [\n    {\n      \"description\": \"Platform usage credit\",\n      \"quantity\": \"1\",\n      \"unit_price\": \"100.00\",\n      \"invoice_line_item_id\": \"ili_01H1VECT\",\n      \"product_id\": \"prod_01H1VECT\"\n    }\n  ],\n  \"refund\": {\n    \"destination\": \"original_payment\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "attachments": [
    {
      "file_url": "<string>",
      "title": "Credit Note PDF"
    }
  ],
  "created_at": "2026-04-01T10:00:00Z",
  "currency": "USD",
  "customer_id": "cust_01H1VECT",
  "description": "Overcharge credit",
  "external_reference": "<string>",
  "id": "cn_01H1VECT",
  "is_pdf_available": true,
  "line_items": [
    {
      "billing_period_end": "2026-01-31T23:59:59Z",
      "billing_period_start": "2026-01-01T00:00:00Z",
      "description": "Platform usage credit",
      "id": "cnli_01H1VECT",
      "is_editable": true,
      "quantity": "1",
      "total_price": "100.00",
      "unit_price": "100.00",
      "additional_description": "<string>",
      "invoice_line_item_id": "<string>",
      "product_id": "prod_01H1VECT",
      "tax_amount": "10.00",
      "tax_rate": "0.10"
    }
  ],
  "status": "draft",
  "subtotal": "100.00",
  "sync_enabled": true,
  "tax": "10.00",
  "total": "110.00",
  "updated_at": "2026-04-01T12:30:00Z",
  "accounting_credit_note_id": "<string>",
  "accounting_credit_note_url": "<string>",
  "accounting_integration_id": "<string>",
  "accounting_provider": "<string>",
  "apply_date": "2026-03-01T00:00:00Z",
  "billing_period_end": "2026-01-31T23:59:59Z",
  "billing_period_start": "2026-01-01T00:00:00Z",
  "credit_date": "2026-03-01T00:00:00Z",
  "invoice_id": "<string>",
  "last_refund_date": "2023-11-07T05:31:56Z",
  "last_refund_id": "<string>",
  "legal_entity_id": "<string>",
  "purchase_order_number": "<string>",
  "void_date": "2023-11-07T05:31:56Z"
}

{
  "detail": "<string>",
  "status": 123
}

{
  "detail": "<string>",
  "status": 123
}

{
  "detail": "<string>",
  "status": 123
}

{
  "detail": "<string>",
  "status": 123
}

{
  "detail": "<string>",
  "status": 123
}

{
  "detail": "<string>",
  "status": 123
}

Authorizations

Authorization

string

header

required

API key authentication. Pass your API key as a Bearer token.

Headers

Alguna-Version

enum<string>

required

Available options:

2026-04-01

Idempotency-Key

string

A unique string used to ensure the request is processed exactly once. If you retry a request with the same idempotency key within 24 hours, the original response is returned without re-executing the operation.

Maximum string length: 255

Example:

"ik_a1b2c3d4e5f6"

Body

application/json

apply

boolean

Apply the credit note as part of creating it, synchronously, exactly as create followed by apply-credit-note would. Defaults to false, leaving it a draft. If applying fails the credit note remains a draft and the error identifies it, so it can be retried via apply-credit-note.

Example:

false

billing_period_end

string<date-time> | null

End of the billing period

Example:

"2026-04-01T00:00:00Z"

billing_period_start

string<date-time> | null

Start of the billing period

Example:

"2026-03-01T00:00:00Z"

customer_id

string | null

Customer the credit note is issued to. Required unless invoice_id is given, in which case it is taken from the invoice; when both are given they must agree.

Minimum string length: 1

Example:

"cust_01H1VECT"

description

string | null

Credit note description

Example:

"Overcharge credit for March"

invoice_id

string | null

Linked invoice. Required unless customer_id is given. Pre-payment credit notes are supported only for Alguna-managed invoices in issued or overdue

Minimum string length: 1

Example:

"inv_01H1VECT"

line_items

object[]

Line items on the credit note

Show child attributes

refund

object | null

Refund the customer as part of applying the credit note. Requires apply and a linked invoice that is paid; omit it to credit the customer without returning funds.

Show child attributes

Response

Success

attachments

object[]

required

Attachments on this credit note

Show child attributes

created_at

string<date-time>

required

Timestamp when the credit note was created

Example:

"2026-04-01T10:00:00Z"

currency

string

required

Currency code

Example:

"USD"

customer_id

string

required

Customer this credit note belongs to

Example:

"cust_01H1VECT"

description

string

required

Description of the credit note

Example:

"Overcharge credit"

external_reference

string

required

External reference identifier

string

required

Unique identifier for the credit note

Example:

"cn_01H1VECT"

is_pdf_available

boolean

required

Whether a PDF is available for download

line_items

object[]

required

Line items on this credit note

Show child attributes

status

enum<string>

required

Current status of the credit note

Available options:

draft,

applied,

void,

pending_refund

Example:

"draft"

subtotal

string

required

Subtotal before tax

Example:

"100.00"

sync_enabled

boolean

required

Whether accounting sync is enabled

tax

string

required

Tax amount

Example:

"10.00"

total

string

required

Total amount including tax

Example:

"110.00"

updated_at

string<date-time>

required

Timestamp when the credit note was last updated

Example:

"2026-04-01T12:30:00Z"

accounting_credit_note_id

string | null

Credit note ID in the accounting system

accounting_credit_note_url

string | null

URL to the credit note in the accounting system

accounting_integration_id

string | null

Accounting integration ID

accounting_provider

string | null

Accounting provider name

apply_date

string<date-time> | null

Date the credit note was applied

Example:

"2026-03-01T00:00:00Z"

billing_period_end

string<date-time> | null

End of the billing period

Example:

"2026-01-31T23:59:59Z"

billing_period_start

string<date-time> | null

Start of the billing period

Example:

"2026-01-01T00:00:00Z"

credit_date

string<date-time> | null

Date of the credit

Example:

"2026-03-01T00:00:00Z"

invoice_id

string | null

Associated invoice ID

last_refund_date

string<date-time> | null

Date of the last refund

last_refund_id

string | null

ID of the last refund

legal_entity_id

string | null

Legal entity ID

purchase_order_number

string | null

Purchase order number

void_date

string<date-time> | null

Date the credit note was voided

⌘I

Create a credit note

curl --request POST \
  --url https://api.alguna.io/credit-notes \
  --header 'Alguna-Version: <alguna-version>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "apply": false,
  "billing_period_end": "2026-04-01T00:00:00Z",
  "billing_period_start": "2026-03-01T00:00:00Z",
  "customer_id": "cust_01H1VECT",
  "description": "Overcharge credit for March",
  "invoice_id": "inv_01H1VECT",
  "line_items": [
    {
      "description": "Platform usage credit",
      "quantity": "1",
      "unit_price": "100.00",
      "invoice_line_item_id": "ili_01H1VECT",
      "product_id": "prod_01H1VECT"
    }
  ],
  "refund": {
    "destination": "original_payment"
  }
}
'

import requests

url = "https://api.alguna.io/credit-notes"

payload = {
    "apply": False,
    "billing_period_end": "2026-04-01T00:00:00Z",
    "billing_period_start": "2026-03-01T00:00:00Z",
    "customer_id": "cust_01H1VECT",
    "description": "Overcharge credit for March",
    "invoice_id": "inv_01H1VECT",
    "line_items": [
        {
            "description": "Platform usage credit",
            "quantity": "1",
            "unit_price": "100.00",
            "invoice_line_item_id": "ili_01H1VECT",
            "product_id": "prod_01H1VECT"
        }
    ],
    "refund": { "destination": "original_payment" }
}
headers = {
    "Alguna-Version": "<alguna-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Alguna-Version': '<alguna-version>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    apply: false,
    billing_period_end: '2026-04-01T00:00:00Z',
    billing_period_start: '2026-03-01T00:00:00Z',
    customer_id: 'cust_01H1VECT',
    description: 'Overcharge credit for March',
    invoice_id: 'inv_01H1VECT',
    line_items: [
      {
        description: 'Platform usage credit',
        quantity: '1',
        unit_price: '100.00',
        invoice_line_item_id: 'ili_01H1VECT',
        product_id: 'prod_01H1VECT'
      }
    ],
    refund: {destination: 'original_payment'}
  })
};

fetch('https://api.alguna.io/credit-notes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.alguna.io/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([
    'apply' => false,
    'billing_period_end' => '2026-04-01T00:00:00Z',
    'billing_period_start' => '2026-03-01T00:00:00Z',
    'customer_id' => 'cust_01H1VECT',
    'description' => 'Overcharge credit for March',
    'invoice_id' => 'inv_01H1VECT',
    'line_items' => [
        [
                'description' => 'Platform usage credit',
                'quantity' => '1',
                'unit_price' => '100.00',
                'invoice_line_item_id' => 'ili_01H1VECT',
                'product_id' => 'prod_01H1VECT'
        ]
    ],
    'refund' => [
        'destination' => 'original_payment'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Alguna-Version: <alguna-version>",
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.alguna.io/credit-notes"

	payload := strings.NewReader("{\n  \"apply\": false,\n  \"billing_period_end\": \"2026-04-01T00:00:00Z\",\n  \"billing_period_start\": \"2026-03-01T00:00:00Z\",\n  \"customer_id\": \"cust_01H1VECT\",\n  \"description\": \"Overcharge credit for March\",\n  \"invoice_id\": \"inv_01H1VECT\",\n  \"line_items\": [\n    {\n      \"description\": \"Platform usage credit\",\n      \"quantity\": \"1\",\n      \"unit_price\": \"100.00\",\n      \"invoice_line_item_id\": \"ili_01H1VECT\",\n      \"product_id\": \"prod_01H1VECT\"\n    }\n  ],\n  \"refund\": {\n    \"destination\": \"original_payment\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Alguna-Version", "<alguna-version>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.alguna.io/credit-notes")
  .header("Alguna-Version", "<alguna-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"apply\": false,\n  \"billing_period_end\": \"2026-04-01T00:00:00Z\",\n  \"billing_period_start\": \"2026-03-01T00:00:00Z\",\n  \"customer_id\": \"cust_01H1VECT\",\n  \"description\": \"Overcharge credit for March\",\n  \"invoice_id\": \"inv_01H1VECT\",\n  \"line_items\": [\n    {\n      \"description\": \"Platform usage credit\",\n      \"quantity\": \"1\",\n      \"unit_price\": \"100.00\",\n      \"invoice_line_item_id\": \"ili_01H1VECT\",\n      \"product_id\": \"prod_01H1VECT\"\n    }\n  ],\n  \"refund\": {\n    \"destination\": \"original_payment\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.alguna.io/credit-notes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Alguna-Version"] = '<alguna-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"apply\": false,\n  \"billing_period_end\": \"2026-04-01T00:00:00Z\",\n  \"billing_period_start\": \"2026-03-01T00:00:00Z\",\n  \"customer_id\": \"cust_01H1VECT\",\n  \"description\": \"Overcharge credit for March\",\n  \"invoice_id\": \"inv_01H1VECT\",\n  \"line_items\": [\n    {\n      \"description\": \"Platform usage credit\",\n      \"quantity\": \"1\",\n      \"unit_price\": \"100.00\",\n      \"invoice_line_item_id\": \"ili_01H1VECT\",\n      \"product_id\": \"prod_01H1VECT\"\n    }\n  ],\n  \"refund\": {\n    \"destination\": \"original_payment\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "attachments": [
    {
      "file_url": "<string>",
      "title": "Credit Note PDF"
    }
  ],
  "created_at": "2026-04-01T10:00:00Z",
  "currency": "USD",
  "customer_id": "cust_01H1VECT",
  "description": "Overcharge credit",
  "external_reference": "<string>",
  "id": "cn_01H1VECT",
  "is_pdf_available": true,
  "line_items": [
    {
      "billing_period_end": "2026-01-31T23:59:59Z",
      "billing_period_start": "2026-01-01T00:00:00Z",
      "description": "Platform usage credit",
      "id": "cnli_01H1VECT",
      "is_editable": true,
      "quantity": "1",
      "total_price": "100.00",
      "unit_price": "100.00",
      "additional_description": "<string>",
      "invoice_line_item_id": "<string>",
      "product_id": "prod_01H1VECT",
      "tax_amount": "10.00",
      "tax_rate": "0.10"
    }
  ],
  "status": "draft",
  "subtotal": "100.00",
  "sync_enabled": true,
  "tax": "10.00",
  "total": "110.00",
  "updated_at": "2026-04-01T12:30:00Z",
  "accounting_credit_note_id": "<string>",
  "accounting_credit_note_url": "<string>",
  "accounting_integration_id": "<string>",
  "accounting_provider": "<string>",
  "apply_date": "2026-03-01T00:00:00Z",
  "billing_period_end": "2026-01-31T23:59:59Z",
  "billing_period_start": "2026-01-01T00:00:00Z",
  "credit_date": "2026-03-01T00:00:00Z",
  "invoice_id": "<string>",
  "last_refund_date": "2023-11-07T05:31:56Z",
  "last_refund_id": "<string>",
  "legal_entity_id": "<string>",
  "purchase_order_number": "<string>",
  "void_date": "2023-11-07T05:31:56Z"
}

{
  "detail": "<string>",
  "status": 123
}

{
  "detail": "<string>",
  "status": 123
}

{
  "detail": "<string>",
  "status": 123
}

{
  "detail": "<string>",
  "status": 123
}

{
  "detail": "<string>",
  "status": 123
}

{
  "detail": "<string>",
  "status": 123
}

API Reference

Examples

SDKs

API Reference

Create a credit note

Authorizations

Headers

Body

Response