> ## Documentation Index > Fetch the complete documentation index at: https://docs.withorb.com/llms.txt > Use this file to discover all available pages before exploring further. # Create credit note > 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). ## OpenAPI ````yaml /api-reference/orb-openapi.json post /credit_notes openapi: 3.1.0 info: title: API Reference description: >- Orb's API is built with the following principles in mind: 1. **Predictable developer experience**: Where applicable, the Orb API uses industry-standard patterns such as cursor-based pagination and standardized error output. To help with debugging in critical API actions, the API always strives to provide detailed and actionable error messages. Aliases such as external customer IDs aid in fast integration times. 2. **Reliably real time**: Orb's event-based APIs, such as event ingestion are designed to handle extremely high throughput and scale with concurrent load. Orb also provides a real-time event-level credits ledger and a highly performant webhooks architecture. 3. **Flexibility at the forefront**: Features like timezone localization and the ability to amend historical usage show the flexible nature of the platform. You can download the latest OpenAPI spec [here](https://api.withorb.com/spec.json) - pass `?version=3.0` for an OpenAPI 3.0-compatible spec. contact: name: Orb, Inc. url: https://www.withorb.com/ email: team@withorb.com version: '1.0' servers: - url: https://api.withorb.com/v1 description: Production server security: - APIKeyAuth: [] tags: - name: Alert description: >- [Alerts within Orb](/product-catalog/configuring-alerts) monitor spending, usage, or credit balance and trigger webhooks when a threshold is exceeded. Alerts created through the API can be scoped to either customers or subscriptions. - name: Availability - name: Coupon description: >- A coupon represents a reusable discount configuration that can be applied either as a fixed or percentage amount to an invoice or subscription. Coupons are activated using a redemption code, which applies the discount to a subscription or invoice. The duration of a coupon determines how long it remains available for use by end users. - name: Credit description: >- The [Credit Ledger Entry resource](/product-catalog/prepurchase) models prepaid credits within Orb. - name: Credit note description: >- The [Credit Note](/invoicing/credit-notes) resource represents a credit that has been applied to a particular invoice. - name: Customer description: >- A customer is a buyer of your products, and the other party to the billing relationship. In Orb, customers are assigned system generated identifiers automatically, but it's often desirable to have these match existing identifiers in your system. To avoid having to denormalize Orb ID information, you can pass in an `external_customer_id` with your own identifier. See [Customer ID Aliases](/events-and-metrics/customer-aliases) for further information about how these aliases work in Orb. In addition to having an identifier in your system, a customer may exist in a payment provider solution like Stripe. Use the `payment_provider_id` and the `payment_provider` enum field to express this mapping. A customer also has a timezone (from the standard [IANA timezone database](https://www.iana.org/time-zones)), which defaults to your account's timezone. See [Timezone localization](/essentials/timezones) for information on what this timezone parameter influences within Orb. - name: Dimensional Price Group - name: Event description: >- The [Event](/core-concepts#event) resource represents a usage event that has been created for a customer. Events are the core of Orb's usage-based billing model, and are used to calculate the usage charges for a given billing period. - name: Invoice description: >- An [`Invoice`](/core-concepts#invoice) is a fundamental billing entity, representing the request for payment for a single subscription. This includes a set of line items, which correspond to prices in the subscription's plan and can represent fixed recurring fees or usage-based fees. They are generated at the end of a billing period, or as the result of an action, such as a cancellation. - name: Item description: >- The Item resource represents a sellable product or good. Items are associated with all line items, billable metrics, and prices and are used for defining external sync behavior for invoices and tax calculation purposes. - name: License - name: LicenseType description: >- The LicenseType resource represents a type of license that can be assigned to users. License types are used during billing by grouping metrics on the configured grouping key. - name: Metric description: >- The Metric resource represents a calculation of a quantity based on events. Metrics are defined by the query that transforms raw usage events into meaningful values for your customers. - name: Plan description: >- The [Plan](/core-concepts#plan-and-price) resource represents a plan that can be subscribed to by a customer. Plans define the billing behavior of the subscription. You can see more about how to configure prices in the [Price resource](/reference/price). - name: Price description: >- The Price resource represents a price that can be billed on a subscription, resulting in a charge on an invoice in the form of an invoice line item. Prices take a quantity and determine an amount to bill. Orb supports a few different pricing models out of the box. Each of these models is serialized differently in a given Price object. The model_type field determines the key for the configuration object that is present. For more on the types of prices, see [the core concepts documentation](/core-concepts#plan-and-price) - name: Price interval description: >- The Price Interval resource represents a period of time for which a price will bill on a subscription. A subscription’s price intervals define its billing behavior. - name: Subscription description: >- A [subscription](/core-concepts#subscription) represents the purchase of a plan by a customer. By default, subscriptions begin on the day that they're created and renew automatically for each billing cycle at the cadence that's configured in the plan definition. Subscriptions also default to **beginning of month alignment**, which means the first invoice issued for the subscription will have pro-rated charges between the `start_date` and the first of the following month. Subsequent billing periods will always start and end on a month boundary (e.g. subsequent month starts for monthly billing). Depending on the plan configuration, any _flat_ recurring fees will be billed either at the beginning (in-advance) or end (in-arrears) of each billing cycle. Plans default to **in-advance billing**. Usage-based fees are billed in arrears as usage is accumulated. In the normal course of events, you can expect an invoice to contain usage-based charges for the previous period, and a recurring fee for the following period. - name: Subscription Change paths: /credit_notes: post: tags: - Credit note summary: Create credit note description: >- 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). operationId: create-credit-note parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateCreditNoteParams' required: true responses: '201': description: Created headers: {} content: application/json: schema: $ref: '#/components/schemas/CreditNote' '400': description: Bad Request headers: {} content: application/json: schema: $ref: '#/components/schemas/400Error' '401': description: Unauthorized headers: {} content: application/json: schema: $ref: '#/components/schemas/401Error' '404': description: Not Found headers: {} content: application/json: schema: $ref: '#/components/schemas/404Error' '409': description: Conflict headers: {} content: application/json: schema: $ref: '#/components/schemas/409Error' '413': description: Content Too Large headers: {} content: application/json: schema: $ref: '#/components/schemas/413Error' '429': description: Too Many Requests headers: {} content: application/json: schema: $ref: '#/components/schemas/429Error' '500': description: Internal Server Error headers: {} content: application/json: schema: $ref: '#/components/schemas/500Error' components: schemas: CreateCreditNoteParams: properties: line_items: items: $ref: '#/components/schemas/CreditNoteLineItemParams' type: array minItems: 1 title: Line Items reason: type: string enum: - duplicate - fraudulent - order_change - product_unsatisfactory title: Reason description: An optional reason for the credit note. examples: - duplicate - fraudulent - order_change - product_unsatisfactory memo: oneOf: - type: string - type: 'null' title: Memo description: An optional memo to attach to the credit note. examples: - An optional memo for my credit note. start_date: oneOf: - type: string format: date - type: 'null' title: Start Date description: >- 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. examples: - '2023-09-22' end_date: oneOf: - type: string format: date - type: 'null' title: End Date description: >- 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. examples: - '2023-09-22' additionalProperties: false type: object required: - line_items - reason title: CreateCreditNoteParams CreditNote: properties: id: type: string title: Id description: The Orb id of this credit note. created_at: type: string format: date-time title: Created At description: The creation time of the resource in Orb. voided_at: oneOf: - type: string format: date-time - type: 'null' title: Voided At description: The time at which the credit note was voided in Orb, if applicable. credit_note_number: type: string title: Credit Note Number description: The unique identifier for credit notes. invoice_id: type: string title: Invoice Id description: The id of the invoice resource that this credit note is applied to. memo: oneOf: - type: string - type: 'null' title: Memo description: An optional memo supplied on the credit note. reason: oneOf: - type: string enum: - Duplicate - Fraudulent - Order change - Product unsatisfactory - type: 'null' title: Reason type: type: string enum: - refund - adjustment title: Type subtotal: type: string title: Subtotal description: >- The total prior to any creditable invoice-level discounts or minimums. total: type: string title: Total description: >- The total including creditable invoice-level discounts or minimums, and tax. customer: $ref: '#/components/schemas/CustomerMinified' credit_note_pdf: oneOf: - type: string - type: 'null' title: Credit Note Pdf description: A URL to a PDF of the credit note. minimum_amount_refunded: oneOf: - type: string - type: 'null' title: Minimum Amount Refunded description: Any credited amount from the applied minimum on the invoice. discounts: items: $ref: '#/components/schemas/CreditNoteDiscount' type: array title: Discounts description: Any discounts applied on the original invoice. default: [] maximum_amount_adjustment: oneOf: - $ref: '#/components/schemas/CreditNoteDiscount' - type: 'null' description: The maximum amount applied on the original invoice line_items: items: $ref: '#/components/schemas/CreditNoteLineItem' type: array title: Line Items description: All of the line items associated with this credit note. type: object required: - id - created_at - voided_at - credit_note_number - invoice_id - memo - reason - type - subtotal - total - customer - credit_note_pdf - minimum_amount_refunded - maximum_amount_adjustment - line_items title: CreditNote description: >- The [Credit Note](/invoicing/credit-notes) resource represents a credit that has been applied to a particular invoice. 400Error: oneOf: - $ref: '#/components/schemas/ConstraintViolationError' - $ref: '#/components/schemas/DuplicateResourceCreationError' - $ref: '#/components/schemas/RequestValidationError' 401Error: $ref: '#/components/schemas/AuthorizationError' title: 401Error 404Error: oneOf: - $ref: '#/components/schemas/FeatureNotAvailableError' - $ref: '#/components/schemas/ResourceNotFoundError' - $ref: '#/components/schemas/URLNotFound' 409Error: $ref: '#/components/schemas/IdempotencyRequestMismatch' title: 409Error 413Error: oneOf: - $ref: '#/components/schemas/RequestTooLargeError' - $ref: '#/components/schemas/ResourceTooLargeError' - $ref: '#/components/schemas/TooManyResultsError' 429Error: $ref: '#/components/schemas/TooManyRequests' title: 429Error 500Error: $ref: '#/components/schemas/ServerError' title: 500Error CreditNoteLineItemParams: properties: invoice_line_item_id: type: string title: Invoice Line Item Id description: The ID of the line item to credit. examples: - 4khy3nwzktxv7 amount: type: string title: Amount description: The total amount in the invoice's currency to credit this line item. start_date: oneOf: - type: string format: date - type: 'null' title: Start Date description: >- 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. examples: - '2023-09-22' end_date: oneOf: - type: string format: date - type: 'null' title: End Date description: >- 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. examples: - '2023-09-22' type: object required: - invoice_line_item_id - amount title: CreditNoteLineItemParams CustomerMinified: properties: id: type: string title: Id external_customer_id: oneOf: - type: string - type: 'null' title: External Customer Id type: object required: - id - external_customer_id title: CustomerMinified CreditNoteDiscount: properties: discount_type: type: string enum: - percentage title: Discount Type percentage_discount: type: number title: Percentage Discount amount_applied: type: string title: Amount Applied reason: oneOf: - type: string - type: 'null' title: Reason applies_to_prices: oneOf: - items: $ref: '#/components/schemas/CreditNoteDiscountAppliesToPrice' type: array - type: 'null' title: Applies To Prices type: object required: - discount_type - percentage_discount - amount_applied title: CreditNoteDiscount CreditNoteLineItem: properties: id: type: string title: Id description: The Orb id of this resource. name: type: string title: Name description: The name of the corresponding invoice line item. subtotal: type: string title: Subtotal description: >- The amount of the line item, excluding any line item minimums and discounts. amount: type: string title: Amount description: >- The amount of the line item, including any line item minimums and discounts. quantity: oneOf: - type: number - type: 'null' title: Quantity description: An optional quantity credited. discounts: items: $ref: '#/components/schemas/CreditNoteLineItemDiscount' type: array title: Discounts description: Any line item discounts from the invoice's line item. default: [] tax_amounts: items: $ref: '#/components/schemas/TaxAmount' type: array title: Tax Amounts description: Any tax amounts applied onto the line item. item_id: type: string title: Item Id description: The id of the item associated with this line item. start_time_inclusive: oneOf: - type: string format: date-time - type: 'null' title: Start Time Inclusive description: The start time of the service period for this credit note line item. end_time_exclusive: oneOf: - type: string format: date-time - type: 'null' title: End Time Exclusive description: The end time of the service period for this credit note line item. type: object required: - id - name - subtotal - amount - quantity - tax_amounts - item_id title: CreditNoteLineItem ConstraintViolationError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#400-constraint-violation title: Type status: type: integer enum: - 400 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: ConstraintViolationError DuplicateResourceCreationError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#400-duplicate-resource-creation title: Type status: type: integer enum: - 400 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: DuplicateResourceCreationError RequestValidationError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#400-request-validation-errors title: Type status: type: integer enum: - 400 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title validation_errors: items: {} type: array title: Validation Errors type: object required: - type - status - validation_errors title: RequestValidationError AuthorizationError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#401-authentication-error title: Type status: type: integer enum: - 401 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: AuthorizationError FeatureNotAvailableError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#404-feature-not-available title: Type status: type: integer enum: - 400 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: FeatureNotAvailableError ResourceNotFoundError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#404-resource-not-found title: Type status: type: integer enum: - 404 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: type: string title: Title type: object required: - type - status - title title: ResourceNotFoundError URLNotFound: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#404-url-not-found title: Type status: type: integer enum: - 404 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: URLNotFound IdempotencyRequestMismatch: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#409-resource-conflict title: Type status: type: integer enum: - 409 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: IdempotencyRequestMismatch RequestTooLargeError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#413-request-too-large title: Type status: type: integer enum: - 413 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: RequestTooLargeError ResourceTooLargeError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#413-resource-too-large title: Type status: type: integer enum: - 413 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: ResourceTooLargeError TooManyResultsError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#413-too-many-results title: Type status: type: integer enum: - 413 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: TooManyResultsError TooManyRequests: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#429-too-many-requests title: Type status: type: integer enum: - 429 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: TooManyRequests ServerError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#500-internal-server-error title: Type status: type: integer title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: ServerError CreditNoteDiscountAppliesToPrice: properties: id: type: string title: Id name: type: string title: Name type: object required: - id - name title: CreditNoteDiscountAppliesToPrice CreditNoteLineItemDiscount: properties: id: type: string title: Id discount_type: type: string enum: - percentage - amount title: Discount Type percentage_discount: type: number title: Percentage Discount amount_discount: oneOf: - type: string - type: 'null' title: Amount Discount amount_applied: type: string title: Amount Applied reason: oneOf: - type: string - type: 'null' title: Reason applies_to_price_ids: items: type: string type: array title: Applies To Price Ids type: object required: - id - discount_type - percentage_discount - amount_applied - applies_to_price_ids title: CreditNoteLineItemDiscount TaxAmount: properties: tax_rate_description: type: string title: Tax Rate Description description: The human-readable description of the applied tax rate. tax_rate_percentage: oneOf: - type: string - type: 'null' title: Tax Rate Percentage description: The tax rate percentage, out of 100. amount: type: string title: Amount description: The amount of additional tax incurred by this tax rate. type: object required: - tax_rate_description - tax_rate_percentage - amount title: TaxAmount securitySchemes: APIKeyAuth: type: http description: API Keys can be issued in the Orb's web application. scheme: bearer ````