# Create order with specified free item

Creates an order with a specified free item. The created order will get a `done` order status. <br> <div class="note">
<strong>Note</strong><br><br>
This API call returns generic item catalog data when used without
authorization. Use authorization to retrieve
<a href="https://developers.xsolla.com/doc/shop-builder/features/personalization/" target="_blank">personalized</a>
user data, such as limits and promotions associated with the item.
To do this, pass the user JWT in the <code>Authorization</code> header.
For more information about user JWT, see the <b>Security</b> block
for this call.
</div>

Endpoint: POST /v2/project/{project_id}/free/item/{item_sku}
Version: 2.0.0
Security: XsollaLoginUserJWT

## Path parameters:

  - `project_id` (integer, required)
    Project ID. You can find this parameter in your [Publisher Account](https://publisher.xsolla.com/0/projects/0/) next to the project name and in the browser address bar when working with a project. The URL has the following format: `https://publisher.xsolla.com/<merchant_id>/projects/<project_id>`.

  - `item_sku` (string, required)
    Item SKU.

## Request fields (application/json):

  - `currency` (string)
    Order price currency. Three-letter currency code per [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217). Check the documentation for detailed information about [currencies supported by Xsolla](https://developers.xsolla.com/doc/pay-station/references/supported-currencies/).

  - `locale` (string)
    Response language.

  - `sandbox` (boolean)
    Creates an order in the sandbox mode. The option is available for those users who are specified in the list of company users.

  - `quantity` (integer)
    Item quantity.

  - `promo_code` (string)
    Redeems a code of a promo code promotion with payment.

  - `settings` (object)
    Settings for configuring payment process and the payment UI for a user.

  - `settings.ui` (object)
    Interface settings.

  - `settings.ui.theme` (string)
    Payment UI theme. Can be `63295a9a2e47fab76f7708e1` for the light theme (default) or `63295aab2e47fab76f7708e3` for the dark theme. You can also [create a custom theme](https://developers.xsolla.com/doc/pay-station/features/ui-theme-customization/#pay_station_ui_theme_customization_in_token) and pass its ID in this parameter.
    Enum: "63295a9a2e47fab76f7708e1", "63295aab2e47fab76f7708e3"

  - `settings.ui.desktop` (object)
    Interface settings for the desktop version.

  - `settings.ui.desktop.header` (object)
    Header settings.

  - `settings.ui.desktop.header.is_visible` (boolean)
    Whether to show the header in the payment UI.

  - `settings.ui.desktop.header.visible_logo` (boolean)
    If `true`, the logo is displayed in the header. To upload the image, open your project in [Publisher Account](https://publisher.xsolla.com/) and go to the Pay Station > Settings section.

  - `settings.ui.desktop.header.visible_name` (boolean)
    Whether to show the project name in the header.

  - `settings.ui.desktop.header.visible_purchase` (boolean)
    Whether to show the purchase description (`purchase.description.value`) in the header. `true` by default.

  - `settings.ui.desktop.header.type` (string)
    How to show the header. Can be `compact` (hides project name and user ID) or `normal` (default).
    Enum: "compact", "normal"

  - `settings.ui.desktop.header.close_button` (boolean)
    Whether to show a **Close** button in desktop payment UI. The button closes the payment UI and redirects the user to the URL specified in the `settings.return_url` parameter. `false` by default.

  - `settings.ui.mode` (string)
    Interface mode in payment UI. Can be `user_account` only. The header contains only the account navigation menu, and the user cannot select a product or make a payment. This mode is only available on the desktop.
    Enum: "user_account"

  - `settings.ui.user_account` (object)
    User account details.

  - `settings.ui.user_account.payment_accounts` (object)
    **My payment accounts** submenu.

  - `settings.ui.user_account.payment_accounts.enable` (boolean, required)
    Whether to show the submenu. `false` by default.

  - `settings.ui.user_account.info` (object)
    Page **My account**.

  - `settings.ui.user_account.info.enable` (boolean, required)
    Whether to show the submenu. `false` by default.

  - `settings.ui.user_account.info.order` (integer, required)
    Position of the submenu in the menu.

  - `settings.ui.user_account.subscriptions` (object)
    **Manage subscriptions** submenu.

  - `settings.ui.user_account.subscriptions.enable` (boolean, required)
    Whether to show the submenu. `false` by default.

  - `settings.ui.user_account.subscriptions.order` (integer, required)
    Position of the submenu in the menu.

  - `settings.ui.header` (object)

  - `settings.ui.mobile` (object)

  - `settings.ui.mobile.header` (object)

  - `settings.ui.mobile.header.close_button` (boolean)
    Whether to show a **Close** button in mobile payment UI. The button closes the payment UI and redirects the user to the URL specified in the `settings.return_url` parameter.

  - `settings.ui.is_prevent_external_link_open` (boolean)
    Whether or not redirecting links to an external resource is disabled. When clicking an external link, the `external-link-open` event is sent via the `postMessage` mechanism. The address for the redirected link is passed in the `url` parameter.

  - `settings.ui.is_payment_methods_list_mode` (boolean)
    Whether the list of payment methods available in the user’s country is displayed when opening the payment UI. If `false` (default), the payment method passed in the `settings.payment_method` parameter or the method selected by the [PayRank algorithm](https://developers.xsolla.com/solutions/payments/payment-ui-management/top-payment-methods-management/) is displayed.

  - `settings.ui.is_independent_windows` (boolean)
    Whether to redirect users from the embedded launcher’s browser (WebView) to their default browser to make a purchase.

  - `settings.ui.currency_format` (string)
    Set to `code` to display a three-letter [ISO 4217](https://developers.xsolla.com/doc/pay-station/references/supported-currencies/) currency code in the payment UI. The currency symbol is displayed instead of the three-letter currency code by default.

  - `settings.ui.is_show_close_widget_warning` (boolean)
    Whether to show a warning about processing the transaction when hovering over the **×** icon before closing the payment page. If `false` is passed, or the parameter is not passed, the warning is not displayed.

  - `settings.ui.layout` (string)
    Location of the main elements of the payment UI. You can open the payment UI inside your game and/or swap the columns with information about an order and payment methods. Refer to the [customization instructions](https://developers.xsolla.com/doc/pay-station/features/ui-theme-customization/#pay_station_ui_theme_customization_layout) for detailed information.
    Enum: "embed", "column_reverse", "embed_column_reverse"

  - `settings.ui.is_three_ds_independent_windows` (boolean)
    Whether the 3-D Secure verification opens in a new browser window. If your setup enforces a Content Security Policy (CSP), set to `true`.

  - `settings.ui.is_cart_open_by_default` (boolean)
    The display of the list of items in the cart when opening the mobile version of the payment UI. If `true`, the list is displayed in an extended view. If `false` (default) or the parameters is not passed, the list is displayed in a collapsed view.

  - `settings.payment_method` (integer)
    Payment method ID. It determines the display of currency in the payment interface, as some payment methods may only support certain currencies.

  - `settings.return_url` (string)
    Page to redirect the user to after payment. Parameters `user_id`, `foreigninvoice`, `invoice_id` and `status` will be automatically added to the link.

  - `settings.redirect_policy` (object)

  - `settings.redirect_policy.redirect_conditions` (string)
    Payment status triggering user redirect to the return URL.
    Enum: "none", "successful", "successful_or_canceled", "any"

  - `settings.redirect_policy.delay` (integer)
    Delay after which the user will be automatically redirected to the return URL.
    Example: 0

  - `settings.redirect_policy.status_for_manual_redirection` (string)
    Payment status triggering the display of a button clicking which redirects the user to the return URL.
    Enum: "none", "successful", "successful_or_canceled", "any"

  - `settings.redirect_policy.redirect_button_caption` (string)
    Localized redirect button captions.
    Example: Text button

  - `custom_parameters` (object)
    Project specific parameters.

## Response 200 fields (application/json):

  - `order_id` (integer)
    Order ID.

## Response 422 fields (application/json):

  - `errorCode` (integer)
    Example: 1411

  - `statusCode` (integer)
    Example: 422

  - `errorMessage` (string)
    Example: [0401-1411]: Invalid item