Developers
Tell it about a sale, any way you like.
Four ways in, one record at the end. Whatever a person can do on a screen in SoldOut OS, your system can do through the API, under the same rules and with the same record of who did what.
You have a back end you control.
Create an API key in the app with the scope conversions.write and send one request per sale. Sending the same order number again updates it; it never counts twice.
- 201 created, 200 updated, 422 with the fields that are wrong
- Up to 500 sales in one batch request
- The e-mail address is hashed on arrival and never stored
POST https://api.soldout-os.com/api/v1/conversions
Authorization: Bearer emos_sk_…
Content-Type: application/json
{
"external_id": "A-1001",
"value": "249.90",
"currency": "EUR",
"quantity": 2,
"offer_external_id": "sku-42",
"customer": { "email": "buyer@example.com" },
"utm": { "source": "facebook", "campaign": "autumn" }
}
Your shop, booking or ticketing system can send events.
Add a data source of the kind “Signed webhook”. You get an address and a signing secret, shown once. Sign every message; one older than five minutes is refused.
- conversion.completed, .refunded, .cancelled, offer.upserted
- 202 accepted, 200 already received, 401 bad signature
- A rotated secret keeps the old one valid until the next rotation
POST https://api.soldout-os.com/ingest/v1/con_…
X-Emos-Timestamp: 1791800000
X-Emos-Delivery-Id: 7c1f0c2e-…
X-Emos-Signature: v1=<hex>
{ "id": "evt-1001", "type": "conversion.completed", "data": { … } }
// signature
"v1=" + hex(HMAC_SHA256(secret, timestamp + "." + delivery_id + "." + raw_body))
You have a website and no back-end integration.
Two lines on every page and one call on the page that confirms the order or the form. Tell it what your cookie banner decided; before consent it stores nothing.
- Also 'signup' and 'booking'
- No third-party cookie, no fingerprinting, no page-view tracking
- List your site’s addresses so no other site can use its id
<script>window.soldout=window.soldout||function(){(soldout.q=soldout.q||[]).push(arguments)};</script>
<script async src="https://api.soldout-os.com/t/con_….js"></script>
// on the confirmation page
soldout('purchase', { order_id: 'A-1001', value: 249.90, currency: 'EUR' });
soldout('lead', { order_id: 'L-88' });
// from your cookie banner
soldout('consent', true);
You want no technical work at all.
Export your orders or leads and import the file in the app. The first line names the columns, in any order, separated by commas or semicolons, in English or Romanian.
- Up to 5,000 rows per file
- Bad rows are reported by line, the rest are imported
- Importing the same file again changes nothing
order_id,date,value,currency,quantity,offer,utm_source,utm_campaign,email
A-1001,2026-10-01 10:00,249.90,EUR,2,Autumn collection,facebook,autumn,buyer@example.com
What happens next
Cleaned on arrival. Counted once.
Comes in
Shop webhook
{"order":"#10432","total":"89,00 EUR","email":"ana@…"}
CSV export
nr_comanda;data;valoare
A-1001;01.10.2026;249,90
Site snippet
purchase · ?utm_source=fb&fbclid=IwAR2…
Same order, again
purchase A-1001 · value 249.9 · browser
Meta Ads
spend "412.18" · clicks 1904 · results 31
Google Ads
cost_micros 128430000 · conversions 12.0
SoldOut OS
0 records cleaned
- One record per order number, however often it arrives
- E-mail addresses hashed on arrival, no names kept
- Amounts in exact cents, never mixed across currencies
- Column names read in English or Romanian
- Every sale traced to the campaign that brought it
- Click identifiers dropped when consent is refused
- A browser never overrides what your server says
Comes out
Steel pan, 28 cm is on track
€702 a day, needs €548
Cost per order €6.62, return 7.2×
Your orders, not Meta’s count
Retargeting DE: 210 clicks, no order
A pause is proposed for approval
Austria brings 14% of buyers
Not targeted yet. Add it?
The rest of the API
Everything on a screen is also an endpoint.
API keys or OAuth client credentials, with scopes, an expiry date and an optional list of IP addresses. The
base address is https://api.soldout-os.com/api/v1.
/api/v1/offers
Create an offer, or update it by your own id
/api/v1/offers/{id}/variants
The options people can buy, with price and stock
/api/v1/offers/{id}/pacing
Pace, pace needed, projection and verdict, with the inputs used
/api/v1/offers/{id}/performance
Spend against your sales by source, cost per sale, return
/api/v1/conversions/batch
Up to 500 sales at once; the answer says what happened to each
/api/v1/conversions/{id}/adjustments
A refund or a cancellation, in full or in part
/api/v1/recommendations
What needs attention, with the figures behind each item
/api/v1/competitors
Competitors you follow, and their running ads
Questions
Asked and answered.
Is there an OpenAPI document or an SDK?
Not yet. The API is plain HTTPS and JSON; the full reference comes with your invitation. A published OpenAPI document and client libraries are planned.
How are API keys protected?
A key is shown once and stored only as a hash. Keys carry scopes and an expiry date, can be limited to a list of IP addresses, and can be revoked at any time.
What is the rate limit?
120 requests a minute by default. Use the batch endpoint to send many sales at once.
Can my system propose campaign changes?
Yes, with the campaigns.write scope. Approving a change is a separate scope, so a key that proposes cannot also approve.
Bring an offer and a number.
We are opening to a few businesses at a time. Tell us what you sell and what you need to reach.