{"id":676,"date":"2024-01-08T11:52:51","date_gmt":"2024-01-08T11:52:51","guid":{"rendered":"https:\/\/olxdoc.wpenginepowered.com\/?p=676"},"modified":"2024-01-31T16:13:09","modified_gmt":"2024-01-31T16:13:09","slug":"applying-promotions","status":"publish","type":"post","link":"https:\/\/doc.olxgroup.com\/api\/?p=676","title":{"rendered":"Applying Promotions"},"content":{"rendered":"\n\n\t<h1>Applying Promotions<\/h1>\n<p>Promotions or Value-Added-Services (VAS)<\/p>\n\t<p>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.<\/p>\n\t<p>This technical documentation provides a comprehensive guide on\u00a0<strong>promoting adverts via the Partner API<\/strong>. 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.<\/p>\n\t<img decoding=\"async\" src=\"https:\/\/files.readme.io\/d9d057d-Screenshot_2023-07-26_at_12.11.11.png\" alt=\"Promotions flow\" \/>\n\t<h4>API Scopes<\/h4>\n<p>In order to use promotions via API, you will need to enable the new scopes<strong> write:vas<\/strong> and <strong>read:vas<\/strong>. Both should be present in your Application as the example below:<\/p>\n<strong class='bg-tag-blue font-bold tag'>JSON<\/strong>\n\t\n\t\t<code>\"scope\": \"read:adverts write:adverts read:leads write:vas read:vas\"\t\t\t<\/code>\n\t\t\n\t\t<button onclick=\"copyJson('copy_3839')\">Copy<\/button>\n\t\t&#8220;scope&#8221;: &#8220;read:adverts write:adverts read:leads write:vas read:vas&#8221;\n\t\tCopied to clipboard\n\t<p>\u2757\ufe0fNew Scopes<\/p>\n<ul>\n<li>Check your\u00a0<em>Application Manager<\/em>\u00a0to confirm if your application already has these scope available. If not, request help from the API team.<\/li>\n<li>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.<\/li>\n<li>You can check your clients&#8217; refresh tokens to see if they already authorized the new scopes, and inform them if they didn&#8217;t.<\/li>\n<\/ul>\n\t<h4><strong>Get Available Promotions<\/strong><\/h4>\n<p><strong>Endpoint<\/strong>: <strong>GET {{domain}}\/taxonomy\/v1\/promotions\/urn:site:&lt;target&gt;<\/strong><\/p>\n<p>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\u00a0<strong>target: storiaro or otodompl<\/strong>.<\/p>\n<p>This is the first step to enable Promotions via API.<\/p>\n<p><strong>Request<\/strong><\/p>\n\t\n\t\t<code>cURL\ncurl --location GET 'https:\/\/api.olxgroup.com\/taxonomy\/v1\/promotions\/urn:site:<target>' \n--header 'Accept: application\/json' \n--header 'Content-Type: application\/json' \n--header 'X-API-KEY: <your API KEY>' \n--header 'User-Agent: <crm NAME>'\t\t\t<\/crm><\/your><\/target><\/code>\n\t\t\n\t\t<button onclick=\"copyJson('copy_19799')\">Copy<\/button>\n\t\tcURL\ncurl &#8211;location GET &#8216;https:\/\/api.olxgroup.com\/taxonomy\/v1\/promotions\/urn:site:<target>&#8216; \n&#8211;header &#8216;Accept: application\/json&#8217; \n&#8211;header &#8216;Content-Type: application\/json&#8217; \n&#8211;header &#8216;X-API-KEY: <your API KEY>&#8216; \n&#8211;header &#8216;User-Agent: <crm NAME>&#8216;\n\t\tCopied to clipboard\n\t<p><strong>Response<\/strong><\/p>\n<strong class='bg-tag-gray font-bold tag'>JSON<\/strong>\n\t\n\t\t<code>{\n    \"site\": \"urn:site:storiaro\",\n    \"promotions\": [\n        {\n            \"promotion_code\": \"bump\",\n            \"promotion_description\": \"Show your offer in the first place in the search results, for one raise.\",\n            \"duration_days\": [\n                1\n            ],\n            \"account_type\": [\n                \"developer\",\n                \"agency\"\n            ]\n        },\n        {\n            \"promotion_code\": \"homepage\",\n            \"promotion_description\": \"This is an effective form of promotion for unique ads with beautiful photos, for x days.\",\n            \"duration_days\": [\n                1,\n                7,\n                15\n            ],\n            \"account_type\": [\n                \"developer\",\n                \"agency\"\n            ]\n        },\n      (...)\t\t\t<\/code>\n\t\t\n\t\t<button onclick=\"copyJson('copy_27293')\">Copy<\/button>\n\t\t{\n    &#8220;site&#8221;: &#8220;urn:site:storiaro&#8221;,\n    &#8220;promotions&#8221;: [\n        {\n            &#8220;promotion_code&#8221;: &#8220;bump&#8221;,\n            &#8220;promotion_description&#8221;: &#8220;Show your offer in the first place in the search results, for one raise.&#8221;,\n            &#8220;duration_days&#8221;: [\n                1\n            ],\n            &#8220;account_type&#8221;: [\n                &#8220;developer&#8221;,\n                &#8220;agency&#8221;\n            ]\n        },\n        {\n            &#8220;promotion_code&#8221;: &#8220;homepage&#8221;,\n            &#8220;promotion_description&#8221;: &#8220;This is an effective form of promotion for unique ads with beautiful photos, for x days.&#8221;,\n            &#8220;duration_days&#8221;: [\n                1,\n                7,\n                15\n            ],\n            &#8220;account_type&#8221;: [\n                &#8220;developer&#8221;,\n                &#8220;agency&#8221;\n            ]\n        },\n      (&#8230;)\n\t\tCopied to clipboard\n\t<h4><strong>Applying a Promotion<\/strong><\/h4>\n<p><strong>Endpoint<\/strong>: <strong>POST {{domain}}\/vas\/v1\/advert\/{{advert_uuid}}<\/strong><\/p>\n<p>This endpoint allows you to apply a promotion to a specific advert on our client&#8217;s behalf. Use this endpoint when you have a valid API key and a valid authorization bearer.<\/p>\n<p><strong>Request<\/strong><\/p>\n\t\n\t\t<code>cURL\ncurl --location POST 'https:\/\/api.olxgroup.com\/vas\/v1\/advert\/{{advert_uuid}}' \n--header 'Authorization: Bearer <basic_auth>' \n--header 'Accept: application\/json' \n--header 'Content-Type: application\/json' \n--header 'X-API-KEY: <your API KEY>' \n--header 'User-Agent: <crm NAME>'\n--data '{\n    \"promotion_code\": \"homepage\",\n    \"duration_days\": 1\n}'\t\t\t<\/crm><\/your><\/basic_auth><\/code>\n\t\t\n\t\t<button onclick=\"copyJson('copy_9371')\">Copy<\/button>\n\t\tcURL\ncurl &#8211;location POST &#8216;https:\/\/api.olxgroup.com\/vas\/v1\/advert\/{{advert_uuid}}&#8217; \n&#8211;header &#8216;Authorization: Bearer <basic_auth>&#8216; \n&#8211;header &#8216;Accept: application\/json&#8217; \n&#8211;header &#8216;Content-Type: application\/json&#8217; \n&#8211;header &#8216;X-API-KEY: <your API KEY>&#8216; \n&#8211;header &#8216;User-Agent: <crm NAME>&#8216;\n&#8211;data &#8216;{\n    &#8220;promotion_code&#8221;: &#8220;homepage&#8221;,\n    &#8220;duration_days&#8221;: 1\n}&#8217;\n\t\tCopied to clipboard\n\t<p>You need to use following details to apply for a promotion:<\/p>\n<table>\n<thead>\n<tr>\n<th>Field<\/th>\n<th>Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td><code tabindex=\"0\" data-lang=\"\">promotion_code<\/code><\/td>\n<td>Code\/name of the promotion. In the example, homepage.<br \/>\nCheck the &#8220;Get Available Promotions&#8221; section for more available promotions.<\/td>\n<\/tr>\n<tr>\n<td><code tabindex=\"0\" data-lang=\"\">duration_days<\/code><\/td>\n<td>Duration days represent the validity of the promotion.<br \/>\nIn this case, the advert will be displayed on the homepage for 1 day.<br \/>\nNote: not all promotions require this field.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n\t<p><strong>Response\/Acknowledge notification<\/strong>:<\/p>\n\t\n\t\t<code>Json\n{\n    \"transaction_id\": \"{{transaction_id}}\",\n    \"uuid\": \"{{advert_uuid}}\", \/\/ deprecated, will be removed in the future in favor of the data.advert_uuid field\n    \"message\": \"Data is valid\",\n    \"data\": {\n        \"advert_uuid\": \"{{advert_uuid}}\",\n        \"vas_uuid\": \"{{vas_uuid}}\",\n        \"status\": \"requested\"\n    }\n}\t\t\t<\/code>\n\t\t\n\t\t<button onclick=\"copyJson('copy_31544')\">Copy<\/button>\n\t\tJson\n{\n    &#8220;transaction_id&#8221;: &#8220;{{transaction_id}}&#8221;,\n    &#8220;uuid&#8221;: &#8220;{{advert_uuid}}&#8221;, \/\/ deprecated, will be removed in the future in favor of the data.advert_uuid field\n    &#8220;message&#8221;: &#8220;Data is valid&#8221;,\n    &#8220;data&#8221;: {\n        &#8220;advert_uuid&#8221;: &#8220;{{advert_uuid}}&#8221;,\n        &#8220;vas_uuid&#8221;: &#8220;{{vas_uuid}}&#8221;,\n        &#8220;status&#8221;: &#8220;requested&#8221;\n    }\n}\n\t\tCopied to clipboard\n\t<table>\n<thead>\n<tr>\n<th>Field<\/th>\n<th>Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td><strong>transaction_id<\/strong><\/td>\n<td>Transaction id uniquely identifies this request.<\/td>\n<\/tr>\n<tr>\n<td><strong>uuid<\/strong><\/td>\n<td>Deprecated field. Same as <strong>advert_uuid<\/strong>\u00a0for backwards compatibility purposes.<\/td>\n<\/tr>\n<tr>\n<td><strong>advert_uuid<\/strong><\/td>\n<td>Advert id to which you applied the promotion.<\/td>\n<\/tr>\n<tr>\n<td><strong>vas_uuid<\/strong><\/td>\n<td>Promotion unique id. Used to track the end-to-end process more accurately.<\/td>\n<\/tr>\n<tr>\n<td><strong>status<\/strong><\/td>\n<td>Request status: <strong>requested\u00a0<\/strong>means that the promotion is in process.<br \/>\nAt this stage, approved requests will have this status.<br \/>\nRead more about the existing\u00a0<a href=\"https:\/\/developer.olxgroup.com\/docs\/promotion-status\" target=\"_self\" rel=\"noopener\">Promotion Status<\/a>.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n\t<p>From this message, save the <strong>transaction_id<\/strong>, <strong>advert_uuid<\/strong>, <strong>vas_uuid<\/strong>, and request <strong>status<\/strong>, to track VAS requests.<\/p>\n\t<p>From this message, save the\u00a0<code tabindex=\"0\" data-lang=\"\">transaction_id<\/code>,\u00a0<code tabindex=\"0\" data-lang=\"\">advert_uuid<\/code>,\u00a0<code tabindex=\"0\" data-lang=\"\">vas_uuid<\/code>, and request\u00a0<code tabindex=\"0\" data-lang=\"\">status<\/code>, to track VAS requests.<\/p>\n\t<p>Great, you&#8217;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\u00a0<strong>webhook notification<\/strong>\u00a0that informs you if the promotion was successfully applied or not. Please refer to\u00a0<a href=\"https:\/\/developer.olxgroup.com\/docs\/value-added-services\" target=\"_self\" rel=\"noopener\">Value-Added-Services webhook page<\/a>.<\/p>\n\t\u2757\ufe0f<strong>OLX Exports might have additional validations<\/strong>\nWhen 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\u00a0<a href=\"https:\/\/developer.olxgroup.com\/docs\/validations-required-for-olx-export\" target=\"_self\" rel=\"noopener\">here<\/a>.\u00a0<strong>If you get an error while applying your OLX promotion, most of the time you don&#8217;t need to apply it again! The ad will automatically export after you fix the payload.<\/strong>\n\t<h3>Get all Active Promotions for an Ad<\/h3>\n<p><strong>Endpoint<\/strong>: <strong>GET {{domain}}\/vas\/v1\/advert\/{{advert_uuid}}<\/strong><\/p>\n\t<p>This endpoint allows you to retrieve the active promotions for a specific advert. It provides information about the active promotions and their expiration dates.<\/p>\n\t<p><strong>Request<\/strong><\/p>\n\t\n\t\t<code>cURL\ncurl --location GET 'https:\/\/api.olxgroup.com\/vas\/v1\/advert\/{{advert_uuid}}' \n--header 'Authorization: Bearer <basic_auth>' \n--header 'Accept: application\/json' \n--header 'Content-Type: application\/json' \n--header 'X-API-KEY: <your API KEY>' \n--header 'User-Agent: <crm NAME>'\n--data ''\t\t\t<\/crm><\/your><\/basic_auth><\/code>\n\t\t\n\t\t<button onclick=\"copyJson('copy_26985')\">Copy<\/button>\n\t\tcURL\ncurl &#8211;location GET &#8216;https:\/\/api.olxgroup.com\/vas\/v1\/advert\/{{advert_uuid}}&#8217; \n&#8211;header &#8216;Authorization: Bearer <basic_auth>&#8216; \n&#8211;header &#8216;Accept: application\/json&#8217; \n&#8211;header &#8216;Content-Type: application\/json&#8217; \n&#8211;header &#8216;X-API-KEY: <your API KEY>&#8216; \n&#8211;header &#8216;User-Agent: <crm NAME>&#8216;\n&#8211;data &#8221;\n\t\tCopied to clipboard\n\t<p><strong>Response<\/strong>:<\/p>\n<p>Response example when the advert has only one applied VAS.<\/p>\n\t\n\t\t<code>Json\n{\n    \"transaction_id\": \"{{transaction_id}}\",\n    \"message\": \"Data is valid\",\n    \"data\": {\n        \"uuid\": \"{{uuid}}\",\n        \"vas\": [\n            {\n                \"uuid\": \"{{vas_uuid}}\",\n                \"advert_uuid\": \"{{advert_uuid}}\",\n                \"promotion_code\": \"bump\",\n                \"status\": \"applied\",\n                \"error\": {},\n                \"custom_fields\": {\n                  \"field\": \"value\"\n                },\n                \"created_at\": \"2023-06-27T08:43:53.266Z\",\n                \"updated_at\": \"2023-06-27T08:44:26.857Z\"\n            }\n        ]\n    }\n}\t\t\t<\/code>\n\t\t\n\t\t<button onclick=\"copyJson('copy_29420')\">Copy<\/button>\n\t\tJson\n{\n    &#8220;transaction_id&#8221;: &#8220;{{transaction_id}}&#8221;,\n    &#8220;message&#8221;: &#8220;Data is valid&#8221;,\n    &#8220;data&#8221;: {\n        &#8220;uuid&#8221;: &#8220;{{uuid}}&#8221;,\n        &#8220;vas&#8221;: [\n            {\n                &#8220;uuid&#8221;: &#8220;{{vas_uuid}}&#8221;,\n                &#8220;advert_uuid&#8221;: &#8220;{{advert_uuid}}&#8221;,\n                &#8220;promotion_code&#8221;: &#8220;bump&#8221;,\n                &#8220;status&#8221;: &#8220;applied&#8221;,\n                &#8220;error&#8221;: {},\n                &#8220;custom_fields&#8221;: {\n                  &#8220;field&#8221;: &#8220;value&#8221;\n                },\n                &#8220;created_at&#8221;: &#8220;2023-06-27T08:43:53.266Z&#8221;,\n                &#8220;updated_at&#8221;: &#8220;2023-06-27T08:44:26.857Z&#8221;\n            }\n        ]\n    }\n}\n\t\tCopied to clipboard\n\t<table>\n<thead>\n<tr>\n<th>Field<\/th>\n<th>Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td><code tabindex=\"0\" data-lang=\"\">transaction_id<\/code><\/td>\n<td>Transaction id uniquely identifies this request.<\/td>\n<\/tr>\n<tr>\n<td><code tabindex=\"0\" data-lang=\"\">advert_uuid<\/code><\/td>\n<td>Advert id to which you applied the promotion.<\/td>\n<\/tr>\n<tr>\n<td><code tabindex=\"0\" data-lang=\"\">vas_uuid<\/code><\/td>\n<td>Promotion unique id. Used to track the end-to-end process more accurately.<\/td>\n<\/tr>\n<tr>\n<td><code tabindex=\"0\" data-lang=\"\">status<\/code><\/td>\n<td>Promotion status. Read more about the existing\u00a0<a href=\"https:\/\/developer.olxgroup.com\/docs\/promotion-status\" target=\"_self\" rel=\"noopener\">Promotion Status<\/a>.<\/td>\n<\/tr>\n<tr>\n<td><code tabindex=\"0\" data-lang=\"\">error<\/code><\/td>\n<td>Error description if promotion is not successfully applied. The error is empty when the promotion was successfully applied.<\/td>\n<\/tr>\n<tr>\n<td><code tabindex=\"0\" data-lang=\"\">custom_fields<\/code><\/td>\n<td>Additional fields related to the VAS. Might include fields such as <strong>olx_url<\/strong> for the URL of the advert on OLX (for <strong>olx\u00a0<\/strong>VAS only). Read more the existing\u00a0<a href=\"https:\/\/developer.olxgroup.com\/docs\/promotion-custom-fields\" target=\"_self\" rel=\"noopener\">Custom Fields<\/a>.<\/td>\n<\/tr>\n<tr>\n<td><code tabindex=\"0\" data-lang=\"\">promotion_code<\/code><\/td>\n<td>Promotion code used on the initial request.<\/td>\n<\/tr>\n<tr>\n<td><code tabindex=\"0\" data-lang=\"\">duration<\/code><\/td>\n<td>Promotion duration used on the initial request.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/crm><\/your><\/basic_auth><\/crm><\/your><\/basic_auth><\/crm><\/your><\/target>\n","protected":false},"excerpt":{"rendered":"<p>Applying Promotions Promotions or Value-Added-Services (VAS) 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. This technical documentation provides a comprehensive guide on\u00a0promoting adverts via the Partner&#8230;  <a href=\"https:\/\/doc.olxgroup.com\/api\/?p=676\" title=\"Read Applying Promotions\">Read more &raquo;<\/a><\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[44],"tags":[],"acf":[],"_links":{"self":[{"href":"https:\/\/doc.olxgroup.com\/api\/index.php?rest_route=\/wp\/v2\/posts\/676"}],"collection":[{"href":"https:\/\/doc.olxgroup.com\/api\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/doc.olxgroup.com\/api\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/doc.olxgroup.com\/api\/index.php?rest_route=\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/doc.olxgroup.com\/api\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=676"}],"version-history":[{"count":0,"href":"https:\/\/doc.olxgroup.com\/api\/index.php?rest_route=\/wp\/v2\/posts\/676\/revisions"}],"wp:attachment":[{"href":"https:\/\/doc.olxgroup.com\/api\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=676"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/doc.olxgroup.com\/api\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=676"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/doc.olxgroup.com\/api\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=676"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}