📘

URL: ​PATCH /api/v2/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
  • backgroundColorHex
  • textColor
  • 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
• Lifestyle Image (this section only describes crop removal)
  • Rectangular Crop
  • Focal Crop (Will apply across all ad units)

Path Parameters

Request Parameters

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

adUnits Field Descriptions

This section describes fields contained within the adUnits object.

• adUnitName: ENUM, required field. Contains one of the following values to denote the ad unit:

  • Desktop ad units: marqueeDesktop, brandboxDesktop, brandboxDesktopVideo, checkInVideo, galleryDesktop, tileDesktop, skylineDesktop, skylineDesktopV2, skylineDesktopV3, tileDesktop
  • App ad units: marqueeApp, tileApp, brandboxApp, brandboxAppVideo,galleryApp, skylineApp, skylineAppV2, skylineAppV3, tileApp
  • Notes:
    • All ad units are required in the request payload for Creative v2 endpoints, including tileApp and tileDesktop.
    • checkInVideo, brandboxDesktopVideo, and brandboxAppVideo ad units must all be included in the request for video creative

• headline: The headline for the ad unit.

• subhead: The sub text for the headline.

  • subhead must end with one of the following characters: ".", "!", "?", or "*".

• cta: Call to Action.

  • cta must be written in sentence casing.

• backgroundColorHex: Optional field supported in skylineV3 ad units.

  • Color hex must be formatted with "#" followed by 6 digits between 0 and F on the hexadecimal scale, e.g., "#F0F0F0".

• textColor: ENUM [gray, white]. Optional field supported in skylineV3 ad units.

• imageAltText: Written description of what's visually represented in your ad. Required field. String.

• logoAltText: Field to provide description to logo image. Required field. String.

• legalDisclaimerLabel: The title text of the popup disclaimer. Optional field. String.

  • legalDisclaimerLabel and legalDisclaimerPopUpCopy must be both supplied or not at all. Set an empty string for both fields to disable the disclaimer popup.

• legalDisclaimerPopUpCopy: The text of the popup disclaimer. 600 character limit. Optional field. String.

  • legalDisclaimerLabel and legalDisclaimerPopUpCopy must be both supplied or not at all. Set an empty string for both fields to disable the disclaimer popup.

• legalDisclaimerText: This is disclaimer text that will appear in the image. Optional field. String. 600 character limit. Set an empty string to clear the value.

  • Note: You can use legalDisclaimerText
    either on its own, or with a popup disclaimer (legalDisclaimerLabel and legalDisclaimerPopUpCopy).

• images: This field is for details of the images being uploaded: desktop/mobile (according to adunit) image and desktop/mobile logo image. Contains the following fields: name, assetId, and crop (optional).

  • Note: For Desktop ad units (marqueeDesktop, skylineDesktop, skylineDesktopV2, skylineDesktopV3, brandboxDesktop, galleryDesktop,tileDesktop) allowed values for name are desktopImage and desktopLogo. For App adunits (marqueeApp, skylineApp, skylineAppV2, skylineAppV3, brandboxApp, galleryApp,tileApp) allowed values for name are mobileImage and mobileLogo.

  • assetId: data type UUID string. Note: Use the assetId you receive from response of POST /api/v1/assets/photo

  • crop: Optional field. Only applicable for desktop images and mobile images. Not applicable for desktop/mobile logo images. Note: Sending in a new image will reset any existing crop settings.

    • When using crop, you cannot use both focal and rectangular values together.

    • focal: focal crop can be passed as part of a lifestyle image for 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 the focal crop, the request body must include the ad unit with its image fields and an empty crop object. This action is supported in PATCH and PUT methods, but not in POST.
      • Note: 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. This action is supported in PATCH and PUT methods, but not in POST.

      • 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 are limited to:

    • Max file size: 10 MB
    • Max dimensions: 5000px by 5000px

Creative Ad Unit Character Limits

Character limits vary across the various ad units, refer to the tables below for character length limits per ad unit.

marqueeDesktop / tablet

marqueeApp

skylineDesktop

skylineApp

skylineDesktopV2

skylineAppV2

skylineDesktopV3

skylineAppV3

brandboxDesktop

brandboxApp

brandboxVideoDesktop

brandboxVideoApp

checkinVideo

galleryDesktop full/mini

galleryApp

tileDesktop

tileApp

👉

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

Headers

Sample Request for Updating Creative Name + Headline

curl -X PATCH 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v2/creatives/aaaaaaa-a0a0-a0a0-a0a0-0000000000' \  --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": "12345678", "metadata": { "name": "Simple Creative - updated" }, "adUnits": [ { "adUnitName": "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/v2/creatives/aaaaaaa-a0a0-a0a0-a0a0-0000000000' \  --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": "12345678", "adUnits": [ { "adUnitName": "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/v2/creatives/aaaaaaa-a0a0-a0a0-a0a0-0000000000' \  --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": "12345678", "metadata": { "name": "Simple Creative PATCH - v1 - edited" }, "adUnits": [ { "adUnitName": "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/v2/creatives/aaaaaaa-a0a0-a0a0-a0a0-0000000000' \  --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": "12345678", "adUnits": [ { "adUnitName": "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/v2/creatives/aaaaaaa-a0a0-a0a0-a0a0-0000000000' \  --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": "12345678", "metadata": { "name": "Simple Creative PATCH - v1 - edited" }, "adUnits": [ { "adUnitName": "skylineDesktopV2", "images": [ { "name": "desktopImage", "assetId": "" } ] } ] }'

Response

Sample Response 1 - Success

[ { "code": "success", "details": ["success"], "creativeId": "abc123-123456-cba321-12345678" }
]

Sample Response 1- Failure

[ { "code": "failure", "message": "Found 1 validation error(s).$.adUnits.skylineDesktopV3.backgroundColorHex: should be a valid hexadecimal color code ", "details": [ "CREATIVE_VALIDATION_ERROR" ] }
] 

Sample Response 2 - Failure

[ { "code": "failure", "message": "Found 1 validation error(s). $.adUnits.skylineDesktopV3.textColor:text color can only be 'white' or 'gray'", "details": [ "CREATIVE_VALIDATION_ERROR" ] }
]

Note: textColor and backgroundColorHex must meet WCAG contrast requirements.

Sample Response 3 - Failure

[ { "code": "failure", "message": "Found 1 validation error. Background color does not meet WCAG contrast requirements with the provided text color. Please choose a different combination.", "details": [ "CREATIVE_VALIDATION_ERROR" ] }
] 

Note: backgroundColorHex will be validated to not be within a tolerance zone of any Walmart reserved color. If validation does not pass, some related colors will be suggested.

Sample Response 4 - Failure

[ { "code": "failure", "message": "Found 1 validation error. Background color violates Walmart color guidelines: #ff0000. nHere are some color suggestions: #ED013B, #E40038, #DB0230, #D2012E, #C80226, #BF011E, #C00018, #B7000F, #B70006, #B50B00, #B01D00, #B32A00, #AF3100, #B33900, #BA4900, #C24D01, #C65401", "details": [ "CREATIVE_VALIDATION_ERROR" ] }
]

Sample Response 5 - Failure

[ { "code": "failure", "message": "Found 1 validation error. Text color 'white' is not valid with default background color (#F8F8F8)due to WCAG contrast requirements.", "details": [ "CREATIVE_VALIDATION_ERROR" ] }
]