Refund an invoice

POST https://api.tamio.com/v2/invoices/refund/{uuid}

Processes a full or partial refund for a paid invoice. Supports refunding specific products, custom amounts, and includes reason tracking for accounting and analytics.

Path Parameters

uuid string*

UUID of the paid invoice to refund

Body Parameters

reason string*

Reason for the refund

requested_by_customerduplicatefraudulentother

refund_gateway_charge boolean*

Whether to refund the payment gateway charge along with the invoice amount

amount integer

Custom refund amount in smallest currency unit (full amount if omitted)

instalment_invoice_id string

Instalment invoice ID for partial instalment refunds

products array of object

Specific products to refund (all products if omitted)

JSON

{ "products": [ { "id": "00000000-0000-0000-0000-000000000000", "invoice_item_id": "00000000-0000-0000-0000-000000000000", "variation_id": "00000000-0000-0000-0000-000000000000" } ] }

id string

Product UUID from catalog

invoice_item_id string

Specific invoice line item UUID

variation_id string

Product variation UUID

Responses

200 Invoice refunded successfully

Invoice refunded successfully

status integer

invoice Invoice

400 Validation or business-logic error.

Validation or business-logic error.

Code	Description
`1002`	Invoice not found or belongs to another account
`10117`	Invoice is not in a valid state for this operation
`10261`	Mollie order payment refund is not allowed
`10340`	Invoice has already been refunded
`10341`	Refund amount is invalid or exceeds the original charge

status integer

error string

Human-readable error message

error_code integer

Machine-readable error code

401 Missing or invalid API key

Cancel an invoice

Update affiliate commission

/invoices/refund/{uuid}

1 const response = await fetch("https://api.tamio.com/v2/invoices/refund/{uuid}", {
2   method: "POST",
3   headers: {
4     "Authorization": "Bearer YOUR_API_KEY",
5     "Content-Type": "application/json"
6   },
7   body: JSON.stringify({
8     "reason": "requested_by_customer",
9     "refund_gateway_charge": false,
10     "amount": 0,
11     "instalment_invoice_id": "string",
12     "products": [
13       {
14         "id": "00000000-0000-0000-0000-000000000000",
15         "invoice_item_id": "00000000-0000-0000-0000-000000000000",
16         "variation_id": "00000000-0000-0000-0000-000000000000"
17       }
18     ]
19   })
20 });
21 const data = await response.json();

1 require "uri"
2 require "net/http"
3 require "json"
4 
5 url = URI("https://api.tamio.com/v2/invoices/refund/{uuid}")
6 
7 https = Net::HTTP.new(url.host, url.port)
8 https.use_ssl = true
9 
10 request = Net::HTTP::Post.new(url)
11 request["Accept"] = "application/json"
12 request["Authorization"] = "Bearer YOUR_API_KEY"
13 request["Content-Type"] = "application/json"
14 request.body = {
15   reason: "requested_by_customer",
16   refund_gateway_charge: false,
17   amount: 0,
18   instalment_invoice_id: "string",
19   products: [
20     {
21       id: "00000000-0000-0000-0000-000000000000",
22       invoice_item_id: "00000000-0000-0000-0000-000000000000",
23       variation_id: "00000000-0000-0000-0000-000000000000"
24     }
25   ]
26 }.to_json
27 
28 response = https.request(request)
29 puts response.read_body

Responses

{
  "status": 200,
  "invoice": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "object": "invoice",
    "currency": "EUR",
    "paid": true,
    "processing_payment": false,
    "prefix": "INV-",
    "number": 1001,
    "total": 5000,
    "payment": "stripe_creditcard",
    "date": 1700000000,
    "status": "paid",
    "subscription": "660e8400-e29b-41d4-a716-446655440001",
    "locale": "en",
    "payment_retried": false,
    "payment_charge_date": 1700100000,
    "3d_secure_failure": false,
    "authorization_expiry": 1700604800,
    "affiliate_program": "770e8400-e29b-41d4-a716-446655440002",
    "affiliate": "880e8400-e29b-41d4-a716-446655440003",
    "late_failure": false,
    "has_subscriptions": false,
    "is_instalment": false,
    "fortnox_submitted": false,
    "start_date": 1700000000,
    "end_date": 1702592000,
    "has_notes": false,
    "customer_information": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "John Doe",
      "country": "NL",
      "email": "[email protected]",
      "stripe_customer_id": "cus_OxR5p8k3nM2qYz",
      "client_id": null,
      "billing_information": {
        "name": "John Doe",
        "country": "NL",
        "email": "[email protected]",
        "phone": "+31612345678",
        "address": "Keizersgracht 123",
        "postcode": "1015 CJ",
        "city": "Amsterdam",
        "ip": "203.0.113.42",
        "state": "Noord-Holland",
        "vat": "NL123456789B01",
        "company": "Acme B.V."
      },
      "shipping_information": {
        "address": "Prinsengracht 456",
        "postcode": "1016 HN",
        "country": "NL",
        "city": "Amsterdam",
        "state": "Noord-Holland",
        "name": "John Doe",
        "email": "[email protected]",
        "phone": "+31612345678",
        "company": "Acme B.V."
      }
    },
    "products": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Premium Widget",
        "quantity": 2,
        "type": "physical_product",
        "classification": "Tangible Goods",
        "currency": "EUR",
        "discount_allowed": true,
        "is_moss_product": false,
        "is_oss_product": false,
        "billing_cycle": null,
        "interval": null,
        "is_metered": false,
        "stripe_price_id": "price_1O2p3Q4r5S6t7U8v",
        "stripe_product_id": "prod_A1b2C3d4E5f6G7",
        "stripe_metered_id": null,
        "invoice_item_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "variation_id": "660e8400-e29b-41d4-a716-446655440001",
        "variation_label": "Large / Blue",
        "is_variant": false,
        "delivered": false,
        "cancelled": false,
        "sku": "WDG-PRM-001",
        "has_shipping": true,
        "weight": 2.5,
        "height": 10,
        "width": 20,
        "length": 30,
        "detailed_description": "string",
        "nshift_parcel_amount": 1,
        "nshift_quick_id": "string",
        "parcels": [],
        "trial_period": 14,
        "charge_shipping_during_trial": false,
        "taxes": {
          "inclusive": true,
          "eu_tax": true,
          "tax_rates": [],
          "shipping_tax_rates": []
        },
        "totals": {
          "unit_price": 2999,
          "item_total": 5998,
          "total": 7258,
          "discount": 0,
          "tax": 1260,
          "subtotal": 5998,
          "item_total_with_tax": 7258,
          "shipping": 500,
          "shipping_subtotal": 500,
          "shipping_discount": 0,
          "shipping_tax": 105,
          "shipping_total": 605,
          "exchange_rate": null,
          "price_conversion": false,
          "moss_taxable_amount": 0,
          "moss_tax_total": 0,
          "oss_taxable_amount": 0,
          "oss_tax_total": 0,
          "full_price": 0,
          "amount_paid": 7258,
          "amount_refunded": 0,
          "amount_cancelled": 0,
          "recurring_shipping_discount": 0,
          "recurring_shipping_cost": 500
        },
        "discounts": [
          {
            "id": "880e8400-e29b-41d4-a716-446655440003",
            "code": "SUMMER20",
            "discount": 600,
            "applies_to": []
          }
        ],
        "reservations": []
      }
    ],
    "shipping": {
      "has_shipping": true,
      "method": "Standard Delivery",
      "tracking": "3SXYZ1234567890",
      "shipped": false,
      "nshift_shipment_prepared": false,
      "nshift_shipment_stored": false,
      "is_nshift_shipment": false
    },
    "totals": {
      "total": 5000,
      "gateway_fees": 145,
      "affiliate_revenue": 0,
      "refunded_total": 0,
      "amount_paid": 5000,
      "amount_cancelled": 0,
      "subtotal": 4132,
      "discount": 0,
      "item_count": 2,
      "tax": 868,
      "shipping": 0,
      "shipping_total": 0,
      "shipping_discount": 0,
      "shipping_tax": 0,
      "moss_tax_total": 0,
      "moss_taxable_amount": 0,
      "item_total": 4132,
      "item_total_with_tax": 5000,
      "oss_taxable_amount": 0,
      "oss_tax_total": 0,
      "interest": 0,
      "amount_due": 0
    },
    "taxes": {
      "tax_rates": [
        {
          "id": "770e8400-e29b-41d4-a716-446655440002",
          "rate_percent": 21,
          "rate_amount": null,
          "label": "VAT 21%",
          "tax": 868,
          "moss": false,
          "jurisdiction": "de",
          "inclusive": true,
          "vat_tax": true,
          "applies_to": [
            "Premium Widget"
          ]
        }
      ],
      "shipping_tax_rates": [],
      "has_vat": true
    },
    "discounts": [
      {
        "id": "880e8400-e29b-41d4-a716-446655440003",
        "code": "SUMMER20",
        "discount": 600
      }
    ],
    "licenses": [
      {
        "key": "XXXX-YYYY-ZZZZ-1111",
        "product_id": "00000000-0000-0000-0000-000000000000"
      }
    ],
    "refunds": [
      {
        "amount": 5000,
        "date": "2024-01-15T14:30:00+00:00",
        "reason": "requested_by_customer"
      }
    ],
    "consents": {},
    "appendix": null,
    "transaction_id": "adf5c33d-3799-4d84-bf62-3b724c073ccf"
  }
}

1	const response = await fetch("https://api.tamio.com/v2/invoices/refund/{uuid}", {
2	method: "POST",
3	headers: {
4	"Authorization": "Bearer YOUR_API_KEY",
5	"Content-Type": "application/json"
6	},
7	body: JSON.stringify({
8	"reason": "requested_by_customer",
9	"refund_gateway_charge": false,
10	"amount": 0,
11	"instalment_invoice_id": "string",
12	"products": [
13	{
14	"id": "00000000-0000-0000-0000-000000000000",
15	"invoice_item_id": "00000000-0000-0000-0000-000000000000",
16	"variation_id": "00000000-0000-0000-0000-000000000000"
17	}
18	]
19	})
20	});
21	const data = await response.json();

1	require "uri"
2	require "net/http"
3	require "json"
4
5	url = URI("https://api.tamio.com/v2/invoices/refund/{uuid}")
6
7	https = Net::HTTP.new(url.host, url.port)
8	https.use_ssl = true
9
10	request = Net::HTTP::Post.new(url)
11	request["Accept"] = "application/json"
12	request["Authorization"] = "Bearer YOUR_API_KEY"
13	request["Content-Type"] = "application/json"
14	request.body = {
15	reason: "requested_by_customer",
16	refund_gateway_charge: false,
17	amount: 0,
18	instalment_invoice_id: "string",
19	products: [
20	{
21	id: "00000000-0000-0000-0000-000000000000",
22	invoice_item_id: "00000000-0000-0000-0000-000000000000",
23	variation_id: "00000000-0000-0000-0000-000000000000"
24	}
25	]
26	}.to_json
27
28	response = https.request(request)
29	puts response.read_body