> For the complete documentation index, see [llms.txt](https://developers-commerce.projectagora.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-commerce.projectagora.com/integration-guides/product-listing-ad-integration-guide/requesting-a-home-page-product-ad.md).

# Requesting a Home Page Product Ad

Home Page ads require a simple "context' to be sent to Project Agora Commerce. A "context" is a bit of code that defines the conditions under which a product is shown to a customer.

### Context:

Below are the values needed to generate a home page ad:

{% tabs %}
{% tab title="HTTP" %}

```yaml
POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_here
{
    "pageType": "Home",
    "catalogId": "$MY_CATALOG_ID",
    "productFilters": [["placement:SponsoredProducts"]],
    "maxNumberOfAds": number
}
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic your_api_key_here" \
-d \
'{
    "pageType": "Home",
    "catalogId": "$MY_CATALOG_ID",
    "productFilters": [["placement:SponsoredProducts"]],
    "maxNumberOfAds": number
}'
```

{% endtab %}
{% endtabs %}

### Exemplar Context

Here is an example of a context for the `pageType "Home"`:

{% tabs %}
{% tab title="HTTP" %}

```yaml
POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "pageType": "Home",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [["placement:SponsoredProducts"]],
    "maxNumberOfAds": 3
}
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
    "pageType": "Home",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [["placement:SponsoredProducts"]],
    "maxNumberOfAds": 3
}'
```

{% endtab %}
{% endtabs %}

### **What Happens when an Ad Is Successfully Requested**

When you successfully request an ad, you receive the following object:

{% tabs %}
{% tab title="HTTP" %}

```yaml
HTTP/2 200
{
    "ads": [
        {
            "id": "display_SEY2W7-VZzspoirbw4ANs-r-w6YyODk5MDQ5UA==",
            "gtin": "catpref--2899049P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516943179Z"
        },
        {
            "id": "display_-hPcUdg5KUQ2sxhE6r0XVN3-iLY5ODkxNTY2UA==",
            "gtin": "catpref--9891566P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516948637Z"
        },
        {
            "id": "display_aGULlK-E_yEiVZ_S_jH9qsH-KhYyOTAyNjIwUA==",
            "gtin": "catpref--2902620P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516953955Z"
        }
    ],
    "banners": [],
    "products": []
}
```

{% endtab %}

{% tab title="cURL" %}

```yaml
{
    "ads": [
        {
            "id": "display_SEY2W7-VZzspoirbw4ANs-r-w6YyODk5MDQ5UA==",
            "gtin": "catpref--2899049P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516943179Z"
        },
        {
            "id": "display_-hPcUdg5KUQ2sxhE6r0XVN3-iLY5ODkxNTY2UA==",
            "gtin": "catpref--9891566P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516948637Z"
        },
        {
            "id": "display_aGULlK-E_yEiVZ_S_jH9qsH-KhYyOTAyNjIwUA==",
            "gtin": "catpref--2902620P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516953955Z"
        }
    ],
    "banners": [],
    "products": []
}
```

{% endtab %}
{% endtabs %}

No customer information or cart items are necessary in this simple context. The simple context consists only of necessary filters. 

{% hint style="info" %}
The `discount` and `products` fields are legacy and can be ignored
{% endhint %}

{% hint style="info" %}
The static filter`placement:SponsoredProducts should be included in all SPL requests`
{% endhint %}

{% hint style="info" %}
In gtin field of the above responses you will get the pa\_id as in the product feed for the product to be displayed. 

**Reminder**: the pa\_id is the concatenation of the catalog prefix and each product SKU, so to identify which SKU to display on your side you may need to remove the catalog prefix and the symbols "--"

pa\_id= catprefix--**SKU**
{% endhint %}

{% hint style="info" %}
If you are unsure of the strings displayed on this page. Take a look at the Reference page.
{% endhint %}