📘

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
  • 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 Object/Field Description

Each ad unit contains following fields:

• headline: Data type is string
• subhead: Data type is string
  Note: subHead should always end with one of these characters ".", "!", "?", "*"
• cta: Call to action. Data type is string
  Note: cta must be drafted in sentence casing to avoid error.
• backgroundColorHex: Color hex is always "#" followed by 6 digits between 0 and F on the hexadecimal scale.
  • This field only applies to Skyline v3 ad units and is optional
• textColor: ENUM [gray, white]
  • This field only applies to Skyline v3 ad units and is optional
• imageAltText: Field to provide description of what is visually represented in your ad. Data type is string.
• logoAltText: Field to provide description to logo image. Data type is string.
• legalDisclaimerLabel: Data type is string. This is the title text of the popup disclaimer. legalDisclaimerLabel and legalDisclaimerPopUpCopy must be both supplied or not at all. Data type is string. Set an empty string to disable the disclaimer popup.
• legalDisclaimerPopUpCopy: This is the text of the popup disclaimer. legalDisclaimerLabel and legalDisclaimerPopUpCopy must be both supplied or not at all. Data type is string. Set an empty string to disable the disclaimer popup.
• legalDisclaimerText: This is disclaimer text that will appear in the image. Data type is string. Set an empty string to clear the value.
  • Note: You may utilize legalDisclaimerText
    either on its own or in conjunction with a popup disclaimer (legalDisclaimerLabel
    and legalDisclaimerPopUpCopy)
• variantId: Defines the spec for the ad unit. Required field. Its fixed value is 436 at present. Data type is string
• images: This field is for details of the images being uploaded: desktop/mobile (according to adunit) image and desktop/mobile logo image.
  • name: data type string
    • Note: For Desktop adunits (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 is "mobileLogo"
      For App adunits (marqueeApp, skylineAppV3, brandboxApp, galleryApp, tileApp) allowed values for name are "mobileImage"
  • assetId: data type UUID string.
    Note: Use the assetId you receive from response of POST/api/v1/assets/photo
  • 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 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 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. 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 should have:

• Max file size 10 mb
• Max dimensions 5000px*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/v1/creatives/abcde-12345' \  --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": { "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/abcde-12345' \  --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": { "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/abcde-12345' \  --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": { "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/abcde-12345' \  --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": "1234578", "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/abcde-12345' \  --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": { "skylineDesktopV2": { "images": [ { "name": "desktopImage", "assetId": "" } ] } } }'

Response

Sample Response 1 - Success

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

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" ] }
]