Admin API: offers

This page covers 22 methods for working with offers. All of them require a token with Full access («Полный доступ») (full). Authorization is described on the Admin API: overview and authorization page, and the request format and common error codes on the Request, response and error format page.

Offer object

The list, read, create, edit and copy methods return an offer in the same form.

Delivery types, payout models and statuses are explained on the Offers page, the cap and the fallback offer on the Daily sales cap and fallback offer page, and php_network on the PHP in hosted pages and network access page.

The fixed payout payout is recorded in the currency from the currency field and does not depend on the currency parameter of the postback. For an amount from the postback, the offer currency is used only if the network did not send its own currency. If currency holds a currency other than USD, it needs an exchange rate: without one, postbacks for an offer with a fixed payout get 422 with code currency_rate. Rates and conversion are covered on the Currencies and rates page.

payout_param applies to the incoming postback. Conversion import from CSV always takes the amount from the payout column.

If there is no offer with the given id, any method with {id} in its address responds 404 with code not_found. For an id that is not in UUID format, the response is 400 with code bad_request.

Offers

List offers

GET /api/v1/offers

Returns an array of offers, newest first. There are no parameters and no pagination. Deleted offers are not included. Response — code 200.

Get an offer

GET /api/v1/offers/{id}

Returns one offer. Response — code 200.

Create an offer

POST /api/v1/offers

Creates an offer. The user who created the token becomes its owner.

The other fields from the Offer object section, except id, seq and owner_id, are optional. Omitted fields get their default values.

curl -X POST https://panel.example.com/api/v1/offers \
  -H "Api-Key: <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Offer PL","url":"https://offer.example.com/?sub={subid}","payout":12.5,"country":"PL","daily_cap":50,"cap_timezone":"Europe/Warsaw"}'

Response — code 201 and the created offer.

Errors with code 422 and validation:

Edit an offer

PUT /api/v1/offers/{id}

Changes the fields you pass. Fields that are not in the body keep their current values. A null value clears country, daily_cap, network_id and overflow_offer_id. The group is removed with an empty string in group_name, and the values with an empty array in values. An empty string in storage, delivery_type, payout_type, payout_param, currency and state keeps the previous value, and in cap_timezone it sets UTC back.

The fields and errors are the same as when creating. The checks apply to the resulting offer. Response — code 200 and the updated offer.

Delete an offer

DELETE /api/v1/offers/{id}

Moves the offer and its files to the trash. Response — code 204 with no body. Restoring is described on the Admin API: trash page.

Copies and access

Clone an offer

POST /api/v1/offers/{id}/clone

Creates a copy of the offer. The suffix “ (copy)” (« (копия)») is added to the name. For a hosted offer, the files are copied too.

Response — code 201 and the new offer.

Give copies to team members

POST /api/v1/offers/{id}/share-clone

Creates a separate copy of the offer for each team member in the list. The copy's name is the same as the original's, and the files of a hosted offer are copied.

Response — code 200 and an object with a results array. Each element has user_id, login and the offer_id of the new copy. If a copy could not be created, error comes instead of offer_id: “user not found” («пользователь не найден»), “could not clone” («не удалось клонировать») or “could not copy the files” («не удалось скопировать файлы»).

An empty list gives 422 with the message “no team member selected” («не выбран ни один сотрудник»).

Who the offer is shared with

GET /api/v1/offers/{id}/shares

Returns an object with a user_ids array — the users the offer is shared with for viewing. Response — code 200.

Share the offer with users

POST /api/v1/offers/{id}/shares

Replaces the list entirely. An empty array closes access for everyone.

Response — code 204 with no body.

Offer groups

A group is the value of the group_name field. To add an offer to a group, pass the group name in group_name when you create or edit the offer. Separate methods rename and delete a group across all its offers at once.

Rename a group

PUT /api/v1/offer-groups?name=<current name>

curl -X PUT "https://panel.example.com/api/v1/offer-groups?name=Nutra" \
  -H "Api-Key: <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Nutra PL"}'

Response — code 200 and {"updated": 4}, where the number is how many offers were changed.

Delete a group

DELETE /api/v1/offer-groups?name=<name>

Removes the group from the offers. The offers themselves stay. No body is needed. Response — code 200 and {"updated": N}.

Errors of both methods — 422 with code validation: “name is required” («name обязателен») if the parameter is missing from the address. Renaming has two more: “invalid request body” («некорректное тело запроса») if the body is not a JSON object, and “new group name is required” («новое имя группы обязательно») if the name in the body is empty.

Hosted offer files

File paths are given relative to the offer folder, separated by /, for example css/style.css. After the first upload of an archive or file, or the first file save, the offer switches to storage: local. How the tracker serves such pages is described on the Hosted pages page.

Upload an archive

POST /api/v1/offers/{id}/upload

Accepts a ZIP as multipart/form-data and replaces all of the offer's files with it. The offer's lead log is kept.

curl -X POST https://panel.example.com/api/v1/offers/7c9e6679-7425-40de-944b-e07fc1f90ae7/upload \
  -H "Api-Key: <token>" \
  -F "[email protected]"

If the offer already had files, they are saved as a version before the replacement.

Response — code 200 and an object with a files array. A list element: path — the path, size — the size in bytes, dir — always false. The list is sorted by path; folders are not listed as separate rows.

If the archive is not accepted, the offer's previous files stay in place. Limits and errors are listed in the Upload limits and errors section.

List files

GET /api/v1/offers/{id}/files

Returns an object with a files array in the same form. For an offer without files, the array is empty. Response — code 200.

Add more files

POST /api/v1/offers/{id}/files

Adds files to the ones already uploaded, format — multipart/form-data. A file with the same path is replaced; the others are not affected.

Response — code 200 and an object: files — the full list of files, saved — the paths of the saved files, storage — local.

Read a file

GET /api/v1/offers/{id}/file?path=<path>

Returns the contents of a file up to 5 MB in size.

Response — code 200 and an object: path, content — the contents as a string, utf8 — false if the file is not UTF-8 text.

Save a file

PUT /api/v1/offers/{id}/file

Creates or overwrites a text file. The body is JSON.

Response — code 200 and {"ok": true, "storage": "local"}.

Delete a file

DELETE /api/v1/offers/{id}/file?path=<path>

Deletes one file. Response — code 204 with no body.

Rename a file

POST /api/v1/offers/{id}/rename

Renames a file or moves it to another folder. A file that already exists at the new path is not overwritten. The leads.php lead log and names starting with a dot are not renamed: the response is 400.

Response — code 200 and {"ok": true}. Without one of the fields — 400 with the message “the source and new path are required” («нужны исходный и новый путь»).

File method errors

Versions and archive

A version is a saved copy of the offer's files. The tracker keeps the offer's 10 latest versions; older ones are deleted when a new one is saved. The lead log and files whose names start with a dot are not included in versions or in the archive. Saving a version and downloading the archive are meant for an offer that has files. Working with versions in the panel is described on the File editor, versions and export page.

List versions

GET /api/v1/offers/{id}/versions

Returns an array of versions, newest first. Fields: id, created_at — creation time in UTC, size — size in bytes. If there are no versions, the array is empty. Response — code 200.

Save a version

POST /api/v1/offers/{id}/versions

Saves the current files as a new version. No body is needed. Response — code 201 and the version object.

Restore a version

POST /api/v1/offers/{id}/versions/{version}/restore

Replaces the offer's files with the files of the version. Put the id from the version list into {version}. Before the replacement, the current files are saved as a new version. The lead log stays in place. No body is needed. Response — code 200 and {"ok": true}.

Download the archive

GET /api/v1/offers/{id}/archive

Returns the offer's current files as a single ZIP file, page.zip. Response — code 200 with the application/zip type.

curl https://panel.example.com/api/v1/offers/7c9e6679-7425-40de-944b-e07fc1f90ae7/archive \
  -H "Api-Key: <token>" \
  -o page.zip

Saving a version and downloading the archive respond 413 if the offer has more than 10,000 files or more than 1 GB.

Upload limits and errors

Archive requirements are on the Hosted pages page.