Line Item Creatives

Overview

Line Item Creatives associate a Creative to a line item. If a creative support product mappings, the creative’s product collections define product placements within the creative. For more information on creative discovery (including product collection requirements), see Creative Search.

Endpoints

Method	Endpoint	Description
`GET`	`/line-items/{lineItemId}/creatives`	Retrieve the creatives and creative product collections associated with a line item.
`POST`	`/line-items/{lineItemId}/creatives/upsert`	Link creatives and creative product collections to a line item.
`POST`	`/line-items/{lineItemId}/creatives/delete`	Remove linked creatives and their creative product collections from a line item.

Fetch Line Item Creatives

Retrieve the creatives and associated creative product collections on an Onsite Display Auction line item.

Path parameters

Parameter	Required	Description
`line-item-id`	Yes	The ID of the line item whose creatives and product collections will be returned.

Response attributes

The resource type is LineItemCreatives.

Attribute	Description
`mediaType`	The line item’s media type. Possible values are `Display`, `Video` or `null`. Creatives associated to the line item match this value.
`creatives`	Creatives associated with the line item. The array is empty when the line item has no creatives.
`creatives[].creative.id`	ID of the creative.
`creatives[].creative.modifiedAt`	Indicates when the associated creative revision was created.
`creatives[].approvalStatus`	Approval status of the creative. Possible values are `Unknown`, `Approved`, `AutoApproved`, `InReview`, `Rejected`, `AutoRejected`, and `Unsubmitted`.
`creatives[].creativePreviewCode`	Creative Live Demo preview code. It is `null` when a preview code is not available.
`creatives[].creativeProductCollections`	Ordered creative product collections.
`creatives[].creativeProductCollections[].isMandatory`	Whether the collection is mandatory for serving.
`creatives[].creativeProductCollections[].products`	Ordered products in the collection.
`creatives[].creativeProductCollections[].products[].id`	ID of the product.
`creatives[].creativeProductCollections[].products[].approvalStatus`	Approval status of the product. Possible values are `Unknown`, `Approved`, `AutoApproved`, `InReview`, `Rejected`, `AutoRejected`, and `Unsubmitted`.

Sample response

A successful response returns a 200 OK.

Example response (200)

{
  "data": {
    "type": "LineItemCreatives",
    "attributes": {
      "mediaType": "Display",
      "creatives": [
        {
          "creative": {
            "id": "creative-a",
            "modifiedAt": "2026-08-20T12:00:00Z"
          },
          "approvalStatus": "Approved",
          "creativePreviewCode": null,
          "creativeProductCollections": [
            {
              "isMandatory": true,
              "products": [
                {
                  "id": "product-1",
                  "approvalStatus": "Approved"
                },
                {
                  "id": "product-2",
                  "approvalStatus": "InReview"
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

When the line item has no associated creatives, lineItemCreatives is empty and mediaType is null:

Example response (200)

{
  "data": {
    "type": "LineItemCreatives",
    "attributes": {
      "mediaType": null,
      "creatives": []
    }
  }
}

Caveat

The response can contain the same creative.id more than once when approved and proposed revisions of that creative are associated with the line item. Use creative.modifiedAt to distinguish the revisions.

For example, the response below contains approved and proposed revisions of the same creative:

Example response (200)

{
  "data": {
    "type": "LineItemCreatives",
    "attributes": {
      "mediaType": "Video",
      "creatives": [
        {
          "creative": {
            "id": "creative-a",
            "modifiedAt": "2026-08-20T12:00:00Z"
          },
          "approvalStatus": "Approved",
          "creativePreviewCode": null,
          "creativeProductCollections": [
            {
              "products": [
                {
                  "id": "product-1",
                  "approvalStatus": "Approved"
                }
              ],
              "isMandatory": true
            }
          ]
        },
        {
          "creative": {
            "id": "creative-a",
            "modifiedAt": "2026-08-22T17:00:00Z"
          },
          "approvalStatus": "InReview",
          "creativePreviewCode": null,
          "creativeProductCollections": [
            {
              "products": [
                {
                  "id": "product-1",
                  "approvalStatus": "Approved"
                }
              ],
              "isMandatory": true
            }
          ]
        }
      ]
    }
  }
}

Errors

HTTP status	Code	Description
`400`	`unsupported-line-item-type`	The target is not an Onsite Display Auction line item.
`401`	`unauthenticated`	The caller is not authenticated.
`403`	`forbidden`	The caller cannot access the target line item, or the line item does not exist.
`503`	`service-unavailable`	A service required to process the request is temporarily unavailable. Retry the request later.

Upsert Line Item Creatives

Associate one or more creatives to a line item, and define the creative’s product collections. If the creative is already mapped to the line item, the association will be updated instead of duplicated. Existing line item creatives that are omitted from the request are unmodified.

Path parameters

Parameter	Required	Description
`line-item-id`	Yes	The ID of the line item to associate the creatives and product collections.

Request attributes

The resource type is Creatives.

Attribute	Required	Description
`creativeType`	Yes	Type of creative being added or updated. Currently, the only accepted value is `AuctionCreative`. It must match the buy type of the target line item.
`auctionCreativeDetails`	Required when `creativeType` is `AuctionCreative`, otherwise it is rejected.	Auction-specific creative configuration.
`auctionCreativeDetails.lineItemCreatives`	Required when `creativeType` is `AuctionCreative`, otherwise it is rejected.	Array of Line Item Creative objects to add or update. An auction line item can have at most 20 associated creatives.

Line Item Creative Attributes

Attribute	Required	Description
`creative.id`	Yes	ID of an existing creative available to the line item’s account and retailer. If the creative id is already mapped to the line item, then the line item creative is updated instead of duplicated.
`creativeProductCollections`	Yes	Complete ordered array of creative product collections for the creative. The supplied array replaces the existing collections. Send an empty array to remove all collections or when the line item uses Dynamic Match.
`creativeProductCollections[].isMandatory`	Required for each collection	Whether the collection is mandatory for serving.
`creativeProductCollections[].products`	Required for each collection	Ordered products in the collection. A product cannot appear more than once in the same collection.
`creativeProductCollections[].products[].id`	Required for each product	ID of a product in the retailer catalog. Products that are not already in the line item’s product pool are added automatically. Products added are subject to the same validation as when using the Line Item Products endpoints.

Sample Auction Creative request

Example request

{
  "data": {
    "type": "Creatives",
    "attributes": {
      "creativeType": "AuctionCreative",
      "auctionCreativeDetails": {
        "lineItemCreatives": [
          {
            "creative": {
              "id": "123"
            },
            "creativeProductCollections": [
              {
                "isMandatory": false,
                "products": [
                  {
                    "id": "product-1"
                  },
                  {
                    "id": "product-2"
                  }
                ]
              },
              {
                "isMandatory": false,
                "products": [
                  {
                    "id": "product-2"
                  },
                  {
                    "id": "product-3"
                  }
                ]
              }
            ]
          }
        ]
      }
    }
  }
}

Response attributes

Attribute	Description
`mediaType`	`Display` or `Video`. The line item media type is set based on the creative provided. Creatives associated to the line item must have the same media type.
`auctionCreativeDetails.lineItemCreatives`	Contains the accepted auction creatives from the request. The other creatives associated to the line item are not included in the response.
`creative.id`	ID of the creative.
`creative.modifiedAt`	Indicates when the associated creative was last modified.
`approvalStatus`	The approval status of the creative associated to the line item.
`creativePreviewCode`	The Creative Live Demo preview code of the associated creative. Will be null if the retailer does not support this feature.
`creativeProductCollections`	The ordered product collections of the associated creative.
`creativeProductCollections[].isMandatory`	Whether the collection is mandatory for serving.
`creativeProductCollections[].products`	The ordered products in the collection.
`creativeProductCollections[].products[].id`	ID of the product.
`creativeProductCollections[].products[].approvalStatus`	The approval status of the product.

Sample Auction Creative response

A successful Upsert request returns a 200 OK

Example response (200)

{
  "data": {
    "type": "Creatives",
    "attributes": {
      "mediaType": "Display",
      "auctionCreativeDetails": {
        "lineItemCreatives": [
          {
            "creative": {
              "id": "123",
              "modifiedAt": "2026-08-13T14:30:00Z"
            },
            "approvalStatus": "Unsubmitted",
            "creativePreviewCode": "preview-code",
            "creativeProductCollections": [
              {
                "isMandatory": false,
                "products": [
                  {
                    "id": "product-1",
                    "approvalStatus": "Approved"
                  },
                  {
                    "id": "product-2",
                    "approvalStatus": "Rejected"
                  }
                ]
              },
              {
                "isMandatory": false,
                "products": [
                  {
                    "id": "product-2",
                    "approvalStatus": "Rejected"
                  },
                  {
                    "id": "product-3",
                    "approvalStatus": "Approved"
                  }
                ]
              }
            ]
          }
        ]
      }
    }
  }
}

Errors

This endpoint does not support partial success. When one or more creative fail validation, the response will contain entries in the errors array.

HTTP status	Code	Description
`400`	`creatives-required`	No creative was supplied for the selected `creativeType`.
`400`	`invalid-creative-id`	A creative ID is missing or invalid.
`400`	`duplicate-creative-id`	The same creative ID appears more than once in the request.
`400`	`invalid-creative-type`	The requested `creativeType` does not match the line item buy type, or its corresponding details object was not supplied.
`400`	`creative-unavailable`	A creative is not available to the line item’s account or retailer.
`400`	`invalid-media-type`	The submitted creatives have different media types or do not match the line item’s media type.
`400`	`invalid-creative-product-collections`	creative product collections must be empty when the line item uses Dynamic Match.
`400`	`invalid-product-collection`	A Creative Product Collection contains the same product ID more than once.
`400`	`invalid-product-id`	A Creative Product Collection contains a product that is not available in the retailer catalog.
`400`	`too-many-products`	Adding the referenced products would exceed the line item’s 1,500-product limit.
`400`	`too-many-creatives`	Adding the submitted creatives would exceed the line item’s creative limit. Up to 20 creatives can be attached to an Onsite Display Auction line item.
`400`	`unsupported-line-item-type`	The line item buy type is not currently supported.
`401`	`unauthenticated`	The caller is not authenticated.
`403`	`forbidden`	The caller cannot modify the target line item, or the line item does not exist.
`500`	`internal-error`	An unexpected error occurred.
`503`	`service-unavailable`	A service required to process the request is temporarily unavailable. Retry the request later.

Delete Line Item Creatives

Remove one or more creative, and associated creative product collections, from an Onsite Display Auction line item. Removing the creative’s association from a line item does not delete the Creative resource itself.

Path parameters

Parameter	Required	Description
`line-item-id`	Yes	The ID of the line item from which to remove the creatives and product collections.

Request attributes

The resource type is Creatives.

Attribute	Required	Description
`creativeIds`	Yes	IDs of the creatives to remove from the line item. At least one ID is required, and a single request accepts at most 20 IDs. Creatives will be removed regardless of approval status.

Sample request

Example request

{
  "data": {
    "type": "Creatives",
    "attributes": {
      "creativeIds": [
        "creativeId1",
        "creativeId3"
      ]
    }
  }
}

Sample responses

A successful delete returns 200 OK. When one or more creative IDs are not associated with the line item, the response includes a warning for each unmatched ID. Matching associations are still removed.

Example response (200)

{
  "warnings": [
    {
      "type": "validation",
      "traceId": "unique-request-id",
      "instance": "@data/attributes/creativeIds/1",
      "code": "unmatched-creative-id",
      "title": "Unmatched line item creative",
      "detail": "Creative creativeId3 is not currently associated with this line item."
    }
  ]
}

Errors and warnings

This endpoint does not support partial success. Errors are returned in the errors array.

HTTP status	Code	Description
`200`	`unmatched-creative-id`	A requested creative ID is not associated with the line item. Returned as a warning; matching creative associations are still removed.
`400`	`unsupported-line-item-type`	The line item buy type is not currently supported. Only Onsite Display Auction line items are supported.
`400`	`too-many-creatives`	More than 20 creative IDs were supplied. No creative associations are removed.
`401`	`unauthenticated`	The caller is not authenticated.
`403`	`forbidden`	The caller cannot modify the target line item, cannot access its account, or the line item does not exist.
`500`	`internal-error`	An unexpected error occurred.
`503`	`service-unavailable`	A service required to process the request is temporarily unavailable. Retry the request later.

Introduction

Guides for Retail Media API

Overview

Endpoints

Fetch Line Item Creatives

Path parameters

Response attributes

Sample response

Caveat

Errors

Upsert Line Item Creatives

Path parameters

Request attributes

Line Item Creative Attributes

Sample Auction Creative request

Response attributes

Sample Auction Creative response

Errors

Delete Line Item Creatives

Path parameters

Request attributes

Sample request

Sample responses

Errors and warnings

​Overview

​Endpoints

​Fetch Line Item Creatives

​Path parameters

​Response attributes

​Sample response

​Caveat

​Errors

​Upsert Line Item Creatives

​Path parameters

​Request attributes

​Line Item Creative Attributes

​Sample Auction Creative request

​Response attributes

​Sample Auction Creative response

​Errors

​Delete Line Item Creatives

​Path parameters

​Request attributes

​Sample request

​Sample responses

​Errors and warnings

Overview

Endpoints

Fetch Line Item Creatives

Path parameters

Response attributes

Sample response

Caveat

Errors

Upsert Line Item Creatives

Path parameters

Request attributes

Line Item Creative Attributes

Sample Auction Creative request

Response attributes

Sample Auction Creative response

Errors

Delete Line Item Creatives

Path parameters

Request attributes

Sample request

Sample responses

Errors and warnings