> ## Documentation Index > Fetch the complete documentation index at: https://docs.numeral.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Refunds > Add a refund to a transaction ## Refund Endpoint (2026-11-01) Add a refund to a previously recorded transaction. > [!NOTE] > > Remember to include the `X-API-Version: 2026-11-01` header in your request to use this API version. ## OpenAPI ````yaml api-reference/v2026-11-01/openapi.json POST /tax/refunds openapi: 3.0.1 info: title: Numeral API description: >- API for sales tax calculations - Version 2026-11-01. This version adds a `note` to every tax jurisdiction row and an `effective_tax_rate` to calculations and platform calculation totals. license: name: MIT version: '2026-11-01' servers: - url: https://api.numeralhq.com/ security: - bearerAuth: [] paths: /tax/refunds: post: summary: Create Refund description: Add a refund to a transaction operationId: createRefund_v20261101 requestBody: content: application/json: schema: $ref: '#/components/schemas/RefundRequest' required: true responses: '200': description: Refund response content: application/json: schema: $ref: '#/components/schemas/RefundResponse' '400': description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Transaction not found content: application/json: schema: $ref: '#/components/schemas/TransactionNotFoundError' components: schemas: RefundRequest: type: object properties: transaction_id: type: string description: >- The ID of the `transaction` to refund. This is the `transaction_id` returned from the `/transactions` creation response. example: tr_123456789 type: type: string enum: - full - partial description: >- This will be either `'full'` or `'partial'`. If `type='partial'`, you must also provide the line item(s) you wish to apply refunds against. example: partial refund_processed_at: type: number description: >- Unix timestamp in **seconds** representing the date and time the refund was made. If not provided, the current date and time will be used. example: 1714787673 line_items: type: array description: >- If the refund is `type=full`, line items aren't necessary. If the refund is `type=partial`, you must provide the line item(s) you wish to apply refunds against using a `reference_product_id`. items: type: object properties: reference_product_id: type: string description: >- The ID of the product to apply refunds against. We will attempt to find the line item from the original transaction based on this `reference_product_id`. example: p-1233543 reference_line_item_id: type: string description: >- This **optional** attribute is the ID of the line item from your system. It will be used only for reporting. example: line_123456789 sales_amount_refunded: type: number description: >- The sale amount that was refunded to the customer on this line item, not inclusive of tax refunded. example: -200 quantity: type: number description: The quantity of this product being refunded. example: 2 tax_amount_refunded: type: number description: The amount of tax that was refunded to the customer. example: -14 required: - transaction_id - type RefundResponse: type: object properties: id: type: string description: >- The ID of the `refund`. We recommend you store this value. If you need to reverse this refund, you will be required to reference this ID. example: ref_tr_123456789 object: type: string description: 'The type of object: `tax.refund`.' example: tax.refund refund_type: type: string description: This will be either `'full'` or `'partial'`. example: partial testmode: type: boolean description: >- `True` if using a production API key. `False` if using a test API key. example: false refund_processed_at: type: number description: >- Unix timestamp in **seconds** representing the date and time the refund was made. If not provided, the time the `refund` was created will be used. example: 1714787673 line_items: type: array items: $ref: '#/components/schemas/RefundTransactionLineItem' Error: type: object description: Standard error response format for API version 2026-01-01 properties: code: type: integer description: HTTP status code example: 400 type: type: string description: Machine-readable error type example: MISSING_FIELD message: type: string description: Human-readable error message example: Required field 'address_country' is missing required: - code - type - message TransactionNotFoundError: type: object properties: code: type: integer example: 404 type: type: string example: TRANSACTION_NOT_FOUND message: type: string example: Transaction not found RefundTransactionLineItem: allOf: - $ref: '#/components/schemas/TransactionLineItem' TransactionLineItem: type: object properties: line_item_id: type: string description: Numeral-generated ID for this line item. example: li_1783369661107e97b4af5-b61a-487d-aa31-ecee6e616f7f product: type: object description: Product information for this line item. properties: reference_product_name: type: string description: The name of the product. example: Red Shoes reference_line_item_id: type: string description: The ID of the line item from your system. example: line_123456789 reference_product_id: type: string description: The product ID in your system. example: p-1233543 product_tax_code: type: string description: The tax code applied to this product. example: GENERAL_MERCHANDISE tax_jurisdictions: type: array description: Array of tax jurisdictions that apply to this line item. items: type: object properties: tax_rate: type: number description: >- The tax rate for this jurisdiction, rounded to 6 decimal places. This is the statutory rate for the jurisdiction and may apply to only part of the line item amount (for example, Tennessee single article rules). Do not sum rates across jurisdictions to derive an effective rate; use `tax_amount / amount_excluding_tax` instead. example: 0.07 tax_due_decimal: type: number description: >- The unrounded tax due for this jurisdiction, in the currency's smallest unit. May be fractional (it is not rounded to an integer). `0` for flat-fee jurisdictions — see `fee_amount` instead. example: 724.9275 fee_amount: type: number description: Any fixed fee amount for this jurisdiction. example: 0 rate_type: type: string description: Descriptive rate classification for this jurisdiction. example: GENERAL STATE SALES TAX tax_authority_name: type: string description: Name of the tax authority. example: Tennessee tax_authority_type: type: string description: Type of tax authority (e.g., STATE, COUNTY, CITY, DISTRICT). example: '' tax_type: type: string description: 'Type of tax: SALES, USE, VAT, or GST.' example: SALES note: type: string description: >- Why this row came out the way it did. Empty string for normally calculated tax. Otherwise one of `no_collection_exempt_customer`, `no_collection_no_state_nexus`, `no_collection_no_vat_registration`, `no_collection_no_gst_registration`, `collection_manually_deactivated`, `automatic_tax_disabled`, `b2b_reverse_charge`, `shipping_follows_highest_taxed_item`, `canary_islands_zero_rate`. Records created before this version was released may return an empty note. example: '' quantity: type: number description: The quantity of this product. example: 2 tax_amount: type: number description: The tax amount for this line item. example: 14 amount_excluding_tax: type: number description: The line item amount excluding tax. example: 200 amount_including_tax: type: number description: The line item amount including tax. example: 214 securitySchemes: bearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.