EntryGoDocs
QuickstartProtocolAPI Reference

Concept

Export Lifecycle

The EntryGo export lifecycle is the operational path from source demand to confirmed export state.

The lifecycle is intentionally small:

  1. sync order demand
  2. plan an export
  3. execute the approved batch
  4. inspect current state

The OpenAPI contract for that lifecycle lives at /docs/api/openapi.

#Lifecycle at a glance

Phase Endpoint Input Output Why it exists
Sync POST /api/orders/sync Account-scoped source orders Stable EntryGo order IDs Makes demand available to the protocol
Plan POST /api/exports/plan Order IDs, warehouse, broker, destination Export decision and readiness Separates decision from side effect
Execute POST /api/exports/execute Planned batchId Customs package state, artifacts, broker submission Applies the approved plan
Inspect GET /api/exports/{id} Export ID Canonical current state Reconciles what actually happened

#1. Order intake and sync

Order sync is the entry point where external demand becomes protocol-visible.

Important behavior:

  • orders are upserted by externalId within the authenticated account
  • line items are replaced on update
  • the response returns the EntryGo order IDs that later planning calls must use

Operationally, sync is not just transport. It defines the exact demand set planning is allowed to reason about. If an order is not in the synced order store, it is not part of the plan.

#2. Planning

Planning is the decision phase of the lifecycle.

Planning takes:

  • accountId
  • warehouseId
  • brokerId
  • destinationCountry
  • orderIds

Planning returns:

  • inclusion and exclusion decisions
  • readiness state
  • validation issues
  • flags and missing data
  • a strategy hint
  • planHash

The key architectural rule is simple: planning computes what should happen, but it does not yet trigger the operational side effects.

#Why planHash matters

planHash is the deterministic fingerprint of the planning snapshot.

Clients should use it when they need to know whether the planning inputs are materially the same across:

  • retries
  • repeated evaluations
  • automation branches
  • human review loops

In practical terms:

  • idempotency tells the server whether two writes are intended to be the same logical request
  • planHash tells the client whether two planning outcomes describe the same planning state

#3. Execution

Execution is the side-effecting phase.

Execution turns a planned batch into operational outputs, including:

  • customs package creation or reuse
  • artifact generation
  • notification creation
  • broker submission handling

Execution should only happen after the caller has decided that the planning result is acceptable for policy and readiness.

That means:

  • 200 or 201 from planning is not enough by itself
  • readinessState and validationMessages must be interpreted before execution

#4. Inspection

Inspection is the lifecycle read model.

Use inspect to answer:

  • what was planned
  • what executed
  • what artifacts currently exist
  • whether broker submission succeeded
  • which events have occurred
  • what state the export is in now

Inspect matters because clients often lose certainty after network failures, partial automation runs, or long-running side effects. The inspect endpoint lets every client converge on the same source of truth.

#Events in the lifecycle

EntryGo exposes event history as part of inspect because lifecycle progress should be observable, not inferred.

Representative events include:

  • planning completed
  • customs package generated
  • broker submission prepared
  • broker submission sent or failed
  • warehouse notification recorded
  • execution completed

Events are useful for:

  • human debugging
  • auditability
  • agent reconciliation
  • automation reporting

#Idempotency rules

EntryGo supports idempotent write behavior on the main write endpoints:

  • POST /api/orders/sync
  • POST /api/exports/plan
  • POST /api/exports/execute

Rules:

  • send the Idempotency-Key header for retriable writes
  • if both header and body keys are sent, the header wins
  • reusing a key for a different logical payload can produce 409 IDEMPOTENCY_CONFLICT

Safe retry pattern:

  1. send the write request with an idempotency key
  2. if the client times out or loses the response, retry with the same key
  3. if state is still unclear, inspect the export or package resource

#Typical lifecycle mistakes

Mistake Why it breaks Correct approach
Planning from external order references only Planning expects EntryGo order IDs Persist IDs returned by order sync
Executing immediately on any successful plan response Readiness may still be REVIEW_REQUIRED or BLOCKED Gate execute on policy and readiness fields
Treating execute as proof of final state forever The client may miss later state or events Use inspect for reconciliation
Generating custom partner side effects outside the protocol Export state becomes fragmented Let execute own broker and notification side effects

#Lifecycle guidance for AI agents

For agentic clients, the correct loop is:

  1. sync current inputs
  2. plan
  3. evaluate readiness and validation
  4. execute only if policy permits
  5. inspect until the observed state supports the next action

That loop is what makes EntryGo usable as an automation substrate rather than just a set of endpoints.