Skip to main content

SPAAdResponse

The top-level ad response object. Contains the JSON payload with ad products and tracking event details for each requested placement.

idstringrequired

Unique id of this ad response. Corresponds to the id (requestId) of the ad request.

Example: adb853c0-6df3-40e2-b243-efb1b56beb41
placement_responses object[]required

Array of PlacementResponse objects, each containing the ads returned for a corresponding placement_request.

FCC returns one entry per placement requested. Each entry carries the ranked ads and the pagination cursor for that placement.

  • Array [
    • placementstringrequired

    The request placement id this response corresponds to.

    Example: SEARCH
    ads object[]required

    The list of ads for this placement. FCC returns an empty array if no matching ads could be found.

  • Array [
    • positionintegerrequired

    The relative position of the ad in the response. This position begins with the offset of the ad request. Earlier positions indicate more relevant ads.

    skustringrequired

    The sku id (listing id) of the sponsored product ad.

    Example: 7109947_123
    product_idstringrequired

    The product id of the sponsored product ad.

    Example: 7109947
    product_group_idstring

    The product group id corresponding to the product ad.

    Example: 98745421
    tracking objectrequired

    The FCC Ad Manager tracking URLs for this ad. Contains the impression, view, and click URLs with placeholders for event-time substitution.

    impressionUrlstringrequired

    URL to fire on an impression. Replace [EVENTTIME] with epoch milliseconds before firing. see the Engagement Events API.

    Example: https://<tracker-domain>/v3/tr/impression?pl=...&iet=[EVENTTIME]
    viewUrlstringrequired

    URL to fire when the ad is viewable per publisher defined criteria. Replace [STARTTIME] with the view start epoch milliseconds and [ENDTIME] with the view end epoch milliseconds. see the Engagement Events API.

    Example: https://<tracker-domain>/v3/tr/view?pl=...&vst=[STARTTIME]&vet=[ENDTIME]
    clickUrlstringrequired

    URL to fire on a click. Replace [EVENTTIME] with epoch milliseconds before firing. see the Engagement Events API.

    Example: https://<tracker-domain>/v3/tr/click?pl=...&cet=[EVENTTIME]
  • ]
    • last_offsetintegerrequired

    Pagination cursor for the next request. To request the next page, increment the returned last_offset by 1 in the subsequent request.

    FCC returns -1 only when the request for the first page does not serve any ads. For all subsequent pages, if no new ads are found, last_offset remains at its previous value to indicate the end of the data stream.

  • ]
    • SPAAdResponse
    {
      "id": "adb853c0-6df3-40e2-b243-efb1b56beb41",
      "placement_responses": [
        {
          "placement": "SEARCH",
          "ads": [
            {
              "position": 0,
              "sku": "7109947_123",
              "product_id": "7109947",
              "product_group_id": "98745421",
              "tracking": {
                "impressionUrl": "https://<tracker-domain>/v3/tr/impression?pl=...&iet=[EVENTTIME]",
                "viewUrl": "https://<tracker-domain>/v3/tr/view?pl=...&vst=[STARTTIME]&vet=[ENDTIME]",
                "clickUrl": "https://<tracker-domain>/v3/tr/click?pl=...&cet=[EVENTTIME]"
              }
            }
          ],
          "last_offset": 0
        }
      ]
    }