Tax Transactions
A Tax Transaction records the tax collected from or refunded to your customer.
Related guide: Calculate tax in your custom payment flow
The Tax Transaction object
Attributes
- idstring
Unique identifier for the transaction.
- objectstring
String representing the object’s type. Objects of the same type share the same value.
- currencystring
Three-letter ISO currency code, in lowercase. Must be a supported currency.
- customer_
detailsobject The customer’s details, such as address and tax IDs.
- line_
itemsnullable objectExpandable The tax collected or refunded, by line item.
- metadatanullable object
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.
- referencestring
A custom unique identifier, such as ‘myOrder_123’.
- typeenum
If
reversal
, this transaction reverses an earlier transaction.Possible enum valuesreversal
Represents a partial or full reversal of an earlier transaction.
transaction
Represents a customer sale or order.
More attributes
- createdtimestamp
- customernullable string
- livemodeboolean
- reversalnullable object
- ship_
from_ detailsnullable object - shipping_
costnullable object - tax_
datetimestamp
{
"id": "tax_1NaS0I2eZvKYlo2CRuMhUcmz",
"object": "tax.transaction",
"created": 1690932566,
"currency": "usd",
"customer": null,
"customer_details": {
"address": {
"city": "South San Francisco",
"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_ONCP443tgfS8I1",
"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_1NaS0I2eZvKYlo2CRuMhUcmz/line_items"
},
"livemode": false,
"metadata": null,
"reference": "myOrder_123",
"reversal": null,
"shipping_cost": {
"amount": 300,
"amount_tax": 0,
"tax_behavior": "exclusive",
"tax_code": "txcd_92010001"
},
"ship_from_details": {
"address": {
"postal_code": "75001",
"state": "TX",
"country": "US"
}
},
"tax_date": 1690932566,
"type": "transaction"
}
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. Iffull
, the original transaction is fully reversed.Possible enum valuesfull
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.
- 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
Returns
A new Tax Transaction
object representing the reversal.
{
"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,
"reference": "myOrder_123",
"reversal": null,
"shipping_cost": {
"amount": 300,
"amount_tax": 0,
"tax_behavior": "exclusive",
"tax_code": "txcd_92010001"
},
"tax_date": 1690938353,
"type": "transaction"
}
Create a transaction from a calculation
Creates a Tax Transaction
from a calculation.
Parameters
- calculationstringRequired
Tax Calculation ID to be used as input when creating the transaction.
- referencestringRequired
A custom order or sale identifier, such as ‘myOrder_123’. Must be unique across all transactions, including reversals.
- 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
.
Returns
A Tax Transaction
object.
{
"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,
"reference": "myOrder_123",
"reversal": null,
"shipping_cost": {
"amount": 300,
"amount_tax": 0,
"tax_behavior": "exclusive",
"tax_code": "txcd_92010001"
},
"tax_date": 1690938353,
"type": "transaction"
}
Retrieve a transaction's line items
Retrieves the line items of a committed standalone transaction as a collection.
Parameters
- ending_
beforestring A cursor for use in pagination.
ending_before
is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting withobj_bar
, your subsequent call can includeending_before=obj_bar
in order to fetch the previous page of the list. - limitinteger
A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
- starting_
afterstring A cursor for use in pagination.
starting_after
is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending withobj_foo
, your subsequent call can includestarting_after=obj_foo
in order to fetch the next page of the list.
Returns
A list of Line Item objects if the Tax Transaction is found. Otherwise returns a ‘not found’ error.
{
"id": "tax_1NaTVd2eZvKYlo2CoOX2Nf7P",
"object": "list",
"url": "/v1/tax/transactions/tax_1NaTVd2eZvKYlo2CoOX2Nf7P/line_items",
"has_more": false,
"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"
}
]
}