Update Campaign - PATCH
Use this endpoint to apply bulk, partial updates to existing campaigns. The API adheres to standard PATCH semantics, meaning only the fields included in the request body are updated, while all unspecified campaign attributes remain unchanged
URL: PATCH /api/v1/campaigns
Note:
- Supports up to 10 campaign objects per request. For bulk operation, the advertiserId must be uniform across all campaign objects within a single payload
- Partial updates are applied at the field level. To clear an existing field value, explicitly pass null
- All of budgetType, dailyBudget, totalBudget, startDate, endDate, and deliverySpeed must be set at same level i.e. either at campaign level or ad group level. Attempting to alter the "level" at which they are set via a PATCH request will result in a validation error
- For details on updatable fields, refer to this link
Request Parameters
| Parameters | Notes | Type | Required | Possible Values |
|---|---|---|---|---|
| advertiserId | ID of advertiser | integer | Y | Valid advertiser ID |
| campaignId | ID of the campaign to be updated | integer | Y | Valid campaign ID |
| name | The name of the campaign Note: Limit on length of campaign name is 240 characters | string | Y | The campaign name should be unique |
| description | Description of the campaign Note: Limit on length of campaign description is 240 characters | string | N | Provide valid description corresponding to campaign type |
| objective | Specifies the campaign objective. Note: You can update objective only for draft campaigns | string | N | Values: If the objective is not specified in the request payload, the existing value of the objective will be retained. |
| campaignType | The type of the campaign Note:
| string | N | Values of campaignType: ngd |
| startDate | The date to start campaign | string | Conditional. This field is required only if it is not set at ad group level. Cannot be changed to ad group level later | ISO 8601 Format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX |
| endDate | The date when campaign ends | string | Conditional. This field is required only if it is not set at ad group level. Cannot be changed to ad group level later | ISO 8601 Format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX
|
| budgetType | Budget allocation type | string | N | Values:
|
| dailyBudget | Daily budget of campaign
| double | Conditional. This field is required only if:
| The value of daily budget should at least be $0.01 |
| totalBudget | Total budget of campaign Attempting to update totalBudget for a campaign with dailyBudget will result in error | double | Conditional. This field is required only if:
| The value of total budget should at least be $0.01 |
| deliverySpeed | Determines pacing of ad delivery Note: You can update it only for campaigns in DRAFT state | string | N | Values:
|
Rules
- You cannot change the level at which budgetType, dailyBudget, totalBudget, startDate, endDate, and deliverySpeed are set i.e. if these are set at campaign level while creating the campaign, it cannot be changed to ad group later and vice versa.
- You can only set either dailyBudget or totalBudget
- To set daily budget, you must choose value of budgetType as “daily” and then define dailyBudget.
- To set total budget, you must choose value of budgetType as “total” and then define totalBudget.
- Budget, Schedule and Delivery speed must be set either at campaign or ad group level
- mediaType field cannot be modified after a campaign is created. mediaType, if included in the request payload, is ignored and will not be modified.
Headers
| Header Name | Description | Required | Values |
|---|---|---|---|
| Authorization | The token will provide you the access to the API. It is same for all advertisers you access through the API. | Y | Please utilize the generated auth_token shared with you at the time of partner onboarding from the Getting Started Guide |
| Content-Type | Format of the message body | Y | application/json |
| WM_CONSUMER.ID | Unique 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. | Y | Please 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_SIGNATURE | Signature for authentication | Y | Use the signature generator code from Getting Started Guide to generate this value |
| WM_SEC.KEY_VERSION | Key version. We will provide you with the KEY VERSION to access the API. It is same for all advertisers you access through the API. | Y | 1 |
| WM_CONSUMER.intimestamp | Timestamp for which the auth signature is generated. Use Unix epoch format for the timestamp. | Y | Use the signature generator code from Getting Started Guide to generate this value |
Sample Request - Remove Description and Update Campaign Name
curl -X PATCH \ 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/campaigns'\ --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 '[ { "campaignId": 1, "advertiserId": 1, "description": null, "name": "test-name3" } ]'Sample Request - Update Campaign Name
curl -X PATCH \ 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/campaigns'\ --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 '[ { "campaignId": 1, "advertiserId": 1, "name": "test-name" } ]'Sample Request - Update Multiple Campaigns
curl -X PATCH \ 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/campaigns'\ --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 '[ { "campaignId": 1, "advertiserId": 1, "name": "test-name1", "description": "test-description" }, { "campaignId": 2, "advertiserId": 1, "name": "test-name2", "description": "test-description", "objective": "awareness" } ]'Response
| Field | Description | Optional field/Nullable? | Type | Possible values |
|---|---|---|---|---|
| code | The response code can have following values:
Click here for more information about Status Codes and Errors | N | string | success, failure |
| details | Details will populate success or error message depending upon value of code. | N | string | Refer to this link for detailed error messages |
| campaignId | ID of the updated campaign. | Y | integer | |
| message | High-level summary of the error, when available. | Y | string | |
| errors | Detailed information about one or more errors, including the affected field (when applicable), error code, and a human-readable description. | Y | array<object> |
errors Array Object Details
| Field | Description | Optional field/Nullable? | Type | Possible values |
|---|---|---|---|---|
| field | JSON field associated with the error (for example, startDate). Omitted if the error applies to the request as a whole. | Y | string | |
| errorType | Machine-readable error code that uniquely identifies the error condition. Applications should use this value for error handling logic. | N | string | |
| description | Human-readable explanation of the error, including why the request failed and, when possible, how to resolve it | N | string |
Sample Response Success - Remove Description along with Name Update
[ { "code": "success", "details": ["string"], "campaignId": 1 } ]Sample Response Failure - Remove Description along with Name Update
[ { "code": "failure", "details": [ "string" ], "campaignId": 1, "message": "string",
"errors": [ { "field": "string", "errorType": "string", "description": "string" } ] } ]Sample Response Success - Update Campaign Name
[ { "code": "success", "details": ["string"], "campaignId": 1 }
]Sample Response Failure - Update Campaign Name
[ { "code": "failure", "details": [ "string" ], "campaignId": 1, "message": "string",
"errors": [ { "field": "string", "errorType": "string", "description": "string" } ] }
]Sample Response Success - Update Multiple Campaigns
[ { "code": "success", "details": ["string"], "campaignId": 1 }, { "code": "success", "details": ["string"], "campaignId": 2 } ]Sample Response Failure - Update Multiple Campaigns
[ { "code": "failure", "details": [ "string" ], "campaignId": 1, "message": "string",
"errors": [ { "field": "string", "errorType": "string", "description": "string" } ] },
{ "code": "failure", "details": ["string"], "campaignId": 2, "message": "string",
"errors": [ { "field": "string", "errorType": "string", "description": "string" } ]
}
]Sample Response Success - Update KPI for a campaign
[ { "code": "success", "details": ["string"], "campaignId": 1 } ]Sample Response Failure - Update KPI for a campaign
[ { "code": "failure", "details": [ "string" ], "campaignId": 1, "message": "string",
"errors": [ { "field": "string", "errorType": "string", "description": "string" } ] } ]Updated 4 days ago
Did this page help you?