Guides

Update Creative (PATCH) v2

📘

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

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
metadata

Fields you can update in a creative:
name: Name of the creative. String data type, required field. 255 character limit.
subscribeEnabled: Indicates whether the Subscribe option is to be enabled for the creative. Boolean datatype, optional field. If subscribeEnabled is true then headline, subhead, and CTA must match one of the following combinations exactly:

  • Option 1
    • Headline: “Subscribe today”
    • Subhead: “Plan ahead & save time.”
    • CTA: “Learn more”
  • Option 2
    • Headline: “Simplify. Subscribe.”
    • Subhead: “Start subscribing today.”
    • CTA: “Learn more”
  • Option 3
    • Headline: “Subscribe & save time”
    • Subhead: “Make your planning easier.”
    • CTA: “Learn more”
  • Option 4
    • Headline: “Plan ahead & save time”
    • Subhead: “Stay stocked. Subscribe today.”
    • CTA: “Subscribe”
  • Option 5
    • Headline: “Simplify your planning”
    • Subhead: “Subscribe & save time later.”
    • CTA: “Subscribe”

If the headline, subhead, or CTA don't match one of the above options, the response will return the following error: "Subscribe cannot be enabled because the provided text does not match the approved text."
associatedItems: Single item ID that is to be associated with the creative. Array <string> datatype. Required when subscribeEnabled = true. The item id must be eligible for Subscription. If subscribeEnabled is set to true, then associatedItems is required. Otherwise, this field should be omitted from the request.
When subscribeEnabled is true, item in associatedItems must be eligible for Subscribe.
Use the isSubscribeEligible field returned by POST /api/v1/items/list to determine whether an item can be associated with a subscribe-enabled creative.
If any item in associatedItems has isSubscribeEligible = false, the request will fail validation.
Note: A maximum of one item can be associated with a creative.

JSON ObjectNname
subscribeEnabled
associatedItems
adUnitsEach ad unit contains the following fields (see adUnits Field Descriptions below for the full description of each field):
  • adUnitName
  • headline
  • subhead
  • cta
  • backgroundColorHex
  • textColor
  • imageAltText
  • logoAltText
  • legalDisclaimerLabel
  • legalDisclaimerPopUpCopy
  • legalDisclaimerText
  • images
    • assetId
    • crop
    • focal
    • rectangular
      • x
      • y
      • w
      • h
JSON ObjectNmarqueeDesktop
marqueeApp
marqueeTablet
skylineDesktop skylineApp skylineDesktopV2
skylineAppV2
skylineDesktopV3
skylineAppV3
brandboxDesktop brandboxApp galleryDesktop galleryApp
checkinVideo
brandboxDesktopVideo
brandboxAppVideo

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
    • Tablet ad units: marqueeTablet
    • Video ad units: f4Video, checkinVideo , brandboxDesktopVideo, brandboxAppVideo
    • _Notes: _
      • All ad units are required in the request payload for Creative v2 endpoints, including tileApp and tileDesktop.

  • 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.
      • For Tablet ad units (marqueeTablet) allowed values for name are tabletImage and tabletLogo.

    • 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

👉

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
Content-TypeFormat of the message bodyYapplication/json
WM_CONSUMER.IDUnique ID for consumer. We 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_SIGNATURESignature for authenticationYUse the signature generator code from Getting Started Guide to generate this value
WM_SEC.KEY_VERSIONKey version. We 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/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": 190001, "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": 190001, "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": 190001, "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": 190001, "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": 190001, "metadata": { "name": "Simple Creative PATCH - v1 - edited" }, "adUnits": [ { "adUnitName": "skylineDesktopV2", "images": [ { "name": "desktopImage", "assetId": "" } ] } ] }'

Sample Request for Updating a Video Creative

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_CONSUMER.ID: <consumerId>' \ --header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.INTIMESTAMP: 0000000000000' \ --header 'WM_SEC.AUTH_SIGNATURE: **************' \ --data '{ "advertiserId": 190001, "metadata": { "name": "A valid creative name" }, "adUnits": [ { "adUnitName": "checkInVideo", "legalDisclaimerLabel": "A valid legal disclaimer label", "legalDisclaimerPopUpCopy": "A valid legal disclaimer pop up copy", "videos": [ { "name": "mainVideo", "assetId": "00000000-0000-0000-0000-000000000005" } ] } ] }'

Response

ElementDescriptionOptional field/Nullable?TypePossible values
codeThe response code can have following values:
  • success
  • failure

Click here for more information about Status Codes and Errors		Nstring
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
NstringRefer to this link for detailed error messages
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 foundYstring
errorsDetailed information about one or more errors, including the affected field (when applicable), error code, and a human-readable description.Yarray<object> 

errors Array Object Details

FieldDescriptionOptional field/Nullable?TypePossible values
fieldJSON field associated with the error. Omitted if the error applies to the request as a whole.Ystring 
errorTypeMachine-readable error code that uniquely identifies the error condition. Applications should use this value for error handling logic.Nstring 
descriptionHuman-readable explanation of the error, including why the request failed and, when possible, how to resolve itNstring 

Sample Response 1 - Success

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

Sample Response 1- Failure

[ { "code": "failure", "message": "Found 8 validation error(s).", "errors": [ { "field": "$.adUnits[marqueeDesktop].headline", "errorType": "E_SCHEMA_FIELD_INVALID", "description": "$.adUnits[marqueeDesktop].headline must be at least 1 characters long. Check your input." }, { "field": "$.adUnits[marqueeDesktop].subhead", "errorType": "E_TEXT_MISSING_PUNCTUATION", "description": "$.adUnits[marqueeDesktop].subhead does not end with a period(.), exclamation(!), question(?), or an asterisk(*). Ensure text ends with one of: . ! ? *" }, { "field": "$.adUnits[marqueeDesktop].cta", "errorType": "E_TEXT_INVALID_CASING", "description": "$.adUnits[marqueeDesktop].cta does not follow sentence casing. Capitalize only the first letter; keep the rest lowercase." }, { "field": "$.adUnits[marqueeDesktop].imageAltText", "errorType": "E_ALT_TEXT_BLANK", "description": "$.adUnits[marqueeDesktop].imageAltText must be at least 1 characters long. Provide descriptive alt text for the image." }, { "field": "$.adUnits[marqueeDesktop].logoAltText", "errorType": "E_ALT_TEXT_BLANK", "description": "$.adUnits[marqueeDesktop].logoAltText must be at least 1 characters long. Provide descriptive alt text for the image." }, { "field": "$.adUnits[marqueeDesktop].images", "errorType": "E_SCHEMA_FIELD_INVALID", "description": "$.adUnits[marqueeDesktop].images: null found, array expected. Check your input." }, { "field": "$.adUnits[marqueeDesktop].disclaimer", "errorType": "E_SCHEMA_FIELD_INVALID", "description": "Disclaimer pop-up copy and label must be used together. Check your input." }, { "field": "$.metadata.templateId", "errorType": "E_SCHEMA_FIELD_INVALID", "description": "$.metadata.templateId does not have a value in the enumeration [436]. Check your input." } ], "details": [ "E_SCHEMA_FIELD_INVALID", "E_TEXT_MISSING_PUNCTUATION", "E_TEXT_INVALID_CASING", "E_ALT_TEXT_BLANK" ] }
]

Sample Response 2- Failure

[ { "code": "failure", "message": "Found 1 validation error(s).", "errors": [ { "field": "$.adUnits[skylineDesktopV3].backgroundColorHex", "errorType": "E_INVALID_COLOR_HEX", "description": "$.adUnits[skylineDesktopV3].backgroundColorHex should be a valid hexadecimal color code. Use a 6-digit hex color code, e.g. #1A2B3C." } ], "details": [ "E_INVALID_COLOR_HEX" ] }
]

Sample Response 3 - Failure

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

Note: textColor and backgroundColorHex must meet WCAG contrast requirements.

Sample Response 4 - Failure

[ { "code": "failure", "message": "Found 1 validation error(s).", "errors": [ { "field": "$.adUnits[skylineDesktopV3].textColor", "errorType": "E_INVALID_TEXT_COLOR", "description": "Background color does not meet WCAG contrast requirements with the provided text color. Please choose a different combination. Set text color to 'white' or 'gray'." } ], "details": [ "E_INVALID_TEXT_COLOR" ] }
]

Note: backgroundColorHex is validated against Walmart reserved colors. If validation does not pass, some related colors will be suggested.

Sample Response 5 - Failure

[ { "code": "failure", "message": "Found 1 validation error(s).", "errors": [ { "field": "$.adUnits[skylineDesktopV3].backgroundColorHex", "errorType": "E_INVALID_COLOR_HEX", "description": "Background color violates Walmart color guidelines: #ff0000. Here are some color suggestions: #ED013B, #E40038, #DB0230, #D2012E, #C80226, #BF011E, #C00018, #B7000F, #B70006, #B50B00, #B01D00, #B32A00, #AF3100, #B33900, #BA4900, #C24D01, #C65401. Use a 6-digit hex color code, e.g. #1A2B3C." } ], "details": [ "E_INVALID_COLOR_HEX" ] }
]

Sample Response 6 - Failure

[ { "code": "failure", "message": "Found 1 validation error(s).", "errors": [ { "field": "$.adUnits[skylineDesktopV3].textColor", "errorType": "E_INVALID_TEXT_COLOR", "description": "Text color 'white' is not valid with default background color (#F8F8F8) due to WCAG contrast requirements. Set text color to 'white' or 'gray'." } ], "details": [ "E_INVALID_TEXT_COLOR" ] }
]

Updated 5 days ago

Did this page help you?