Certification

Required sandbox test cases and evidence format before production access.

TopicsGo live

Avrix grants production access against evidence that your integration handles failure paths — not only the happy path. Run every case in sandbox, capture requestId and the response, and keep a one-line note of how your system behaved.

Use Environments for host and key rules, and Go-live for the cutover checklist after certification passes.

Automatic certification report#

Avrix evaluates the 28 cases below from your sandbox key's own traffic. Call GET /api/seller/v1/sandbox/certification with the sandbox key you certify, or open Settings → Integrations → API Keys → Sandbox developer tools in the Console, which shows the same report per key.

Bash
curl -s "https://api.avrix.io/api/seller/v1/sandbox/certification" \
  -H "Authorization: Bearer $AVRIX_API_KEY"

The report covers the last 30 days of that key's sandbox requests, webhook deliveries (including test-fire receiver challenges) and fault scenarios. It is computed on each call, and it contains request and delivery references only: no keys, tokens or buyer data. Production keys receive 422 SANDBOX_KEY_REQUIRED.

Each case has one status:

StatusMeaning
passThe traffic proves the expected behaviour, or Avrix accepted your evidence for the case.
failThe traffic proves the opposite, for example a mis-signed test event answered 2xx, or a 5xx retried with a new Idempotency-Key.
not_runNo traffic exercises the case yet. reason says what to run.
needs_partner_evidenceWhat Avrix can see is consistent, but the case is about behaviour inside your systems. Submit evidence for it.
JSON
{
  "data": {
    "reportVersion": 1,
    "generatedAt": "2026-10-12T09:30:00.000Z",
    "apiKeyId": "5b2f0d1e-7c3a-4e8b-9f61-2a4c8d0e1b37",
    "environment": { "mode": "isolated", "environmentId": "0c9e6f4a-1d2b-4c3e-8a7f-5b6d9e0f1a2c" },
    "window": { "from": "2026-09-12T09:30:00.000Z", "to": "2026-10-12T09:30:00.000Z" },
    "summary": { "pass": 4, "fail": 0, "not_run": 20, "needs_partner_evidence": 4 },
    "collectionErrors": [],
    "cases": [
      {
        "number": 18,
        "name": "Invalid signature",
        "group": "webhooks",
        "status": "needs_partner_evidence",
        "evidenceQuality": "complete",
        "reason": "Your endpoint refused the mis-signed delivery. Show that it was refused for the signature, not for another reason.",
        "observations": [
          {
            "at": "2026-10-12T08:21:00.000Z",
            "deliveryId": "9e5f3c2b-7d4a-4b6f-8c8e-2a3f4d5e6b7c",
            "detail": "order.fulfilled mis-signed delivery → 401"
          }
        ],
        "partnerEvidence": "none"
      }
    ],
    "notCovered": [
      {
        "area": "promotions",
        "reason": "Answering event shares and deals, and promotion events. Rehearse them on SANDBOX-PROMO-001 (Sandbox guide, Promotions)."
      }
    ]
  },
  "meta": { "requestId": "req_av1203_example" }
}

The example shows one of the 28 cases; cases always lists all of them in case-number order.

What the report does not certify. notCovered lists the areas of the Seller API the 28 cases do not exercise, each with the reason and where to rehearse it, so a report with every case passed is not read as covering them: promotions, finance_statements, key_management, allocation_requests and partner_access (the example shows the first). The list is the same for every key; rehearse these areas yourself before go-live. See Sandbox.

How each case is decided#

  • Traffic that proves the case passes it. A fulfilled SANDBOX-ALWAYS-001 order (case 7), a replay with the same Idempotency-Key (12), IDEMPOTENCY_KEY_MISMATCH (13), a price or territory refusal (10, 11), a correctly signed delivery acknowledged (17), both secrets accepted during a rotation (22), keys returned and the refund read back (23, 24), a request after a 429 that waited for Retry-After (25), and a 5xx retried after a delay with the same Idempotency-Key (26).
  • Traffic that contradicts the case fails it. A sold unsellable fixture (5, 6), a mis-signed or stale delivery answered 2xx (18, 19, and then 22), a request sent before Retry-After elapsed (25), or a failed order retried under a new Idempotency-Key (14, 26).
  • Cases about your own systems need your evidence. Avrix cannot see a PSP refund, durable key storage, a delisted product or why your endpoint refused a delivery. Cases 1 to 6, 8, 9, 14, 18 to 21 and 28 become needs_partner_evidence once the related traffic exists; cases 15, 16 and 27 always need evidence.
  • Missing evidence is never a pass. When a source cannot be read, the report lists it in collectionErrors, marks the affected cases evidenceQuality: "unknown" and does not pass them. Retry later.

Fault scenarios and test-fire produce the traffic for the hardest cases: timeout_then_success or error_after_commit for case 14, webhook_delay_duplicate for case 21 (see Sandbox), and the invalid_signature, stale_timestamp, duplicate and previous_secret_only challenges of POST /webhooks/{id}/test for cases 18 to 20 and 22 (see Webhooks).

Submitting evidence#

For a case in needs_partner_evidence, open the report in the Console and choose Add evidence: describe how your system behaved, with request ids and timestamps, and optionally link to logs or a recording (an https:// link). One submission per case can wait for review at a time. Avrix reviews it: an accepted submission turns the case into pass on that key's report (partnerEvidence: "accepted"); a rejected one leaves the case open, and you can submit again.

Evidence format#

Use this format for evidence you submit, and for any case you report outside the automatic report. For each case record:

  1. Case number and name
  2. requestId from the response (or X-Request-Id)
  3. HTTP status and error code if any
  4. One line describing your system's behaviour (refund issued, webhook deduped, catalog delisted, …)

A test-suite log or structured log excerpt is enough. The goal is demonstrable behaviour, not a formal document.

Required test cases#

Catalog#

#CaseExpectedFixture
1Cold-start syncFull sellable catalog persisted with cursor—
2Incremental syncDeltas applied, cursor advanced—
3Tombstone handlingRemoved SKU delisted from storefront—
4Allocation mergeSellable set built from GET /allocations rows with sellable: true, joined to the catalog on the SKU id—
5Unsellable SKU excludedShared-but-unallocated SKU has no buy buttonSANDBOX-NOALLOC-001
6Non-live product excludedNot offered for saleSANDBOX-LIFECYCLE-001

Case 4 verifies you did not build the catalog from /products alone. See Catalog and allocations.

Orders#

#CaseExpectedFixture
7Happy pathOrder fulfilled; key delivered and persistedSANDBOX-ALWAYS-001
8Preview gatingNo charge when canFulfill is false—
9Sold out after payment409; buyer refunded at your PSPSANDBOX-NOKEYS-001
10Price driftMismatch handled; no silent repricing—
11Territory rejectionHandled before or at checkout—
12Idempotent replaySame key + same body → original response, one fulfilment—
13Idempotency conflictSame key + different body → IDEMPOTENCY_KEY_MISMATCH—
14Unknown outcomeTimeout → replay same key; no double charge, no double pull—

Case 14 is the highest-value test. Simulate it by killing the connection mid-request, or with the timeout_then_success and error_after_commit sandbox scenarios. See Order lifecycle.

Fulfilment#

#CaseExpected
15Key persistenceKey written to durable storage before responding to the buyer
16Key non-recoveryConfirm GET /orders never returns plaintext keys

Webhooks#

#CaseExpected
17Valid signatureAccepted and processed
18Invalid signatureRejected — deliberately corrupt one
19Stale timestampRejected beyond 300 seconds
20Duplicate deliverySecond delivery ignored via event id
21Webhook before responseHandler tolerates an unrecorded order
22Secret rotationBoth secrets accepted during overlap window

Case 18 is the one integrations most often skip. An endpoint that accepts every signature is worse than no verification. Send a mis-signed delivery with POST /webhooks/{id}/test and "challenge": "invalid_signature".

Refunds#

#CaseExpected
23Key returnKeys quarantined using persisted keyIds from the order response
24Refund recordedRefund status retrievable via GET /refunds

Operations#

#CaseExpected
25Rate limit429 handled with Retry-After
26Server error5xx retried with backoff and the same idempotency key
27Request correlationrequestId logged on every error
28ReconciliationScheduled job compares local orders against GET /orders

Approval#

When the automatic report shows every case as pass, or you have submitted evidence for the cases that remain, tell your Avrix partner contact or support@avrix.io. Cases the report does not cover for your integration can still be sent in the evidence format above.

To be told instead of checking, subscribe the key's sandbox webhook endpoint to sandbox.certification_passed. It fires when a report for the key passes every case: the first time, and again only if the report passes after showing a failed case. The report is evaluated when it is built (GET /sandbox/certification, the console panel, or Avrix accepting your evidence), so a pass that comes from new traffic is announced the next time the report is built. See the Event reference.

Certification does not enable production access automatically, and an all-pass report does not by itself grant it. After review, Avrix enables production Seller API access on your company. Until that happens, production keys on api.avrix.io receive 403 PRODUCTION_ACCESS_NOT_APPROVED even after you have signed the API Revenue Share Channel Terms and created a production key. Sandbox continues to work for regression testing.

Avrix publishes no review turnaround. Ask your partner contact for an expected date when you submit, and plan your cutover around it. If a case fails review, fix it and resubmit only the failed rows with fresh requestIds.

What links here

Published guides that link to this page.

Search docs

Search documentation…