Idempotency and retries

Networks fail in awkward places. A timeout does not tell you whether Perkstar accepted a request, so every production integration must be safe to retry.

Request idempotency

Send an Idempotency-Key with every POST request:

Idempotency-Key: order-94721-loyalty-v1

Use a stable value for one logical operation, not a new random value on each retry. Perkstar keeps the result for 24 hours and returns the same outcome when the same request is repeated.

Reusing one key for a different request body is an integration error. Create a new key only when you intend to perform a new operation.

Permanent transaction deduplication

POS and commerce integrations should also send transaction.external_transaction_id to /marketplace/accrue.

{
  "transaction": {
    "type": "STAMP",
    "external_transaction_id": "odoo-pos-order-94721"
  }
}

This reference is unique for the business and remains a deduplication key after the 24-hour request cache expires. A repeated call returns the existing transaction with idempotent_replay: true. Use an upstream ID that is:

stable across webhook retries;
unique to one loyalty operation;
available again when a refund must reverse the operation; and
namespaced when several stores can produce the same numeric order ID.

Good: odoo:shop_12:pos_order:94721 Risky: 94721 Keep test and live references in separate namespaces, for example test:odoo:shop_12:pos_order:94721 and live:odoo:shop_12:pos_order:94721. Perkstar rejects a permanent transaction reference that already belongs to the other environment instead of silently replaying it.

Retry policy

Result	Action
Network error or timeout	Retry with the same idempotency key
`429`	Wait for `Retry-After`, then retry
`500`, `502`, `503`, `504`	Retry with exponential backoff and jitter
`400`, `403`, `404`, `409`, `422`	Fix the request or state; do not blindly retry
`401`	Replace or rotate the credential before retrying

A practical schedule is 1 second, 2 seconds, 4 seconds, then a background retry queue. Cap attempts and surface terminal failures for an operator to inspect.

Reversals

Reverse a transaction by Perkstar ID or by its original external_transaction_id. Give the reversal its own idempotency key. Test and live transactions cannot be reversed across environments.

Get started

Core concepts

Integration recipes

Ship safely

Request idempotency

Permanent transaction deduplication

Retry policy

Reversals

​Request idempotency

​Permanent transaction deduplication

​Retry policy

​Reversals

Request idempotency

Permanent transaction deduplication

Retry policy

Reversals