.. index::
    single: Price Models


.. _price_models:

Price Models
============

Each advertisement has a price model which determines the type of transaction the seller would like to perform. Model type must be specified
for each price model. It should have one of the allowed values.

There are some price models which have required and optional fields. And there
are price models without any additional fields. In the documentation below, if a field is not mentioned in a model specific field table
then it is not allowed. Note that 'modelType' is mandatory for all price models (and not mentioned in a field tables.)

The following table lists the valid price model types and their descriptions.

=====================================================  ============================================================================================
Price model types                                      Description
=====================================================  ============================================================================================
:ref:`fixed <price_model_fixed>`                       Seller requests fixed price
:ref:`bidding <price_model_bidding>`                   Seller requests bidding
:ref:`to be discussed <price_model_to_be_discussed>`   Price needs to be discussed between seller and buyer
:ref:`by request <price_model_by_request>`             Price is given on request
:ref:`trade <price_model_trade>`                       Item can be traded for another item
:ref:`see description <price_model_see_description>`   Information about price is available in the item description
:ref:`buy it now <price_model_buy_it_now>`             Item can be bought directly from Marktplaats
:ref:`reserved <price_model_reserved>`                 The item has been reserved
=====================================================  ============================================================================================


.. _price_model_fixed:

fixed
^^^^^
Seller requests fixed price.

.. apifields::
     .. apifield::
        :name: askingPrice
        :type: long
        :constraints: non-negative
        :required: true
        :writable: true
        :updateable: true

         The price in cents which seller asks for an item.

     .. apifield::
        :name: retailPrice
        :type: long
        :constraints: non-negative, only writeable with retail_price privilege
        :required: false
        :writable: false
        :updateable: false

        The retail price of the item in cents. Only writable and updateable when the client has outlet privilege.

.. code-block:: javascript

   ...
   "priceModel" : {
        "modelType" : "fixed",
        "askingPrice" : 1550
   }
   ...

.. _price_model_bidding:

bidding
^^^^^^^
Seller requests bidding.
Leave both minimalBid and askingPrice empty if you do not want to specify an asking price. but still allow bidding

.. apifields::
    .. apifield::
        :name: minimalBid
        :type: int
        :constraints: non negative
        :required: false
        :writable: true
        :updateable: true

        The minimum bid accepted by a seller. The minimal bid is set to the askingPrice if it is missing. If minimalBid is
        provided, it is also required to specify an askingPrice.

    .. apifield::
        :name: askingPrice
        :type: int
        :constraints: non negative
        :required: false
        :writable: true
        :updateable: true

        The asking price for an item. If askingPrice is not provided, the displayed price on the website will be 'bieden'.
        If minimalBid is provided, it is also mandatory to provide an askingPrice.

    .. apifield::
        :name: retailPrice
        :type: long
        :constraints: non-negative, only writeable with retail_price privilege
        :required: false
        :writable: false
        :updateable: false

        The retail price of the item in cents. Only writable and updateable when the client has retail_price privilege.


.. code-block:: javascript

   ...
   "priceModel" : {
        "modelType" : "bidding",
        "minimalBid" : 2000,
        "askingPrice" : 5550,
        "retailPrice" : 6000
   }
   ...


.. _price_model_to_be_discussed:

to be discussed
^^^^^^^^^^^^^^^

Price needs to be discussed between seller and buyer.

.. code-block:: javascript

   ...
   "priceModel" : {
        "modelType" : "to be discussed"
   }
   ...

.. _price_model_by_request:

by request
^^^^^^^^^^

Seller provides price by a request.

.. code-block:: javascript

   ...
   "priceModel" : {
        "modelType" : "by request"
   }
   ...


.. _price_model_trade:

trade
^^^^^
Item can be traded for another item.

.. code-block:: javascript

   ...
   "priceModel" : {
        "modelType" : "trade"
   }
   ...

.. _price_model_see_description:

see description
^^^^^^^^^^^^^^^
Information about price is available in the item description

.. code-block:: javascript

   ...
   "priceModel" : {
        "modelType" : "see description"
   }
   ...

.. _price_model_buy_it_now:

buy it now
^^^^^^^^^^
Item can be bought directly from Marktplaats. May only be used by selected sellers.

.. apifields::
    .. apifield::
        :name: askingPrice
        :type: long
        :constraints: non-negative
        :required: true
        :writable: true
        :updateable: true

        The price in cents which seller asks for an item.

    .. apifield::
        :name: shippingCosts
        :type: long
        :constraints: non-negative
        :required: false
        :writable: true
        :updateable: true

        The price in cents which seller asks for shipping an item.

    .. apifield::
        :name: retailPrice
        :type: long
        :constraints: non-negative, only writeable with retail_price privilege
        :required: false
        :writable: false
        :updateable: false

        The retail price of the item in cents. Only writable and updateable when the client has retail_price privilege.

.. code-block:: javascript

   ...
   "priceModel" : {
        "modelType" : "buy it now",
        "askingPrice" : 5550,
        "shippingCosts" : 695
   }
   ...

.. _price_model_reserved:

reserved
^^^^^^^^^^^^^^^
The item has been reserved, meaning that in principle the item has been sold to a buyer.

.. code-block:: javascript

   ...
   "priceModel" : {
        "modelType" : "reserved"
   }
   ...


Field errors
^^^^^^^^^^^^

.. fielderrors::
    .. error::
        :field: priceModel.type
        :code: input-invalid
        :description: A required price model type is missing
    .. error::
        :field: priceModel.type
        :code: invalid-field-value
        :value: "fixed|bidding|trade|see description|by request|to be discussed|buy it now|reserved"
        :description: Model type doesn't contain any of the allowed values
    .. error::
        :field: priceModel.type
        :code: input-not-allowed
        :value: "buy it now"
        :description: User is not allowed to use this model type
    .. error::
        :field: priceModel.askingPrice
        :code: invalid-input
        :description: The required asking price field is missing
    .. error::
        :field: priceModel.askingPrice
        :code: invalid-input
        :description: The required asking price field is missing
    .. error::
        :field: priceModel.askingPrice
        :code: input-not-allowed
        :description: The asking price is not allowed for the selected model type
    .. error::
        :field: priceModel.askingPrice
        :code: input-too-short
        :description: The specified asking price is too short
    .. error::
        :field: priceModel.minimalBid
        :code: input-not-allowed
        :description: The minimal bid is not allowed for the selected model type
    .. error::
        :field: priceModel.minimalBid
        :code: value-too-high
        :description: The minimal bid is too high (it is higher then the asking price)
    .. error::
        :field: priceModel.minimalBid
        :code: input-too-short
        :description: The specified asking price is too short
    .. error::
        :field: priceModel.shippingCosts
        :code: input-too-low
        :description: The specified shipping costs are too low
    .. error::
        :field: priceModel.retailPrice
        :code: input-invalid
        :description: It is only allowed to set or update the retailPrice when the user has retail_price privileges.