Skip to content

Receipts, status, and errors

When you send orders by API or webhook, every accepted order returns a receipt you can track. This page covers the receipt lifecycle, the ingestion log in your portal, and the error responses.

The receipt lifecycle

Section titled “The receipt lifecycle”

A successful REST or webhook POST returns 202 with a receipt_id. Look it up any time:

GET https://api.samvertex.com/ingest/status/<receipt_id>
Authorization: Bearer <your api key>

The status moves through these states:

  • received we accepted the order and queued it.
  • normalized we mapped it to a SamVertex order shape.
  • written the order exists in your account; the response includes its order_id.
  • duplicate an order with this source_order_id already exists, so we did not create a second one.
  • failed processing hit an error and will be retried.
  • dead processing failed repeatedly and was set aside. The SamVertex team is alerted automatically and can replay it after fixing the cause; the original payload is kept.

The ingestion log

Section titled “The ingestion log”

Your portal Integrations card shows a recent ingestion log: the latest receipts across every source, each with its source, status, your order id, and any error. It is the quickest way to confirm a batch landed and to spot a feed that is sending malformed rows.

Error responses

Section titled “Error responses”
  • 401 the API key is missing or invalid, or, on the webhook endpoint, the x-svx-signature did not match. Check the key, and for webhooks confirm you signed the raw body with the right secret.
  • 400 the body was not valid JSON, or source_order_id was missing. source_order_id is the one required field.
  • 404 a status lookup was for a receipt id we do not have, or that does not belong to your account.
  • 429 too many requests in a short window. Slow down and retry; the response includes a Retry-After.

Duplicate handling

Section titled “Duplicate handling”

Duplicates are safe and expected. Two mechanisms protect you:

  • Idempotency-Key if you send this header, a repeat with the same key returns the original receipt with "duplicate": true and does not enqueue again.
  • source_order_id even without the header, the same order id never creates a second order.