Refund Transaction

post https://marketplace.taxamo.com/api/v3/marketplace/transactions/{key}/refunds

Use this request to refund a transaction.

See Refund Transactions.

Response

Response body

object

transaction

object

Transaction data

confirm_timestamp

date-time

Date and time of transaction confirmation.

deducted_tax_amount

number

How much tax has been deducted.

buyer_tax_number_validation_info

string

A code describing the outcome of the buyer tax number validation.

tax-number-country-blocked tax-number-service-temporarily-unavailable tax-number-validation-not-available tax-number-ignored tax-number-syntax-valid tax-number-syntax-invalid tax-number-syntax-considered-valid-but-not-verified tax-number-considered-valid-in-domestic-country tax-number-valid-according-to-external-service tax-number-invalid-according-to-external-service tax-number-validation-requested-additional-interactions

purchase_order_number

string

length ≤ 64

An identifier for the purchase, to be displayed on the invoice if it is required.

billing_address

object

Billing address. If the billing address is empty, its value will be filled with the shipping address.

payment_address

object

Payment address.

custom_data

string

length ≤ 256

Custom data related to transaction.

buyer_name

string

length ≤ 512

Buyer's name - first name and last name or company name. This value will be overwritten with buyer's name from VAT verification authority - but only if the VAT has been verified properly

create_timestamp

date-time

Date and time of transaction creation.

currency_code

string

required

length between 3 and 3

ISO currency code for transaction - e.g. EUR.

discounts

array of objects

List of discounts.

These are to be distributed over all transaction lines linked tothe corresponding sellers.

discounts

object

discount_code

string

required

Discount code. Used to track the relationship of transaction-level discountsand discounts to individual transaction lines.

discount_description

string

length ≤ 256

A short description of the discount.

discount_amount

number

A tax-exclusive discount amount. It'll be applied to the (base) amount.

discount_total_amount

number

A tax-inclusive discount amount. It'll be applied to the total_amount
as long as there's tax calculated. Otherwise, corresponding discount_amount
(calculated when determining the liability) will be applied to the
(base) amount.

seller_code

string

required

The seller code of the seller that issued this discount.

buyer_tax_number_normalized

string

length ≤ 256

Buyer's tax number - normalized form.

sellers

array of objects

List of sellers.

Seller information can be provided in two ways:

using the Sellers API
in each transaction request (here)

When using a Sellers API, seller needs to be set up prior to sending a transaction request. Such seller is configured once and its configuration is then reused each time a new transaction is processed.

Sellers provided inline here on the other hand are one-off sellers used to process a single transaction only. They are not going to be available through the Sellers API. A full seller configuration needs to be provided for each virtual seller in each transaction request.

sellers

object

country_subdivision_code

string

length ≤ 6

ISO based code of the principal subdivision - region/province/state...

country

string

length between 2 and 2

Two letter ISO country code.

referrer

string

Source of referral.

settings

object

Seller settings.

postal_code

string

length ≤ 256

Postal code.

business_name

string

Name of the seller's business. Will appear on invoices.

string

Email of the seller's legal representative.

postal_address_line3

string

Third address line of the seller. Will appear on invoices whenever the seller is liable.

billing_customer_id

string

Billing customer id.

postal_address_line2

string

Second address line of the seller. Will appear on invoices whenever the seller is liable.

last_name

string

length ≥ 1

Last name of the seller's legal representative.

first_name

string

length ≥ 1

First name of the seller's legal representative.

seller_code

string

length between 1 and 512

Code used by the Marketplace to identify to which seller any given transaction line belongs to. Whenever required, it should be passed in the request body in the 'seller_code' field.

postal_address_line1

string

First address line of the seller. Will appear on invoices whenever the seller is liable.

middle_name

string

length ≥ 1

Middle name of the seller's legal representative.

key

string

length ≤ 64

Transaction key, assigned by Taxamo.

self_declared_address

object

Self-declared tax location address.

buyer_tax_number_format_valid

boolean

If the buyer tax number has been checked for syntax and is correct. It does not determine if the transaction should be tax deducted.

control_flags

array of objects

length ≤ 32

Control flags, stored as key-value string pairs. Possible flags (keys): "b2b-number-service-timeoutms", "b2b-number-service-expiry-days", "b2b-number-service-on-error" (values: "syntax-check", "block", "proceed"). Region code can be appended to all of the keys, e.g. "b2b-number-service-timeoutms-EU".

control_flags

object

key

string

length ≤ 64

Flag's key.

value

string

length ≤ 256

Flag's value.

buyer_tax_number_valid

boolean

If the buyer tax number has been provided and was validated successfully. Always true for domestic transactions (billing country same as merchant's country), tax number doesn't get validated in that case.

update_timestamp

date-time

Date and time of the last transaction update.

note

string

length ≤ 256

Additional note related to transaction state.

location_detection

object

Results of location detection based on provided evidence.

refunded_amount

number

Refunded amount (excluding tax).

transaction_lines

array of objects

required

length between 1 and 256

Transaction lines.

transaction_lines*

object

carrier_id

string

length ≤ 32

Carrier id.

import_address

object

The EU country where the goods have been put into free circulation (for customs purposes). In case the goods have been put into transit in an EU country, this country is NOT the import country. Import country can be the same or different than the ship_to country.

discounted_tax_amount

number

The sum of discount tax amounts of all discounts applied to this line.

back_to_back_invoice_country_code

string

2-letter ISO country code for the back to back transaction.

seller_kind

string

length ≤ 1

Seller kind. B - Business (default), C - Consumer.

taxes

array of objects

length ≤ 32

List of taxes, either calculate by the tax engine, or provided

taxes

object

tax_jurisdiction_code

string

length ≤ 128

Tax jurisdiction code.

tax_type

string

O-Series determined tax type, based on situs, transaction type, and party role type (perspective).

tax_calculation_rule_id

string

Tax rule id used by the tax engine

tax_jurisdiction_type

string

length ≤ 128

Tax jurisdiction type.

amount_fraction_taxable

number

What fraction of the base amount is taxable. Defaults to 1 (meaning 100%).

tax_authority_name

string

length ≤ 128

Tax authority name.

tax_external_code

string

Optional external tax code, if provided by the tax engine

tax_base_amount

number

What base amount has been used for the tax calculation.
This value is not rounded, except in presence of discounts, as discounts are applied to rounded amounts.

rate_type

string

Describes a type of the tax rate.

rate

number

Tax rate, calculated by the engine or provided by the client.

imposition

string

The imposition to which the relevant tax rule belongs. This is assigned either by Vertex or by the user when setting up a user-defined imposition on the O-Series user interface.

product_class

string

length ≤ 1

Product class that the tax applies to.

tax_name

string

length ≤ 128

deprecated

DEPRECATED: Please use imposition, imposition_type and tax_type instead.

Tax name, calculated by the engine.

imposition_type

string

The type description assigned to the imposition. When multiple impositions are imposed within a jurisdiction, each must have a different type. This is assigned either by Vertex or by the user when setting up a user-defined imposition on the O-Series user interface.

tax_authority_id

string

length ≤ 128

Tax authority id

tax_amount

number

Tax amount for the tax item. Does not have to sum to line's tax amount because of rounding.

tax_country_subdivision_code

string

length ≤ 128

Country subdivision code - for example state code for US.

discounts

array of objects

Discounts to be applied to this transaction line.
These will be subtracted from the relevant amount fields by the engine.

discounts

object

discount_code

string

required

Discount code. Used to track the relationship of transaction-level discountsand discounts to individual transaction lines.

discount_description

string

length ≤ 256

A short description of the discount.

discount_amount

number

A tax-exclusive discount amount. It'll be applied to the (base) amount.

discount_total_amount

number

tax_address_kind

string

length ≤ 256

Which address has been used for tax calculation on this line - billing-address, payment-address, ship-to-address, or self-declared-address. When null, synthetic addres has been constructed based on determined details.

invoice_image_url

string

length ≤ 512

Invoice image URL - provided by the service.

tax_number_service

string

length ≤ 64

Tax number service identifier - if available for a given region and the region is enabled.

seller_tax_number

string

Seller's tax number in the tax country - used for physical goods and assigned from merchant configuration.

product_cn_code

string

length ≤ 16

Combined Nomenclature code. Used in EU. Example 8504 or 8504 31 80 15

number

Generated id.

product_reference_number

string

length ≤ 32

Tax reference number. Used in US.

consignment_id

string

length ≤ 64

Consignment identifier. This allows to group the sale per-package.

back_to_back_transaction_key

string

Back to back transaction key. The back to back transaction is not created immediately, so the key might not yield a back to back transaction exactly after the sale was confirmed.

parcel_reference

string

length ≤ 64

Parcel reference.

tax_supported

boolean

Is tax supported on this line.

invoice_status

string

length ≤ 1

'R' - required, 'O' - optional, 'F' - forbidden

refunded_amount

number

Refunded amount without tax, calculated by the engine.

unit_price

number

Unit price.

platform_liability_assumed_amount

number

The amount calculated with assumed liability on the marketplace.Used for threshold determination - when only total amount is present, the amount for comparison with the thresholds needs to be calculated. Because it cannot be done without knowing if taxes are to be applied or not, it's done with the assumption that marketplace is liable.

unit_of_measure

string

The unit of measure for the line item to be used in surcharges based on quantity and not price.

Possible values:
BO - Bottle
BX - Box
CR - Crate
CS - Case
CT - Carton
DAY - Day
EA - Each
FO - Fluid Ounce
GLL - Gallon (US)
HUR - Hour
KG - Kilogram
LTR - Liter
MIN - Minutes
PF - Pallet
QT - Quart (US)
STN - Ton (US)
SYD - Square Yard
TRK - Trunk Line

BO BX CR CS CT DAY EA FO GLL HUR KG LTR MIN PF QT STN SYD TRK

invoice_capable

boolean

True if an invoice can be generated for this transaction. False otherwise. Depends of invoice-status and optional settings

quantity

number

Quantity Defaults to 1.

is_seller_permanent

boolean

Whether seller associated with this line permanently exists in the database.True for sellers configured using the Sellers API.
False for sellers provided in the transaction request.

custom_fields

array of objects

length ≤ 256

Custom fields, stored as key-value pairs. This property is not processed.

custom_fields

object

key

string

length ≤ 64

Field's key.

value

string

length ≤ 256

Field's value.

tax_region

string

Tax region code - e.g. EU, US, NO, JP...

special_tax_scheme

string

Denotes if one of the special tax schemes applies for given transaction.

OSS IOSS VOEC OVR LVG

line_key

string

length ≤ 64

Generated transaction line unique identifier (key). Thanks to this identifier, it is possible to refer directly to the line in the transaction (e.g. in refund API services)

refunds

array of objects

List of refunds.

refunds

object

refund_tax_amount

number

Refund tax amount.

refund_total_amount

number

Refunded total amount. Tax will be calculate back from this value. This takes precedence when also the amount is provided.

refund_note_url

string

Refund note URL.

refund_amount

number

Refund amount. Tax will be calculate based on this value.

refund_note_number

integer

Sequential refund note number.

refund_key

string

Refund identifier.

refund_note_subnumber

integer

Sequential refund note subnumber.

line_key

string

length ≤ 32

Generated refund line key.

refund_timestamp

date-time

The moment the invoice should be issued, in yyyy-MM-dd'T'HH:mm:ssZZZ format.
Defaults to the present moment in merchant's timezone.
This field is used on the invoice document and to apply fx conversions.

refund_unique_reference

string

length ≤ 64

Refund unique reference per line.

refund_fees

array of objects

List of fees calculated for this refund.

refund_fees

object

amount

object

Fee amount, with FX conversion information, if applied.

seller_code

string

The seller code for which the fee applies.

type

string

Type of the fee:

amount-fee - fee calculated based on the amounts
tax-fee - value denoting a tax amount that needs to be treated as a fee,
(tax being due on the deemed seller),
commission-fee - commission fee amount (decreases back to back transaction amount),
revshare-partner-fee - split of commission-fee that goes to the partner (does not decrease back to back transaction amount),
regular-tax-fee - same as tax-fee, but not used in billing (decreases back to back transaction amount),
additional-tax-DST - additional DST tax (decreases back to back transaction amount).

amount-fee tax-fee commission-fee revshare-partner-fee regular-tax-fee additional-tax-DST

calculation_method

string

Method applied during calculation of the fee.

min max percent fixed

rule

string

The rule which resulted in adding given fee.

fee_key

string

The key that uniquely identifies the fee across the transaction.

correlated_fee_key

string

The fee key (in this transaction) to which the current fee applies. This is used for VAT refunds.

settlement_method

string

The method used to settle fees.

treasury

refund_amount_trimmed

boolean

Flag indicating if refund was trimmed. Trimming takes place when refund amount is
too large in comparison to the transaction line amount (the initial line amount
reduced by values of all previous refunds)

refund_reason

string

required

length ≤ 256

Refund reason.

invoice_number

string

length ≤ 256

Invoice number.

discounted_total_amount

number

The sum of discount total amounts of all discounts applied to this line.

tax_engine

string

Tax engine used for the calculation.

tax_engine_additional_parameters

array of objects

Additional parameters passed in/returned from the tax engine.

tax_engine_additional_parameters

object

param

string

length ≤ 64

Parameter name

value

string

length ≤ 256

Value

product_class

string

Product class:

'P' - physical goods 'D' - digital goods/services 'S' - other services.

P D S

kind

string

What kind of sale is it - for example b2b or b2c.

fees

array of objects

List of fees calculated for this line.

fees

object

amount

object

Fee amount, with FX conversion information, if applied.

seller_code

string

The seller code for which the fee applies.

type

string

Type of the fee:

amount-fee - fee calculated based on the amounts
tax-fee - value denoting a tax amount that needs to be treated as a fee,
(tax being due on the deemed seller),
commission-fee - commission fee amount (decreases back to back transaction amount),
revshare-partner-fee - split of commission-fee that goes to the partner (does not decrease back to back transaction amount),
regular-tax-fee - same as tax-fee, but not used in billing (decreases back to back transaction amount),
additional-tax-DST - additional DST tax (decreases back to back transaction amount).

amount-fee tax-fee commission-fee revshare-partner-fee regular-tax-fee additional-tax-DST

calculation_method

string

Method applied during calculation of the fee.

min max percent fixed

rule

string

The rule which resulted in adding given fee.

fee_key

string

The key that uniquely identifies the fee across the transaction.

correlated_fee_key

string

The fee key (in this transaction) to which the current fee applies. This is used for VAT refunds.

settlement_method

string

The method used to settle fees.

treasury

amount

number

Amount of transaction line without tax. Required if total amount or both unit price and quantity are not provided.

seller_code

string

required

length between 1 and 512

Seller code. This information determines which seller provides the goods for this line.
seller_code may point to:

the seller associated with the marketplace and stored in SellerDB
the so called virtual seller - a seller defined in request under sellers entry
the code of the marketplace itself - in this case it denotes the marketplace being a seller on its own platform.

invoice_image_url_secret

string

length ≤ 16

Invoice image URL secret - provided by the service.

custom_id

string

required

length ≤ 64

Custom id, provided by ecommerce software.

line_num

number

Line index.

tax_amount

number

Tax amount for the line, calculated by the engine.

tax_entity_additional_id

string

Tax entity additional id.

back_to_back_external_unique_id

string

Back to back transaction external unique id. The back to back transaction is not created immediately.

additional_currencies

object

Additional currency information - can be used to receive additional information about invoice in another currency.

tax_exempt

boolean

Has this line tax been exempt from tax?

invoice_place

string

length ≤ 256

Invoice place of issue.

total_amount

number

Total amount. Required if amount or both unit price and quantity are not provided.

tax_entity_name

string

To which entity is the tax due.

tax_rule_applied

string

Denotes which tax rule has been applied to this line.

refunded_tax_amount

number

Refunded tax amount, calculated by the engine.

ship_from_address

object

Ship from address.

country_name

string

Human-readable name of the country.

description

string

length ≤ 256

Line contents description.

tax_liability_owner_code

string

length ≤ 256

Taxation liability owner code - it can reference a seller, a marketplace or a buyer.

tax_liability_rule

string

What rule has been applied to assign the liability.

discounted_amount

number

The sum of discount amounts of all discounts applied to this line.

reverse_charge

boolean

Was a reverse charge mechanism applied to this line?

tax_country_code

string

length between 2 and 2

Two-letter ISO country code, e.g. FR.

refunded_total_amount

number

Refunded total amount, calculated by the engine.

tax_country_subdivision_code

string

Country subdivision ISO code - for example state code for US.

buyer_tax_number

string

length ≤ 256

Buyer's tax number - EU VAT number for example. If using EU VAT number, it is possible to provide country code in it (e.g. IE1234567X) or simply use billing_country_code field for that. In the first case, if billing_country_code value was provided, it will be overwritten with country code value extracted from VAT number - but only if the VAT has been verified properly.

additional_interactions

array of objects

length ≤ 1

List of additional interactions

additional_interactions

object

interaction_key

string

required

length ≤ 64

Key regarding the interaction, e.g. india-b2b-captcha

interaction_kind

string

length ≤ 64

Kind of the interaction, e.g. b2b-captcha

requested

boolean

Should Taxamo trigger this interaction (e.g. request the captcha image) if possible. Please note this will increase the request time as we have to reach out to external resources.

captcha

object

Captcha-specific information

status

string

Transaction status: 'N' - new, 'C' - confirmed.

custom_fields

array of objects

length ≤ 256

Custom fields, stored as key-value pairs. This property is not processed and used mostly with Taxamo-built helpers.

custom_fields

object

key

string

length ≤ 64

Field's key.

value

string

length ≤ 256

Field's value.

total_billable_amount

number

Total amount the buyer should be charged.

It's equal to the total_amount minus the value of any vouchers.

supply_timestamp

date-time

Date and time od supply. Format is: yyyy-MM-dd'T'HH:mm:ssZZZ.

payment_due_timestamp

date-time

Date and time of payment due. Format is: yyyy-MM-dd'T'HH:mm:ssZZZ.

tax_country_codes

string

length ≤ 256

Comma separated list of tax country codes.

tax_engine

string

Tax engine used for the calculation.

product_classes

string

length ≤ 16

Product classes present in this transaction.

external_unique_id

string

length between 20 and 64

External unique id. It is advised to use secure and random identifiers in this field.

vouchers

array of objects

length ≤ 1

List of vouchers applied to the transaction.

Note that currently at most 1 voucher can be used.

vouchers

object

voucher_type

string

required

Type of the voucher.

cash-equivalent

voucher_code

string

length ≤ 256

Voucher code. If present, it will appear on the invoice.

voucher_description

string

length ≤ 256

A custom voucher description. It will not appear on the invoice.

voucher_amount

number

required

Voucher amount.

Voucher amount can be greater than the transaction total amount. In such case the total_billable_amount will be 0 and the voucher-applied-amount and voucher-remaining-amount will indicate what portion of the voucher has been applied.

voucher_applied_amount

number

A voucher amount that has been applied.

Voucher might've not been fully applied if its amount was higher than the total transaction amount.

voucher_remaining_amount

number

A voucher amount that has not been applied.

Voucher might've not been fully applied if its amount was higher than the total transaction amount.

tax_liability_owner_codes

string

length ≤ 256

Comma separated list of liability owner codes.

customer_id

string

length ≤ 256

Free-form field for storing customer id.

source

string

length ≤ 256

Transaction source software - e.g. plugin

fees

array of objects

List of fees calculated for the transaction.

fees

object

amount

object

Fee amount, with FX conversion information, if applied.

seller_code

string

The seller code for which the fee applies.

type

string

Type of the fee:

amount-fee - fee calculated based on the amounts
tax-fee - value denoting a tax amount that needs to be treated as a fee,
(tax being due on the deemed seller),
commission-fee - commission fee amount (decreases back to back transaction amount),
revshare-partner-fee - split of commission-fee that goes to the partner (does not decrease back to back transaction amount),
regular-tax-fee - same as tax-fee, but not used in billing (decreases back to back transaction amount),
additional-tax-DST - additional DST tax (decreases back to back transaction amount).

amount-fee tax-fee commission-fee revshare-partner-fee regular-tax-fee additional-tax-DST

calculation_method

string

Method applied during calculation of the fee.

min max percent fixed

rule

string

The rule which resulted in adding given fee.

fee_key

string

The key that uniquely identifies the fee across the transaction.

correlated_fee_key

string

The fee key (in this transaction) to which the current fee applies. This is used for VAT refunds.

settlement_method

string

The method used to settle fees.

treasury

amount

number

Amount of transaction without tax.

buyer_tax_numbers

array of objects

length ≤ 2

List of buyer's tax numbers. Can be used only if buyer_tax_number is not provided.

buyer_tax_numbers

object

buyer_tax_number_validation_info

string

A code describing the outcome of the buyer tax number validation.

buyer_tax_number_normalized

string

length ≤ 256

Buyer's tax number - normalized form.

buyer_tax_number_format_valid

boolean

If the buyer tax number has been checked for syntax and is correct. It does not determine if the transaction should be tax deducted.

tax_number_service

string

length ≤ 64

Tax number service identifier - if available for a given region and the region is enabled.

buyer_tax_number_valid

boolean

buyer_tax_number

string

length ≤ 256

warnings

array of objects

Warnings related to contacting B2B validation service.

warnings

object

type

string

Type of error.

message

string

Error details

buyer_tax_number_service_cache_timestamp

date-time

A timestamp of when was the last time a buyer tax number validation result has been updated using the external service (like VIES in EU).

See also the buyer_tax_number_service_cache_used.

buyer_tax_number_service_cache_used

boolean

When a tax number is validated using the external service (like VIES in EU), the validation result will be cached and reused the next time the same tax number is submitted.

This results in a faster and more robust processing, because the external service typically responds much slower than the internal cache.

The maximum age of the cache response can be configured with the following Marketplace settings:

tax_number_validation.cache_expiry_timeout_days
regions.EU.tax_number_validation.cache_expiry_timeout_days
regions.EU.countries.IE.tax_number_validation.cache_expiry_timeout_days

comments

string

length ≤ 512

Additional information about the transaction - for example if the evidence has been amended.

buyer_email

string

length ≤ 256

Buyer's declared email address. Used when address needs to be captured for further processing, such as invoice delivery.

tax_timestamp

date-time

A moment the tax liability has occurred.

Tax point date is used to find out the correct tax and currency exchange rates. It appears on the invoice too.

If not provided, tax_timestamp defaults to the value of invoice_timestamp.

Format is: yyyy-MM-dd'T'HH:mm:ssZZZ.

invoice_image_url_secret

string

length ≤ 16

Invoice image URL secret - provided by Taxamo.

payment_timestamp

date-time

Date and time of payment. Format is: yyyy-MM-dd'T'HH:mm:ssZZZ.

custom_id

string

length ≤ 256

Custom identifier provided upon transaction creation.

tax_amount

number

Tax amount of transaction.

warnings

array of objects

Warnings for the transaction process, usually related to contacting B2B validation service.

warnings

object

type

string

Type of error.

message

string

Error details

ship_to_address

object

Ship to address.

buyer_tax_number_service_cache_timestamp

date-time

A timestamp of when was the last time a buyer tax number validation result has been updated using the external service (like VIES in EU).

See also the buyer_tax_number_service_cache_used.

buyer_tax_number_service_cache_used

boolean

When a tax number is validated using the external service (like VIES in EU), the validation result will be cached and reused the next time the same tax number is submitted.

This results in a faster and more robust processing, because the external service typically responds much slower than the internal cache.

The maximum age of the cache response can be configured with the following Marketplace settings:

tax_number_validation.cache_expiry_timeout_days
regions.EU.tax_number_validation.cache_expiry_timeout_days
regions.EU.countries.IE.tax_number_validation.cache_expiry_timeout_days

total_amount

number

Total amount of transaction.

refunded_tax_amount

number

Refunded tax amount.

description

string

length ≤ 512

Transaction description.

marketplace_code

string

length ≤ 32

Identifier of the marketplace for this transaction.

parent_transaction_key

string

Parent transaction key (for example sale for self-billed back to back).

required_fields

object

Information on the required fields.

invoice_timestamp

date-time

The moment the invoice has been issued.

This field is used on the invoice document. It also serves as a default value for tax-timestamp.

Defaults to the value of tax_timestamp or the present moment in merchant's timezone.

Format is: yyyy-MM-dd'T'HH:mm:ssZZZ.

refunded_total_amount

number

Total amount refunded (including tax).

location_evidence

object

Digital goods tax country of residence evidence.

errors

array of objects

Errors (if any)

errors

object

type

string

Type of error.

message

string

Error details

Language

Credentials

Header


xxxxxxxxxx
1
curl --request POST \
2
     --url https://marketplace.taxamo.com/api/v3/marketplace/transactions/key/refunds \
3
     --header 'accept: application/json' \
4
     --header 'content-type: application/json'

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200Success