HomeGuidesAPI Reference
Guides

Update Creative (PATCH)

You can update specific fields on a creative using this PATCH call

📘

URL: ​PATCH/api/v1/creatives/:creativeId

Notes on Updating and Deleting Attributes

Certain attributes of a creative can be modified independently, while some attributes are dependent on other attributes and must both be updated at the same time. These attributes are described in the following sections.

Updating Attributes

Attributes listed in the same line must be updated together, while items on a single line can be updated independently of each other.

  • Metadata
    • Name
  • Ad Unit (Single)
    • Headline
    • Sub head
    • CTA
    • Image Alt text + Lifestyle Image (dependent, must be updated together)
    • Logo Alt text + Logo Image (dependent, must be updated together)
    • Legal disclaimer label
    • Legal disclaimer pop up copy
    • Legal disclaimer text
    • Lifestyle Image (Requires Image alt text when passed)
      • Rectangular Crop
      • Focal Crop (Will apply across all ad units)
    • Logo image (Requires Logo alt text when passed)

Deleting Attributes

  • Subhead in Skyline desktop V1 and V2
  • Lifestyle image + image alt text in Skyline Desktop V1 and V2 (dependent, must be deleted together)
  • Ad Unit
    • Legal disclaimer label
    • Legal disclaimer pop up copy
    • Legal disclaimer text
  • Lifestyle Image (this section only describes crop removal)
    • Rectangular Crop
    • Focal Crop (Will apply across all ad units)

Path Parameters

ParameterDescriptionTypeRequiredPossible Values
creativeIdThe ID of the creativestringYA valid creative ID

Request Parameters

Note: You can pass either the metadata parameter or the adUnits object. Only one of either parameter is required.

ParameterDescriptionTypeRequiredPossible Values
advertiserIdThe ID of the specific advertiserintegerYA valid advertiser ID
metadataFields you can update in a creative:
  • name: Name of the creative. String data type, required field
Note: templateID cannot be updated for a creative.		JSON ObjectNThe values:
  • name
adUnitsAd units on creative platform:
marqueeDesktop, marqueeApp, skylineDesktop, skylineApp, skylineDesktopV2, skylineAppV2, brandboxDesktop, brandboxApp, galleryDesktop, galleryApp
Ad units can contain the following fields. Go to the Appendix for a complete list of which fields apply to which ad units.
  • headline: This field cannot be deleted. Optional field. Character limit is dependent on the ad unit. Data type is string
  • subhead: This field can only be deleted for skyline ad units. Optional field. Character limit is dependent on the ad unit. Data type is string
    Note: subHead should always end with one of these characters ".", "!", "?", "*"
  • cta: Call to action. This field cannot be deleted. Optional field. Character limit 16 characters. Data type is string
    Note: cta must be drafted in sentence casing to avoid error.
  • imageAltText: This field cannot be deleted. Optional field. Data type is string. Character limit 150 characters
  • logoAltText: This field cannot be deleted. Optional field. Data type is string. Character limit 150 characters
  • legalDisclaimerLabel: Optional field, data type is string. legalDisclaimerLabel and legalDisclaimerPopUpCopy must be both supplied or not at all. Data type is string up to 12 characters. Set an empty string to disable the disclaimer popup.
  • legalDisclaimerPopUpCopy: Optional field, This is the text of the popup disclaimer. legalDisclaimerLabel and legalDisclaimerPopUpCopy must be both supplied or not at all. Data type is string, up to 600 characters. Set an empty string to disable the disclaimer popup.
  • legalDisclaimerText: You can update/delete this field. Pass an empty string if you don’t want to put a disclaimer text. Sending in a null or skipping the field WILL NOT delete the field, as all fields are optional by default. Optional field. Data type is string, up to 600 characters.
  • images: This field can only be deleted for skylineDesktop and skylineDesktopV2. It is recommended to send in images in all ad units unless the advertiser intends to update only a specific ad unit. It is also recommended to externally produce images as final assets (per Display ad specifications) as opposed to using the crop functionality.
    • name: data type string
      Note: For Desktop ad units (marqueeDesktop, skylineDesktop, skylineDesktopV2, brandboxDesktop, and galleryDesktop), allowed values for name are "desktopImage" and "desktopLogo".
      For App ad units (marqueeApp, brandboxApp, and galleryApp), allowed values for name are "mobileImage" and "mobileLogo".
    • assetId: You can replace the image by adding a new assetId. Data type: UUID string
    • crop: Only applicable for desktop image and mobile image. Not applicable for desktop/mobile logo image. It's an optional field. If you decide to crop the image, you cannot use both focal and rectangular values together.
      Note: Sending in a new image will reset crop settings.
      • focal: focal crop can be passed as part of a lifestyle image in any/all ad units. If set, the same Focal point crop settings will be applied to all ad units and will also overwrite any previously set rectangular crop settings.
        Focal will set the focus of the image at the specified x and y coordinates where x is horizontal, y is vertical, the origin is at the top left corner, and the range is between 0 and 1 exclusive.
        To remove Focal crop, request body must specify any ad unit(s) for which it is to be removed, with the image fields and an empty crop object. Note that, Focal crop will be removed from all ad units irrespective of the number of ad units passed without the focal crop attribute.
        • x: coordinate of the horizontal, ex: 0.2
        • y: coordinate of the vertical, ex: 0.4
      • rectangular: Rectangular crop settings can be modified for each ad unit. To remove the rectangular crop, request body must specify the ad unit(s) from which it is to be removed, including the image fields and an empty crop object
        • x: use x to crop image from left side
        • y: use y to crop image from top. Values of both x and y range between 0 and 1
        • w: use w to crop width of the image
        • h: use h to crop height of the image.
    Note: The desktop/mobile Image and desktop/mobile logos should have:
    • Max file size 10 mb
    • Max dimensions 5000px\5000px
JSON ObjectNmarqueeDesktop
marqueeApp
skylineDesktop skylineApp skylineDesktopV2
skylineAppV2
brandboxDesktop brandboxApp galleryDesktop galleryApp

👉

Please refer to the Appendix to find the required, optional, and non-required assets for each ad unit.

Headers

Header NameDescriptionRequiredValues
AuthorizationThe token will provide you the access to the API. It is same for all advertisers you access through the API.YPlease utilize the generated auth_token shared with you at the time of partner onboarding from the Getting Started Guide
WM_CONSUMER.IDWe will provide you the consumer ID to access the API. It is same for all advertisers you access through the API.   YPlease use the generated ConsumerId shared with you at the time of partner onboarding. Refer to the Getting Started Guide for more information
WM_SEC.AUTH_SIGNATUREAuth signature as an API key.YUse the signature generator code from Getting Started Guide to generate this value
WM_SEC.KEY_VERSIONWe will provide you with the KEY VERSION to access the API. It is same for all advertisers you access through the API.Y1
WM_CONSUMER.intimestampTimestamp for which the auth signature is generated. Use Unix epoch format for the timestamp.YUse the signature generator code from Getting Started Guide to generate this value

Sample Request for Updating Creative Name + Headline

curl -X PATCH 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/creatives/e02a09b2-1e3c-2g22-bf47-8a123c35002a' \  --header 'Content-Type: application/json' \  --header 'Authorization: Bearer <auth_token>' \ --header 'WM_SEC.AUTH_SIGNATURE: **************' \  --header 'WM_SEC.KEY_VERSION: 1' \  --header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \  --header 'WM_CONSUMER.intimestamp: 1565309779' \
--data '{ "advertiserId": 123, "metadata": { "name": "Simple Creative - updated" }, "adUnits": { "marqueeDesktop": { "headline": "Updated headLine" }, } }'

Sample Request for Removing Disclaimer Text

Note: You must send an empty string to confirm the removal of any existing Legal disclaimer text. Sending a null value or skipping the field will not delete the field, as all fields are optional by default.

curl -X PATCH 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/creatives/e02a09b2-1e3c-2g22-bf47-8a123c35002a' \  --header 'Content-Type: application/json' \  --header 'Authorization: Bearer <auth_token>' \ --header 'WM_SEC.AUTH_SIGNATURE: **************' \  --header 'WM_SEC.KEY_VERSION: 1' \  --header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \  --header 'WM_CONSUMER.intimestamp: 1565309779' \
--data '{ "advertiserId": 123, "adUnits": { "marqueeDesktop": { "legalDisclaimerText": "" } } }'

Sample Request for Removing Subhead (Skyline Desktop)

curl -X PATCH 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/creatives/e02a09b2-1e3c-2g22-bf47-8a123c35002a' \  --header 'Content-Type: application/json' \  --header 'Authorization: Bearer <auth_token>' \
--header 'WM_SEC.AUTH_SIGNATURE: **************' \  --header 'WM_SEC.KEY_VERSION: 1' \  --header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \  --header 'WM_CONSUMER.intimestamp: 1565309779' \
--data '{ "advertiserId": "16273800", "metadata": { "name": "Simple Creative PATCH - v1 - edited" }, "adUnits": { "skylineDesktopV2": { "subhead": "" } } }'

Sample Request for Removing Crop On a Single Ad Unit

curl -X PATCH 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/creatives/e02a09b2-1e3c-2g22-bf47-8a123c35002a' \  --header 'Content-Type: application/json' \  --header 'Authorization: Bearer <auth_token>' \
--header 'WM_SEC.AUTH_SIGNATURE: **************' \  --header 'WM_SEC.KEY_VERSION: 1' \  --header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \  --header 'WM_CONSUMER.intimestamp: 1565309779' \
--data '{ "advertiserId": "16273800", "adUnits": { "marqueeApp": { "images": [ { "name": "mobileImage", "assetId": "7c3049ed-8145-4727-9ca8-56b4c2388266", "crop": {} } ] } } }'

Sample Request for Removing Lifestyle Image from Skyline desktop ad unit

curl -X PATCH 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/creatives/e02a09b2-1e3c-2g22-bf47-8a123c35002a' \  --header 'Content-Type: application/json' \  --header 'Authorization: Bearer <auth_token>' \
--header 'WM_SEC.AUTH_SIGNATURE: **************' \  --header 'WM_SEC.KEY_VERSION: 1' \  --header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \  --header 'WM_CONSUMER.intimestamp: 1565309779' \
--data '{ "advertiserId": "16273800", "metadata": { "name": "Simple Creative PATCH - v1 - edited" }, "adUnits": { "skylineDesktopV2": { "images": [ { "name": "desktopImage", "assetId": "" } ] } } }'

Response

ElementDescriptionType
codePossible values of response code:
  • success
  • failure
string
detailsPossible values of details:
  • Details of the error if value of response code is failure
  • It returns a string value "success" if value of response code is success
string
creativeIdID of the creative. It is returned in response only if code=successstring
messageDetails of the error if value of code is failure and validation errors were foundstring

Sample Response

[ { "code": "success", "details": ["success"], "creativeId": "e02a09b2-1e3c-2g22-bf47-8a123c35002a" }
]

Updated 13 days ago