Skip to main content

PUT/email_campaign/{email_campaign_id}

This method lets users update an existing email campaign. Pass the emailCampaignId in the request URL and specify the changes to field values in the request payload.

Note: You can only update the custom fields of an email campaign. Fixed values, such as the emailCampaignType, cannot be changed. For full specifications of fixed values for each email campaign type, see the createEmailCampaign method documentation.

Input

Resource URI

PUT https://api.ebay.com/sell/marketing/v1/email_campaign/{email_campaign_id}

This method is supported in Sandbox environment. To access the endpoint, just replace the api.ebay.com root URI with api.sandbox.ebay.com

URI parameters

ParameterTypeDescription
email_campaign_idstringThis path parameter specifies the unique eBay assigned identifier for the email campaign being updated.

Use the getEmailCampaigns method to retrieve a list of email campaign IDs for a seller.

Occurrence: Required

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

The table below shows additional HTTP request headers that are either required, conditionally required, or strongly recommended for this method. Other standard HTTP request headers- opens rest request components page (not in this table) can also be used, but they are optional.

HeaderTypeDescription
Content-TypestringThis header indicates the format of the request body provided by the client. Its value should be set to application/json.

For more information, refer to HTTP request headers.

Occurrence: Required

OAuth scope

This request requires an access token created with the authorization code grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):

https://api.ebay.com/oauth/api_scope/sell.marketing

See OAuth access tokens for more information.

Request payload

Copy complete valid JSON to clipboard

Request fields

Input container/fieldTypeDescription
audienceCodesarray of string

An array of audience codes for the audiences of the email campaign. At least one audience code is required. There is no limit to the number of audience codes that may be entered.

Example: if the current email campaign contains "audienceCodes": "code1", "code2" and the user wishes to add an audience code code3, set the audienceCodes value to "audienceCodes": "code1", "code2", "code3".

To retrieve seller audiences, call getAudiences. Use the code values in the response to populate audienceCodes.

Occurrence: Required

categoryIdstring

The unique identifier of either an eBay category or a store category.

This field is used if a seller wants to apply an email campaign to a specific eBay category or store category. The categoryType determines whether the categoryId value is an eBay category or store category.

To retrieve eBay categories, use the getCategories or Taxonomy API. To retrieve seller store categories, use the getStore call. Use the categoryId value of the desired category from the results as the value in the request.

itemSelectMode must be set to AUTO in order to use a category ID.

Occurrence: Conditional

categoryTypeCategoryTypeEnum

This field must be set when applying an email campaign to a specific eBay category or store category. The enumeration value used indicates which type of category the categoryId belongs to.

Occurrence: Optional

itemIdsarray of string

An array of unique identifiers for the listings displayed in an email campaign. Used if the seller wishes to select the eBay listings in the email campaign rather than have eBay automatically select them.

Call getSellerList to retrieve all seller listings. Each Item result contains an ItemID value. Use this value in itemIds to feature that listing.

The maximum number of itemIds for the COUPON campaign type is 4, and for every other campaign type is 10.

itemSelectMode must be set to MANUAL in order to use this field.

Occurrence: Optional

itemSelectModeItemSelectModeEnum

Determines whether listings featured in an email campaign are selected by the seller or by eBay.

If itemSelectMode is set to AUTO, eBay automatically choses listings based on values set for sort, categoryType, categoryId, and priceRange.

If itemSelectMode is set to MANUAL, listings are set by the seller by populating the itemIds array.

Note: itemSelectMode is always set to AUTO for WELCOME email campaigns.

Occurrence: Required

personalizedMessagestring

The body of the email campaign. Accepts HTML and CSS. The maximum length is 1000 characters

Occurrence: Required

priceRangePriceRange

This container is used if the seller wants to apply the email campaign to listings based on a price range.

The priceRange container consists of the currency, gte, and lte fields.

"gte" stands for "greater than or equal to" and "lte" stands for "less than or equal to". Either gte, lte, or both must be used if the seller wishes to include a price range.

Note: Use this object when the itemSelectMode is set to AUTO.

Occurrence: Optional

priceRange.currencystring

Specifies the currency of the listings in an email campaign using one of the three-digit codes of the CurrencyCodeEnum type.

Occurrence: Conditional

priceRange.gtenumber

The listings selected will be greater than or equal to this value. The value entered must be given in number format, such as 20.00.

Either gte, lte, or both must contain a value if the seller wishes to use a price range.

Occurrence: Optional

priceRange.ltenumber

The listings selected will be less than or equal to this value. The value entered must be given in number format, such as 100.00.

Either gte, lte, or both must contain a value if the seller wishes to use a price range.

Occurrence: Optional

promotionIdstring

The ID of the discount used for an email campaign if the emailCampaignType is set to COUPON, SALE_EVENT, or ORDER_DISCOUNT, and promotionSelectModeEnum is set to MANUAL.

To find a discount, call getPromotions to retrieve a list of the seller's discounts. Use the promotionId from an individual PromotionDetail result for the request.

Occurrence: Conditional

promotionSelectModeEnumPromotionSelectModeEnum

The selection mode for the discount used. If set to AUTO, eBay will choose the discount to include in the email campaign. If set to MANUAL, the seller must specify the discount in the promotionId field.

This field is required if the emailCampaignType is set to COUPON, SALE_EVENT, or ORDER_DISCOUNT.

Occurrence: Conditional

scheduleDatestring

The date and time that the email campaign newsletter will be sent, given in UTC format. Example: 2023-05-20T03:13:35Z

This field should be used if the seller wishes to send the email campaign on a future date. If no scheduleDate is set, the email campaign will send once it is created or updated.

Occurrence: Optional

sortItemSortEnum

The sort rule is used to display the listings featured in the email campaign.

Sort rules are only used if itemSelectMode is set to AUTO. If itemSelectMode is MANUAL, listings are displayed in the order in which they are listed in the itemIds array.

The following sort rules are available:

  • ENDING_FIRST displays listings by ending date, from soonest to latest.
  • LOWEST_PRICED displays listings by price, from lowest to highest.
  • HIGHEST_PRICED displays listings by price, from highest to lowest.
  • NEWLY_LISTED displays listings by date listed, with the newest first.


The default sort rule is NEWLY_LISTED.

Occurrence: Optional

subjectstring

The email campaign subject. The maximum length is 70 characters.

Occurrence: Required

Output

HTTP response headers

This call has no response headers.

Response payload

Response fields

Output container/fieldTypeDescription
emailCampaignIdstring

The unique eBay-assigned ID to the email campaign that is generated when the email campaign is created.

Occurrence: Always

emailCampaignStatusEmailCampaignStatusEnum

The email campaign status. See EmailCampaignStatusEnum for a list of email campaign statuses and their descriptions.

Occurrence: Always

HTTP status codes

This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.

StatusMeaning
200OK
400Bad Request
500Internal Server Error

Error codes

For more on errors, plus the codes of other common errors, see Handling errors.

CodeDomainCategoryMeaning
35000STORE_CRMAPPLICATIONInternal server error encountered. If this problem persists, contact the eBay Developers Program for support.
35001STORE_CRMBUSINESSA store subscription is required for this call, please check the store subscription status for current seller.
35801STORE_CRMREQUEST'audiences' is required for this call.
35802STORE_CRMREQUESTNo email campaign found for email campaign ID {email_campaign_id}.
35803STORE_CRMREQUEST'subject' is required for this call.
35804STORE_CRMREQUEST'personalizedMessage' is required for this call.
35805STORE_CRMREQUEST'subject' length is too long. For maximum limits, see the documentation for this call.
35806STORE_CRMREQUEST'audiences' value is not suitable for current email campaign type.
35807STORE_CRMREQUEST'itemIds' is required for this call.
35808STORE_CRMREQUESTFor 'WELCOME' type campaign, 'itemIds' should be empty.
35809STORE_CRMREQUESTThe item {itemIds} size exceeds maximum. For maximum limits, see the documentation for this call.
35810STORE_CRMREQUESTNo eligible items for current campaign.
35811STORE_CRMREQUEST'promotionId' is required for this call.
35812STORE_CRMREQUEST'promotionId' is invalid, promotion may be inactive or non-exist.
35813STORE_CRMREQUEST'scheduleDate' is not required for this call.
35814STORE_CRMREQUEST'scheduleDate' is missing or invalid, please use a valid UTC format(yyyy-MM-ddThh:mm:sssZ) string.
35815STORE_CRMREQUEST'email_campaign_id' is not eligible for editing.
35816STORE_CRMREQUEST'personalizedMessage' length is too long. For maximum limits, see the documentation for this call.
35817STORE_CRMREQUESTThe email campaign schedule date {scheduleDate} must be in the future.
35818STORE_CRMREQUEST'itemIds' contains ineligible item id, please check the item list
35819STORE_CRMREQUEST'itemSelectMode' is invalid for this campaign, please see the documentation for this call.

Warnings

This call has no warnings.

Samples

New to making API calls? Please see Making a Call.

Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.

Sample 1: Updating an Email Campaign

This method updates an existing email campaign.

Input

The emailCampaignId URI parameter is required to specify the email campaign that is being updated.

The existing email campaign will be updated with the values passed in the request payload. Note that only custom fields can be updated. Fixed values, such as the emailCampaignType cannot be changed.

In this sample, the subject, audienceCodes, scheduledDate, and personalizedMessage are being updated. In addiiton, the lte has been updated to show that the price range of the listings selected will be less than or equal to 100 USD.

PUThttps://api.ebay.com/sell/marketing/v1/email_campaign/b********3

Output

If the call is successful, the emailCampaignId and emailCampaignStatus for the updated email campaign are returned.