Guides

Pagination & conventions

Shared rules for lists, timestamps, money, and identifiers.

Cursor pagination

List endpoints return one page and a cursor to the next.

Query parameter	Meaning
`cursor`	Opaque string from the previous page’s pageInfo.nextCursor. Omit it for the first page.
`limit`	Page size, 1 to 200. Default 50.

Response shape

{
  "items": [
    "…"
  ],
  "pageInfo": {
    "nextCursor": "eyJ0Ijoi…",
    "hasMore": true
  }
}

Keep requesting with cursor=pageInfo.nextCursor while pageInfo.hasMore is true. On the last page nextCursor is null.
Treat cursors as opaque: do not parse, build, or store them long-term. Keep the other filters unchanged between pages.
Some small lists (stores, labels, warehouses) are returned whole without pageInfo; the reference shows each response.

Timestamps

Timestamps are ISO 8601 strings in UTC, e.g. 2026-11-04T08:00:00.000Z. Send filters such as from and to in the same format (with Z or an explicit offset like +07:00). Indonesian local time (WIB) is UTC+7. Date-only fields use YYYY-MM-DD.

Money

Amounts are decimal strings with exactly two fraction digits, e.g. "189000.00", never floats. The currency is in a sibling currency field and is IDR for Indonesian stores. Parse with a decimal type (BigInt of cents, decimal.Decimal), not binary floating point.

Identifiers

Kind	Example	Meaning
TheComNet id	`0192f0c4-8d1e-7a4b-…`	UUID (fields named id, orderId, storeId, itemId, …). Stable; use these in API paths.
External id	`578123456789012345`	Fields prefixed external (externalOrderId, externalReturnId, externalProductId, externalSkuId, …) are the marketplace’s own ids, as shown in TikTok Shop or Shopee Seller Center. Unique only together with the store or marketplace.

marketplace is one of tiktok, shopee, lazada, tokopedia. Use external ids to match records with marketplace exports and support tickets; use TheComNet ids for everything else.

Nulls and unknown fields

Fields listed as required are always present; nullable ones may be null. Optional fields may be absent.
New fields and new enum values can appear without a version change. Ignore unknown fields and handle unknown enum values.
Parameters and bodies are validated against the contract; invalid input answers 400 VALIDATION_FAILED with field errors (see Errors).