---
title: "Create credit note"
description: "Raises a credit note for an invoice, as the order page does: a copy of the invoice with the next credit note number that credits the full invoice, then renders its PDF and returns it in full. If the invoice already has a"
url: https://docs.invoicefalcon.com/v3-reference/documents/create-credit-note/
api: "API v3 reference"
method: POST
path: "/documents/credit_notes"
---

# Create credit note

`POST https://app.invoicefalcon.com/api/v3/external/documents/credit_notes`

Raises a credit note for an invoice, as the order page does: a copy of the invoice with the next credit note number that credits the full invoice, then renders its PDF and returns it in full. If the invoice already has a credit note, that one is returned with already_existed: true. Partial credits are not supported; edit the credit note lines in the dashboard editor.

**Note:** Creates a new numbered document and renders a PDF (counts against a free plan invoice limit). With send_email: true it also emails the credit note to the customer immediately.

## Request body

- `invoice_id` (integer, required): The invoice to credit (its id from GET /documents/invoices).
- `send_email` (boolean): true emails the credit note to the customer right after creating it (default false).
- `generate_pdf` (boolean): false skips rendering the PDF (default true).
- `template_id` (integer): Template to render with. Default: the shop default credit note template.

## Returns

- `id` (integer): e.g. `980190966`
- `document_type` (string): e.g. `credit_note`
- `invoice_number` (string): e.g. `1`
- `title` (string): e.g. `Credit Note`
- `order` (object, nullable)
- `customer` (object)
  - `id` (integer): e.g. `4`
  - `name` (string): e.g. `Customer 1`
  - `email` (string): e.g. `cus1@gmail.com`
  - `shopify_customer_id` (string): e.g. `gid://shopify/Customer/23935678808145`
  - `phone` (string, nullable)
  - `tax_number` (string, nullable)
  - `eori_number` (string, nullable)
  - `tags` (array of anys)
- `financial_status` (string): e.g. `paid`
- `currency` (string): e.g. `USD`
- `total` (string): e.g. `1100.22`
- `issued_on` (string): e.g. `2026-11-10`
- `due_on` (string, nullable)
- `sent_at` (string, nullable)
- `printed_at` (string, nullable)
- `reminder_sent_at` (string, nullable)
- `paid` (boolean): e.g. `true`
- `edited` (boolean): e.g. `false`
- `trashed` (boolean): e.g. `false`
- `e_invoice_status` (string, nullable)
- `created_at` (string): e.g. `2026-11-10T08:35:17Z`
- `credited` (object)
  - `invoice_number` (string): e.g. `#1001`
  - `invoice_id` (integer): e.g. `980190965`
  - `shopify_order_id` (string): e.g. `gid://shopify/Order/12213474623569`
- `fulfillment_status` (string, nullable)
- `dates` (object)
  - `order_placed_at` (string): e.g. `2026-11-10T00:00:00Z`
  - `issued_on` (string): e.g. `2026-11-10`
  - `due_on` (string, nullable)
  - `tax_date` (string, nullable)
  - `fulfilled_on` (string, nullable)
- `po_number` (string, nullable)
- `payment_terms` (string, nullable)
- `payment_gateway` (string): e.g. `manual`
- `locale` (string): e.g. `en`
- `totals` (object)
  - `currency` (string): e.g. `USD`
  - `taxes_included` (boolean): e.g. `false`
  - `subtotal` (string): e.g. `1497.95`
  - `discounts` (string): e.g. `494.32`
  - `shipping` (string): e.g. `6.90`
  - `tax` (string): e.g. `89.69`
  - `duties` (string): e.g. `0.00`
  - `total` (string): e.g. `1100.22`
  - `total_paid` (string): e.g. `0.00`
  - `total_refunded` (string): e.g. `0.00`
  - `total_due` (string): e.g. `0.00`
- `billing_address` (object)
  - `name` (string): e.g. `Customer 1`
  - `first_name` (string): e.g. `Customer`
  - `last_name` (string): e.g. `1`
  - `company` (string, nullable)
  - `address1` (string, nullable)
  - `address2` (string, nullable)
  - `city` (string, nullable)
  - `province` (string, nullable)
  - `zip` (string, nullable)
  - `country` (string): e.g. `United States`
  - `country_code` (string): e.g. `US`
  - `phone` (string, nullable)
  - `tax_number` (string, nullable)
  - `eori_number` (string, nullable)
- `shipping_address` (object)
  - `name` (string): e.g. `Customer 1`
  - `first_name` (string): e.g. `Customer`
  - `last_name` (string): e.g. `1`
  - `company` (string, nullable)
  - `address1` (string): e.g. `New York`
  - `address2` (string, nullable)
  - `city` (string): e.g. `New York`
  - `province` (string): e.g. `New York`
  - `zip` (string): e.g. `10004`
  - `country` (string): e.g. `United States`
  - `country_code` (string): e.g. `US`
  - `phone` (string, nullable)
  - `tax_number` (string, nullable)
  - `eori_number` (string, nullable)
- `line_items` (array of objects)
  - `id` (integer): e.g. `473`
  - `title` (string): e.g. `The Videographer Snowboard`
  - `variant_title` (string, nullable)
  - `sku` (string): e.g. `9506.11.21`
  - `barcode` (string, nullable)
  - `product_type` (string, nullable)
  - `quantity` (integer): e.g. `1`
  - `unit_price` (string): e.g. `885.95`
  - `discount` (string): e.g. `0.00`
  - `discounted_unit_price` (string): e.g. `885.95`
  - `total_discount` (string): e.g. `0.00`
  - `tax` (string): e.g. `78.63`
  - `tax_lines` (array of objects)
    - `title` (string): e.g. `New York State Tax`
    - `rate` (string): e.g. `4.0`
  - `total` (string): e.g. `885.95`
  - `refunded_quantity` (integer): e.g. `0`
  - `image_url` (string, nullable)
  - `properties` (array of anys)
  - `note` (string, nullable)
- `shipping_lines` (array of objects)
  - `title` (string): e.g. `Standard`
  - `price` (string): e.g. `6.90`
  - `discount` (string): e.g. `0.00`
  - `tax` (string): e.g. `0.62`
  - `tax_lines` (array of objects)
    - `title` (string): e.g. `New York State Tax`
    - `rate` (string): e.g. `4.0`
    - `amount` (string): e.g. `0.28`
- `tax_lines` (array of objects)
  - `title` (string): e.g. `New York State Tax`
  - `rate` (string): e.g. `4.0`
  - `amount` (string): e.g. `40.42`
- `discount_codes` (array of strings)
- `notes` (object)
  - `note` (string, nullable)
  - `custom_note` (string, nullable)
  - `note_attributes` (array of anys)
- `custom_fields` (array of anys)
- `tags` (array of anys)
- `tracking` (object)
  - `companies` (array of anys, nullable)
  - `numbers` (array of anys, nullable)
- `pdf` (object)
  - `available` (boolean): e.g. `false`
  - `filename` (string, nullable)
  - `url` (string, nullable)
  - `generated_at` (string, nullable)
- `e_invoice` (object)
  - `status` (object, nullable)
  - `requested` (boolean): e.g. `false`
  - `error` (string, nullable)
- `updated_at` (string): e.g. `2026-11-10T08:35:17Z`
- `refunds` (array of anys)
- `already_existed` (boolean): e.g. `true`

Rate limit: this call costs 2 points ([rate limits](https://docs.invoicefalcon.com/v3/docs/api-v3/rate-limits/)).

## Examples

### Credit an invoice

```sh
curl -X POST "https://app.invoicefalcon.com/api/v3/external/documents/credit_notes" \
  -H "X-Auth-Token: $INVOICE_FALCON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_id": 48213
  }'
```

### Credit an invoice and email the credit note

```sh
curl -X POST "https://app.invoicefalcon.com/api/v3/external/documents/credit_notes" \
  -H "X-Auth-Token: $INVOICE_FALCON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_id": 48213,
    "send_email": true
  }'
```

### Credit with a specific template, no PDF yet

```sh
curl -X POST "https://app.invoicefalcon.com/api/v3/external/documents/credit_notes" \
  -H "X-Auth-Token: $INVOICE_FALCON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_id": 48213,
    "template_id": 313,
    "generate_pdf": false
  }'
```

## 200

The resource, when it already existed.

```json
{
  "id": 980190966,
  "document_type": "credit_note",
  "invoice_number": "1",
  "title": "Credit Note",
  "order": null,
  "customer": {
    "id": 4,
    "name": "Customer 1",
    "email": "cus1@gmail.com",
    "shopify_customer_id": "gid://shopify/Customer/23935678808145",
    "phone": null,
    "tax_number": null,
    "eori_number": null,
    "tags": []
  },
  "financial_status": "paid",
  "currency": "USD",
  "total": "1100.22",
  "issued_on": "2026-11-10",
  "due_on": null,
  "sent_at": null,
  "printed_at": null,
  "reminder_sent_at": null,
  "paid": true,
  "edited": false,
  "trashed": false,
  "e_invoice_status": null,
  "created_at": "2026-11-10T08:35:17Z",
  "credited": {
    "invoice_number": "#1001",
    "invoice_id": 980190965,
    "shopify_order_id": "gid://shopify/Order/12213474623569"
  },
  "fulfillment_status": null,
  "dates": {
    "order_placed_at": "2026-11-10T00:00:00Z",
    "issued_on": "2026-11-10",
    "due_on": null,
    "tax_date": null,
    "fulfilled_on": null
  },
  "po_number": null,
  "payment_terms": null,
  "payment_gateway": "manual",
  "locale": "en",
  "totals": {
    "currency": "USD",
    "taxes_included": false,
    "subtotal": "1497.95",
    "discounts": "494.32",
    "shipping": "6.90",
    "tax": "89.69",
    "duties": "0.00",
    "total": "1100.22",
    "total_paid": "0.00",
    "total_refunded": "0.00",
    "total_due": "0.00"
  },
  "billing_address": {
    "name": "Customer 1",
    "first_name": "Customer",
    "last_name": "1",
    "company": null,
    "address1": null,
    "address2": null,
    "city": null,
    "province": null,
    "zip": null,
    "country": "United States",
    "country_code": "US",
    "phone": null,
    "tax_number": null,
    "eori_number": null
  },
  "shipping_address": {
    "name": "Customer 1",
    "first_name": "Customer",
    "last_name": "1",
    "company": null,
    "address1": "New York",
    "address2": null,
    "city": "New York",
    "province": "New York",
    "zip": "10004",
    "country": "United States",
    "country_code": "US",
    "phone": null,
    "tax_number": null,
    "eori_number": null
  },
  "line_items": [
    {
      "id": 473,
      "title": "The Videographer Snowboard",
      "variant_title": null,
      "sku": "9506.11.21",
      "barcode": null,
      "product_type": null,
      "quantity": 1,
      "unit_price": "885.95",
      "discount": "0.00",
      "discounted_unit_price": "885.95",
      "total_discount": "0.00",
      "tax": "78.63",
      "tax_lines": [
        {
          "title": "New York State Tax",
          "rate": "4.0"
        },
        {
          "title": "New York City City Tax",
          "rate": "4.5"
        },
        {
          "title": "Metropolitan Commuter Transportation District",
          "rate": "0.375"
        }
      ],
      "total": "885.95",
      "refunded_quantity": 0,
      "image_url": null,
      "properties": [],
      "note": null
    },
    {
      "id": 474,
      "title": "Custom 1",
      "variant_title": null,
      "sku": null,
      "barcode": null,
      "product_type": null,
      "quantity": 1,
      "unit_price": "12.00",
      "discount": "0.00",
      "discounted_unit_price": "12.00",
      "total_discount": "0.00",
      "tax": "1.07",
      "tax_lines": [
        {
          "title": "New York State Tax",
          "rate": "4.0"
        },
        {
          "title": "New York City City Tax",
          "rate": "4.5"
        },
        {
          "title": "Metropolitan Commuter Transportation District",
          "rate": "0.375"
        }
      ],
      "total": "12.00",
      "refunded_quantity": 0,
      "image_url": null,
      "properties": [],
      "note": null
    },
    {
      "id": 475,
      "title": "The Collection Snowboard: Hydrogen",
      "variant_title": null,
      "sku": "9506.11.21",
      "barcode": null,
      "product_type": null,
      "quantity": 1,
      "unit_price": "600.00",
      "discount": "0.00",
      "discounted_unit_price": "600.00",
      "total_discount": "0.00",
      "tax": "53.25",
      "tax_lines": [
        {
          "title": "New York State Tax",
          "rate": "4.0"
        },
        {
          "title": "New York City City Tax",
          "rate": "4.5"
        },
        {
          "title": "Metropolitan Commuter Transportation District",
          "rate": "0.375"
        }
      ],
      "total": "600.00",
      "refunded_quantity": 0,
      "image_url": null,
      "properties": [],
      "note": null
    }
  ],
  "shipping_lines": [
    {
      "title": "Standard",
      "price": "6.90",
      "discount": "0.00",
      "tax": "0.62",
      "tax_lines": [
        {
          "title": "New York State Tax",
          "rate": "4.0",
          "amount": "0.28"
        },
        {
          "title": "New York City City Tax",
          "rate": "4.5",
          "amount": "0.31"
        },
        {
          "title": "Metropolitan Commuter Transportation District",
          "rate": "0.375",
          "amount": "0.03"
        }
      ]
    }
  ],
  "tax_lines": [
    {
      "title": "New York State Tax",
      "rate": "4.0",
      "amount": "40.42"
    },
    {
      "title": "New York City City Tax",
      "rate": "4.5",
      "amount": "45.47"
    },
    {
      "title": "Metropolitan Commuter Transportation District",
      "rate": "0.375",
      "amount": "3.80"
    }
  ],
  "discount_codes": [
    "Order discount in percentage"
  ],
  "notes": {
    "note": null,
    "custom_note": null,
    "note_attributes": []
  },
  "custom_fields": [],
  "tags": [],
  "tracking": {
    "companies": null,
    "numbers": null
  },
  "pdf": {
    "available": false,
    "filename": null,
    "url": null,
    "generated_at": null
  },
  "e_invoice": {
    "status": null,
    "requested": false,
    "error": null
  },
  "updated_at": "2026-11-10T08:35:17Z",
  "refunds": [],
  "already_existed": true
}
```

## 201

Created: the new resource.

```json
{
  "id": 980190966,
  "document_type": "credit_note",
  "invoice_number": "1",
  "title": "Credit Note",
  "order": null,
  "customer": {
    "id": 4,
    "name": "Customer 1",
    "email": "cus1@gmail.com",
    "shopify_customer_id": "gid://shopify/Customer/23935678808145",
    "phone": null,
    "tax_number": null,
    "eori_number": null,
    "tags": []
  },
  "financial_status": "paid",
  "currency": "USD",
  "total": "1100.22",
  "issued_on": "2026-11-10",
  "due_on": null,
  "sent_at": null,
  "printed_at": null,
  "reminder_sent_at": null,
  "paid": true,
  "edited": false,
  "trashed": false,
  "e_invoice_status": null,
  "created_at": "2026-11-10T08:35:17Z",
  "credited": {
    "invoice_number": "#1001",
    "invoice_id": 980190965,
    "shopify_order_id": "gid://shopify/Order/12213474623569"
  },
  "fulfillment_status": null,
  "dates": {
    "order_placed_at": "2026-11-10T00:00:00Z",
    "issued_on": "2026-11-10",
    "due_on": null,
    "tax_date": null,
    "fulfilled_on": null
  },
  "po_number": null,
  "payment_terms": null,
  "payment_gateway": "manual",
  "locale": "en",
  "totals": {
    "currency": "USD",
    "taxes_included": false,
    "subtotal": "1497.95",
    "discounts": "494.32",
    "shipping": "6.90",
    "tax": "89.69",
    "duties": "0.00",
    "total": "1100.22",
    "total_paid": "0.00",
    "total_refunded": "0.00",
    "total_due": "0.00"
  },
  "billing_address": {
    "name": "Customer 1",
    "first_name": "Customer",
    "last_name": "1",
    "company": null,
    "address1": null,
    "address2": null,
    "city": null,
    "province": null,
    "zip": null,
    "country": "United States",
    "country_code": "US",
    "phone": null,
    "tax_number": null,
    "eori_number": null
  },
  "shipping_address": {
    "name": "Customer 1",
    "first_name": "Customer",
    "last_name": "1",
    "company": null,
    "address1": "New York",
    "address2": null,
    "city": "New York",
    "province": "New York",
    "zip": "10004",
    "country": "United States",
    "country_code": "US",
    "phone": null,
    "tax_number": null,
    "eori_number": null
  },
  "line_items": [
    {
      "id": 473,
      "title": "The Videographer Snowboard",
      "variant_title": null,
      "sku": "9506.11.21",
      "barcode": null,
      "product_type": null,
      "quantity": 1,
      "unit_price": "885.95",
      "discount": "0.00",
      "discounted_unit_price": "885.95",
      "total_discount": "0.00",
      "tax": "78.63",
      "tax_lines": [
        {
          "title": "New York State Tax",
          "rate": "4.0"
        },
        {
          "title": "New York City City Tax",
          "rate": "4.5"
        },
        {
          "title": "Metropolitan Commuter Transportation District",
          "rate": "0.375"
        }
      ],
      "total": "885.95",
      "refunded_quantity": 0,
      "image_url": null,
      "properties": [],
      "note": null
    },
    {
      "id": 474,
      "title": "Custom 1",
      "variant_title": null,
      "sku": null,
      "barcode": null,
      "product_type": null,
      "quantity": 1,
      "unit_price": "12.00",
      "discount": "0.00",
      "discounted_unit_price": "12.00",
      "total_discount": "0.00",
      "tax": "1.07",
      "tax_lines": [
        {
          "title": "New York State Tax",
          "rate": "4.0"
        },
        {
          "title": "New York City City Tax",
          "rate": "4.5"
        },
        {
          "title": "Metropolitan Commuter Transportation District",
          "rate": "0.375"
        }
      ],
      "total": "12.00",
      "refunded_quantity": 0,
      "image_url": null,
      "properties": [],
      "note": null
    },
    {
      "id": 475,
      "title": "The Collection Snowboard: Hydrogen",
      "variant_title": null,
      "sku": "9506.11.21",
      "barcode": null,
      "product_type": null,
      "quantity": 1,
      "unit_price": "600.00",
      "discount": "0.00",
      "discounted_unit_price": "600.00",
      "total_discount": "0.00",
      "tax": "53.25",
      "tax_lines": [
        {
          "title": "New York State Tax",
          "rate": "4.0"
        },
        {
          "title": "New York City City Tax",
          "rate": "4.5"
        },
        {
          "title": "Metropolitan Commuter Transportation District",
          "rate": "0.375"
        }
      ],
      "total": "600.00",
      "refunded_quantity": 0,
      "image_url": null,
      "properties": [],
      "note": null
    }
  ],
  "shipping_lines": [
    {
      "title": "Standard",
      "price": "6.90",
      "discount": "0.00",
      "tax": "0.62",
      "tax_lines": [
        {
          "title": "New York State Tax",
          "rate": "4.0",
          "amount": "0.28"
        },
        {
          "title": "New York City City Tax",
          "rate": "4.5",
          "amount": "0.31"
        },
        {
          "title": "Metropolitan Commuter Transportation District",
          "rate": "0.375",
          "amount": "0.03"
        }
      ]
    }
  ],
  "tax_lines": [
    {
      "title": "New York State Tax",
      "rate": "4.0",
      "amount": "40.42"
    },
    {
      "title": "New York City City Tax",
      "rate": "4.5",
      "amount": "45.47"
    },
    {
      "title": "Metropolitan Commuter Transportation District",
      "rate": "0.375",
      "amount": "3.80"
    }
  ],
  "discount_codes": [
    "Order discount in percentage"
  ],
  "notes": {
    "note": null,
    "custom_note": null,
    "note_attributes": []
  },
  "custom_fields": [],
  "tags": [],
  "tracking": {
    "companies": null,
    "numbers": null
  },
  "pdf": {
    "available": false,
    "filename": null,
    "url": null,
    "generated_at": null
  },
  "e_invoice": {
    "status": null,
    "requested": false,
    "error": null
  },
  "updated_at": "2026-11-10T08:35:17Z",
  "refunds": [],
  "already_existed": false
}
```

## 401

Missing or unknown `X-Auth-Token`, or the shop uninstalled the app.

```json
{
  "errors": [
    "Invalid API key"
  ],
  "code": "unauthorized"
}
```

## 403

`v3_required`: the shop still runs the previous dashboard. `paid_plan_required`: API access needs a paid plan.

```json
{
  "errors": [
    "API access requires a paid plan"
  ],
  "code": "paid_plan_required"
}
```

## 404

The resource does not exist for this shop, or no action is registered at this path.

```json
{
  "errors": [
    "Resource not found"
  ],
  "code": "not_found"
}
```

## 422

The request failed validation. Nothing was saved.

```json
{
  "errors": [
    "id is missing"
  ]
}
```

## 429

Rate limited: cost-weighted per key (reads cost less than writes). Wait `Retry-After` seconds; see `X-RateLimit-*` headers.

```json
{
  "errors": [
    "Rate limit exceeded"
  ],
  "code": "rate_limited"
}
```

