.. index:: Advertisement, AdvertisementFeatures, BuyAdvertisementFeature

.. _buy_advertisement_feature:

Buy advertisement feature
=========================

You can buy features for an advertisement by doing performing POST against the buy feature controller resource.
Buying features for an advertisement is only possible when the authenticated user owns the advertisement.

.. apifields::

    .. apifield::
        :name: orderId
        :type: int
        :constraints: --
        :required: false
        :updateable: false
        :writable: true

        Optional argument that when specified indicates that these products should be added to an existing order rather
        than that a new order should be created (not yet implemented)

    .. apifield::
        :name: pay
        :type: boolean
        :constraints: --
        :required: true
        :updateable: false
        :writable: true

        When set to true indicates that you want to immediately pay for the order via invoicing
        (only API partners can do this) *ONLY TRUE IS CURRENTLY SUPPORTED*

Reference
---------

.. endpoint:: POST /v1/advertisements/{itemId}/features/{featurename}/buy-feature

Purchase a feature

Example
-------

.. include:: examples/buy-advertisement-feature-example.rst

Errors
------

.. errors::
    .. error::
        :http: 400
        :code: invalid-feature-type
        :description: The provided feature type is invalid

    .. error::
        :http: 400
        :code: invalid-order-state
        :description: The provided order cannot be modified

    .. error::
        :http: 400
        :code: unknown-order
        :description: The provided order id is unknown

    .. error::
        :http: 400
        :code: feature-not-allowed
        :description: The given feature cannot be bought by the current user. This is usually because
         the feature requires special privileges. If you think you really need this feature, contact
         us for more information.

    .. error::
        :http: 403
        :code: unauthorized
        :description: The action you are trying to perform is not allowed