Promotions via API (VAS) allow you to programmatically create, manage, and track promotions for the listings you manage on our platform. With this integration, you can automate the promotion process, saving time and effort for your users.

🚧

Not yet available for Imovirtual.

This technical documentation provides a comprehensive guide on promoting adverts via the Partner API. Promoting an advert increases its visibility and generates more leads. The promotions feature allows you to apply promotions to specific adverts managed by you on behalf of our mutual clients.

API Scopes

In order to use promotions via API, you will need to enable the new scopes write:vas and read:vas. Both should be present in your Application as the example below:

"scope": "read:adverts write:adverts read:leads write:vas read:vas"

❗️

New Scopes

• Check your Application Manager to confirm if your application already has these scope available. If not, request help from the API team.
• If you want to enable this feature to already authorized clients, they will need to authorize the new scope, by performing the authorization of API integration again.
• You can check your clients’ refresh tokens to see if they already authorized the new scopes, and inform them if they didn’t.

Get Available Promotions

Endpoint: GET {{domain}}/taxonomy/v1/promotions/urn:site:<target>

This endpoint lets you retrieve the available promotions taxonomy for agencies and developers. It provides information about the promotions, including their codes, descriptions, duration, and applicable account types. Remember to filter by the correct marketplace target: storiaro or otodompl.

This is the first step to enable Promotions via API.

Request

curl --location GET 'https://api.olxgroup.com/taxonomy/v1/promotions/urn:site:<target>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <YOUR API KEY>' \
--header 'User-Agent: <CRM NAME>'

Response

{
    "site": "urn:site:storiaro",
    "promotions": [
        {
            "promotion_code": "bump",
            "promotion_description": "Show your offer in the first place in the search results, for one raise.",
            "duration_days": [
                1
            ],
            "account_type": [
                "developer",
                "agency"
            ]
        },
        {
            "promotion_code": "homepage",
            "promotion_description": "This is an effective form of promotion for unique ads with beautiful photos, for x days.",
            "duration_days": [
                1,
                7,
                15
            ],
            "account_type": [
                "developer",
                "agency"
            ]
        },
      (...)

Applying a Promotion

Endpoint: POST {{domain}}/vas/v1/advert/{{advert_uuid}}

This endpoint allows you to apply a promotion to a specific advert on our client's behalf. Use this endpoint when you have a valid API key and a valid authorization bearer.

Request

curl --location POST 'https://api.olxgroup.com/vas/v1/advert/{{advert_uuid}}' \
--header 'Authorization: Bearer <basic_auth>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <YOUR API KEY>' \
--header 'User-Agent: <CRM NAME>'
--data '{
    "promotion_code": "homepage",
    "duration_days": 1
}'

You need to use following details to apply for a promotion:

Response/Acknowledge notification:

{
    "transaction_id": "{{transaction_id}}",
    "uuid": "{{advert_uuid}}", // deprecated, will be removed in the future in favor of the data.advert_uuid field
    "message": "Data is valid",
    "data": {
        "advert_uuid": "{{advert_uuid}}",
        "vas_uuid": "{{vas_uuid}}",
        "status": "requested"
    }
}

📘

Backwards Compatibility

You can find the uuid parameter present in some notifications. We will keep this parameter to have backward compatibility with the legacy version of the promotions system.

It will soon be discontinued, which means that you need to rely on advert_uuid/object_id instead.

From this message, save the transaction_id, advert_uuid, vas_uuid, and request status, to track VAS requests.

📘

Don't forget about webhook notifications!

Great, you're almost there! Prepare the webhook to handle VAS notifications to check if the request succeeded. This means that later you will receive on your Webhook URL the webhook notification that informs you if the promotion was successfully applied or not. Please refer to Value-Added-Services webhook page.

❗️

OLX Exports might have additional validations

When applying the OLX Export VAS, you should keep in mind that there can be different validation rules for the adverts. Sometimes the advert is successfully posted on the target site but not on OLX. Please confirm extra required validations here. If you get an error while applying your OLX promotion, most of the times you don't need to apply it again! The ad will automatically export after you fix the payload.

Get all Active Promotions for an Ad

Endpoint: GET {{domain}}/vas/v1/advert/{{advert_uuid}}

This endpoint allows you to retrieve the active promotions for a specific advert. It provides information about the active promotions and their expiration dates.

Request

curl --location GET 'https://api.olxgroup.com/vas/v1/advert/{{advert_uuid}}' \
--header 'Authorization: Bearer <basic_auth>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <YOUR API KEY>' \
--header 'User-Agent: <CRM NAME>'
--data ''

Response:

Response example when the advert has only one applied VAS.

{
    "transaction_id": "{{transaction_id}}",
    "message": "Data is valid",
    "data": {
        "uuid": "{{uuid}}",
        "vas": [
            {
                "uuid": "{{vas_uuid}}",
                "advert_uuid": "{{advert_uuid}}",
                "promotion_code": "bump",
                "status": "applied",
                "error": {},
                "custom_fields": {
                  "field": "value"
                },
                "created_at": "2023-06-27T08:43:53.266Z",
                "updated_at": "2023-06-27T08:44:26.857Z"
            }
        ]
    }
}