GET `/v1/invoices/external/{externalId}`

Get an invoice live by the placing system's order id

Key	Required. See Authentication.
Capability	`sales-data`
Scope	`sales.read`
Price	1 credit, per call. How pricing works.
Estimate	Add `estimate=true` for a free quote. With estimate=true the 200 body is EstimateResponse (a priced quote for exactly this request), not the schema documented under responses.200; nothing is reserved or dispatched.

Example

curl -s "https://api.compudime.com/v1/invoices/external/{externalId}" \
  -H "Authorization: Bearer $PUBLIC_API_KEY"

Parameters

Name	In	Type	Description
`externalId` required	path	string	The placing system's own order id as the POS stored it (externalId on an invoice row), matched exactly, percent-encoded. Note the POS strips leading zeros from a feed's order id. 1-128 characters: a letter or digit, then letters, digits or . _ : # @ + -; anything else is a free 400 before billing. The POS keeps only the first characters of each value (10 of the processor code and 25 of the external id on current TisWin3 databases); the store compares what you send the way the POS stored it, so the full values you sent at intake work. When more than one invoice carries the pair as the POS keeps it (the POS does not enforce uniqueness), the read answers 409 invoice_ambiguous instead of choosing one. At most 128 characters. Pattern: ^[A-Za-z0-9][A-Za-z0-9._:#@+-]{0,127}$
`processorCode` required	query	string	Required. The code of the system that placed the order (processorCode on an invoice row), matched without regard to case; orders placed through POST /v1/orders carry CDAPI:<integration id>. 1-50 characters: a letter or digit, then letters, digits, spaces or . _ : # & + @ -. Missing or malformed is a free 400 before billing. The POS keeps only the first characters of each value (10 of the processor code and 25 of the external id on current TisWin3 databases); the store compares what you send the way the POS stored it, so the full values you sent at intake work. At most 50 characters. Pattern: ^[A-Za-z0-9][A-Za-z0-9 ._:#&+@-]{0,49}$
`fields`	query	string	Comma-separated invoice detail fields to include (see x-compudime-field-catalog), or * for every field the key may see. Omitted: a flat-priced endpoint returns every field; once IT prices the endpoint by field count (includedFields in x-compudime-pricing), an omitted fields returns the standard set at the base price and each field beyond the included count adds extraFieldCost. An unknown or denied field is a free 400 field_not_allowed.
`estimate`	query	boolean	When true, returns EstimateResponse instead of the normal body and never reserves credits: the request is authenticated, authorized and field-resolved exactly like a real call, then priced by billing (base cost plus extra-field credits for the resolved fields) and returned without dispatching to the store. Free of charge. Default: false.

Responses

Status	Description	Body
`200`	The live invoice an order feed stamped with that processor code and external id, with its lines and its delivery record.	`InvoiceResponse`
`400`	The externalId is missing or not of the documented shape, or processorCode is missing or not of the documented shape (code bad_request); or a requested field is not allowed (code field_not_allowed). Rejected before billing.	`Problem`
`401`	Public API key is missing, invalid, or revoked.	`Problem`
`402`	The request was blocked by billing policy: no_api_plan (no plan funds this meter), billing_card_missing, billing_card_failed, usage_exhausted, overage_cap_reached, subscription_paused, sandbox_exhausted, or billing_blocked. A key the store pays for under its approval gets grant_cap_exceeded (the store's monthly limit for your calls) or payer_billing_blocked (the store cannot be charged right now; ask the store owner) instead: what is wrong with the store's billing is not shown to it.	`Problem`
`403`	The API key is not enabled for this endpoint.	`Problem`
`404`	The store has no invoice carrying that processorCode and externalId (code invoice_not_found). The reservation is released, nothing is charged.	`Problem`
`405`	The requested method is not allowed for this endpoint.	`Problem`
`409`	More than one invoice carries that processorCode and externalId as the POS keeps them (code invoice_ambiguous); read the invoice by its POS invoice id. The reservation is released, nothing is charged.	`Problem`
`422`	scope_not_applicable: the API key carries a row scope, and no row scope can be applied to invoices (rejected before billing). filter_unsupported: the store's POS keeps no external order id or processor code (both exist only from TisWin3 database version 1.324); read the invoice by its POS invoice id. invoices_unsupported: the store keeps its orders in legacy tables the invoice reads cannot answer. The reservation is released, nothing is charged.	`Problem`
`429`	Too many requests from this API key (code rate_limited). Each key has its own request budget at the API edge, refilled continuously; it covers every authenticated endpoint, including the free ones, and is checked before anything is billed or sent to the store. Billed endpoints are also subject to the store plan's per-minute ceiling, which answers the same problem code. Wait at least Retry-After seconds before the next request with this key, then resume; if 429 answers again, back off exponentially (double the wait each time, up to a minute or so) and add random jitter so parallel workers do not retry in step. A 429 is never charged and reserves nothing. Header `Retry-After`: Whole seconds to wait before retrying with this key: the time until the key's next request token at the edge (never less than 1), or 60 when the store plan's per-minute ceiling refused the call.	`Problem`
`500`	The API edge encountered an internal error.	`Problem`
`502`	The store's POS could not complete the invoice read (code store_error): the agent answered an error, the store has not enabled per-item data for developers, or the agent or relay build predates this operation. The reservation is released.	`Problem`
`503`	The store's POS agent is offline (code store_offline), or a Public API dependency is unavailable. The reservation is released. Also answered, with code endpoint_disabled, while CompuDime has temporarily switched the endpoint off: the whole API, the endpoint's family (x-compudime-family) or this endpoint alone; the detail says which and why. It is checked before anything is validated, reserved or sent to the store, so it is never charged; it is retryable and carries Retry-After. Header `Retry-After`: Sent with code endpoint_disabled: whole seconds to wait before asking again. A switch has no scheduled end, so this is a polling interval (60), not a promise.	`Problem`
`504`	The store did not answer inside the read ceiling (code store_timeout). The reservation is released.	`Problem`

Error bodies are problem JSON; every code is listed there.

Fields

Choose with fields=; see Choosing fields.

All fields	`invoiceId`, `number`, `orderNumber`, `customerId`, `anonymousCustomer`, `date`, `due`, `status`, `payType`, `orderDept`, `deliveryMethod`, `deliveryTime`, `route`, `routeSeq`, `processorCode`, `externalId`, `source`, `totals`, `taxRate1`, `taxRate2`, `timeline`, `modifiedAt`, `lines`, `linesTruncated`, `delivery`
Standard set	`invoiceId`, `number`, `orderNumber`, `customerId`, `anonymousCustomer`, `date`, `due`, `status`, `payType`, `orderDept`, `deliveryMethod`, `deliveryTime`, `route`, `routeSeq`, `processorCode`, `externalId`, `source`, `totals`, `taxRate1`, `taxRate2`, `timeline`, `modifiedAt`, `lines`, `linesTruncated`, `delivery`

Access level

What your integration's access level changes here.