Verify a serialized unit for returns

curl --request GET \
  --url https://www.closient.com/epcis/api/2.0/verification/serial \
  --header 'X-API-Key: <api-key>'

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://www.closient.com/epcis/api/2.0/verification/serial', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.closient.com/epcis/api/2.0/verification/serial",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://www.closient.com/epcis/api/2.0/verification/serial"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://www.closient.com/epcis/api/2.0/verification/serial")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "gtin": "<string>",
  "serial": "<string>",
  "lot": "<string>",
  "sold_at": "2023-11-07T05:31:56Z",
  "sale_transaction_reference": "<string>",
  "returned_at": "2023-11-07T05:31:56Z",
  "recall": {
    "lot": "L2847",
    "recall_id": "RCL-2026-04821",
    "severity": "FDA Class II",
    "title": "Voluntary recall: undeclared allergen"
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

EPCIS 2.0

Verify a serialized unit for returns

Decide whether a scanned GTIN + serial was sold by the authenticated organization, when, under which transaction, and whether it has already been returned. Intended for a return desk scanner or POS plugin: one call, one decision object.

Decisions are computed only from the querying organization’s own EPCIS events — another retailer’s sale of the same GTIN + serial is never visible here, and a unit this organization has no events for is reported as unknown_serial rather than falling back to anyone else’s history. Recall status is the one deliberate exception: it is public product-safety information, so an open recall covering the unit is reported regardless of which organization published it.

The lifecycle states ride GS1 CBV 2.0 dispositions — retail_sold for a sale (bizStep retail_selling) and returned for a return (bizStep returning). Caller must hold an OWNER or MANAGER membership on the organization.

GET

epcis

api

2.0

verification

serial

Verify a serialized unit for returns

curl --request GET \
  --url https://www.closient.com/epcis/api/2.0/verification/serial \
  --header 'X-API-Key: <api-key>'

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://www.closient.com/epcis/api/2.0/verification/serial', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.closient.com/epcis/api/2.0/verification/serial",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://www.closient.com/epcis/api/2.0/verification/serial"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://www.closient.com/epcis/api/2.0/verification/serial")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "gtin": "<string>",
  "serial": "<string>",
  "lot": "<string>",
  "sold_at": "2023-11-07T05:31:56Z",
  "sale_transaction_reference": "<string>",
  "returned_at": "2023-11-07T05:31:56Z",
  "recall": {
    "lot": "L2847",
    "recall_id": "RCL-2026-04821",
    "severity": "FDA Class II",
    "title": "Voluntary recall: undeclared allergen"
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

Authorizations

X-API-Key

string

header

required

Query Parameters

gtin

string

required

GTIN-8/12/13/14 of the scanned unit. Normalized to GTIN-14; check digit is validated.

Pattern: ^[0-9]{8}$|^[0-9]{12,14}$

serial

string

required

GS1 AI(21) serial number of the scanned unit.

Required string length: 1 - 255

Response

Decision object for one GTIN + serial.

decision

enum<string>

required

The verdict. recalled_lot outranks the lifecycle states — when a unit is under an open recall it is reported as such whether or not it was sold, and the sale/return fields below remain populated.

Available options:

sold,

already_returned,

never_sold,

unknown_serial,

recalled_lot

gtin

string

required

Normalized GTIN-14 the decision was computed for.

serial

string

required

GS1 AI(21) serial number the decision was computed for.

lot

string | null

GS1 AI(10) lot identifier recorded for this unit, when known.

sold_at

string<date-time> | null

Event time of the sale, when this organization has recorded one.

sale_transaction_reference

string | null

bizTransaction identifier carried on the sale event, scoped to this organization.

returned_at

string<date-time> | null

Event time of the recorded return, when the unit has already come back.

recall

RecallNoticeSchema · object | null

Populated only when decision is recalled_lot.

Show child attributes

Example:

{
  "lot": "L2847",
  "recall_id": "RCL-2026-04821",
  "severity": "FDA Class II",
  "title": "Voluntary recall: undeclared allergen"
}

Overview

Account

Products

Brands

Locations

Retailers

Search

GS1 Digital Link

EPCIS 2.0

Integrations

Billing

Scanner

Compliance

Certifications

Sustainability

Notifications

Dashboard

Analytics

Agent

Substances

BYOS

Content

Signals

Verify a serialized unit for returns

Authorizations

Query Parameters

Response