> ## 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 (2024-09-01)

Add a refund to a previously recorded transaction.


## OpenAPI

````yaml POST /tax/refunds
openapi: 3.0.1
info:
  title: Numeral API
  description: API for sales tax calculations
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.numeralhq.com/
security:
  - bearerAuth: []
paths:
  /tax/refunds:
    post:
      description: Add a refund to a transaction
      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
          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:
            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:
            - reference_product_id
            - sales_amount_refunded
            - tax_amount_refunded
      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
      properties:
        error:
          type: object
          properties:
            error_code:
              type: string
            error_message:
              type: string
            error_meta:
              type: object
              properties:
                field:
                  type: string
                expected:
                  type: string
                received:
                  type: string
        request_id:
          type: string
          description: The ID of the request
          example: req_123456789
      example:
        error:
          error_code: missing_field
          error_message: Field is required
          error_meta:
            field: path.to.fieldname
            expected: string
            received: undefined
    TransactionNotFoundError:
      type: object
      properties:
        error:
          type: object
          properties:
            error_code:
              type: string
            error_message:
              type: string
            error_meta:
              type: object
              properties:
                field:
                  type: string
                expected:
                  type: string
                received:
                  type: string
      example:
        error:
          error_code: transaction_not_found
          error_message: 'Unable to find transaction with ID: {transaction_id}.'
    RefundTransactionLineItem:
      allOf:
        - $ref: '#/components/schemas/TransactionLineItem'
        - type: object
          properties:
            amount_including_tax:
              type: number
              format: int32
              example: -214
              description: >-
                The amount including tax, which should be a negative number for
                refunds.
            amount_excluding_tax:
              type: number
              format: int32
              example: -200
              description: >-
                The amount excluding tax, which should be a negative number for
                refunds.
            tax_amount:
              type: number
              format: int32
              example: -14
              description: The tax amount, which should be a negative number for refunds.
            quantity:
              type: number
              format: int32
              example: 2
              description: The quantity of this product being refunded.
    TransactionLineItem:
      type: object
      properties:
        product:
          type: object
          properties:
            reference_product_name:
              type: string
              example: Widget
            reference_line_item_id:
              type: string
              example: line_987654321
            reference_product_id:
              type: string
              example: p-1233543
            product_tax_code:
              type: string
              example: GENERAL_MERCHANDISE
        tax_jurisdictions:
          type: array
          items:
            type: object
            properties:
              tax_rate:
                description: The tax rate percentage applied to this transaction.
                type: number
                example: 0.07
              tax_due_decimal:
                type: number
                description: >-
                  Tax amount due for this jurisdiction in the currency's
                  smallest unit.
                example: 700
              rate_type:
                type: string
                description: Descriptive rate classification for this jurisdiction.
                example: GENERAL STATE SALES TAX
              fee_amount:
                description: >-
                  The flat fee that is added to this transaction. Like all
                  numeric values, this will be returned in cents and should be
                  added directly to the tax amount independent of other
                  percentages. For example, a $100 transaction taxed at 5% and
                  with a `fee_amount: 50` will lead to `($100 * 5% + 0.50) =
                  $5.50` in tax being charged 
                type: number
                example: 0
              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
            nullable: true
        quantity:
          type: number
          format: int32
          example: 2
        tax_amount:
          type: number
          format: int32
          example: 14
        amount_excluding_tax:
          type: number
          format: int32
          example: 200
        amount_including_tax:
          type: number
          format: int32
          example: 214
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````