---
title: "Create credit note"
method: POST
path: "/credit_notes"
tags: ["Credit note"]
---

# Create credit note

`POST /credit_notes`

This endpoint is used to create a single [`Credit Note`](/invoicing/credit-notes).

The credit note service period configuration supports two explicit modes:

1. Global service periods: Specify start_date and end_date at the credit note level.
   These dates will be applied to all line items uniformly.

2. Individual service periods: Specify start_date and end_date for each line item.
   When using this mode, ALL line items must have individual periods specified.

3. Default behavior: If no service periods are specified (neither global nor individual),
   the original invoice line item service periods will be used.

Note: Mixing global and individual service periods in the same request is not allowed
to prevent confusion.

Service period dates are normalized to the start of the day in the customer's timezone to ensure
consistent handling across different timezones.

Date Format: Use start_date and end_date with format "YYYY-MM-DD" (e.g., "2023-09-22")
to match other Orb APIs like /v1/invoice_line_items.

Note: Both start_date and end_date are inclusive - the service period will cover both
the start date and end date completely (from start of start_date to end of end_date).

## Request body

- CreateCreditNoteParams
  - `line_items` CreditNoteLineItemParams[], required
    - `invoice_line_item_id` string, required — The ID of the line item to credit.
    - `amount` string, required — The total amount in the invoice's currency to credit this line item.
    - `start_date` string, date, nullable — A date string to specify this line item's credit note service period start date in the customer's timezone. If provided, this will be used for this specific line item. If not provided, will use the global start_date if available, otherwise defaults to the original invoice line item's start date. This date is inclusive.
    - `end_date` string, date, nullable — A date string to specify this line item's credit note service period end date in the customer's timezone. If provided, this will be used for this specific line item. If not provided, will use the global end_date if available, otherwise defaults to the original invoice line item's end date. This date is inclusive.
  - `reason` 'duplicate' | 'fraudulent' | 'order_change' | 'product_unsatisfactory', required — An optional reason for the credit note.
  - `memo` string, nullable — An optional memo to attach to the credit note.
  - `start_date` string, date, nullable — A date string to specify the global credit note service period start date in the customer's timezone. This will be applied to all line items that don't have their own individual service periods specified. If not provided, line items will use their original invoice line item service periods. This date is inclusive.
  - `end_date` string, date, nullable — A date string to specify the global credit note service period end date in the customer's timezone. This will be applied to all line items that don't have their own individual service periods specified. If not provided, line items will use their original invoice line item service periods. This date is inclusive.

## Response `201`

Created

- CreditNote — The [Credit Note](/invoicing/credit-notes) resource represents a credit that has been applied to a particular invoice.
  - `id` string, required — The Orb id of this credit note.
  - `created_at` string, date-time, required — The creation time of the resource in Orb.
  - `voided_at` string, date-time, nullable, required — The time at which the credit note was voided in Orb, if applicable.
  - `credit_note_number` string, required — The unique identifier for credit notes.
  - `invoice_id` string, required — The id of the invoice resource that this credit note is applied to.
  - `memo` string, nullable, required — An optional memo supplied on the credit note.
  - `reason` 'Duplicate' | 'Fraudulent' | 'Order change' | 'Product unsatisfactory', nullable, required
  - `type` 'refund' | 'adjustment', required
  - `subtotal` string, required — The total prior to any creditable invoice-level discounts or minimums.
  - `total` string, required — The total including creditable invoice-level discounts or minimums, and tax.
  - `customer` CustomerMinified, required
    - `id` string, required
    - `external_customer_id` string, nullable, required
  - `credit_note_pdf` string, nullable, required — A URL to a PDF of the credit note.
  - `minimum_amount_refunded` string, nullable, required — Any credited amount from the applied minimum on the invoice.
  - `discounts` CreditNoteDiscount[] — Any discounts applied on the original invoice.
    - `discount_type` 'percentage', required
    - `percentage_discount` number, required
    - `amount_applied` string, required
    - `reason` string, nullable
    - `applies_to_prices` CreditNoteDiscountAppliesToPrice[], nullable
      - `id` string, required
      - `name` string, required
  - `maximum_amount_adjustment` CreditNoteDiscount, required
    - `discount_type` 'percentage', required
    - `percentage_discount` number, required
    - `amount_applied` string, required
    - `reason` string, nullable
    - `applies_to_prices` CreditNoteDiscountAppliesToPrice[], nullable
      - `id` string, required
      - `name` string, required
  - `line_items` CreditNoteLineItem[], required — All of the line items associated with this credit note.
    - `id` string, required — The Orb id of this resource.
    - `name` string, required — The name of the corresponding invoice line item.
    - `subtotal` string, required — The amount of the line item, excluding any line item minimums and discounts.
    - `amount` string, required — The amount of the line item, including any line item minimums and discounts.
    - `quantity` number, nullable, required — An optional quantity credited.
    - `discounts` CreditNoteLineItemDiscount[] — Any line item discounts from the invoice's line item.
      - `id` string, required
      - `discount_type` 'percentage' | 'amount', required
      - `percentage_discount` number, required
      - `amount_discount` string, nullable
      - `amount_applied` string, required
      - `reason` string, nullable
      - `applies_to_price_ids` string[], required
    - `tax_amounts` TaxAmount[], required — Any tax amounts applied onto the line item.
      - `tax_rate_description` string, required — The human-readable description of the applied tax rate.
      - `tax_rate_percentage` string, nullable, required — The tax rate percentage, out of 100.
      - `amount` string, required — The amount of additional tax incurred by this tax rate.
    - `item_id` string, required — The id of the item associated with this line item.
    - `start_time_inclusive` string, date-time, nullable — The start time of the service period for this credit note line item.
    - `end_time_exclusive` string, date-time, nullable — The end time of the service period for this credit note line item.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `404` — Not Found
- `409` — Conflict
- `413` — Content Too Large
- `429` — Too Many Requests
- `500` — Internal Server Error

---

[API](https://skmtc.net/withorb/apis/api-reference.md) · [All operations](https://skmtc.net/withorb/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/withorb/api-reference/versions/816dfe734e2e/schema)