Generic marketplace flow [TBR]
This document’s purpose is to describe the generic marketplace flow which we always should be aiming to achieve.
| Terminology | Meaning |
|---|---|
| Listing | The whole product descriptive information as per marketplace best practice. |
| Order | The whole information about the order that has been placed on the marketplace including address of the receiver, product on order, etc. |
| Taxonomy | Refers to the information about category tree and all of it’s components(mandatory attributes, not mandatory attributes, their values, etc.) |
| MP | Refers to Marketplace. |
To start off we are going to differentiate a few different integration states:
- Minimum viable product(MVP)
- Fully extended integration
MVP
Definition:
The MVP approach should aim to have the essential flows for a working automation of the whole end to end process from gettin order data to providing that order data to an external system and then receiving shipping confirmations that would be automatically sent to the Marketplace. That approach would also include the other 2 main processes we aim to automate from end to end which are updating stock and updating prices. So following all of that the MVP approach requires:
- Update stock levels on the marketplace
- Update prices on the marketplace
- Download order data from the marketplace
- Update orders as dispatched/shipped on the marketplace
Fully extended integration
Definition:
The fully extended integration should aim to have all flows which means:
- Create/update whole listing information(including but not limited to product description, product title, etc.) as per best practice for the marketplace.
- Update stock levels on the marketplace
- Update prices on the marketplace
- Download order data from the marketplace
- Update orders as dispatched/shipped on the marketplace
- Download cancelled orders information and update in WAP technology(if available)
- Download returns information(if available)
- Download taxonomy(if available)
Flows and flag behaviour
There are a lot of flags and statuses in the system which define what the logic behind every process in the system. Below they are broken down by section of the system:
Listing create flow:
CASE#1 - Listing a single SKU on a marketplace with feed based communication.
| IF | THEN |
|---|---|
| IF we want to create a listing on the marketplace then: | list update the whole item = pendingproduct status = awaiting creationlisting status = inactiveclosed = Noprotect whole item = Nochannelitemid = Nullvariation group = Null |
| If all internal validations are passed and the info gets successfully sent: | list update the whole item = sentproduct status = awaiting creationlisting status = inactiveclosed = Noprotect whole item = Nochannelitemid = Nullvariation group = Null |
| If the creation was successfull: | list update the whole item = normalproduct status = product publishedlisting status = activeclosed = Noprotect whole item = Nochannelitemid = to be populated with the listing id provided by the marketplacevariation group = Null |
| If an error is returned by the marketplace: | list update the whole item = errorlisting error = to be populated with the error from the marketplaceproduct status = awaiting creationlisting status = inactiveclosed = Noprotect whole item = Nochannelitemid = Nullvariation group = Null |
CASE#2 - Listing a variation on a marketplace with feed based communication.
| IF | THEN |
|---|---|
| IF we want to create a listing on the marketplace then: | list update the whole item = pendingproduct status = awaiting creationlisting status = inactiveclosed = Noprotect whole item = Nochannelitemid = Nullvariation group = Not Empty |
| In that case the information for all SKU’s that have the same variation group has to be selected and sent to the Marketplace. | |
| If all internal validations are passed and the info gets successfully sent: | list update the whole item = sentproduct status = awaiting creationlisting status = inactiveclosed = Noprotect whole item = Nochannelitemid = Nullvariation group = Not Empty |
| This is applied on all SKU’s that have the same variation group. | |
| If the creation was successfull: | list update the whole item = normalproduct status = product publishedlisting status = activeclosed = Noprotect whole item = Nochannelitemid = to be populated with the listing id provided by the marketplacevariation group = Not Empty |
| This is applied on all SKU’s that have the same variation group. | |
| If an error is returned by the marketplace: | list update the whole item = errorlisting error = to be populated with the error from the marketplaceproduct status = awaiting creationlisting status = inactiveclosed = Noprotect whole item = Nochannelitemid = Nullvariation group = Not Empty |
| This is applied on all SKU’s that have the same variation group. |
CASE#3 - Listing a single SKU on a marketplace with sync base communication.
| IF | THEN |
|---|---|
| If we want to create the listing: | list update the whole item = pendingproduct status = awaiting creationlisting status = inactiveclosed = Noprotect whole item = Nochannelitemid = Nullvariation group = Null |
| If the creation was successfull: | list update the whole item = normalproduct status = product publishedlisting status = activeclosed = Noprotect whole item = Nochannelitemid = to be populated with the listing id provided by the marketplacevariation group = Null |
| If an error is returned by the marketplace: | list update the whole item = errorlisting error = to be populated with the error from the marketplaceproduct status = awaiting creationlisting status = inactiveclosed = Noprotect whole item = Nochannelitemid = Nullvariation group = Null |
CASE#4 - Listing a variation on a marketplace with sync base communication.
| IF | THEN |
|---|---|
| If we want to create the listing: | list update the whole item = pendingproduct status = awaiting creationlisting status = inactiveclosed = Noprotect whole item = Nochannelitemid = Nullvariation group = Not Empty |
| In that case the information for all SKU’s that have the same variation group has to be selected and sent to the Marketplace. | |
| If the creation was successfull: | list update the whole item = normalproduct status = product publishedlisting status = activeclosed = Noprotect whole item = Nochannelitemid = to be populated with the listing id provided by the marketplacevariation group = Not Empty |
| This is applied on all SKU’s that have the same variation group. | |
| If an error is returned by the marketplace: | list update the whole item = errorlisting error = to be populated with the error from the marketplaceproduct status = awaiting creationlisting status = inactiveclosed = Noprotect whole item = Nochannelitemid = Nullvariation group = Not Empty |
| This is applied on all SKU’s that have the same variation group. |
CASE#5 - Listing a single SKU on a marketplace with separate listing and offer.
| IF | THEN |
|---|---|
| IF we want to create a listing on the marketplace then: | list update the whole item = pendingproduct status = awaiting creationlisting status = inactiveclosed = Noprotect whole item = Nochannelitemid = Nullvariation group = Null |
| If all internal validations are passed and the info gets successfully sent: | list update the whole item = sentproduct status = awaiting creationlisting status = inactiveclosed = Noprotect whole item = Nochannelitemid = Nullvariation group = Null |
| If the creation was successfull: | list update the whole item = normalproduct status = product publishedlisting status = activeclosed = Noprotect whole item = Nochannelitemid = to be populated with the listing id provided by the marketplacevariation group = Null |
| If an error is returned by the marketplace: | list update the whole item = errorlisting error = to be populated with the error from the marketplaceproduct status = awaiting creationlisting status = inactiveclosed = Noprotect whole item = Nochannelitemid = Nullvariation group = Null |
Update Price Flow:CASE#1 - Marketplace allows separate feed based price and stock updates
Price Update should work the same way for single products and for variation products. We always send just the item accounts which meets the requirements for price update.
| IF | THEN |
|---|---|
| If we want to update price we need to have the following case: | update_price = pendingclosed = 0protect whole item = 0protect price = 0ChannelItemID != ““listingStatus = activeproductStatus = product_published |
| After successful send price update : | update_price = sentclosed = 0protect whole item = 0protect price = 0ChannelItemID != ““listingStatus = activeproductStatus = product_published |
| After successful price update: | update_price = normalclosed = 0protect whole item = 0protect price = 0ChannelItemID != ““listingStatus = activeproductStatus = product_published |
| After NOT successful price update: | update_price = errorupdate_price_error = error messageclosed = 0protect whole item = 0protect price = 0ChannelItemID != ““listingStatus = activeproductStatus = product_published |
CASE#2 - Marketplace does NOT allow separate feed based price and stock updates
Price Update should work the same way for single products and for variation products. We always send just the item accounts which meets the requirements for price update.
| IF | THEN |
|---|---|
| If we want to update price we need to have the following case: | update_price = pendingupdate_quantity = pendingclosed = 0protect whole item = 0protect price = 0ChannelItemID != ““listingStatus = activeproductStatus = product_published |
OR
update_price = pendingclosed = 0protect whole item = 0protect price = 0ChannelItemID != ““listingStatus = activeproductStatus = product_published
OR
update_quantity = pendingclosed = 0protect whole item = 0protect price = 0ChannelItemID != ““listingStatus = activeproductStatus = product_published |
| After successful send price update : | update_price = sentupdate_quantity = sentclosed = 0protect whole item = 0protect price = 0ChannelItemID != ““listingStatus = activeproductStatus = product_published |
| After successful price update: | update_price = normalupdate_quantity = normalclosed = 0protect whole item = 0protect price = 0ChannelItemID != ““listingStatus = activeproductStatus = product_published |
| After NOT successful price update: | update_price = errorupdate_quantity = errorupdate_price_error = error messageupdate_quantity_error = error messageclosed = 0protect whole item = 0protect price = 0ChannelItemID != ““listingStatus = activeproductStatus = product_published |
CASE#3 - Marketplace allows separate sync based price and stock updates
Price Update should work the same way for single products and for variation products. We always send just the item accounts which meets the requirements for price update.
| IF | THEN |
|---|---|
| If we want to update price we need to have the following case: | update_price = pendingclosed = 0protect whole item = 0protect price = 0ChannelItemID != ““listingStatus = activeproductStatus = product_published |
| After successful price update: | update_price = normalclosed = 0protect whole item = 0protect price = 0ChannelItemID != ““listingStatus = activeproductStatus = product_published |
| After NOT successful price update: | update_price = errorupdate_price_error = error messageclosed = 0protect whole item = 0protect price = 0ChannelItemID != ““listingStatus = activeproductStatus = product_published |
CASE#4 - Marketplace does NOT allow sync feed based price and stock updates
Price Update should work the same way for single products and for variation products. We always send just the item accounts which meets the requirements for price update.
| IF | THEN |
|---|---|
| If we want to update price we need to have the following case: | update_price = pendingupdate_quantity = pendingclosed = 0protect whole item = 0protect price = 0ChannelItemID != ““listingStatus = activeproductStatus = product_published |
OR
update_price = pendingclosed = 0protect whole item = 0protect price = 0ChannelItemID != ““listingStatus = activeproductStatus = product_published
OR
update_quantity = pendingclosed = 0protect whole item = 0protect price = 0ChannelItemID != ““listingStatus = activeproductStatus = product_published |
| After successful price update: | update_price = normalupdate_quantity = normalclosed = 0protect whole item = 0protect price = 0ChannelItemID != ““listingStatus = activeproductStatus = product_published |
| After NOT successful price update: | update_price = errorupdate_quantity = errorupdate_price_error = error messageupdate_quantity_error = error messageclosed = 0protect whole item = 0protect price = 0ChannelItemID != ““listingStatus = activeproductStatus = product_published |
VALIDATION:
Internal validation for price updates should be
start_price != 0
start_price > 0
start_price != NULL
RRP != 0
RRP > 0
RRP != NULL
Send RRP only when:
RRP > start_price
Listing flags:
- List/Update the whole item
Possible values: Not Needed, Pending, Relist, Sent, Completed, Error
Logic: standard feed based marketplace
Standard when the flag is set to Pending the integration is supposed to pick it up and send it for creation
- Update quantity
Possible values: Not Needed, Pending, Sent, Completed, Error
- Update price
Possible values: Not Needed, Pending, Sent, Completed, Error
- End Item
Possible values: Yes, No
- End Listing
Possible values: Yes, No
- Protect Price
Possible values: Yes, No
- Protect Whole Item
Possible values: Yes, No
- Closed
Possible values: Yes, No
Listing statuses:
- Listing Status
Possible values: Active, Inactive
- Product Status
Possible vales: Awaiting creation, Product created, Images uploaded, Product published, Product removed
-
Listing duration
-
Listing Type
Possible values: Auction, Fixed price item
Order flags:
- Take action
Possible values: Yes, No
- Exported
Possible values: Yes, No
- Notification was sent to the app
Possible values: Yes, No
- Re-Calculate VAT
- Recalculate Fee
- Update shipping pending
Possible values: Yes, No
- Billing info received
Possible values: Yes, No
- Out of stock
Possible value: Yes, No
- Splitted shipping cost
Order statuses:
- Marketplace status
Possible values: Depends on the MP.
- Order status
Possible values: Pending, Incomplete, Ready For Shipping, Shipped, Cancelled, Refused
- Order payment/hold status
Possible values: Depends on the MP.
- Marketplace fulfillment channel
Possible values: Depends on the MP.
- Order Type
Possible values: Depends on the MP.