Refund Transaction
Use this request to create a refund.
More information about refunds is available in the Refunds topic. See Refunds.
Use the following URL and a POST method to refund transactions:
{service_url}/api/v3/seller/transactions/{key}/refunds
Where:
{service_url}is the URL of the sandbox or production system.{key}is the transaction key value. This specifies which transaction request you wish to refund. You also need to provide the line_key to identify which line to refund.
Details
| Type | Value |
|---|---|
| Endpoint | /api/v3/seller/transactions/{key}/refunds |
| Method | POST |
| API Reference Documentation | Refund transaction |
Where {key} is the transaction key value. This specifies which transaction request you wish to refund.
Fields
The full list of fields is contained in the Refund object and is provided in the Refund Object Fields topic.
The following table identifies some of the more prominent fields in this request:
| Field | Description |
|---|---|
line_key | Unique identifier for the line that is to be refunded. This field is mandatory. |
refund_total_amount | If you specify an amount here, the total amount including the tax is refunded. The service does not calculate any tax. |
refund_amount | If you specify an amount here, the service calculates the tax based on this amount and that tax is refunded. |
refund_reason | Description of the reason for the refund. |
Request example
The following example shows how to model the required information to refund 20 for the specified line key value:
{
"refunds": [
{
"line_key": "UwJ85ua2PYVf48bX",
"refund_amount": "100",
"refund_reason": "Refund line X"
},
{
"line_key": "bjjMpRAXWINsH9uZ",
"refund_amount": "20",
"refund_reason": "Refund line Y"
}
]
}
Response example
Here is an example response:
{
"transaction": {
"ship_to_address": {
"city": "Big city",
"country_code": "GB",
"postal_code": "00000",
"street_name": "Street name",
"address_detail": "2nd fl",
"building_number": "100a",
"tax_region": "GB"
},
"description": "Transaction description",
"amount": 200,
"required_fields": {
"tax_required_fields": [],
"storage_required_fields": []
},
"refunded_amount": 120.00,
"marketplace_code": "V4EDemo",
"tax_country_codes": "GB",
"key": "PSqiwAQAAPJFqz_jLCgzo6VMqW1xn5klQ9goY6w",
"tax_amount": 40,
"update_date": "2025-03-28",
"invoice_timestamp": "2025-03-01T12:00:00Z",
"confirm_timestamp": "2025-03-28T07:06:07Z",
"tax_liability_owner_codes": "",
"create_timestamp": "2025-03-28T07:01:36Z",
"transaction_lines": [
{
"description": "Product 1",
"reverse_charge": false,
"amount": 100.00,
"refunded_amount": 100.00,
"tax_engine_additional_parameters": [
{
"param": "FLEX.output.FlexCode25",
"value": "OSC-AK-TEST"
}
],
"tax_rule_applied": "physical-tax",
"unit_price": 100.00,
"taxes": [
{
"tax_type": "VAT",
"imposition_type": "VAT",
"tax_jurisdiction_code": "78295",
"tax_amount": 20.0,
"tax_calculation_rule_id": "v301086121",
"exempt_amount": 0.0,
"tax_base_amount": 100,
"tax_jurisdiction_type": "COUNTRY",
"rate": 20,
"taxable_amount": 100.0,
"tax_authority_name": "UNITED KINGDOM",
"rate_type": "Standard",
"tax_authority_id": "78295",
"tax_name": "VAT physical",
"non_taxable_amount": 0.0,
"imposition": "VAT",
"amount_fraction_taxable": 1
}
],
"tax_amount": 20.00,
"seller_tax_number": "GB123456789",
"tax_region": "GB",
"invoice_place": "Postal address line 1, Postal address line 2, Postal address line 3",
"invoice_number": "GB2025-1",
"tax_exempt": false,
"additional_currencies": {
"invoice": {
"amount": 82.59,
"currency_code": "GBP",
"fx_date": "2025-02-28T12:00:00Z",
"fx_rate": 0.825900231252,
"fx_source": "source_bankofengland",
"total_amount": 99.11,
"tax_amount": 16.52
}
},
"tax_country_code": "GB",
"line_key": "UwJ85ua2PYVf48bX",
"custom_id": "",
"refunded_tax_amount": 20.00,
"tax_address_kind": "ship_to_address",
"ship_from_address": {
"country_code": "GB",
"tax_region": "GB"
},
"tax_engine": "oseries",
"invoice_status": "R",
"kind": "b2c",
"product_tax_code": {
"class": "TPP/Goods"
},
"invoice_image_url": "(URL)",
"tax_number_service": "tax.service.gov.uk",
"refunded_total_amount": 120.00,
"product_class": "P",
"custom_rules_applied": [],
"line_num": 1,
"is_seller_permanent": true,
"quantity": 1.000000000000,
"invoice_capable": true,
"total_amount": 120.00,
"seller_code": "V4EDemo_Seller3",
"invoice_image_url_secret": "id4-IlvR2vU4GMn7",
"refunds": [
{
"refund_reason": "Refund line X",
"refund_amount": 100.00,
"refund_timestamp": "2025-03-28T07:16:37Z",
"refund_note_url": "(URL)",
"refund_tax_amount": 20.00,
"refund_note_number": 1,
"refund_note_subnumber": 1,
"refund_key": "OrTyp5dwX4pL0AtM1qmCJg",
"refund_total_amount": 120.00
}
],
"tax_entity_name": "United Kingdom",
"tax_supported": true
},
{
"description": "Shipping",
"reverse_charge": false,
"amount": 100.00,
"refunded_amount": 20.00,
"tax_engine_additional_parameters": [
{
"param": "FLEX.output.FlexCode25",
"value": "OSC-AK-TEST"
}
],
"tax_rule_applied": "postage-insurance-vat",
"unit_price": 100.00,
"taxes": [
{
"tax_type": "VAT",
"imposition_type": "VAT",
"tax_jurisdiction_code": "78295",
"tax_amount": 20.00,
"tax_calculation_rule_id": "v301086121",
"exempt_amount": 0.0,
"tax_base_amount": 100.00,
"tax_jurisdiction_type": "COUNTRY",
"rate": 20,
"taxable_amount": 100.0,
"tax_authority_name": "UNITED KINGDOM",
"rate_type": "Standard",
"tax_authority_id": "78295",
"tax_name": "VAT physical",
"non_taxable_amount": 0.0,
"imposition": "VAT",
"amount_fraction_taxable": 1
}
],
"tax_amount": 20.00,
"seller_tax_number": "GB123456789",
"tax_region": "GB",
"invoice_place": "Postal address line 1, Postal address line 2, Postal address line 3",
"invoice_number": "GB2025-1",
"additional_currencies": {
"invoice": {
"amount": 82.59,
"currency_code": "GBP",
"fx_date": "2025-02-28T12:00:00Z",
"fx_rate": 0.825900231252,
"fx_source": "source_bankofengland",
"total_amount": 99.11,
"tax_amount": 16.52
}
},
"tax_country_code": "GB",
"line_key": "bjjMpRAXWINsH9uZ",
"custom_id": "",
"refunded_tax_amount": 4.00,
"tax_address_kind": "ship_to_address",
"ship_from_address": {
"country_code": "GB",
"tax_region": "GB"
},
"tax_engine": "oseries",
"invoice_status": "R",
"kind": "b2c",
"invoice_image_url": "(URL)",
"tax_number_service": "tax.service.gov.uk",
"refunded_total_amount": 24.00,
"product_class": "S",
"custom_rules_applied": [
"postage-insurance-vat"
],
"line_num": 2,
"is_seller_permanent": true,
"quantity": 1.000000000000,
"invoice_capable": true,
"total_amount": 120.00,
"seller_code": "V4EDemo_Seller3",
"invoice_image_url_secret": "id4-IlvR2vU4GMn7",
"refunds": [
{
"refund_reason": "Refund line Y",
"refund_amount": 20.00,
"refund_timestamp": "2025-03-28T07:16:37Z",
"refund_note_url": "(URL)",
"refund_tax_amount": 4.00,
"refund_note_number": 1,
"refund_note_subnumber": 2,
"refund_key": "EJa36uLAd7SmXiOuL8OPPg",
"refund_total_amount": 24.00
}
],
"tax_entity_name": "United Kingdom",
"tax_supported": true
}
],
"discounts": [],
"refunded_tax_amount": 24.00,
"product_classes": "SP",
"billing_address": {
"city": "The big city",
"country_code": "GB",
"postal_code": "00000",
"street_name": "The street name",
"building_number": "100a",
"tax_region": "GB"
},
"status": "C",
"refunded_total_amount": 144.00,
"update_timestamp": "2025-03-28T07:01:36Z",
"buyer_name": "Test buyer",
"tax_timestamp": "2025-03-01T12:00:00Z",
"total_amount": 240,
"invoice_image_url_secret": "id4-IlvR2vU4GMn7",
"currency_code": "EUR"
}
}
Updated about 1 month ago