> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/api-documentation/api-guides/checkout/fee/fee.md).

# Fee Tutorial

The Fee Service allows you to manage additional fees that you want to connect to specific items. For example, you can add a fee and link it to a product or a payment type.

**Fee types**:

The Fee Service supports multiple fee types. Each type determines how the fee is calculated and applied:

* **ABSOLUTE** - A fixed amount fee applied regardless of the item’s price, for example, €3 packaging fee per product.
* **PERCENTAGE** - A fee calculated as a percentage of the item’s price, for example, 5% of the product price as a handling fee.
* **ABSOLUTE\_MULTIPLY\_ITEMQUANTITY** - Monetary amount multiplied by the item quantity and assigned to the item line.

{% hint style="info" %}
If you're looking for information about fees and cart calculations, see [How to calculate a payment fee at cart level](/api-documentation/api-guides/checkout/cart/cart.md#how-to-calculate-a-payment-fee-at-cart-level) and [How is price calculated](/api-documentation/api-guides/checkout/cart/cart.md#how-is-price-calculated).
{% endhint %}

## How to create a product fee

Follow these steps to create a fee and connect it to a product.

{% stepper %}
{% step %}

#### Create a fee

Send the request to the [Creating a fee](https://developer.emporix.io/api-references/api-guides/checkout/fee/api-reference/fee-management#post-fee-tenant-fees) endpoint.

```bash
curl -i -X POST 
  'https://api.emporix.io/fee/{tenant}/fees' 
  -H 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}' 
  -H 'Content-Language: string' 
  -H 'Content-Type: application/json' 
  -d '{
    "name": {
      "de": "Sixpack PET",
      "en": "Sixpack PET"
    },
    "code": "apple_picking_fee",
    "feeType": "ABSOLUTE",
    "siteCode": "main",
    "feeAbsolute": {
      "amount": 3.5,
      "currency": "EUR"
    },
    "active": true,
    "taxable": false
  }'
```

{% hint style="danger" %}
Make sure you provide the relevant `siteCode` of a site that you want to apply the fee to.
{% endhint %}
{% endstep %}

{% step %}

#### Copy the `feeId` of the created fee

To add the fee to the specific product, send the request to the [Adding a list of fees to a product](https://developer.emporix.io/api-references/api-guides/checkout/fee/api-reference/product-fees-management#put-fee-tenant-productfees-productid-fees) endpoint. You need to add the `feeId` in the request.

```bash
curl -i -X PUT 
  'https://api.emporix.io/fee/{tenant}/productFees/{productId}/fees?siteCode=main&partial=false' 
  -H 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}' 
  -H 'Content-Type: application/json' 
  -d '{
    "feeIds": [
      "57b30fd2289c48001daf5486",
      "96b30fd4586c48001daf1752"
    ]
  }'
```

In the request path parameter, provide the `productId` to add the fee to. The `siteCode` in the query parameter must correspond to the site you've created the fee for.
{% endstep %}

{% step %}

#### Review the fee

To make sure the fee has been added properly, you can send the request to the [Retrieving all fees with the given productId](https://developer.emporix.io/api-references/api-guides/checkout/fee/api-reference/product-fees-management#get-fee-tenant-productfees-productid-fees) endpoint.

```bash
curl -i -X GET 
  'https://api.emporix.io/fee/{tenant}/productFees/{productId}/fees?siteCode=main&expand=false' 
  -H 'Accept-Language: *' 
  -H 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}'
```

In the query parameter, provide the `siteCode` of the specific site the fee was applied to, for example `?siteCode=DE`.

Or, you can check if the fee was applied by sending the request to the [Searching itemFees by productId](https://developer.emporix.io/api-references/api-guides/checkout/fee/api-reference/item-fee-search#post-fee-tenant-itemfees-searchbyproductid) endpoint.

```bash
curl -i -X POST 
  'https://api.emporix.io/fee/{tenant}/itemFees/searchByProductId' 
  -H 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}' 
  -H 'Content-Type: application/json' 
  -d '{
    "productId": "Apple_A_productId",
    "siteCodes": [
      "example_site_code"
    ],
    "pageNumber": 1,
    "pageSize": 10
  }'
```

{% endstep %}
{% endstepper %}

{% hint style="success" %}
To test the endpoint, open the API reference or check the example of a curl request.
{% endhint %}

{% content-ref url="/pages/cuGoGzvIEhkgXFzvAdrz" %}
[API Reference](/api-documentation/api-guides/checkout/fee/api-reference.md)
{% endcontent-ref %}

## How to create a payment fee

The Fee Service supports adding fees to payments methods. See the example of creating a fee for a payment type.

{% stepper %}
{% step %}

#### Create a fee

Send the request to the [Creating a fee](https://developer.emporix.io/api-references/api-guides/checkout/fee/api-reference/fee-management#post-fee-tenant-fees) endpoint.

```bash
curl -i -X POST 
  'https://api.emporix.io/fee/{tenant}/fees' 
  -H 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}' 
  -H 'Content-Language: string' 
  -H 'Content-Type: application/json' 
  -d '{
    "name": {
      "de": "Sixpack PET",
      "en": "Sixpack PET"
    },
    "code": "apple_picking_fee",
    "feeType": "ABSOLUTE",
    "siteCode": "main",
    "feeAbsolute": {
      "amount": 3.5,
      "currency": "EUR"
    },
    "active": true,
    "taxable": false
  }'
```

When creating a payment fee, the fee `code` has to be identical with the payment mode `code`. To check the available payment modes for a given site, make a call to the [Retrieving all the payment modes](https://developer.emporix.io/api-references/api-guides/checkout/payment-gateway/api-reference/payment-mode-frontend#get-payment-gateway-tenant-paymentmodes-frontend) endpoint first.

Notice the `code` in the above payload corresponds to the payment mode `code` we want ta apply the fee to.
{% endstep %}

{% step %}

#### Copy the `feeId` of the created fee

To connect the fee to the specific payment type, create the item fee by sending the request to the [Creating itemFee](https://developer.emporix.io/api-references/api-guides/checkout/fee/api-reference/item-fee-management#post-fee-tenant-itemfees) endpoint and specify the `itemYrn` of the chosen payment type in the request body.

```bash
curl -i -X POST 
  'https://api.emporix.io/fee/{tenant}/itemFees' 
  -H 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}' 
  -H 'Content-Language: string' 
  -H 'Content-Type: application:json' 
  -d '[object Object]'
```

Note that the part of `itemYrn` contains the payment mode `code` which is identical with the fee `code`.
{% endstep %}

{% step %}

#### Apply the fee to the payment mode

Send a request to the [Adding a list of fees to an item](https://developer.emporix.io/api-references/api-guides/checkout/fee/api-reference/item-fee-management#put-fee-tenant-itemfees-itemyrn-fees) endpoint. You need to specify the `itemYrn` of the chosen payment type in the request path and pass the `feeId` in the body.

```bash
curl -i -X PUT 
  'https://api.emporix.io/fee/{tenant}/itemFees/{itemYRN}/fees?partial=false' 
  -H 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}' 
  -H 'Content-Type: application/json' 
  -d '{
    "feeIds": [
      "57b30fd2289c48001daf5486",
      "96b30fd4586c48001daf1752"
    ]
  }'
```

{% hint style="danger" %}
This operation overwrites the item's fees. For each payment mode you can create and connect one fee only.
{% endhint %}
{% endstep %}

{% step %}

#### Review the fee

Send the request to the [Checking of a fee has been applied](https://developer.emporix.io/api-references/api-guides/checkout/fee/api-reference/item-fee-search#post-fee-tenant-itemfees-search) endpoint.

```bash
curl -i -X POST 
  'https://api.emporix.io/fee/{tenant}/itemFees/search?siteCode=main' 
  -H 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}' 
  -H 'Content-Type: application/json' 
  -d '{
    "itemYrns": [
      "urn:yaas:saasag:caasproduct:product:tenantName;5c2e4957a46b0e0008491095",
      "urn:yaas:saasag:caasproduct:product:tenantName;5c2e4957a46b0e0008491096"
    ],
    "siteCode": "main"
  }'
```

The response contains the details of the fee applied to the payment for a given site.
{% endstep %}
{% endstepper %}

{% hint style="success" %}
To test the endpoint, open the API reference or check the example of a curl request.
{% endhint %}

{% content-ref url="/pages/cuGoGzvIEhkgXFzvAdrz" %}
[API Reference](/api-documentation/api-guides/checkout/fee/api-reference.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.emporix.io/api-documentation/api-guides/checkout/fee/fee.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.