Validate coupon codes

POST https://api.tamio.com/v2/transactions/validate-coupons

Validates coupon codes against specific products and customer criteria to verify discount eligibility and calculate savings before applying them to a transaction.

Body Parameters

coupons array of string*

Coupon codes to validate.

currency string*

Currency code for discount calculation.

customer_country string

Customer country for geo-restricted coupon validation.

products array of ProductItem*

Products to validate coupons against (1–20).

JSON

{ "products": [ { "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890", "quantity": 2, "price": 2500, "name": "Premium Widget", "variant": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "pack": "c3d4e5f6-a7b8-9012-cdef-123456789012" } ] }

id string

Product UUID.

quantity integer

Number of units.

price integer

Custom price in smallest currency unit (required when no id/variant/pack).

name string

Custom product name (required when no id/variant/pack).

variant string

Variant UUID.

pack string

Pack UUID.

Responses

200 Returns validation results for each submitted coupon code.

Returns validation results for each submitted coupon code.

status integer

coupons array of object

Validation result for each submitted coupon.

valid boolean

Whether the coupon code is valid.

coupon string

The coupon code that was validated.

amount_off integer

Fixed discount amount in smallest currency unit. Null for invalid coupons.

percent_off number

Percentage discount. Null for invalid coupons.

shipping_amount_off integer

Fixed shipping discount in smallest currency unit.

shipping_percent_off number

Percentage shipping discount.

currency string

Currency the discount applies in. Null for invalid coupons.

applies_to string

Product scope the discount applies to.

all_productsselected_productsselected_categories

selected_products array of string

Product UUIDs the coupon is restricted to. Null unless applies_to is selected_products.

selected_categories object

Category groups the coupon is restricted to. Null unless applies_to is selected_categories.

customer object

Customer the discount is restricted to. Null for non-customer-specific discounts.

expiry_date integer

Unix timestamp of coupon expiry. Null if no expiry.

requirements object

Additional requirements for the coupon (e.g. specific countries or payment methods).

invalid_reason string

Reason the coupon is invalid. Null for valid coupons.

invalid-couponexpiry-dateinvalid-orderinvalid-countryinvalid-currency

400 Validation error.

Code	Description
400	Invalid or missing required parameters.

401 Missing or invalid API key

Finalise a transaction

/transactions/validate-coupons

1 const response = await fetch("https://api.tamio.com/v2/transactions/validate-coupons", {
2   method: "POST",
3   headers: {
4     "Authorization": "Bearer YOUR_API_KEY",
5     "Content-Type": "application/json"
6   },
7   body: JSON.stringify({
8     "coupons": [
9       "SAVE20",
10       "EXPIRED2023"
11     ],
12     "currency": "EUR",
13     "customer_country": "de",
14     "products": [
15       {
16         "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
17         "quantity": 2,
18         "price": 2500,
19         "name": "Premium Widget",
20         "variant": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
21         "pack": "c3d4e5f6-a7b8-9012-cdef-123456789012"
22       }
23     ]
24   })
25 });
26 const data = await response.json();

1 require "uri"
2 require "net/http"
3 require "json"
4 
5 url = URI("https://api.tamio.com/v2/transactions/validate-coupons")
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   coupons: ["SAVE20", "EXPIRED2023"],
16   currency: "EUR",
17   customer_country: "de",
18   products: [
19     {
20       id: "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
21       quantity: 2,
22       price: 2500,
23       name: "Premium Widget",
24       variant: "b2c3d4e5-f6a7-8901-bcde-f12345678901",
25       pack: "c3d4e5f6-a7b8-9012-cdef-123456789012"
26     }
27   ]
28 }.to_json
29 
30 response = https.request(request)
31 puts response.read_body

Responses

{
  "status": 200,
  "coupons": [
    {
      "valid": true,
      "amount_off": 0,
      "percent_off": 20,
      "shipping_amount_off": 0,
      "shipping_percent_off": 0,
      "currency": "EUR",
      "coupon": "SAVE20",
      "requirements": {},
      "selected_products": null,
      "selected_categories": null,
      "applies_to": "all_products",
      "customer": null,
      "expiry_date": null
    },
    {
      "valid": false,
      "currency": null,
      "coupon": "EXPIRED2023",
      "requirements": null,
      "invalid_reason": "expiry-date"
    }
  ]
}

1	const response = await fetch("https://api.tamio.com/v2/transactions/validate-coupons", {
2	method: "POST",
3	headers: {
4	"Authorization": "Bearer YOUR_API_KEY",
5	"Content-Type": "application/json"
6	},
7	body: JSON.stringify({
8	"coupons": [
9	"SAVE20",
10	"EXPIRED2023"
11	],
12	"currency": "EUR",
13	"customer_country": "de",
14	"products": [
15	{
16	"id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
17	"quantity": 2,
18	"price": 2500,
19	"name": "Premium Widget",
20	"variant": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
21	"pack": "c3d4e5f6-a7b8-9012-cdef-123456789012"
22	}
23	]
24	})
25	});
26	const data = await response.json();

1	require "uri"
2	require "net/http"
3	require "json"
4
5	url = URI("https://api.tamio.com/v2/transactions/validate-coupons")
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	coupons: ["SAVE20", "EXPIRED2023"],
16	currency: "EUR",
17	customer_country: "de",
18	products: [
19	{
20	id: "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
21	quantity: 2,
22	price: 2500,
23	name: "Premium Widget",
24	variant: "b2c3d4e5-f6a7-8901-bcde-f12345678901",
25	pack: "c3d4e5f6-a7b8-9012-cdef-123456789012"
26	}
27	]
28	}.to_json
29
30	response = https.request(request)
31	puts response.read_body