Conventions

Reference for cross-cutting technical conventions: field naming, special field types, pagination, localization, HTTP status codes, and error response shapes.

Field naming

• All fields use PascalCase (e.g. ReferenceCustomer, DateCreated).
• Shared identifier fields are prefixed with Reference (e.g. ReferenceCustomer).
• Internal identifier fields: Id (the resource's own ID) or Id<Resource> (a foreign key, e.g. IdSubscription).

Special field types

Value type	JSON type	Format / example
Date	string	ISO 8601 — "2025-01-31T00:00:00Z"
Amount	integer	Smallest currency unit (cents) — 1999 = €19.99
Currency	string	ISO 4217 — "EUR", "USD"
Country	string	ISO 3166-1 alpha-2 — "FR", "US"
Region	string	ISO 3166-2 — only for US, Canada (CA), Spain (ES)
Language	string	ISO 639 code or locale — "fr", "fr-FR"

Common object fields

Every resource object includes these fields:

Field	Type	Description
Id	integer	Internal numeric identifier
Links	array	HATEOAS links to related resources

Links format:

"Links": [
  { "rel": "self", "href": "/v1/Customer/42" }
]

Pagination

All list endpoints accept:

Parameter	Default	Description
Page	1	1-based page index
SizePage	10	Items per page (max: 1000). Pass 0 to get only the total count without fetching items.

Paginated response shape:

{
  "Count": 10,
  "Page": 1,
  "SizePage": 10,
  "TotalItems": 42,
  "DateGenerated": "2025-01-31T00:00:00Z",
  "Items": [ ... ]
}

Field	Description
Count	Items returned in this page
TotalItems	Total matching items across all pages
DateGenerated	When this list was generated

Localization

Some fields (TitleLocalized, DescriptionLocalized) are resolved through a four-level fallback chain:

Priority	Source	Condition
1	?lang= query parameter	Always takes precedence when provided
2	Customer language	When the request targets a specific customer
3	Segment language	When the request targets a specific segment
4	Business language	Catch-all default

The lang value follows the language format above ("fr", "fr-FR", etc.).

HTTP status codes

Code	Meaning
200	OK — success, body contains the resource
201	Created — resource created, body contains the new resource
204	No content — success, no body
400	Bad request — general client error
401	Unauthorized — credentials missing or invalid
403	Forbidden — credentials valid but action not permitted
404	Not found — resource does not exist
409	Conflict — duplicate reference or state conflict
422	Unprocessable entity — validation errors (see error shape below)
500	Internal server error

Error response shapes

All non-422 errors return a single object:

{
  "Code": "string",
  "Message": "Human-readable description",
  "Exception": "string",
  "Target": "string"
}

Exception is only present on some 500 errors. Target is rarely returned; it identifies the field or resource at fault.

422 responses return an array of error objects:

[
  { "Code": "string", "Message": "string", "Target": "string" }
]