Use the AddListingEventBuilder when a seller adds/uploads/creates a new object on your marketplace that is available for sale.

This can include but is not limited to:

  • Creating an new listing through your website/app
  • Using an API to upload a new item
  • Making something newly available that already exists on the platform (not re-activating)

Every time any of the above occurs Kahuna will create a new listing_object to track within our database, only if the listing_id does not already exist. If the listing has previously been created, use the EditListingEventBuilder object to update the listing.

This event will power 90% of the marketplace tools within Kahuna including the Marketplace Health Dashboard, the Seller Performance Profile and several marketing performance tools. This event and its associated properties is REQUIRED for all marketplace integrations.

Required Properties:

  • listing_id
  • category (multiple categories allowed)
  • title
  • price (per unit)
  • quantity

Additional Properties:

  • sku
  • revenue (per unit)
  • subcategory (multiple subcategories allowed)
  • subtitle
  • description
  • buy_type (multiple buy_types allowed)
  • expiration
  • shipping_price (per unit)
  • shipping_type
  • location

*POSSIBLE METADATA : These are additional properties that you may include in your payload of “add_listing” to further define reports. These are currently NOT used in platform reporting, and you must add these using the addProperty method.

  • brand
  • condition
  • color
  • size
  • model
  • mpn
  • upc
  • country_of_origin
  • material
  • accepted_payments
  • photo_count
  • return_policy
  • promote



Create an empty AddListingEventBuilder

 AddListingEventBuilder(String listing_id)

Create an AddListingEventBuilder with just a listing ID

 AddListingEventBuilder(String listing_id, String category, String title, Double pricePerUnit, Integer quantity)

Create an AddListingEventBuilder with all required properties

Public Methods

 AddListingEventBuilder addBuyType(String buy_type)

Add a short description of the way that a buyer can buy the item. You may have any number of BuyType values. You may add your own buy types. Common buy types are:

  • "fixed price item"
  • "auction"
  • "second chance offer"
  • "subscription"
  • "trade in"
 AddListingEventBuilder addCategory(String category)

The category in which the listing appears. You may have any number of Category values.

 AddListingEventBuilder addSubcategory(String subcategory)

The subcategory in which the listing appears. You may have any number of Subcategory values.

 AddListingEventBuilder setDescription(String description)

The description of the item in plain text (no markup). It is recommended that the description be less than 2000 characters.

 AddListingEventBuilder setExpiration(Date expiration)

Set the Date and Time (in UTC) that the listing expires. If not set, the listing does not expire. The Date must be in the Coordinated Universal Time (UTC) timezone, and it is the responsibility of the application developer to do the timezone conversion. The Expiration should always be in the future.

 AddListingEventBuilder setListingID(String listing_id)

Set the unique Listing Identifier used to reference this specific listing. This Listing Identifier is used in other calls to edit the Listing, add the listing the a customers cart, purchase the listing, etc. 

 AddListingEventBuilder setLocation(String location)

Set the location of the listing. The location format should be consistent, such as
"San Francisco, California, United States".

addProperty(name, value) can be used to store additional location properties, such as:

addProperty("postalcode", "94109")
addProperty("city", "san francisco")
addProperty("state", "california")

 AddListingEventBuilder setPricePerUnit(Double pricePerUnit)

Set the price of the listing (per unit purchased). All listings should be in the same currency as defined by your namespace's currency choice.

 AddListingEventBuilder setQuantity(Integer quantity)

Set the quantity of items available in the listing. The quantity must be a positive integer. If you have an unlimited number of items available (such as for services), you should choose a number based on the upper bound of your forecast for sales.

 AddListingEventBuilder setRevenuePerUnit(Double revenue)

Set the revenue (per item) that you (as the marketplace) makes for a purchase. 

Prior to a purchase, if the amount could change, it is the estimated amount. If specified, this must be a non-negative number measured consistently in the same currency across your platform.

 AddListingEventBuilder setShippingPrice(Double shipping_price)

How much is listed as the shipping price AND/OR how much the shipping was calculated as when purchased

If specified, this must be a non-negative number measured consistently in the same currency across your platform.

 AddListingEventBuilder setShippingType(String shipping_type)

The shipping types supported by the seller for this listing. You may have any number of shipping types. Common shipping types might include:

  • fedex
  • ups
  • usps
  • same day
  • next day
  • two day
 AddListingEventBuilder setSKU(String SKU)

Set the SKU (Stock Keeping Unit, or other item identifier) of the product being listed. Multiple listings (by the same or different sellers) can have the same SKU.

 AddListingEventBuilder setSubtitle(String subtitle)

Set the Subtitle of the listing, if available. It is recommended that the subtitle be less than 100 characters.

 AddListingEventBuilder setTitle(String title)

Set the primary Title of the listing.

Methods inherited from EventBuilder

 Object build()

Returns the object required by the track() method in the Kahuna SDK. This should be used just as a KahunaEventBuilder would.

 EventBuilder addProperty(String key, String value)

Sets the event property named "key" with the value "value".

Intelligent Event campaign filters ignore the letter case of event names, property keys, and property values. For example, the event WATCH_MOVIE matches the filter value watch_movie, Watch_Movie, and Watch_movie.

The property key must be a string value.

Property keys cannot start with k_, because this prefix is reserved for Kahuna system keys.

Property values must be a single string. You can provide a set of values by calling addProperty() multiple times with the same key, passing in a different value each time.

You can add up to 25 properties to a single builder object.

Because multiple values for a key are stored as a set, you can't add the same value more than once. If you try, you still have one occurrence of that value in the set.

If you try to set an empty key or value, addProperty ignores the call and writes a message to the debug logs.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request