Idempotency
Use one key per intended change so a retry does not create a second payout or action.
A request can succeed even if your connection drops before the response arrives. An idempotency key tells a supported endpoint, “This is the same change I already asked for,” so retrying does not create a second payout or action.
Generate a hard-to-guess value such as a random UUID and save it with the change you intend to make. Reuse that key only for the same operation with identical inputs. A new change needs a new key.
Supported operations
| Operation | Transport | Required | Reuse behavior |
|---|---|---|---|
POST /v2/affiliates/{affiliate}/payouts | Idempotency-Key header, max 100 characters | Yes | Same affiliate returns the existing payout; another affiliate is rejected. |
POST /v2/wallets/{customer}/adjustments | JSON idempotency_key, max 128 | Yes | Identical input returns 200 with the existing ledger entry; different input is rejected. |
POST /v2/credit-transactions | JSON idempotency_key, 1–128 characters | Yes | Identical input returns 200; conflicting reuse and reserved internal prefixes are rejected. |
POST /v2/seller-payouts | JSON idempotency_key, 8–100 characters matching A-Z, a-z, 0-9, ., _, :, or - | Yes | Same amount returns the existing request; another amount is rejected. |
| Subscription cancellation and lifecycle writes | Idempotency-Key header or JSON idempotency_key, max 128 | No, strongly recommended | The header takes precedence. A confirmed replay returns the persisted action; conflicting reuse is rejected. |
Keys are stored with the related ledger, payout, or subscription action. SellApp does not currently expire these saved keys automatically, so do not recycle them for another operation.
Inherently idempotent operations
POST /v2/reward-grantsis unique per reward rule and customer. A repeat returns the existing grant.- Updating an affiliate payout to the status it already has is a no-op.
- Fulfillment retry endpoints reset the same retryable effects instead of creating another effect.
These guarantees apply only to the listed operations. A write is not safe to repeat just because another endpoint accepts an idempotency key.
Replay rules
Supported operations save successful results and return the existing resource when you repeat the same request. Validation, authentication, authorization, rate-limit, and server failures are not cached as idempotent successes.
If a connection fails after sending a keyed request, resend the exact method, path, body, store slug, and key. Never generate a new key merely because the first response was lost.
Set SELLAPP_API_BASE_URL, SELLAPP_API_KEY, and SELLAPP_STORE_SLUG as shown
in the quickstart.
curl --request POST \
--url "${SELLAPP_API_BASE_URL}/v2/affiliates/42/payouts" \
--header "Authorization: Bearer ${SELLAPP_API_KEY}" \
--header "X-STORE: ${SELLAPP_STORE_SLUG}" \
--header 'Idempotency-Key: 01992a65-e064-71ba-b38f-902b7966a6be' \
--header 'Accept: application/json'