Introduction

Advantages of integrating with Ounass Marketplace

Ounass Marketplace API Integration is an exclusive integration served only to Ounass Marketplace Vendors in which vendors execute their Ounass Marketplace related operations systematically and get latest updates on each product and transfer whenever they request. Using API decreases operational costs for companies and let them use their valuable workforce for more strategic actions. Our API's gives you many capalities so that you have the autonomy to operate by yourself in every step of your operation.

Product Creation

Vendors can send product information to create/update products.

• You can decide in which website to sell each SKU among your available regions initially agreed
• You can put AED prices and auto conversion & rounding will turn prices into local currencies considering VAT’s in each region and currency rates
• You can apply different price to any region if you don’t want to use conversions or can apply conversions in few and put different value to a specific region
• You can update barcode, website you will sell and retail price information any time you prefer
• You can either create product in the form for of excel by downloading template, filling it and posting or via JSON.
• You can create product in the form for of JSON. Following that option you will be able to get all available attributes and their values per each category via API.
• You can only select attribute values from available options or can map with your existing values (mapping will be release on March 2021)

Monitoring Product Statuses

We generate a catalog per each vendor that compose of successful product creations for vendors to monitor their products

• After creating products just half an hour later you can create transfer for products uploaded on the system.
• You can monitor product statuses to understand if SKU is available and processed to include inside a transfer.
• You can get all products uploaded on the system with all available information (price, status, barcode, VPN etc.) any time you want.

Transfer/PO Creation

Vendors can create a transfer/PO anytime they want by checking if products are already in Ready status.

• You can create/update a transfer in the form of excel or JSON
• You can update or delete transfer if the appointment is not requested
• You can see transfer content (SKU, quantity etc.) any time they want
• You can monitor their transfers created via API’s and see their statuses if transfers are received, if the appointment is created etc.

Appointment Creation

Vendors can request appointment automatically via API. No additional information is required.

• After creating transfer you can directly request for an appointment creation via API. There is a 1 to 1 conection between transfers and appointments
• The Appointment team sends scheduling information over email to primary contact of the vendor after receiving your appointment creation request

Shipment Information Creation/Update

Vendors can create shipment information as international or local with shipment address, shipment contact, courier information /drop by vendor.

• You can create/update shipment information for a transfer via API and our logistic team will be acknowledged automatically and will communicate with you if necessary
• Address used in shipment information is stored in the form of address id and can be used in future shipments
• You can not request pick up from Ounass via API now but it is in roadmap and can be developed sooner if requested

Sales Information

Vendors can request and get full order detail any time they want. We do record orders real time.

• Full order detail includes:

Order ID, Order Creation Date, Order Status, Status Record Date, Customer ID, Website, Shipment Country, Shipment City, SKU, Brand, VPN, Color, Size, Barcode, Gender, Category, Item Name, Pricing Type, Discount Amount, Retail Price, Retail Price AED, Gross Revenue AED, Currency Rate, SKU Quantity, Return Reason (exists if item is returned or cancelled)

Stock Information

Vendors can request and get stock detail any time they want. Stock Information can be received per different states.

• Stock states available is:
  Stock on Hand, Sellable Stock, Received Stock, In Transit Stock, Out of stock.
  
• Stock information per each state includes:
  Item Name, Brand, SKU ID, Barcode, VPN, Color, Size, Gender, Season, Category, Quantity.
  

Availability To Use Vendor Portal

Only vendors who integrate with our API’s can fully benefit from our portal.

• marketplace.ounass.com will be available for integrated vendors to manually operate if preferred / any problem arise. Same, even more feature set is available on the portal
• Semi integration can be done (for example product creation/update integration solely) and rest of the operation can also be done via our user friendly Vendor Portal
• Vivid dashboard for you to monitor your Sales & Stock in order to create replenishment on time, see your new orders, what is top selling and how your gross revenue is growing

Faster Go Live

We give autonomy to vendors to self-serve in each process with high visibility over their actions and decrease go live durations and increase efficiency on vendor behalf.

• We process product creation/update requests in around half an hour (only price updates are processed after 07:00 PM (GMT+4)) letting you to create transfers right away without any dependency to Marketplace Team
• There is no back and forth emails between warehouse departments such as appointment team and logistic team to coordinate shipment or tramsfer. All processes are automatic which decrease operational hassle on vendor side
• We give higher visibility by using product and transfer statuses so that vendors know if their action is reflected and processed in the system

Dedicated Tech Team

As a part of Vendor Portal a fresh tech team is dedicated to serve Marketplace vendor needs.

• We do support you before and after integration
• We consider and highly value each vendor need. We put them in our roadmap, prioritize and develop accordingly; assuring vendor requirements are met during their partnership with us

Evolving API’s

Ounass Marketplace portal and it’s API’s will evolve in time giving users more functionality every month.

• We aim to serve vendor 360° in each process they undergo with our tech capabilities
• We release new features to our portal every month

How to integrate via API

For end to end integration your systems should also have services available in the form of API’s as well and should be able to call REST API's. In order to integrate via API, you should have a technical employee or a 3rd party you work with to assess your integration capabilities. If you want to discuss further, please contact with your Account Manager.

Authorization

Marketplace Vendor portal uses API Token to allow access. The identity of the vendor is determined with API Token. In this way, it is ensured that the vendor only inquires about its products and other informations. You can create an API Token from API Management page under "Settings" after login.

Get API Key

After logging into the Vendor portal once you click Settings, a sub-menu will open called “API Management”. Once you clicked API Management, you will land to a page where you can create API Token. Only Token Name is necessary to generate an API Key. Still we recommend you to fill IP Restriction field. IP restriction is a second layer of security. By not typing any IP you will make your API's public. That means everyone who has your API token will be able to reach your API's. You can type multiple IPs by separating with comma. Once you click Generate API Token button don't forget to copy your Token and share with your tech team. You won't be able to reach your token again for security purposes once it is generated. If you didn't copy the Token then we advise you to create a new one. You can create multiple API Tokens and revoke the ones you don't use. Keep in mind that only Vendor Admins can reach API Management page.

Marketplace Vendor portal expects the API Token to be included in all API requests to the server.

Integration Flow

Our integration flow and our REST API’s are as follows:

Get Required Product Fields

To sell your products at Ounass, first the products has to be added to Ounass Catalog System. Before creating a product we have an API for our vendors to see the product fields necessary to be filled per each category.

• Products in different category has different fields to fill mandatory & non mandatory.
• Vendors who prefer to upload product via Excel can download our template for all categories in the form of excel with API [GET] /api/v1/vendors/productTemplate?empty=true. Template includes multiple sheets/category labels and each sheet has different fields mandatory/non mandatory as data collected changes according to category.
• We also have API’s in the form of JSON. Vendor can see available categories via API [GET] /api/v1/categories and according to category of the product they will create, they are able to get necessary attributes and their available values via API [GET] /api/v1/categories/{categoriesId}/attributes.
• Also vendors can only send products for Brands agreed with Marketplace. As it doesn’t necessarily be all brand portfolio, we have another API [GET] /api/v1/vendors/brands which vendors can see their available Brand agreed. If they want to add new Brand, they need to contact with their Account Executive and Account Executive will add the Brand to vendor brand portfolio and only after then this API values will include the new brand for vendor to operate.

Create Product

We have two types of API’s for our vendors to create/update product information.

• Vendors who prefer to upload product via Excel can upload product information in the form of excel with API [POST] /api/v1/vendors/productTemplate.
• We also have another API in the form of JSON. Vendor can send product information in the form of JSON with API [POST] /api/v1/vendors/products.
• While filling product information vendor should use available values for many fields but we also have mapping infrastructure that will be published in the beginning of March 2021 in which vendor can send the mapped values of mandatory attributes up front and then use their own values among integration. Once a new value is generated in vendor system that is not mapped yet used during product creation will cause product creation request to fail but vendors will be able to map it via our mapping API fastly and retry their requests.

• Unique Barcode - Barcode should be unique for each product
• Style - VPN (Vendor Product Number), color and size combination makes your product unique and creates the product’s unique SKU ID on our system. The VPN should remain the same for products with same style but their color or size should be different. This is important to display variants of a product grouped under single product detail page on our website
• Category And Brand Alignment Per Style - If products share the same style, their VPN’s should be the same. Hence products which has the same VPN (variants of a product) should share the same category and brand as well
• Size Of The Fields - Fields with limited freetext values are Item Name (80 characters max), VPN (30 characters max) and Barcode (25 characters max). Most of the rest of the fields should be selected from specifications which you can find in each excel template or category attributes API.
• Request Size - You can send up to 1000 products (rows) in a single request.
• Mandatory fields - Mandatory columns indicated with asterix * on excel template or “M” in JSON category attributes API need to be sent with their values to create a product
• Attribute Names - The attribute names should remain the same (case insensitive). If you are having difficulty that way you can contact with your Account Manager for mapping with your field names.
• Alignment With Specifications - All fields listed as dropdown in excel and in JSON API [GET] /api/v1/categories/{categoryId}/attributes?mappingType=PRODUCT_API should have a value selected among the available values. If you are having difficulty that way you can contact with your Account Manager for mapping with your field values (on March 2021 we will start supporting this as well)
• Season-Phase Of The Product - Products sent to our system should have recent season-phase values. There are 5 season-phase values available for product creation. You can not create products for old seasons. Marketplace is decisive upon active season-phases.

Update Product

Product Creation and Product Update works exactly in the same manner. For update same API’s are used for excel and JSON.

• We update the product if only vendor product exists in our system. Validation is made via VPN, Color and Size field comparison.
• Fields that vendor can update is Barcode, Retail price and Website Activation Information (in which website product will be sold) for all regions or exclusively per region.
• Attribute values such as country of origin etc. can only be updated by Account Executives on Master catalog. If you send change for attribute values your product update won’t fail but any change regarding attribute values will be overridden by catalog attribute values.
• Optional fields that are sent null during update will be replaced by the pre-recorded values.

Get Vendor Catalog

We have an API for vendors to get product information they created in our system. It brings detailed information about the products of the vendor: Including vendor product statuses, attribute values, price, stock etc.

• Vendors who prefer to get existing product via Excel can extract product information in the form of excel with API [GET] /api/v1/vendors/productTemplate.
• We also have another API in the form of JSON. Vendor can get existing product information in the form of JSON with API [GET] /api/v1/vendors/productsfor all products or API [GET] /api/v1/vendors/products/{vendorProductId} for a single product.
• Those API's are especially important for vendors to monitor product statuses to understand if products are processed and ready to create a transfer as we share products statuses beside other fields.

Get Required Transfer/PO Fields

Purchase order means Transfer for us as in Marketplace Business Model nothing is purchased upfront. In order to send your stock to our warehouses, we have API’s which returns necessary fields to create a transfer.

• Vendors who prefer to create a transfer via Excel can download transfer template in the form of excel with API [GET] /api/v1/vendors/transferTemplate.
• We also have another API in the form of JSON. Vendor can get necessary transfer information fields in the form of JSON with API [GET] /api/v1/vendors/mapping?keyMappingType=TRANSFER_API.
• Only mandatory fields to create a transfer is VPN, Color, Size, Quantity and Warehouse information.

Create Transfer/PO

We expect vendors to create a transfer to send their stock to our warehouses. Vendors can create a transfer for multiple brands or categories at the same time.

• Vendors who prefer to create a transfer via Excel can upload transfer information in the form of excel with API [POST] /api/v1/vendors/transferTemplate.
• We also have another API in the form of JSON. Vendor can send transfer information in the form of JSON with API [POST] /api/v1/vendors/transfers.
• Once this API’s are used, in success response vendor will get transfer number.
• Once we receive vendor request of creating/updating a transfer, we process the request and change the transfer status to “OPEN” in 20 minutes. That means we created your transfer on our system. Once a transfer is processed and get the status OPEN, vendors can create appointment request.

• Transfers can only be created with mature products, meaning that the product will need to include the Ounass General Retail Price, Currency, as well as at least 1 website set as ACTIVE. Products eligible for transfers will have the statuses of Ready (ready means products processed and recorded) or Active (active means products processed, recorded and also stock exists). You can check product statuses by getting catalog information in the form of JSON Via API [GET] /api/v1/vendors/products or via Excel [GET] /api/v1/vendors/productTemplate .
• You can only create a transfer for products existing in your catalogue (First you should create your products in our system to create a transfer).
• The combination of VPN, Color, Size, Warehouse information and Quantity should be sent to create a transfer.
• The field names should remain the same (case insensitive). If you are having difficulty that way you can contact with your Account Manager for mapping with your field names.
• Season-Phase of the SKU’s that became a subject of a transfer should be active season-phases. You can not send stock for old season products.
• Warehouse name should be matching with available options.

Update Transfer/PO

Transfer Creation and Transfer Update works exactly in the same manner. For update same API’s are used for excel and JSON. Only difference is inclusion of existing Transfer Number.

• You can update the transfer via Excel with API [POST] /api/v1/vendors/transferTemplate if only transfer number field is filled with an existing value and value belongs to an open transfer number.
• You can update the transfer via JSON with API [POST] /api/v1/vendors/transfers if only transfer number field is sent with an existing value and value belongs to an open transfer number.
• Your request will override all transfer items both SKU wise and quantity wise.
• You can update single transfer per request.
• Transfers update can only take place in “OPEN” status; before appointment creation.

Create Appointment

After transfer creation vendors can request for an appointment anytime depending on their convenience and readiness to ship the stock. Appointment request means, vendor fully decided the SKU’s, Quantity and Warehouse they will transfer hence ship; there won’t be any update and want to share this information with appointment team so that appointment team can schedule earliest convenience to receive the shipment considering stock volume and warehouse operational density.

• In order to create an appointment vendor can use API [POST] /api/v1/vendors/transfers/{transferId}/appointment by putting transfer ID on the path upon transfer which they want to create appointment for.
  
• Appointment can only be created for transfers with “OPEN” status.
• To receive status of the transfer that the appointment will be created for, vendor can use API [GET] /api/v1/vendors/transfers/{transferId} or can receive success or fail as a response to your appointment request.
• Vendors should communicate the referring Appointment ID inside the shipment package or to our warehouse employees during shipment drop.

Delete Transfer/PO

Vendors can delete their existing transfers if they change their mind/stock is not available etc.

• In order to delete an existing transfer vendor can use API [DELETE] /api/v1/vendors/transfers/{transferId} by putting transfer ID on the path upon transfer which they want to delete and transfer status will turn to deleted.
• Vendors can only delete the transfer after their initial creation/update request is processed and created. Shortly only after their transfers get the status “OPEN” and before appointment creation. If you change your mind after appointment creation, simply don’t ship the stock and ignore the transfer that you created.

Create Shipment Info

After creating an appointment and deciding shipment method (drop by vendor or courier etc.), we expect vendors to send the related shipment and contact information so that in any problem our logic team can track your shipment from the information you transmit. Even though this is not mandatory, we especially recommend vendors to send shipment information on international shipments.

• In order to create shipment information regarding a transfer vendors can use API [POST] /api/v1/vendors/transfers/{transferId}/shipment by putting transfer ID on the path upon transfer which they want to send shipment information for.
• Regarding your request, we will create and share a Shipment ID on response body.
• After shipment information creation, typed address title creates an address id for you to use in future shipments if your FROM address is not changing. If you have multiple addresses we expect you to put different Address Titles in the body.

Update Shipment Info

Vendors can change shipment method or where the shipment is shipped from as well as courier details if typed wrong etc. To support this change, we have an API for vendors to update their existing shipment information.

• In order to update shipment information regarding a transfer, vendors can use API [PUT] /api/v1/vendors/transfers/{transferId}/shipment/{shipmentId} by putting transfer ID on the path upon transfer which they want to send shipment information for as well as existing Shipment ID.

Monitor Your Transfers

Vendors can track their transfer’s statuses in order to monitor the availability of the action they want to take regarding their transfer. This is mostly important if vendor would like to take further action right after transfer creation.

• Vendors can use API [GET] /api/v1/vendors/transfers to get information upon all their transfers and [GET] /api/v1/vendors/ transfers/{transferId} if they want to get information upon a specific transfer.
• Transfer status monitoring is important if right away vendors wants to update their transfer /delete their transfer /create an appointment for their transfer /create or update a shipment information for a transfer after the transfer is created.
• Transfers get the status OPEN when their transfer is processed and created in our system. Only in that status vendors can update their transfer /delete their transfer /create an appointment for their transfer.
• Transfers get the status WAITING FOR APPOINTMENT when they request appointment.
• Transfers get the status READY TO SHIP when appointment request is processed and an Appointment ID is received from appointment system.
• Transfers get the status SHIPPED when vendor creates a shipment information for a transfer. They can as well update their shipment information in this status.
• Transfers get the status RECEIVED once shipment is received in our Warehouse and inbounded/scanned.

Get Order Data

We do record orders received real time. In order to report how your sales are going, which SKU is selling, which category is selling the most, full price or markdown is performing well, how frequent your customers are buying, from which website you are selling the most, where your products are shipped to, what is being returned or cancelled and why etc. you can get full order detail any time you want.

• In order to get your orders with their details vie excel you can use API [GET] /api/v1/vendors/download/returnAndCancellation. On March 2021 we will also publish JSON API for this purpose as well.
• Full order detail includes: Order ID, Order Creation Date, Order Status, Status Record Date, Customer ID, Website, Shipment Country, Shipment City, SKU, Brand, VPN, Color, Size, Barcode, Gender, Category, Item Name, Pricing Type, Discount Amount, Retail Price, Retail Price AED, Gross Revenue AED, Currency Rate, SKU Quantity, Return Reason (exists if item is returned or cancelled)
• You can login to Vendor portal and use our vivid sales dashboard at the same time if you wish.

Get Stock Data

We do record stock transactions in our system and accordingly let vendor to get information upon Stock On Hand, Sellable Stock, Received Stock, In Transit Stock and Out of stock item detail and their quantities.

• In order to get stock information you can use our JSON API [GET] /api/v1/vendors/reports/stockDetails. We will also publish an API to extract this data as excel if needed.
• You need to filter your stock according to states.
• Stock states available is Stock on Hand, Sellable Stock, Received Stock, In Transit Stock, Out of stock.
• Stock information per each state includes Item Name, Brand, SKU ID, Barcode, VPN, Color, Size, Gender, Season, Category, Quantity

Product Integration

By making product integration with Ounass Marketplace Portal, you will be able to create your products which will form a catalog, update your existing products and list your products in your catalog to monitor their statuses in order to successfully create a transfer.

Create or Update Product

You can create a new product or update an existing product via excel or Json. Please view Excel - Product Create or Update. or JSON - Product Create or Update section according to your integration choice.

Excel - Product Create or Update

You can create a new or update an existing product by using following API's.

• GET /api/v1/vendors/productTemplate is used for downloading the product template to fill from scratch or update.

Depending on the parameters you pass, it will download a product creation template or a product update template, which are slightly different. Please see the details.

• POST /api/v1/vendors/productTemplate is used for uploading the template in order to create / update a product. If VPN, Color and Size values of a product exist, this product will be updated, otherwise a new product will be created.

Validations:

There are many validations on API level. Any data against validations will receive error.

1. Unique Barcode
   Barcode should be unique for each product.
   
2. Style
   VPN, color and size combination makes your product unique and creates the product’s unique SKU ID. The VPN should remain the same for products with same style but their color and size should be different. VPN, color and size will not be changeable after creation, so please fill this field cautiously. If you would like to change these details in the future, you will have to create a new product that the system will register as new product.
   
3. Category And Brand Alignment Per Style
   If products share the same style, their VPN’s should be the same. Hence products which has the same VPN should share the same category and brand as well.
   
4. Size Of The Fields
   Fields with free-form values are Item Name (80 characters max), Description (250 characters max), VPN (30 characters max) and Barcode (25 characters max). Rest of the fields should be selected from specifications which you can find in each template with latest possible values.
   
5. Request Size
   You can send up to 1,000 products (rows) in a single request.
   
6. Mandatory fields
   Mandatory columns indicated with asterix * need to be sent with their values to create a product.
   
7. Attribute Names
   The attribute names should remain the same (case insensitive). If you are having difficulty that way please contact your Account Manager for mapping with your column names.
   
8. Alignment With Specifications
   All fields listed as dropdown should have a value selected among the specifications.
   

Download Vendor Product Template

This API is to download the product template that will be used to fill product information.

There are two types of templates slightly different: Product Create and Product Update

Product Creation Template vs Product Update Template

The parameter to determine to download product create or update template with the api is 'empty' parameter. If it is not passed (or passed as false), it will download update template with existing products. Otherwise, it will download an empty create template.

Here are what differs between two:

However, the create template is also capable of updating products. If an existing product is listed in the create template, it will be treated as an update operation.

For product creation in order to download empty template with necessary fields and specifications, you can use following API's. Depending on your product portfolio, you can download a product template with single sheet by using below listed API's or can type multiple category ID's to your API request to download multiple sheets and process your upload for all.

Downloading empty product template examples

GET https://be-marketplace.ounass.com/api/v1/vendors/productTemplate?empty=true HTTP/1.1
Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Authorization: Bearer {access-token}
Host: example.com

curl --request GET \
  --url 'https://be-marketplace.ounass.com/api/v1/vendors/productTemplate?empty=true' \
  --header 'Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' \
  --header 'Authorization: Bearer {access-token}'

Downloading product template with existing products examples

GET https://be-marketplace.ounass.com/api/v1/vendors/productTemplate HTTP/1.1
Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Authorization: Bearer {access-token}
Host: example.com

curl --request GET \
  --url 'https://be-marketplace.ounass.com/api/v1/vendors/productTemplate' \
  --header 'Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' \
  --header 'Authorization: Bearer {access-token}'

For product update, instead of filling the template from scratch, you can download all your existing product information or per main category by using following API's. Note that the products will be listed in a single sheet named 'Update'.

Download Product Template Query Parameters

In addition to above examples, Product template can be downloaded with a combination of below query parameters.

While deciding which product is available for an update, check vendor product statuses.

Vendor Product Statuses

Upload Vendor Product Template

POST /api/v1/vendors/productTemplate HTTP/1.1
Content-Type: multipart/form-data
Accept: application/json
Authorization: Bearer {access-token}
Content-Type: multipart/form-data; boundary=---011000010111000001101001
Host: be-marketplace.ounass.com
Content-Length: 119

-----011000010111000001101001
Content-Disposition: form-data; name="file"

string
-----011000010111000001101001--

curl --request POST \
  --url https://be-marketplace.ounass.com/api/v1/vendors/productTemplate \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}' \
  --header 'Content-Type: multipart/form-data' \
  --header 'content-type: multipart/form-data; boundary=---011000010111000001101001' \
  --form file=string

This API is to upload the filled version of the product template to create the vendor products.

You can create / update your product via excel following the validations listed below.

Http Request:

POST /api/v1/vendors/productTemplate

Parameters:

The above command returns JSON structured like this:

{
  "status": 200,
  "result": [
    {
      "sheet": "string",
      "rowNumber": 0,
      "vendorProduct": {
        "id": 0,
        "parentId": "string",
        "barcode": "string",
        "vendorProductNo": "string",
        "color": "string",
        "size": "string",
        "status": "WAITING",
        "product": {
          "id": 0,
          "name": "string",
          "sku": "string",
          "status": "FAILED",
          "brand": {
            "id": 0,
            "name": "string"
          },
          "categories": [
            {
              "id": 0,
              "name": "string",
              "hierarchy": "string",
              "parentId": 0,
              "productCategory": {
                "categoryId": 0,
                "productId": 0,
                "categoryWithAttributes": 0
              }
            }
          ],
          "productAttributeValues": [
            {
              "attributeId": 0,
              "key": "string",
              "value": "string",
              "type": "OPTION",
              "group": "PRODUCT_INFORMATION",
              "mandatory": true
            }
          ]
        },
        "vendorProductAttributeValues": [
          {
            "attributeId": 0,
            "key": "string",
            "value": "string",
            "type": "OPTION",
            "group": "PRODUCT_INFORMATION",
            "mandatory": true
          }
        ],
        "vendorProductItems": [
          {
            "id": 0,
            "vendorProductId": 0,
            "platformWebsiteId": 0,
            "commission": 0,
            "retailPrice": 0,
            "basePrice": 0,
            "currencyCode": "string",
            "baseCurrencyCode": "string",
            "promotionPrice": 0,
            "promotionStart": "2019-08-24T14:15:22Z",
            "promotionEnd": "2019-08-24T14:15:22Z",
            "fulfilmentLocation": "string",
            "status": "ACTIVE"
          }
        ],
        "vendorProductStock": [
          {
            "id": 0,
            "stock": 0,
            "vendorProductId": 0,
            "vendorsWarehouseId": 0,
            "vendorsWarehouse": {
              "id": 0,
              "warehouse": {
                "id": 0,
                "name": "UAE Warehouse",
                "platform": {
                  "id": 0,
                  "name": "string",
                  "code": "string",
                  "logo": "string"
                }
              }
            }
          }
        ]
      }
    }
  ]
}

Response:

1. Check validations listed below
2. Get product category hierarchy id
3. Get list of category attributes
4. Get brand name
5. Construct payload and send product creation request

Validations:

There are many validations on API level. Any data against validations will receive error.

1. Unique Barcode
   Barcode should be unique for each product.
   
2. Style
   VPN, color and size combination makes your product unique and creates the product’s unique SKU ID. The VPN should remain the same for products with same style but their color and size should be different. VPN, color and size will not be changeable after creation, so please send this field cautiously. If you would like to change these details in the future, you will have to create a new product that the system will register as new product.
   
3. Category And Brand Alignment Per Style
   If products share the same style, their VPN’s should be the same. Hence products which has the same VPN should share the same category and brand as well.
   
4. Size Of The Fields
   Fields with free-form values are Item Name (80 characters max), Description (250 characters max), VPN (30 characters max) and Barcode (25 characters max).
   
5. Request Size
   You can send up to 1,000 products (rows) in a single request.
   
6. Mandatory fields
   Mandatory columns indicated with asterix * need to be sent with their values to create a product.
   
7. Attribute Names
   The attribute names should remain the same (case insensitive). If you are having difficulty that way please contact your Account Manager for mapping with your column names.
   
8. Alignment With Attribute Keys
   All fields listed as Attribute Keys should have a value matching within GET /api/v1/categories/{categoryId}/attributes per
   

Get product category hierarchy id

GET /api/v1/categories?level=4 HTTP/1.1
Accept: application/json
Authorization: Bearer {access-token}
Host: be-marketplace.ounass.com

curl --request GET \
  --url 'https://be-marketplace.ounass.com/api/v1/categories?level=4' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}'

Http Request:

GET /api/v1/categories?level=4

The above command returns JSON structured like this:

{
  "status": 200,
  "result": [
    {
      "id": 2839,
      "node_path": "2799.2800.2807.2839",
      "name": "Caps",
      "label": null,
      "level": 4,
      "hierarchy": "Womens > Accessories > Hats > Caps",
      "isSingleHierarchy": true,
      "isLeaf": true
    },
    .
    .
    .
    {
      "id": 2840,
      "node_path": "2799.2800.2807.2840",
      "name": "Cold Weather",
      "label": null,
      "level": 4,
      "hierarchy": "Womens > Accessories > Hats > Cold Weather",
      "isSingleHierarchy": true,
      "isLeaf": true
    },
    .
    .
    .
  ]
}

Response:

Please note category.id down, as it will be used in product creation json body as categoryId and used to query category attributes lists.

Get list of category attributes

GET /api/v1/categories/1670/attributes?keyMappingType=PRODUCT_API HTTP/1.1
Accept: application/json
Authorization: Bearer {access-token}
Host: be-marketplace.ounass.com

curl --request GET \
  --url 'https://be-marketplace.ounass.com/api/v1/categories/1670/attributes?keyMappingType=PRODUCT_API' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}'

Basically main category label of each product is the decisive of which information should be filled in order to create / update a product. Each main category label has different data fields mandatory / non mandatory to be captured.

Http Request:

GET /api/v1/categories/1670/attributes?keyMappingType=PRODUCT_API

Path Parameters:

The above command returns JSON structured like this:

{
  "result": {
    "attributes": [
      {
        "key": "description",
        "type": "FREE_TEXT",
        "mandatory": true,
      },
      {
        "key": "Color",
        "type": "OPTION",
        "mandatory": true,
        "options": [
          {
            "id": 1584,
            "value": "Bright Red",
            "languageCode": "en"
          },
          {
            "id": 1585,
            "value": "Bright Yellow",
            "languageCode": "en"
          },
          .
          .
          .
        ]
      },
      {
        "key": "countryOfOrigin",
        "type": "OPTION",
        "mandatory": false,
        "options": [
          {
            "id": 1586,
            "value": "United Arab Emirates",
            "languageCode": "en"
          },
          {
            "id": 1587,
            "value": "United Kingdom",
            "languageCode": "en"
          },
          .
          .
          .
        ]
      },
      .
      .
      .
   }
  }
} 

Response:

How to use category attributes array

sample categoryAttributes array to be used in product creation json body

{
  ...
  "categoryAttributes": [
    { "key": "description", "value": "my product description" },
    { "key": "color", "value": "Bright Red" },
    { "key": "countryOfOrigin", "value": "United Arab Emirates" },
    ...
  ],
}

attributes array contains list of all attributes of the given category, while constructing product creation json body you MUST include all mandatory attributes.

If an attribute type is OPTION, value of the attribute MUST be one from attribute.options array.

We will use the attribute.key and attribute.options for constructing categoryAttributes array of product creation json body.

Get brand name

GET /api/v1/vendors/brands HTTP/1.1
Accept: application/json
Authorization: Bearer {access-token}
Host: be-marketplace.ounass.com

curl --request GET \
  --url https://be-marketplace.ounass.com/api/v1/vendors/brands \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}'

Http Request:

GET /api/v1/vendors/brands

The above command returns JSON structured like this:

{
  "status": 200,
  "result": [
    {
      "id": 5232,
      "name": "Bobbi Brown",
      "rmsCode": 9682
    },
    {
      "id": 5236,
      "name": "New Brand",
      "rmsCode": 9678
    },
    .
    .
    .
  ],
}

Please note brand.name down that you want to use for your products, as it will be used in product creation json body as brand.

Response:

Create Vendor Product

POST /api/v1/vendors/products HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer {access-token}
Host: be-marketplace.ounass.com
Content-Length: 599

{"items":[{"vpn":"vpn1234","barcodeUpc":"bardode1234","brand":"New Brand","itemName":"mp product name","ounassGeneralPriceCurrency":0,"ounassGeneralRetailPrice":0,"ounassKuwaitRetailPriceKwd":0,"ounassOmanRetailPriceOmr":0,"ounassBahrainRetailPriceBhd":0,"ounassQatarRetailPriceQar":0,"ounassSaudiRetailPriceSar":0,"ounassUaeRetailPriceAed":0,"isActiveOunassAll":"ACTIVE","isActiveOunassKuwait":"ACTIVE","isActiveOunassOman":"ACTIVE","isActiveOunassBahrain":"ACTIVE","isActiveOunassQatar":"ACTIVE","isActiveOunassSaudi":"ACTIVE","isActiveOunassUae":"ACTIVE","categoryAttributes":[{"key":"description","value":"my product description"},{ "key": "color", "value": "Bright Red" }]}]}

curl --request POST \
  --url https://be-marketplace.ounass.com/api/v1/vendors/products \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}' \
  --header 'Content-Type: application/json' \
  --data '{"items":[{"vpn":"vpn1234","barcodeUpc":"barcode1234","brand":"New Brand","itemName":"mp product name","ounassGeneralPriceCurrency":0,"ounassGeneralRetailPrice":0,"ounassKuwaitRetailPriceKwd":0,"ounassOmanRetailPriceOmr":0,"ounassBahrainRetailPriceBhd":0,"ounassQatarRetailPriceQar":0,"ounassSaudiRetailPriceSar":0,"ounassUaeRetailPriceAed":0,"isActiveOunassAll":"ACTIVE","isActiveOunassKuwait":"ACTIVE","isActiveOunassOman":"ACTIVE","isActiveOunassBahrain":"ACTIVE","isActiveOunassQatar":"ACTIVE","isActiveOunassSaudi":"ACTIVE","isActiveOunassUae":"ACTIVE","categoryAttributes":[{"key":"description","value":"my product description"},{ "key": "color", "value": "Bright Red" }]}]}'

This API is to send product information to create the vendor products using JSON payloads.

Http Request:

POST /api/v1/vendors/products

Body Parameters:

Sample json body

{
  "items": [
    {
      "vpn": "vpn1234",
      "barcodeUpc": "bardode1234",
      "brand": "New Brand",
      "itemName": "mp product name",
      "ounassGeneralPriceCurrency": "AED",
      "ounassGeneralRetailPrice": 0,
      "ounassKuwaitRetailPriceKwd": 0,
      "ounassOmanRetailPriceOmr": 0,
      "ounassBahrainRetailPriceBhd": 0,
      "ounassQatarRetailPriceQar": 0,
      "ounassSaudiRetailPriceSar": 0,
      "ounassUaeRetailPriceAed": 0,
      "isActiveOunassAll": "ACTIVE",
      "isActiveOunassKuwait": "ACTIVE",
      "isActiveOunassOman": "ACTIVE",
      "isActiveOunassBahrain": "ACTIVE",
      "isActiveOunassQatar": "ACTIVE",
      "isActiveOunassSaudi": "ACTIVE",
      "isActiveOunassUae": "ACTIVE",
      "categoryAttributes": [
        { "key": "Category1/Category2/Category3/Category4", "value": "Category1 > Category 2 > Category3 > Category4" },
        { "key": "description", "value": "my product description" },
        { "key": "mainCategory", "value": "Category1" },
        { "key": "currentGroup", "value": "2" },
        { "key": "seasonPhase", "value": "Continuity - Continuity" },
        { "key": "key1", "value": "value1" },
        { "key": "key2", "value": "value2" }
      ]
    }
  ]
}

For details of fields, please see Fields and Explanations

Response:

Response has same structure as product creation with excel

Fields and Explanations

Below you can find common fields that will be filled in order to successfully record your product information. To see each field necessary mandatory /non mandatory to create a product view different category fields.

Accessories

Activewear

Bags

Beauty

Casual & Contemporary

Designer

Footwear

Home

Jewellery

Kids

Swimwear & Basics & Intimates

Vintage

Vendor Catalog

Service is used to extract vendor products recorded on the system. The method brings detailed information about the products of the vendor. Including vendor product statuses, attribute values, price, stock etc.

GET vendor products

GET /api/v1/vendors/products HTTP/1.1
Accept: application/json
Authorization: Bearer {access-token}
Host: be-marketplace.ounass.com

curl --request GET \
  --url https://be-marketplace.ounass.com/api/v1/vendors/products \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}'

Http Request:

GET /api/v1/vendors/products

Parameters:

The above command returns JSON structured like this:

{
  "status": 200,
  "result": {
    "page": 1,
    "maxPage": 9,
    "count": 10,
    "totalCount": 87,
    "data": [
      {
        "id": 0,
        "parentId": "string",
        "barcode": "string",
        "vendorProductNo": "string",
        "color": "string",
        "size": "string",
        "status": "WAITING",
        "createdAt": "2019-08-24T14:15:22Z",
        "updatedAt": "2019-08-24T14:15:22Z",
        "deletedAt": "2019-08-24T14:15:22Z",
        "productId": 0,
        "product": {
          "id": 0,
          "name": "string",
          "sku": "string",
          "status": "FAILED",
          "brand": {
            "id": 0,
            "name": "string"
          },
          "categories": [
            {
              "id": 0,
              "name": "string",
              "hierarchy": "string",
              "parentId": 0,
              "productCategory": {
                "categoryId": 0,
                "productId": 0,
                "categoryWithAttributes": 0
              }
            }
          ],
          "productAttributeValues": [
            {
              "attributeId": 0,
              "key": "string",
              "value": "string",
              "type": "OPTION",
              "group": "PRODUCT_INFORMATION",
              "mandatory": true
            }
          ]
        },
        "vendorProductAttributeValues": [
          {
            "attributeId": 0,
            "key": "string",
            "value": "string",
            "type": "OPTION",
            "group": "PRODUCT_INFORMATION",
            "mandatory": true
          }
        ],
        "vendorProductItems": [
          {
            "id": 0,
            "vendorProductId": 0,
            "platformWebsiteId": 0,
            "commission": 0,
            "retailPrice": 0,
            "basePrice": 0,
            "currencyCode": "string",
            "baseCurrencyCode": "string",
            "promotionPrice": 0,
            "promotionStart": "2019-08-24T14:15:22Z",
            "promotionEnd": "2019-08-24T14:15:22Z",
            "fulfilmentLocation": "string",
            "status": "ACTIVE"
          }
        ],
        "vendorProductStock": [
          {
            "id": 0,
            "stock": 0,
            "vendorProductId": 0,
            "vendorsWarehouseId": 0,
            "vendorsWarehouse": {
              "id": 0,
              "warehouse": {
                "id": 0,
                "name": "UAE Warehouse",
                "platform": {
                  "id": 0,
                  "name": "string",
                  "code": "string",
                  "logo": "string"
                }
              }
            }
          }
        ]
      }
    ]
  }
}

Response:

GET single vendor product info

GET /api/v1/vendors/products/0 HTTP/1.1
Accept: application/json
Authorization: Bearer {access-token}
Host: be-marketplace.ounass.com

curl --request GET \
  --url https://be-marketplace.ounass.com/api/v1/vendors/products/0 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}'

You can get information upon a single product as well as getting all products with filters. This API lets you extract single product information ith vendor product ID.

Http Request:

GET /api/v1/vendors/products/{vendorProductId}

Parameters:

The above command returns JSON structured like this:

{
  "status": 200,
  "result": {
    "id": 0,
    "parentId": "string",
    "barcode": "string",
    "vendorProductNo": "string",
    "color": "string",
    "size": "string",
    "status": "WAITING",
    "product": {
      "id": 0,
      "name": "string",
      "sku": "string",
      "status": "FAILED",
      "brand": {
        "id": 0,
        "name": "string"
      },
      "categories": [
        {
          "id": 0,
          "name": "string",
          "hierarchy": "string",
          "parentId": 0,
          "productCategory": {
            "categoryId": 0,
            "productId": 0,
            "categoryWithAttributes": 0
          }
        }
      ],
      "productAttributeValues": [
        {
          "attributeId": 0,
          "key": "string",
          "value": "string",
          "type": "OPTION",
          "group": "PRODUCT_INFORMATION",
          "mandatory": true
        }
      ]
    },
    "vendorProductAttributeValues": [
      {
        "attributeId": 0,
        "key": "string",
        "value": "string",
        "type": "OPTION",
        "group": "PRODUCT_INFORMATION",
        "mandatory": true
      }
    ],
    "vendorProductItems": [
      {
        "id": 0,
        "vendorProductId": 0,
        "platformWebsiteId": 0,
        "commission": 0,
        "retailPrice": 0,
        "basePrice": 0,
        "currencyCode": "string",
        "baseCurrencyCode": "string",
        "promotionPrice": 0,
        "promotionStart": "2019-08-24T14:15:22Z",
        "promotionEnd": "2019-08-24T14:15:22Z",
        "fulfilmentLocation": "string",
        "status": "ACTIVE"
      }
    ],
    "vendorProductStock": [
      {
        "id": 0,
        "stock": 0,
        "vendorProductId": 0,
        "vendorsWarehouseId": 0,
        "vendorsWarehouse": {
          "id": 0,
          "warehouse": {
            "id": 0,
            "name": "UAE Warehouse",
            "platform": {
              "id": 0,
              "name": "string",
              "code": "string",
              "logo": "string"
            }
          }
        }
      }
    ]
  }
}

Response:

Transfer Integration

Create or Update Transfer

Once the product is created in order to transfer any stock, create or update transfer service should be called with below listed fields. API decides if this transfer creation or update via Transfer No. If Transfer No. field value is null then a new transfer will be created with a new Transfer No. Sending transfer number that belongs to one of your current open transfers will delete and re-write that transfer with the items sent, leading transfer update.

Validations:

1. Transfers can only be created with mature products, meaning that the product will need to include the Ounass General Retail Price, Currency, as well as at least 1 website set as ACTIVE. Products eligible for transfers will have the statuses of Ready (for products finalized and recorded) or Active (products which we have received the stock for). You can check product statuses via GetVendorProductInfo service
2. You can only create a transfer for products existing in your catalogue
3. The combination of VPN, Color and Size makes a product unique. Therefore, these fields should be sent in order to recognize the product for the transfer. Also warehouse information and sales quantity should be sent. Shortly mandatory columns are indicated with * need to be sent to create the product
4. The field names should remain the same (case insensitive). If you are having difficulty that way please contact your Account Manager for custom integration
5. All fields listed as dropdown should have a value selected among the specifications. Warehouse should be up to specifications
6. Transfers with “OPEN” status can only be updated

Transfer Statuses:

Excel - Create or Update Transfer

Download a Transfer Template

Download an empty transfer template

GET /api/v1/vendors/transferTemplate HTTP/1.1
Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Authorization: Bearer {access-token}
Host: be-marketplace.ounass.com

curl --request GET \
  --url https://be-marketplace.ounass.com/api/v1/vendors/transferTemplate \
  --header 'Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' \
  --header 'Authorization: Bearer {access-token}'

In order to create a transfer, you should first download the transfer template to fill and upload. This API is to get transfer template.

Http Request:

GET /api/v1/vendors/transferTemplate

Query Parameters:

Response:

The above command downloads a file

download transfer template with a specific type

Download the transfer template with READY and ACTIVE products

curl --request GET \
  --url https://be-marketplace.ounass.com/api/v1/vendors/transferTemplate?transferType=CREATE \
  --header 'Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' \
  --header 'Authorization: Bearer {access-token}'

GET /api/v1/vendors/transferTemplate?transferType=CREATE HTTP/1.1
Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Authorization: Bearer {access-token}
Host: be-marketplace.ounass.com

You can download your catalog template with different option, transferType query parameter can be one of from table below.

curl --request GET \
  --url 'https://be-marketplace.ounass.com/api/v1/vendors/transferTemplate?transferType=UPDATE&transferNo={rmsTransferId}' \
  --header 'Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' \
  --header 'Authorization: Bearer {access-token}'

GET /api/v1/vendors/transferTemplate?transferType=UPDATE&transferNo={rmsTransferId} HTTP/1.1
Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Authorization: Bearer {access-token}
Host: be-marketplace.ounass.com

curl --request GET \
  --url https://be-marketplace.ounass.com/api/v1/vendors/transferTemplate?transferType=FAILED \
  --header 'Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' \
  --header 'Authorization: Bearer {access-token}'

GET /api/v1/vendors/transferTemplate?transferType=FAILED HTTP/1.1
Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Authorization: Bearer {access-token}
Host: be-marketplace.ounass.com

POST /api/v1/vendors/transferTemplate HTTP/1.1
Content-Type: multipart/form-data
Accept: application/json
Authorization: Bearer {access-token}
Content-Type: multipart/form-data; boundary=---011000010111000001101001
Host: be-marketplace.ounass.com
Content-Length: 119

-----011000010111000001101001
Content-Disposition: form-data; name="file"

string
-----011000010111000001101001--

curl --request POST \
  --url https://be-marketplace.ounass.com/api/v1/vendors/transferTemplate \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}' \
  --header 'Content-Type: multipart/form-data' \
  --header 'content-type: multipart/form-data; boundary=---011000010111000001101001' \
  --form file=string

{
  "status": 200,
  "result": [
    {
      "sheet": "string",
      "rowNumber": 0,
      "transferItem": {
        "id": 0,
        "quantityRequested": 0,
        "quantityReceived": 0,
        "quantityDiscrepancy": 0,
        "reason": "string",
        "vendorProductId": 0
      }
    }
  ]
}

Create a new transfer

POST /api/v1/vendors/transfers HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer {access-token}
Host: be-marketplace.ounass.com
Content-Length: 159

{"items":[{"quantity":1,"vpn":"V2000013","color":"28642/01B PINK MULTI","size":"One Size","warehouseLocation":"UAE Warehouse"}]}

curl --request POST \
  --url https://be-marketplace.ounass.com/api/v1/vendors/transfers \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}' \
  --header 'Content-Type: application/json' \
  --data '{
  "items": [
    {
      "quantity": 1,
      "barcocde": "BRCD",
      "vpn": "V2000013",
      "color": "28642/01B PINK MULTI",
      "size": "One Size",
      "warehouseLocation": "UAE Warehouse"
    }
  ]
}'

Http Request:

POST /api/v1/vendors/transfers

Body Parameters:

The above command returns JSON structured like this:

{
  "status": 200,
  "result": [
    {
      "rowNumber": 0,
      "transferItem": {
        "id": 0,
        "quantityRequested": 0,
        "quantityReceived": 0,
        "quantityDiscrepancy": 0,
        "reason": "string",
        "vendorProductId": 0
      }
    }
  ]
}

Response:

Update Transfer with Json

Update an existing transfer with transfer.rmsTransferId

POST /api/v1/vendors/transfers HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer {access-token}
Host: be-marketplace.ounass.com
Content-Length: 159

{"items":[{"transferNo":<rmsTransferId>,"quantity":1,"vpn":"V2000012","color":"28642/01B PINK MULTI","size":"One Size","warehouseLocation":"UAE Warehouse"}]}

curl --request POST \
  --url https://be-marketplace.ounass.com/api/v1/vendors/transfers \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}' \
  --header 'Content-Type: application/json' \
  --data '{
  "items": [
    {
      "transferNo": <transfer.rmsTransferId>,
      "quantity": 1,
      "vpn": "V2000012",
      "color": "28642/01B PINK MULTI",
      "size": "One Size",
      "barcocde": "BRCD",
      "warehouseLocation": "UAE Warehouse"
    }
  ]
}'

Parameters and response structure of update transfer with json request is identical to transfer creation with json request but includes transfer.rmsTransferId for update in the request parameters

Get Transfers

Get list of all transfers

GET /api/v1/vendors/transfers HTTP/1.1
Accept: application/json
Authorization: Bearer {access-token}
Host: be-marketplace.ounass.com

curl --request GET \
  --url https://be-marketplace.ounass.com/api/v1/vendors/transfers \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}'

Transfer List service will give you all your recently created transfers.

Http Request:

GET /api/v1/vendors/transfers

The above command returns JSON structured like this:

{
  "status": 200,
  "result": [
    {
      "id": 0,
      "fileName": "string",
      "rmsTransferId": 0,
      "rmsAppointmentId": 0,
      "asnTrackingNumber": 0,
      "status": "OPEN",
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z",
      "vendorsWarehouse": {
        "id": 0,
        "warehouse": {
          "id": 0,
          "name": "UAE Warehouse"
        }
      },
      "transferItems": [
        {
          "id": 0,
          "quantityRequested": 0,
          "quantityReceived": 0,
          "quantityDiscrepancy": 0,
          "reason": "string",
          "vendorProductId": 0
        }
      ]
    }
  ]
}

Response:

Get a Transfer's Detail

Get transfer details of transfer with transfer id

GET /api/v1/vendors/transfers/{transferId} HTTP/1.1
Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Authorization: Bearer {access-token}
Host: be-marketplace.ounass.com

curl --request GET \
  --url https://be-marketplace.ounass.com/api/v1/vendors/transfers/{transferId} \
  --header 'Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' \
  --header 'Authorization: Bearer {access-token}'

Transfer Detail service will give you details of a specific transfer requested. You can call this service via transfer's unique number "TransferId" to receive below listed details of the transfer.

Http Request:

GET /api/v1/vendors/transfers/{transferId}

Path Parameters:

The above command returns JSON structured like this:

{
  "status": 200,
  "result": {
    "id": 0,
    "fileName": "string",
    "rmsTransferId": 0,
    "rmsAppointmentId": 0,
    "asnTrackingNumber": 0,
    "status": "OPEN",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z",
    "vendorsWarehouse": {
      "id": 0,
      "warehouse": {
        "id": 0,
        "name": "UAE Warehouse"
      }
    },
    "transferItems": [
      {
        "id": 0,
        "quantityRequested": 0,
        "quantityReceived": 0,
        "quantityDiscrepancy": 0,
        "reason": "string",
        "vendorProductId": 0
      }
    ],
    "transferShipment": {
      "id": 0,
      "vendorAddress": {
        "id": 0,
        "title": "string",
        "address": "string",
        "countryCode": "string",
        "city": "string",
        "postalCode": "string"
      },
      "type": "LOCAL",
      "dropByVendor": true,
      "courierCompany": "string",
      "trackingNumber": "string",
      "contactPhone": "string"
    }
  }
}

Response:

Delete a Transfer

Delete the transfer with transfer id

DELETE /api/v1/vendors/transfers/{transferId} HTTP/1.1
Authorization: Bearer {access-token}
Host: be-marketplace.ounass.com

curl --request DELETE \
  --url https://be-marketplace.ounass.com/api/v1/vendors/transfers/{transferId} \
  --header 'Authorization: Bearer {access-token}'

You can only delete a transfer with “OPEN” status.

Http Request:

DELETE /api/v1/vendors/transfers/{transferId}

Path Parameters:

The above command returns JSON structured like this:

{
  "status": 200
}

Response:

Create Appointment for a Transfer

Create an appointment for the transfer with transfer id

POST /api/v1/vendors/transfers/{transferId}/appointment HTTP/1.1
Accept: application/json
Authorization: Bearer {access-token}
Host: be-marketplace.ounass.com

curl --request POST \
  --url https://be-marketplace.ounass.com/api/v1/vendors/transfers/{transferId}/appointment \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}'

Once we process your request of creating transfer, we will change your transfer status to “OPEN”. In transfers with open status you will be able to Create Appointment by using unique transfer No "TransferId". To receive status of related transfer you can use TransferDetail service or can receive success or fail as a response to your appointment request.

After appointment request is successful, logistic team will send email about scheduling time to vendor's primary contact email address. To change primary contact, please contact with your Account Executive

Http Request:

POST /api/v1/vendors/transfers/{transferId}/appointment

Path Parameters:

The above command returns JSON structured like this:

{
  "status": 200,
  "result": {
    "id": 0,
    "fileName": "string",
    "rmsTransferId": 0,
    "rmsAppointmentId": 0,
    "asnTrackingNumber": 0,
    "status": "OPEN",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z",
    "vendorsWarehouse": {
      "id": 0,
      "warehouse": {
        "id": 0,
        "name": "UAE Warehouse"
      }
    },
    "transferItems": [
      {
        "id": 0,
        "quantityRequested": 0,
        "quantityReceived": 0,
        "quantityDiscrepancy": 0,
        "reason": "string",
        "vendorProductId": 0
      }
    ]
  }
}

Response:

Appointment ID Acknowledgement

Appointment Id is used to communicate warehouse which stock is coming in. Once an Appointment ID is created on the system you will receive an email for scheduling. Appointment ID is created on the system couple of hours later appointment creation. To request appointment ID created on the system you can use Transfer Detail service.

Please check Transfer Detail Service to get appointment ID

Create/Update Shipment Info

After you receive an appointment ID and plan your shipment choice, we expect you to send the related shipment information so that in any problem we track your shipment from the information you transmit. To do so, you need to send your shipment information and we will be sharing this info with our logistic team. The moment you sent below listed information, your transfer status will change to “Shipped”. If you sent this information wrongly you can also send update. If you don’t send this info you transfer status will keep being Ready to ship and will become received once warehouse issues your stock. f For creation of a shipment information; [POST] /api/v1/vendors/transfers/{transferId}/shipment shipment API is used, for updating [PUT] /api/v1/vendors/transfers/{transferId}/shipment/{shipmentId} is used.

Create Shipment for a Transfer

Create a shipment for the transfer id with a new shipment address

POST /api/v1/vendors/transfers/{transferId}/shipment HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer {access-token}
Host: be-marketplace.ounass.com
Content-Length: 234

{"vendorAddress":{"title":"string","address":"string","countryCode":"string","city":"string","postalCode":"string"},"type":"LOCAL","dropByVendor":true,"courierCompany":"string","trackingNumber":"string","contactPhone":"string"}

curl --request POST \
  --url https://be-marketplace.ounass.com/api/v1/vendors/transfers/{transferId}/shipment \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}' \
  --header 'Content-Type: application/json' \
  --data '{
  "vendorAddress": {
    "title": "string",
    "address": "string",
    "countryCode": "string",
    "city": "string",
    "postalCode": "string"
  },
  "type": "LOCAL",
  "dropByVendor": true,
  "courierCompany": "string",
  "trackingNumber": "string",
  "contactPhone": "string"
}'

The API is used for creating a shipment for a transfer. Please see the details below and for detailed parameter descriptions please check Shipment Schema

Http Request:

POST /api/v1/vendors/transfers/{transferId}/shipment

Path Parameters:

Body Parameters:

The above command returns JSON structured like this:

{
  "status": 200,
  "result": {
    "id": 0,
    "vendorAddress": {
      "id": 0,
      "title": "string",
      "address": "string",
      "countryCode": "string",
      "city": "string",
      "postalCode": "string"
    },
    "type": "LOCAL",
    "dropByVendor": true,
    "courierCompany": "string",
    "trackingNumber": "string",
    "contactPhone": "string"
  }
}

Response:

Update Shipment for a Transfer

Update the shipment: 12 of transfer id with shipment address: 123

PUT /api/v1/vendors/transfers/{transferId}/shipment/{shipmentId} HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer {access-token}
Host: be-marketplace.ounass.com
Content-Length: 234

{"vendorAddress":{"id":123},"type":"LOCAL","dropByVendor":true,"courierCompany":"string","trackingNumber":"string","contactPhone":"string"}

curl --request PUT \
  --url https://be-marketplace.ounass.com/api/v1/vendors/transfers/{transferID}/shipment/{shipmentId} \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}' \
  --header 'Content-Type: application/json' \
  --data '{
  "vendorAddress": {
    "id": 123,
  },
  "type": "LOCAL",
  "dropByVendor": true,
  "courierCompany": "string",
  "trackingNumber": "string",
  "contactPhone": "string"
}'

You can update an existing shipment address with shipmentId and vendorAddressId. Both shipmentId and vendorAddressId is available in response of shipment creation request or can be retrieved from Transfer Detail Api with the corresponding transferId.

The "shipment ID" will be used in the URL of the API and the vendorAddressID will be used in "id" parameter while updating the shipment address.

Http Request:

PUT /api/v1/vendors/transfers/{transferId}/shipment/{shipmentId}

Path Parameters:

Body Parameters:

The above command returns JSON structured like this:

{
  "status": 200,
  "result": {
    "id": 0,
    "vendorAddress": {
      "id": 0,
      "title": "string",
      "address": "string",
      "countryCode": "string",
      "city": "string",
      "postalCode": "string"
    },
    "type": "LOCAL",
    "dropByVendor": true,
    "courierCompany": "string",
    "trackingNumber": "string",
    "contactPhone": "string"
  }
}

Response:

Reporting Integration

Order Report

Order report gives info upon orders received between any time interval requested. You will need to select start date and end date with Vendor ID to receive order item based list.

download return and cancellation statistics

GET /api/v1/vendors/download/returnAndCancellation HTTP/1.1
Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Authorization: Bearer {access-token}
Host: be-marketplace.ounass.com

curl --request GET \
  --url https://be-marketplace.ounass.com/api/v1/vendors/download/returnAndCancellation \
  --header 'Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' \
  --header 'Authorization: Bearer {access-token}'

Http Request:

GET /api/v1/vendors/download/returnAndCancellation

Parameters:

Response:

Return and Cancellation Fields

get return and cancellation reports

GET /api/v1/vendors/reports/returnAndCancellation HTTP/1.1
Accept: application/json
Authorization: Bearer {access-token}
Host: be-marketplace.ounass.com

curl --request GET \
  --url https://be-marketplace.ounass.com/api/v1/vendors/reports/returnAndCancellation \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}'

Http Request:

GET /api/v1/vendors/reports/returnAndCancellation

Parameters:

The above command returns JSON structured like this:

{
  "status": 200,
  "result": [
    {
      "vendorId": 0,
      "orderId": 0,
      "orderCreationDate": "string",
      "statusRecordDate": "string",
      "orderStatus": "string",
      "customerId": "string",
      "website": "string",
      "shipmentCountry": "string",
      "shipmentCity": "string",
      "sku": "string",
      "brand": "string",
      "vpn": "string",
      "color": "string",
      "size": "string",
      "barcode": "string",
      "gender": "string",
      "category": "string",
      "season": "string",
      "itemName": "string",
      "pricingType": "string",
      "discountAmount": "string",
      "retailPrice": 0,
      "retailPriceAed": 0,
      "grossRevenueAed": 0,
      "currencyRate": 0,
      "skuQuantity": 0,
      "reason": "string"
    }
  ]
}

Response:

Stock Report

Stock report gives info upon related stock. You can select Type and can receive regarding stock information or you can send VPN+Color+Size info to learn SOH.

get stock details report

GET /api/v1/vendors/reports/stockDetails?stockFilter=STOCK_ON_HAND HTTP/1.1
Accept: application/json
Authorization: Bearer {access-token}
Host: be-marketplace.ounass.com

curl --request GET \
  --url 'https://be-marketplace.ounass.com/api/v1/vendors/reports/stockDetails?stockFilter=STOCK_ON_HAND' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}'

Http Request:

GET /api/v1/vendors/reports/stockDetails

Parameters:

Stock Filter options

The above command returns JSON structured like this:

{
  "status": 200,
  "result": {
    "page": 1,
    "maxPage": 9,
    "count": 10,
    "totalCount": 87,
    "data": [
      {
        "vendorId": 0,
        "vendorName": "string",
        "itemName": "string",
        "brandName": "string",
        "sku": "string",
        "barcode": "string",
        "vpn": "string",
        "color": "string",
        "size": "string",
        "gender": "string",
        "season": "string",
        "category": "string",
        "quantity": "string",
        "threshold": 0
      }
    ]
  }
}

Response:

Stock Details Fields

Financial Report

The Financial Report API provides in-depth financial information on orders that have been completed or returned within the specified time period highlighted by the "Order Completion Date" column/field. If no time period parameter is provided, the default period is set to month-to-date from the date of request.

Download Financial Report

GET /api/v1/vendors/download/financialReport HTTP/1.1
Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Authorization: Bearer {access-token}
Host: be-marketplace.ounass.com

curl --request GET \
  --url https://be-marketplace.ounass.com/api/v1/vendors/download/financialReport \
  --header 'Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' \
  --header 'Authorization: Bearer {access-token}'

Http Request:

GET /api/v1/vendors/download/financialReport

Parameters:

Response:

Financial Report Fields