Create a reversal Transaction

Partially or fully reverses a previously created Transaction.

Returns

A new Tax Transaction object representing the reversal.

Parameters

• mode (enum, required) 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_transaction (string, required) The ID of the Transaction to partially or fully reverse.

• reference (string, required) 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.

  The maximum length is 500 characters.

• flat_amount (integer, required 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_items (array of objects, required if mode=partial and neither shipping_cost nor flat_amount is provided) The line item amounts to reverse.

  • line_items.amount (integer, required) The amount to reverse, in the smallest currency unit in negative.

  • line_items.amount_tax (integer, required) The amount of tax to reverse, in the smallest currency unit in negative.

  • line_items.original_line_item (string, required) The id of the line item to reverse in the original transaction.

  • line_items.reference (string, required) A custom identifier for this line item in the reversal transaction, such as ‘L1-refund’.

    The maximum length is 500 characters.

  • line_items.metadata (object, optional) 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.quantity (integer, optional) The quantity reversed. Appears in tax exports, but does not affect the amount of tax reversed.

• metadata (object, optional) 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.

• shipping_cost (object, required if mode=partial and neither line_items nor flat_amount is provided) The shipping cost to reverse.

  • shipping_cost.amount (integer, required) The amount to reverse, in the smallest currency unit in negative.

  • shipping_cost.amount_tax (integer, required) The amount of tax to reverse, in the smallest currency unit in negative.

curl https://api.stripe.com/v1/tax/transactions/create_reversal \
  -u "<<YOUR_SECRET_KEY>>" \
  -d mode=partial \
  -d original_transaction={{TRANSACTION_ID}} \
  -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"
}