Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Privacy
Webhooks

Create a reversal transaction 

Tax
Tax Transactions
Create a reversal transaction

Partially or fully reverses a previously created Transaction.

Parameters

  • modeenumRequired

    If partial, the provided line item or shipping cost amounts are reversed. If full, the original transaction is fully reversed.

    Possible enum values
    full

    The original transaction is fully reversed.

    partial

    The provided line item amounts are reversed.

  • original_transactionstringRequired

    The ID of the Transaction to partially or fully reverse.

  • referencestringRequired

    A custom identifier for this reversal, such as myOrder_123-refund_1, which must be unique across all transactions. The reference helps identify this reversal transaction in exported tax reports.

  • flat_amountintegerRequired if mode=partial and line_items nor shipping_cost provided

    A flat amount to reverse across the entire transaction, in the smallest currency unit in negative. This value represents the total amount to refund from the transaction, including taxes.

  • line_itemsarray of objectsRequired if mode=partial and neither shipping_cost nor flat_amount is provided

    The line item amounts to reverse.

    • line_items.amountintegerRequired

      The amount to reverse, in the smallest currency unit in negative.

    • line_items.amount_taxintegerRequired

      The amount of tax to reverse, in the smallest currency unit in negative.

    • line_items.original_line_itemstringRequired

      The id of the line item to reverse in the original transaction.

    • line_items.referencestringRequired

      A custom identifier for this line item in the reversal transaction, such as ‘L1-refund’.

    • line_items.metadataobject

      Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

    • line_items.quantityinteger

      The quantity reversed. Appears in tax exports, but does not affect the amount of tax reversed.

  • metadataobject

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

More parameters

  • shipping_costobjectRequired if mode=partial and neither line_items nor flat_amount is provided

    The shipping cost to reverse.

Returns

A new Tax Transaction object representing the reversal.

POST /v1/tax/transactions/create_reversal
curl https://api.stripe.com/v1/tax/transactions/create_reversal \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d mode=partial \
  -d original_transaction=tax_1NaTVd2eZvKYlo2CoOX2Nf7P \
  -d reference=myOrder_123-refund_1 \
  -d "line_items[0][amount]"=-1499 \
  -d "line_items[0][amount_tax]"=-148 \
  -d "line_items[0][original_line_item]"=tax_li_ONDxh8JZw14sP8 \
  -d "line_items[0][reference]"="refund of Pepperoni Pizza" \
  -d "expand[0]"=line_items
Response
{
  "id": "tax_1NaTVd2eZvKYlo2CoOX2Nf7P",
  "object": "tax.transaction",
  "created": 1690938353,
  "currency": "usd",
  "customer": null,
  "customer_details": {
    "address": {
      "city": null,
      "country": "US",
      "line1": "354 Oyster Point Blvd",
      "line2": "",
      "postal_code": "94080",
      "state": "CA"
    },
    "address_source": "shipping",
    "ip_address": null,
    "tax_ids": [],
    "taxability_override": "none"
  },
  "line_items": {
    "object": "list",
    "data": [
      {
        "id": "tax_li_ONDxh8JZw14sP8",
        "object": "tax.transaction_line_item",
        "amount": 1499,
        "amount_tax": 148,
        "livemode": false,
        "metadata": null,
        "product": null,
        "quantity": 1,
        "reference": "Pepperoni Pizza",
        "reversal": null,
        "tax_behavior": "exclusive",
        "tax_code": "txcd_40060003",
        "type": "transaction"
      }
    ],
    "has_more": false,
    "url": "/v1/tax/transactions/tax_1NaTVd2eZvKYlo2CoOX2Nf7P/line_items"
  },
  "livemode": false,
  "metadata": null,
  "posted_at": 1690932566,
  "reference": "myOrder_123",
  "reversal": null,
  "shipping_cost": {
    "amount": 300,
    "amount_tax": 0,
    "tax_behavior": "exclusive",
    "tax_code": "txcd_92010001"
  },
  "tax_date": 1690938353,
  "type": "transaction"
}