The reference, and retrying safely
Your reference is the only thing standing between a timeout and a double charge.
Every order carries a reference you choose. We claim it against a unique
index before anything is charged, so two orders can never share one. The
second request does not create anything: it returns the first order, with a
200 and "This reference was already used. Returning the original order."
This is what makes the API safe to retry. It is also the only thing that does.
Choosing one
- Unique across your own orders, forever. Not just within a day.
- 120 characters or fewer.
- Something you can find again in your own records.
- Generated before you send the request, and stored with the order you are about to place.
A UUID works. So does alpha-2026-11-18-000147. What matters is that you can
reproduce it, because a retry has to send the same one.
Warning
Never generate a new reference for a retry. That is not a retry, it is a second order, and your customer pays twice. If your code generates the reference inside the function that sends the request, it is already wrong.
Which failures are safe to retry
| What you got | Did the order happen? | Do this |
|---|---|---|
202 | yes | nothing. Poll, or wait for the webhook. |
200 with the "already used" message | yes, earlier | nothing. |
422 from validation, data is null | no | fix the request. The reference is free. |
422 with the order in data | yes, and it failed | read data.state. Do not retry. |
429 | no | let your open requests finish, then retry, same reference. |
503 | unknown | retry with the same reference, or poll it. |
| A timeout, no response at all | unknown | retry with the same reference, or poll it. |
401, 403 | no | fix the credential. Retrying changes nothing. |
The two "unknown" rows are the ones that matter. Both have the same safe answer, and it is the same answer either way.
Recovering from a timeout
Your request timed out. You do not know whether we got it.
Option one, retry. Send the identical request again, same reference. If the
first attempt landed you get the original order back with a 200 and nothing
is charged twice. If it did not land, this one goes through normally.
Option two, ask. Call Get an order with that reference.
curl https://stagingapi.getelectric.ng/api/v2/reseller/orders/alpha-000147 \
-H 'Authorization: Bearer <your-key>'A 404 with "No order with that reference." is the one response that tells you
nothing was created and the reference is still free to use. Anything else means
the order exists, and its state tells you where it got to.
Tip
Polling is the better habit of the two. A retry re-sends the whole body and is counted against your in-flight budget as a purchase; a poll is a cheap read. Retry when you want the result in the same request, poll when you are reconciling afterwards.
Reconciling in bulk
To check a batch, List orders pages through your orders newest first. For anything older than a page or two, keep your own record keyed by your reference and ask about the ones you are unsure of. There is no bulk lookup by a list of references.
What the reference is not
It is not a transaction id. We generate our own, and it appears as
transaction on the order once there is one. Use ours when talking to us about
money, and yours to find your own records.