DocsFor advertisers

Offer Postbacks for Advertisers

For advertisers running offer campaigns: add {click_id} to your tracking link, then call our postback URL from your server for every step a user reaches.

This page is for advertisers who run an offer campaign: users reach goals in your app or on your site, for example install, sign up, or buy, and your server confirms each goal with a postback. Publishers do not need it.

How it works

A user starts your offer on an offerwall. We create a click and send the user to your tracking link, with our {click_id} filled in.
Your tracker stores that value together with the user.
When the user reaches a step, your server calls our postback URL with the same click ID and the event ID of the step.
We charge the price of that step for the country of the user, and the user gets the reward right away.

Tracking link

You set the tracking link when you create the offer. It must contain {click_id}. We fill in these values for every user:

Macro	Value
`{click_id}`required	32 characters, unique for every user who starts the offer. Send it back unchanged in the postback.
`{country}`optional	Two-letter country code of the user, for example `US`.
`{device}`optional	`desktop`, `android`, or `ios`.
`{source}`optional	A number for the site or app the user came from. Use it to compare the quality of sources.

https://track.example.com/click?cid={click_id}&geo={country}&sub={source}

Postback URL

You find the full URL, with your key, on the offer page in your dashboard, under Postback. It looks like this:

https://api.sharklio.com/v1/postback?key=YOUR_KEY&click_id={click_id}&goal=install

Use GET or POST. The parameters:

Parameter	Description
`key`required	The secret key of the offer. Every offer has its own. Keep it on your server: anyone who has it can report conversions for the offer.
`click_id`required	The value we put in `{click_id}` of your tracking link. Replace `{click_id}` in the URL with the macro of your tracker that holds it.
`goal`required with more than one step	The event ID of the step, see Event IDs. With a single step you can leave it out.
`status`optional	Leave it out to report a conversion. Send `reversed` to take one back, see Reversals.
`event_id`optional	Your own ID for the conversion, up to 64 characters. We store it with the conversion for your records.

One URL for all your offers

Besides the key of each offer, your account has its own key. The account postback URL works for all your offers, so you set it up once in your tracker:

https://api.sharklio.com/v1/postback?key=ACCOUNT_KEY&click_id={click_id}&goal={event}

We find the offer from the click ID. You find the URL on the page of any offer in your dashboard, under Postback. Both kinds of keys can be replaced there with one click, for example if a key was shared by mistake. The old key stops working right away.

Event IDs

Every step of an offer has an event ID. It is what you send as goal=. You choose it in the offer editor, next to the name and price of each step:

Use the event names of your tracker, for example install, level_10, or purchase. Then one postback URL covers every step: put the event macro of your tracker after goal=, for example goal={event}.
Letters, numbers, and _ . - are allowed, up to 32 characters. Upper and lower case do not matter.
If you leave it empty, the event ID is the number of the step: 1, 2, and so on.
A number also works as a fallback: goal=2 means the second step, unless another step has 2 as its event ID.

The editor shows the postback of every step while you type, and the offer page in your dashboard lists every event ID with a ready-to-copy URL.

Responses

Every answer is JSON. A 200 means we received the postback and you do not need to send it again:

result	Meaning
`credited`	The step was recorded and charged. `cost_usd` is the amount.
`waiting_for_balance`	The step was recorded, but your balance does not cover it. We charge it as soon as it does, and the offer is paused until then.
`duplicate`	This step was already recorded for this click. Nothing was charged again.
`reversed`	The conversion was taken back and `refund_usd` went back to your balance.
`already_reversed`	This conversion was taken back before.
`test`, `test_reversed`	A postback with a test click ID. Nothing was charged. See Testing your setup.

Errors have "ok": false, an error code, and a message that explains the fix:

HTTP	error	What to check
401	`invalid_key`	The key is missing or wrong. Copy the URL again from your dashboard.
404	`unknown_click`	We do not know this click ID for this offer. Send back the exact value we passed.
400	`goal_required`	The offer has more than one step. Add `goal=`.
400	`unknown_goal`	No step has this event ID. The message lists the valid ones.
400	`invalid_status`	Leave `status` out, or send `status=reversed`.
409	`click_expired`	The click is older than 30 days.
409	`offer_not_running`	The offer is not approved, or it was removed.
409	`country_not_targeted`	You removed the country of this user from the offer.
409	`too_late`	A reversal came more than 30 days after the conversion.
429	`rate_limited`	More than 600 postbacks per minute from your server. Retry after 60 seconds.

Retry only on timeouts, 429, and 5xx answers. Sending the same postback twice is safe: the second one returns duplicate.

Prices and charging

Every step has its own price. You set a default price per step, and you can change it for any country.
You pay for a step when its postback arrives, at the price for the country of the user. You never pay for steps that were not confirmed.
The offer is shown to users only while your balance covers every step of it for their country.
Each user can do an offer once, and each step counts once per user.

Reversals

If a conversion turns out to be invalid, for example after a refund or fraud, send the same postback with status=reversed added, within 30 days:

https://api.sharklio.com/v1/postback?key=YOUR_KEY&click_id=6acbabe4c079d1977cc6644398c630b5&goal=purchase&status=reversed

The price goes back to your balance, and the reward is taken back from the user. Reverse only invalid conversions: we review advertisers with unusually many reversals.

Testing your setup

On the offer page in your dashboard, under Test your integration, create a test click. It is valid for 7 days.
Open your tracking link with it, so you see that your tracker stores the click ID.
Send a postback for every step with the test click ID. The answer is "result": "test", and each step is ticked off on the offer page. Nothing is charged and no user is credited. You can test status=reversed the same way.

The offer page also lists the latest postbacks we received, with the result and the message of each one, and the Sources table shows which sites and apps your users come from. You can block a source there if its users do not convert.

Request

GETapi.sharklio.com/v1/postback

curl "https://api.sharklio.com/v1/postback?key=$OFFER_KEY&click_id=6acbabe4c079d1977cc6644398c630b5&goal=install"

$url = 'https://api.sharklio.com/v1/postback?' . http_build_query([
    'key' => $offerKey, 'click_id' => $clickId, 'goal' => 'install',
]);
$data = json_decode(file_get_contents($url), true);

const params = new URLSearchParams({ key: offerKey, click_id: clickId, goal: 'install' });
const res = await fetch(`https://api.sharklio.com/v1/postback?${params}`);
const data = await res.json();

r = requests.get(
    "https://api.sharklio.com/v1/postback",
    params={"key": offer_key, "click_id": click_id, "goal": "install"},
)
data = r.json()

Response 200

{
  "ok": true,
  "result": "credited",
  "message": "The conversion was recorded and $0.50 was charged.",
  "cost_usd": 0.5
}

Response 400

{
  "ok": false,
  "error": "unknown_goal",
  "message": "This offer has no step with goal=level10. The event IDs are: install, level_10, 3."
}