Follow

Kahuna Marketplace Integration

At Kahuna we want to make sure that you are able to take advantage of one of the most powerful data resources available.  To make sure that happens Kahuna has a pre-defined integration that we ask all customers to follow.

This integration is additional to the regular Kahuna integration you would normally perform in order to send and track messaging within Kahuna

For the developer documentation, please visit the Kahuna Marketplace SDK Reference.

marketplace_health_dashboard.png

The Kahuna marketplace integration, using our data format, is required in order to take advantage of all of Kahuna’s marketplace tools but you may integrate as much as is available.*


Credentials

Login credentials are unique identifiers that a Marketplace uses to uniquely identify its users. You may also create the same value as an attribute on the user for targeting purposes. Each credential is required to be a unique ID to every individual user.

 

username (string)

The login identity for your platform

bigseller123

user_id (string)

The ID number your platform assigns to a user

534982

email (string)

Email used for login

user@kahuna.com

id (string)

A unique identifier (kahuna made?)

534982

 

User Attributes

User attributes are details that define each individual user on your platform. That should be descriptions that don’t change often and help you uniquely identify them. (First Name, Gender, Location).

Kahuna will use the attributes of your users to develop powerful user dashboards that not only provide insight into the demographics of your property but also performance and history of specified demographics (specified by customer) over time.

 

Attribute

Definition

Example

first_name (string)

First name of the user

john, maria

last_name (string)

Last name of the user

smith, jones

username (string)

The login identity for your platform

bigseller123

user_id (string)

The ID number your platform assigns to a user

534982

join_date (date)

The date the user signs up for your marketplace (ISO 8601 format)

2018-09-05
2018-09-05T21:56:04

gender (string)

The designated gender of your user

male, female, undecided

birth_date (date)

The date of birth for the user

1985-01-10

buyer_flag* (string)

Has the user been identified as a buyer

  • If you do not pre-define a user as a “buyer” by saying true, then Kahuna will automatically add the flag if/when they make their first purchase

true

seller_flag* (string)

Has the user been identified as a seller

  • If you do not pre-define a user as a “seller” by saying true, then Kahuna will automatically add the flag if/when they make their first listing

true

city (string)

Current city location of user

New York, Paris

country (string)

Current country of your user

US, Singapore, Italy

rating (number)

The rating given to your user by other users

  • Anytime the users rating changes you will need to send the new rating score.  Kahuna will NOT update this score automatically

1, 3

followers (number)

How many users are following this seller/buyer

500

view(s) (number)

How many users have viewed this users profile

2398

email (string)

The email address (credential) for this user

emailme@kahuna.com

 

Listings

When using the Kahuna Marketplace SDK to add, edit and reference listings, Kahuna maintains the status of the listing.

listing_status

active

complete

expired

removed

The listing status is a the state of a listing that Kahuna derives based on a set of rules.  You DO NOT integrate this event but should be aware that we label all listings under one of these states

 

Events and Properties

Events are any action that a user can take anywhere within your property. Whether that be on your mobile application, your website or non-direct actions tracked through your servers (API).

In order to take advantage of Marketplace tools, it is REQUIRED that all the following events and their associated properties be integrated AND formatted exactly as requested below. The Kahuna Marketplace SDK for iOS, Android, and Javascript provides an interface to ensure that your integration uses the correct event names and properties.

If the integration does not follow the below formats exactly Kahuna can not guarantee that it’s marketplace tools will deliver accurate or detailed information.

POSSIBLE METADATA : These are additional properties that you may include in your payload of “add_listing” to further define reports.  These are current NOT used in platform reporting

REQUIRED PROPERTIES : Properties that are bolded are required for the event

PROPERTIES WITH MULTIPLE VALUES : Properties with an asterisk (*) indicate that they event may have more than one value for this property.

Event (listing)

Required Properties

Definition

add_listing

listing_id
*category
title
price
(per unit)
quantity
sku
revenue (per unit)
*sub_category
sub_title
description
*buy_type
expiration
shipping_price (per unit)
shipping_type
location

POSSIBLE METADATA

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

When a user 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)

Everytime any of the above occurs Kahuna will create a new listing_object to track within our database.

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.

edit_listing

  

listing_id
* category
title
price (per unit)
quantity
sku
revenue (per unit)
* sub_category
sub_title
description
* buy_type
expiration
shipping_price (per unit)
shipping_type
location

POSSIBLE METADATA

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

When a “seller” edits any aspect of a listing_objects properties.


This can include but is not limited to

  • Changing the title
  • Updating the price
  • Increasing the quantity

remove_listing

listing_id

When a “seller” removes or ends a listing prior to completion


This can include but is not limited to

  • Deleting a listing
  • Marking a sold manually

promote_listing

listing_id
promotion_type

When you as a k_user decide to specifically promote an item on your marketplace


This can include but is not limited to

  • Advertising an listing
  • Recommending an listing

purchase_listing

listing_id
transaction_id
price
(per unit)
quantity
revenue (per unit)
offer_id
bid_id
buy_type
shipping_price (per unit)
shipping_type

When a “buyer” completes a purchase and that purchase is confirmed


This can include but is not limited to

  • Winning an auction
  • An offer is accepted
  • A user BIN

make_offer_listing

listing_id
offer_id
price (per unit)
quantity

When a “buyer” makes an offer on a listing

bid_listing

listing_id
bid_id
price
(per unit)
quantity

When a “buyer” makes bids on a listing

add_to_cart_listing

listing_id
price
(per unit)
quantity
buy_type
revenue (per unit)
shipping_price (per unit)
shipping_type

When a “buyer” places an item into a “shopping cart” which would be one step before making a purchase


  • What a “shopping cart” is can be defined by you
    • A traditional store shopping cart
    • A reserve placeholder
    • A selected item

remove_from_cart_listing

listing_id
quantity

When a “buyer” removes a listing from the above defined “shopping cart”

view_listing

listing_id

When a “buyer” views a listing


This is defined as landing on the specific page for the listing

watch_listing

listing_id

When a “buyer” watches a listing


This is defined as any action in which a buyer sends a signal that they would like to be kept informed about an item.


This can include but is not limited to

  • Follow
  • Favorite
  • Watch

Timestamps are added to every single event by default from Kahuna and therefore “date” properties are not required needed

Property Definitions

IDs

Property Name Description Examples
listing_id

A unique ID for every single item added to your marketplace.  This is NOT a product page but can include multiple quantities

listing_20938
user_id

This could be any unique credential assigned to a user.  It is REQUIRED to be unique

user@kahuna.com
user2341
123128
chat_id

A unique ID given to any chat started between 2 users

chat_23901
offer_id

A unique ID given to every single offer on a listing.  If the same user changes their offer it is a NEW offer_ID

offer_32912
store_id

If you have a “storefront” for sellers with several items, this is the unique ID for that area

store_userid_23492
bid_id

A unique ID given to every single bid on a listing.  If the same user makes a new bid it is a NEW bid_ID

bid_93012

Other Properties

Property Name Description Examples
buy_type

When a user makes a purchase what type of purchase was it

BIN, Auction, Offer
category

The section of the marketplace that the listing exists

men, women, kids, fashion, electronics, sports, condo, SFH, studio, bar, restaurant, café
credential_type (seller/buyer)

Certain events require specific credentials to be used and so they must be specified

email
id
username
credential_value (seller/buyer)

The value of the above referenced credential

user@kahuna.com
23490283
kahuna_seller
description

The full description of the listing item

Newly released pair of great shoes
Seats available at this amazing restaurant
expiration_date

The date (if available) that the listing will expire if not purchased or remote (ISO 8601 format)

2018-09-05
2018-09-05T21:56:04
item_number

A unique identifier for this specific item.  In many cases this is your SKU. 

3249820
location

The location of the item.  This should be consistent always but can be any level of location.  Additional properties (city, state, postal_code, country, etc.) can always be used to store more specific values 

US, Canada, Italy
CA, US / NY, US
94012 / 29049
price

The price per individual item in a listing.  If there is one item this is  the single price, if there are 2 items available, it is the price for only 1 of those items. A multipack is considered a single item.

9.99
quantity

How many (inventory) are available of a single item in a listing

5
rating

When a user rates another user (buyer or seller) what was their rating

4 stars
good/bad
1 out of 5
removelisting_reason

If a listing is removed by a seller, what was the reason for that removal

mistake listing
no longer available
no longer want to sell
revenue (per unit)

What is the total revenue YOU as a marketplace will make on the sale of this item.  Prior to a purchase, if the amount could change, it is the estimated amount

9.99
search_term

If a user searches, what is the string that they searched

“this is a search”
shipping_price (per unit)

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

9.99

 

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

Comments