Data Types and Enums

This document defines the field types used across the API and the allowed values of every status and type field an integrator reads or sends. These are API contract values: the strings and shapes that appear in requests and responses: stated once here and used by every endpoint reference. Terms are defined in Glossary.

Field types

Type	Format	Notes
id	Opaque string	Assigned by the Platform. Never parse, construct, or guess an id; equality is the only operation
string	UTF-8 text	Length limits are stated per field in the endpoint references
integer	Whole number, no fraction	Quantities and counts. Quantities are never negative in responses
decimal string	"24.99"	All money and rates. Always accompanied by a currency field for money. Never a JSON number
currency	ISO 4217 code, uppercase	For example USD
boolean	true or false
timestamp	ISO 8601, UTC	For example 2026-10-14T10:42:32Z. Every *_at field
date	ISO 8601 calendar date	YYYY-MM-DD. Every period bound and *_on date
array	JSON array	Element type stated per field
object	JSON object	Shape stated per field
null	JSON null	A field present with value null means "no value yet", for example delivered_at before delivery

Conventions that apply everywhere (Overview): responses may add fields over time, and clients shall ignore fields they do not recognize; a field's absence and a null value are not the same signal: where an endpoint always returns a field, it does so, with null when there is no value.

Enum values

Enum values are lowercase strings with underscores. The sets below are closed for requests: sending a value outside the set fails with 422. For responses, treat the sets as the current contract; a new value is an additive change announced in the Changelog, so code that switches on status should carry a safe default branch.

Account

Field	Values
account_type	manufacturer, supplier, reseller, dropshipper, veterinary, pharmacy, franchise
api_tier	import, partner, none
Account status	active, suspended, closed

Catalog

Field	Values
Product status	active, inactive, archived
Brand status	live, not_live, suspended
Authorization status (Brand and Manufacturer Endpoints)	pending_review, current, expired, revoked, ended

Inventory (Inventory Endpoints)

Field	Values
Adjustment reason	received, sold, returned, damaged, expired, correction, count

Orders (Orders Endpoints)

Field	Values
Order status	pending_payment, confirmed, fulfilling, shipped, completed, cancelled, returned
Cancellation reason	out_of_stock, cannot_fulfill, buyer_requested, duplicate

Fulfillment

Field	Values
Shipment status	label_created, in_transit, out_for_delivery, delivered, exception, cancelled

Returns

Field	Values
Return status	requested, approved, awaiting_package, in_transit, received, inspection, approved_for_refund, rejected, restocked, refunded, exchanged, completed, cancelled
Line condition	unopened, opened_unused, used, damaged
Line disposition	restock, refurbish, dispose
Refund method	original_payment, store_credit

Payments (Payments Endpoints)

Field	Values
Payment type	charge, refund
Charge status	pending, succeeded, failed, refunded
Refund status	pending, completed, failed
Payment method	card, bank_transfer, store_credit, cash
Payout status	scheduled, in_transit, paid, failed

Governance

Field	Values
Evaluation result	pass, flag, fail
Violation severity	low, medium, high, critical
Violation status	open, under_review, resolved, closed
Appeal status	pending, approved, denied

Veterinary and pharmacy

Field	Values
Referral urgency	emergency, urgent, routine, information
Referral status	new, contacted, responded, booked, closed
Consultation status	scheduled, in_progress, completed, cancelled, no_show
VCPR status	current, expired, none
Prescription pharmacy_status	received, in_preparation, shipped, delivered, on_hold

Franchise

Field	Values
Location status	pending_opening, active, suspended, closed
Agreement status	pending_signature, in_force, expired, terminated
Statement status	issued, paid, overdue, corrected

Identifiers in practice

Ids carry a short prefix that names the resource kind (prod_, ord_, pay_, ret_) followed by an opaque suffix. The prefix is a reading aid only: do not branch business logic on it, and do not assume a suffix's length or character set stays fixed. Human-facing numbers: order_number (AAP-2026-104821), return_number (RMA-2026-00319): are separate fields, formatted for people and support calls; use id in API calls and the number in correspondence.