Orchid eBound API - Responses

This reference lists every response the Orchid eBound™ Transaction API can return, so you can map each one to a handling rule in your POS or ERP integration. It is a companion to the Orchid eBound™ API Documentation, which covers authentication, transaction types, and payload structure.

Which endpoint to use

Important — the asynchronous endpoint is no longer supported. POST /api/transactions/queue, and the API feedback webhook that reported its outcomes, have been retired. All integrations must use the synchronous endpoint, POST /api/transactions. Everything else in this article describes that endpoint.

Authenticate with your API token. The supported endpoint reads the transaction type from a transactionType property on each transaction in the array — no additional headers are required.

The response format

The endpoint returns an array with one element per transaction you submitted. Each element is your original transaction echoed back, with a Result object added:

[{
  "...your original submitted fields...": "...",
  "transactionIdentifier": "T-099999-4567_1668086463",
  "Result": {
    "status":          "Complete-Sent",
    "received":        "2026-07-30T09:14:22",
    "processed":       "2026-07-30T09:14:23",
    "Results":         "Success",
    "transactionType": "Receive"
  }
}]

Three rules for handling responses

• Do not branch on the HTTP status code. Once your request passes the pre-flight checks, a rejected transaction still returns HTTP 200. Always read Result.status.
• Treat Results as display text, not parseable data. When a transaction fails more than one check, the reasons are joined with commas — and the messages themselves contain commas. Log and display the string; branch on status instead.
• Batches are evaluated per transaction. Some elements of an array can succeed while others fail. Check every element, not just the first.

When a transaction is rejected because the serial number is not in an open disposition, the response adds a Result.AdditionalData.OpenDispositions list showing which entries are open for that serial number. Use it to correct and resubmit.

Messages below are reproduced exactly as the API returns them, so you can match on them directly.

Response type 1 — Pre-flight responses

These are returned before any transaction in your payload is examined, and they reject the entire batch — nothing is written. They are the only responses that use meaningful HTTP status codes, so they are worth handling separately from transaction failures.

Response type 2 — Transactional responses

These appear in Result.Results for an individual transaction, always with Result.status set to Failed-Sent and an HTTP status of 200. The “Applies to” column shows which transaction types can produce each message.

Acceptance

Missing transaction data

Returned when the transaction object itself, or a required sub-object, could not be read.

Firearm identity and specification

Validation of the item being recorded — manufacturer, model, type, calibre, serial number, and the optional NFA and SOT fields. Each message is returned with the SKU and serial number of the item that failed, so you can identify the offending row in a batch.

Acquisition information

Applies to transaction types that bring an item into the bound book.

Disposition information

Applies to transaction types that move an item out of the bound book.

Book state and item availability

Returned when the item’s current state in the bound book does not permit the requested movement. These are the most common failures in live integrations and usually indicate the two systems have drifted out of step.

Inventory management location

Returned when the optional imDepartment, imLocation or imSublocation values cannot be matched to your configured hierarchy. The hierarchy resolves top-down, so a department must be valid before a location can be, and a location before a sublocation.

Related documentation

• Orchid eBound™ API Documentation — authentication, architecture, transaction types, and full payload samples for every ATF-regulated transaction.
• Orchid API — Swagger UI — explore and test the Transaction Queue endpoints interactively.

If a response in your logs is not listed here, or a transaction is rejected in a way you cannot explain, raise a ticket through the Orchid support portal with the transactionIdentifier and the full Result object.