eBay Promoted Listing Technical Scope

PHASE 1

Creating Campaign

A new table should be introduced for eBay Campaigns where we will be able to track the campaign status, pause, resume, end anddelete them. We need to be able to insert a new record in eBay Campaigns and set the campaign details. The new section will have a slave table with all the products added in a specific campaign for example campaign ads.

For Hemi we will go for the Key-based campaigns and will use the bulkCreateAdsByListingId in order to add the Listings in the campaign.

In order to do so first we need to create the campaign.

POST https://api.ebay.com/sell/marketing/v1/ad_campaign

{
  "campaignCriterion": {
    "autoSelectFutureInventory": "boolean",
    "criterionType": "CriterionTypeEnum : [INVENTORY_PARTITION]",
    "selectionRules": [
      {
        "brands": [
          "string"
        ],
        "categoryIds": [
          "string"
        ],
        "categoryScope": "CategoryScopeEnum : [MARKETPLACE,STORE]",
        "listingConditionIds": [
          "string"
        ],
        "maxPrice": {
          "currency": "CurrencyCodeEnum : [AED,AFN,ALL,AMD,ANG,AOA,ARS,AUD,AWG,AZN,BAM,BBD,BDT,BGN,BHD,BIF,BMD,BND,BOB,BRL,BSD,BTN,BWP,BYR,BZD,CAD,CDF,CHF,CLP,CNY,COP,CRC,CUP,CVE,CZK,DJF,DKK,DOP,DZD,EGP,ERN,ETB,EUR,FJD,FKP,GBP,GEL,GHS,GIP,GMD,GNF,GTQ,GYD,HKD,HNL,HRK,HTG,HUF,IDR,ILS,INR,IQD,IRR,ISK,JMD,JOD,JPY,KES,KGS,KHR,KMF,KPW,KRW,KWD,KYD,KZT,LAK,LBP,LKR,LRD,LSL,LTL,LYD,MAD,MDL,MGA,MKD,MMK,MNT,MOP,MRO,MUR,MVR,MWK,MXN,MYR,MZN,NAD,NGN,NIO,NOK,NPR,NZD,OMR,PAB,PEN,PGK,PHP,PKR,PLN,PYG,QAR,RON,RSD,RUB,RWF,SAR,SBD,SCR,SDG,SEK,SGD,SHP,SLL,SOS,SRD,STD,SYP,SZL,THB,TJS,TMT,TND,TOP,TRY,TTD,TWD,TZS,UAH,UGX,USD,UYU,UZS,VEF,VND,VUV,WST,XAF,XCD,XOF,XPF,YER,ZAR,ZMW,ZWL]",
          "value": "string"
        },
        "minPrice": {
          "currency": "CurrencyCodeEnum : [AED,AFN,ALL,AMD,ANG,AOA,ARS,AUD,AWG,AZN,BAM,BBD,BDT,BGN,BHD,BIF,BMD,BND,BOB,BRL,BSD,BTN,BWP,BYR,BZD,CAD,CDF,CHF,CLP,CNY,COP,CRC,CUP,CVE,CZK,DJF,DKK,DOP,DZD,EGP,ERN,ETB,EUR,FJD,FKP,GBP,GEL,GHS,GIP,GMD,GNF,GTQ,GYD,HKD,HNL,HRK,HTG,HUF,IDR,ILS,INR,IQD,IRR,ISK,JMD,JOD,JPY,KES,KGS,KHR,KMF,KPW,KRW,KWD,KYD,KZT,LAK,LBP,LKR,LRD,LSL,LTL,LYD,MAD,MDL,MGA,MKD,MMK,MNT,MOP,MRO,MUR,MVR,MWK,MXN,MYR,MZN,NAD,NGN,NIO,NOK,NPR,NZD,OMR,PAB,PEN,PGK,PHP,PKR,PLN,PYG,QAR,RON,RSD,RUB,RWF,SAR,SBD,SCR,SDG,SEK,SGD,SHP,SLL,SOS,SRD,STD,SYP,SZL,THB,TJS,TMT,TND,TOP,TRY,TTD,TWD,TZS,UAH,UGX,USD,UYU,UZS,VEF,VND,VUV,WST,XAF,XCD,XOF,XPF,YER,ZAR,ZMW,ZWL]",
          "value": "string"
        }
      }
    ]
  },
  "campaignName": "string",
  "endDate": "string",
  "fundingStrategy": {
    "bidPercentage": "string",
    "fundingModel": "FundingModelEnum : [COST_PER_SALE]"
  },
  "marketplaceId": "MarketplaceIdEnum : [EBAY_AT,EBAY_AU,EBAY_BE,EBAY_CA,EBAY_CH,EBAY_CN,EBAY_CZ,EBAY_DE,EBAY_DK,EBAY_ES,EBAY_FI,EBAY_FR,EBAY_GB,EBAY_GR,EBAY_HK,EBAY_HU,EBAY_ID,EBAY_IE,EBAY_IL,EBAY_IN,EBAY_IT,EBAY_JP,EBAY_MY,EBAY_NL,EBAY_NO,EBAY_NZ,EBAY_PE,EBAY_PH,EBAY_PL,EBAY_PR,EBAY_PT,EBAY_RU,EBAY_SE,EBAY_SG,EBAY_TH,EBAY_TW,EBAY_US,EBAY_VN,EBAY_ZA,EBAY_HALF_US,EBAY_MOTORS_US]",
  "startDate": "string"
}

New Table eBay Campaign

End Pause Resume | Enumeration with the relevant actions. Create is our Default Action | | | eBay Campaign > Action Status | Pending Error Not Needed Sent | Based on this status the relevant action will be performed | | | eBay Campaign > Campaign Error | | We store the error message from eBay if returned during campaign creation | | | eBay Campaign > Total Ads | | Field which will count the total products in a campaign. (Need to be indexed because will count the records dynamically) | | | eBay Campaign > Successful Ads | | Field which will count the total successfully added products in a campaign (Need to be indexed because will count the records dynamically) | | | eBay Campaign > Account ID | Dropdown field with all eBay Accounts | Internal Field which will allow us to set campaigns per account | | | eBay Campaign >status | | ERROR Indicates there is an error

DELETED Indicates the campaign is deleted and is no longer accessible. Only ended campaigns can be deleted. ENDED Indicates the campaign has ended and it cannot be restarted. The listings associated with this campaign are not being promoted. ENDING_SOON Indicates a request to end the campaign was received and the system is going through the process of ending the campaign. No further operations are possible on this campaign until it ends. PAUSED Indicates the campaign has been paused and the listings in that campaign are not being promoted. Sellers can pause campaigns when they want to temporarily suspend a campaign. For example, a seller can pause a campaign if they go on vacation. The campaign can restored to a running state at any time. PENDING Indicates the campaign is a criterion-based campaign and is in process of being created. RUNNING Indicates the campaign is active. Listings included in the campaign are actively being promoted with sponsored ads, which are displayed to buyers as they search for items on eBay. SCHEDULED Indicates the campaign has been created, but it is scheduled to start on specific date in the future. SYSTEM_PAUSED Indicates a system-generated, temporary pause on the campaign due to the seller's level dropping to Below Standard. Below Standard sellers cannot create new campaigns or edit their existing campaigns, but they can still view their campaign data and download reports. Once their seller level improves to Above Standard or Top Rated, sellers can resume using Promoted Listings and their campaigns will be automatically unpaused and return their last status. For more details on returning their seller level to Above Standard or Top Rated, sellers can refer to their seller dashboard on the eBay platform. | | campaignCriterion | eBay Campaign > campaign criterion | Leave Empty the whole node | Container for the fields that define the criteria for a rule-based campaign. | | campaignName | eBay Campaign >campaign name | Internal Unique Hemi Value | A seller-defined name for the campaign. This value must be unique for the seller. You can use any alphanumeric characters in the name, except the less than (<) or greater than (>) characters. Max length: 80 characters | | endDate | eBay Campaign > end date | Date Field | The date and time the campaign ends, in UTC format (yyyy-MM-ddThh:mm:ssZ). If this field is blank (code>null), it indicates a campaign that has no end date. For display purposes, convert this time into the local time of the seller. | | fundingStrategy.bidPercentage | eBay Campaign >bid percentage | Integer field with allowed valued form 1 - 100. | The user-defined bid percentage (also known as the ad rate) sets the level that eBay increases the visibility in search results for the associated listing. The higher the bidPercentage value, the more eBay promotes the listing. The value specified here is also used to calculate the Promoted Listings fee. This percentage value is multiplied by the final sales price to determine the fee. The Promoted Listings fee is determined at the time the transaction completes and the seller is assessed the fee only when an item sells through a Promoted Listings ad campaign. bidPercentage is a single precision value that is guided by the following rules: • These values are valid:    1,    1.0,    4.1,    5.0,    5.5, ... • These values are not valid:    0.01,    10.75,    99.99,    and so on. If a bid percentage is not provided for an ad, eBay uses the default bid percentage of the associated campaign. Minimum value: 1.0 Maximum value: 100.0 | | fundingStrategy.fundingModel | eBay Campaign > funding model | Dropdown field available as an enum COST_PER_SALE or COST_PER_CLICK | Indicates the model that eBay uses to calculate the Promoted Listings fee. Currently, only COST_PER_SALE is supported.

Default: COST_PER_SALE | | marketplaceId | | Based on the Item Account > Account ID the correct marketplace ID should be pushed Additional mapping is added in the code | The ID of the eBay marketplace where the campaign is hosted. Note the X-EBAY-C-MARKETPLACE-Id header value is ignored for this purpose. | | startDate | eBay Campaign > start date | Date Field | The date and time the campaign starts, in UTC format (yyyy-MM-ddThh:mm:ssZ). For display purposes, convert this time into the local time of the seller. On the date specified, the service derives the keywords for each listing in the campaign, creates an ad for each listing, and associates each new ad with the campaign. The campaign starts after this process is completed. The amount of time it takes the service to start the campaign depends on the number of listings in the campaign. Call getCampaign to check the status of the campaign. |

If we successfully create a campaign a campaignId will be returned which we will need to store in eBay Campaigns > Campaign ID field.

Get Campaigns

This method retrieves the details of a single campaign, as specified with the campaign_id query parameter.

This method returns all the details of a campaign (including the campaign's the selection rules), except the for the listing IDs or inventory reference IDs included in the campaign. These IDs are returned by getAds.

We need to use this call in order to obtain the campaignStatus using the compaign_id. We need to check the campaign status on a regular basis every time when we have a campaign id and the status is different from ENDED, ERROR, DELETED.

GET https://api.ebay.com/sell/marketing/v1/ad_campaign/{campaign_id}

After getCampaign call we will check if there is difference between external status that we receive from eBay and our action + action status normal. If there is such difference we will update both status.

We update the action only when we have normal status in Hemi

End, Pause, Resume Campaign

All this actions will be controlled with our internal Action Status and Action field on each campaign

End Campaign: This method ends an active (RUNNINGM) or paused campaign. Specify the campaign you want to end by supplying its campaign ID in a query parameter.

Call getCampaigns to retrieve the campaign_id and the campaign status (RUNNING, PAUSED, ENDED, and so on) for all the seller's campaigns.

POST https://api.ebay.com/sell/marketing/v1/ad_campaign/{campaign_id}/end

There is no response body if success if error we store the error in our error field with error status.

However if we receive success we need to mark the campaign with status ENDING_SOON and Action Status = Not Needed If we receive an error we do not update the campaign status but we set Action Status = Error and populate the error message in campaign error field

Pause Campaign:

This method pauses an active (RUNNING) campaign.

You can restarted by calling resumeCampaign, as long as the campaign's end date is in the future.

Note: The listings associated with a paused campaign cannot be added into another campaign.

Call getCampaigns to retrieve the campaign_id and the campaign status (RUNNING, PAUSED, ENDED, and so on) for all the seller's campaigns.

POST https://api.ebay.com/sell/marketing/v1/ad_campaign/{campaign_id}/pause

There is no response body if success if error we store the error in our error field with error status. However if we receive success we need to mark the campaign with status = PAUSED and Action Status = Not Needed If we receive an error we do not update the campaign status but we set Action Status = Error and populate the error message in campaign error field

Resume Campaign:

This method resumes a paused campaign, as long as it's end date is in the future. Supply the campaign_id for the campaign you want to restart as a query parameter in the request.

Call getCampaigns to retrieve the campaign_id and the campaign status (RUNNING, PAUSED, ENDED, and so on) for all the seller's campaigns.

POST https://api.ebay.com/sell/marketing/v1/ad_campaign/{campaign_id}/resume

There is no response body if success if error we store the error in our error field with error status.

However if we receive success we need to mark the campaign with status RUNNING and Action Status = Not Needed If we receive an error we do not update the campaign status but we set Action Status = Error and populate the error message in campaign error field

Adding ads (listings) into Promoted Listings campaign

This method adds multiple listings to an existing Promoted Listings campaign using listingId (our channel item id) values generated by either the Trading API or Inventory API.

For each listing ID specified in the request, this method:

• Creates an ad for the listing.
• Sets the bid percentage (also known as the ad rate) for the ad.
• Associates the ad with the specified campaign.

To create an ad for a listing, specify its listingId, plus the bidPercentage for the ad in the payload of the request. Specify the campaign to associate the ads with using the campaign_id path parameter. Listing IDs are generated by eBay when a seller creates listings with the Trading API.

You can specify a maximum of 500 listings per call and each campaign can have ads for a maximum of 50,000 items. Be aware when using this call that each variation in a multiple-variation listing creates an individual ad. Note: No matter how you add items to a Promoted Listings campaign, each campaign can contain ads for a maximum of 50,000 items.

New Table Campaign Ads which will be slave table of eBay Campaigns

POST https://api.ebay.com/sell/marketing/v1/ad_campaign/{campaign_id}/bulk_create_ads_by_listing_id

{ /* BulkCreateAdRequest */
"requests" : [
{ /* CreateAdRequest */
"bidPercentage" : "string",
"listingId" : "string"}
]
}

In the response we will receive all ads processed by the call and included in the campaign. Only these ids need to be added in the slave table Campaign Ads for the specific campaign.

TBD

{
  "responses": [
    {
      "adId": "string",
      "errors": [
        {
          "category": "string",
          "domain": "string",
          "errorId": "integer",
          "inputRefIds": [
            "string"
          ],
          "longMessage": "string",
          "message": "string",
          "outputRefIds": [
            "string"
          ],
          "parameters": [
            {
              "name": "string",
              "value": "string"
            }
          ],
          "subdomain": "string"
        }
      ],
      "href": "string",
      "listingId": "string",
      "statusCode": "integer"
    }
  ]
}

Deleting ads (listings) from Promoted Listings campaign

This method removes the specified ad from the specified campaign.

Pass the ID of the ad to delete with the ID of the campaign associated with the ad as path parameters to the call. After successful deletion we will remove the Ad Id.

DELETE https://api.ebay.com/sell/marketing/v1/ad_campaign/{campaign_id}/ad/{ad_id}

This call has no response headers.

PHASE 2

In second phase we will include Promoted Listings Advance

Q&A

Q&A Can an add be added in a campaign if the campaign is RUNNING or SCHEDULED? Yes, seller can add the new listing in the Running/Scheduled PLS/PLA campaigns (ad groups).

Can we add a product with 0 stock and then become available? Yes, for both PLS/PLA campaigns.

Can we have an add participating in two campaigns? PLS: No, one listing can be added in only one PLS campaign PLA: Yes, one listing can be added in multiple PLA campaigns And you can also add the same listing in both PLS and PLA campaigns as well.

Can a single listing be a part of a campaign and promotion at the same time? Yes, the listing can be added in PLS/PLA campaigns and Promotion Manager at the same time.

#