Getting Started with Deposits and Fees

This guide walks you through creating and managing Deposit and Fee Rules on the Hii Retail platform. By the end of this guide, you will understand how to configure refundable deposits (like bottle deposits) and non-refundable fees (like eco taxes) for your Items.

Overview

What is a Deposit and Fee Rule?

A Deposit and Fee Rule defines how a refundable deposit or fee is applied to specific Items. It specifies the amount to be added to a receipt when an Item is sold at the POS.

Common use cases include:

• Bottle deposits - Refunded when containers are returned
• Eco taxes - Fees on tires, electronics, or packaging
• Packaging fees - Charges for bags or containers

┌─────────────────────────────────────────────────────────────────────┐
│                    Deposit and Fee Rules                            │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   Item: "Coca-Cola 500ml"                                           │
│   Price: €1.49                                                      │
│   ────────────────────────                                          │
│   + Deposit Rule: "bottle-deposit-pet-500ml"                        │
│   + Amount: €0.25 (refundable)                                      │
│   ────────────────────────                                          │
│   Total at POS: €1.74                                               │
│                                                                     │
│   When bottle returned → €0.25 refunded                             │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Rule Types

Type	Description	Example
REFUNDABLE_DEPOSIT	Amount refunded when item/container is returned	Bottle deposits, electronics recycling
FEE	Non-refundable charge added to the sale	Eco tax on tires, plastic bag fee

Rule Statuses

Status	Description
ACTIVE	Rule is active and applied to items
DELETED	Rule is deleted and should not be used

How Rules Link to Items

Deposit and Fee Rules are global (not per Business Unit). Each rule is referenced by its depositAndFeeRuleId on the Item entity:

┌────────────────────┐         ┌─────────────────────────┐
│       Item         │         │   Deposit/Fee Rule      │
│                    │         │                         │
│ id: "cola-500ml"   │────────▶│ id: "pet-bottle-025"    │
│ depositAndFeeRuleId│         │ amount: 0.25            │
│   "pet-bottle-025" │         │ type: REFUNDABLE_DEPOSIT│
└────────────────────┘         └─────────────────────────┘

Prerequisites

Before you begin, ensure you have:

1. Business Unit Group created: At least one Business Unit Group (see Business Units guide)
2. Authentication Token: A valid JWT bearer token with the pnp.dep-and-fee-rule.create permission

Authentication

For details on obtaining an access token, see the OAuth2 Authentication documentation.

API Base URL

All Deposit and Fee Rule Input API requests should be sent to:

https://deposit-and-fee-rule-input.retailsvc.com/api/v1

Step 1: Create a Refundable Deposit Rule

Create a bottle deposit rule that will be refunded when the container is returned.

Required Fields

Field	Type	Description
id	string	Unique identifier (max 250 characters)
amount	number	Deposit amount to add at POS
status	string	ACTIVE or DELETED
businessUnitGroupId	string	The Business Unit Group where this rule applies

Code Examples

cURL

curl -X POST 'https://deposit-and-fee-rule-input.retailsvc.com/api/v1/deposit-and-fee-rules' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "pet-bottle-025",
    "name": "PET Bottle Deposit 0.25",
    "description": "Refundable deposit for PET bottles up to 500ml",
    "type": "REFUNDABLE_DEPOSIT",
    "status": "ACTIVE",
    "amount": 0.25,
    "taxableGroupId": "Standard",
    "isPercentage": false,
    "isIncludedInPrice": false,
    "businessUnitGroupId": "acme-retail-group"
  }'

Python

response = requests.post(
    "https://deposit-and-fee-rule-input.retailsvc.com/api/v1/deposit-and-fee-rules",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "id": "pet-bottle-025",
        "name": "PET Bottle Deposit 0.25",
        "description": "Refundable deposit for PET bottles up to 500ml",
        "type": "REFUNDABLE_DEPOSIT",
        "status": "ACTIVE",
        "amount": 0.25,
        "taxableGroupId": "Standard",
        "isPercentage": False,
        "isIncludedInPrice": False,
        "businessUnitGroupId": "acme-retail-group"
    }
)

Node.js

const response = await fetch('https://deposit-and-fee-rule-input.retailsvc.com/api/v1/deposit-and-fee-rules', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    id: 'pet-bottle-025',
    name: 'PET Bottle Deposit 0.25',
    description: 'Refundable deposit for PET bottles up to 500ml',
    type: 'REFUNDABLE_DEPOSIT',
    status: 'ACTIVE',
    amount: 0.25,
    taxableGroupId: 'Standard',
    isPercentage: false,
    isIncludedInPrice: false,
    businessUnitGroupId: 'acme-retail-group'
  })
});

Java

var payload = """
    {
      "id": "pet-bottle-025",
      "name": "PET Bottle Deposit 0.25",
      "description": "Refundable deposit for PET bottles up to 500ml",
      "type": "REFUNDABLE_DEPOSIT",
      "status": "ACTIVE",
      "amount": 0.25,
      "taxableGroupId": "Standard",
      "isPercentage": false,
      "isIncludedInPrice": false,
      "businessUnitGroupId": "acme-retail-group"
    }
    """;

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://deposit-and-fee-rule-input.retailsvc.com/api/v1/deposit-and-fee-rules"))
    .header("Authorization", "Bearer " + accessToken)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(payload))
    .build();

var response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

.NET

var payload = new {
    id = "pet-bottle-025",
    name = "PET Bottle Deposit 0.25",
    description = "Refundable deposit for PET bottles up to 500ml",
    type = "REFUNDABLE_DEPOSIT",
    status = "ACTIVE",
    amount = 0.25,
    taxableGroupId = "Standard",
    isPercentage = false,
    isIncludedInPrice = false,
    businessUnitGroupId = "acme-retail-group"
};

var content = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");
var response = await httpClient.PostAsync("https://deposit-and-fee-rule-input.retailsvc.com/api/v1/deposit-and-fee-rules", content);

Response

A successful request returns 202 Accepted.

Asynchronous Processing

The Deposit and Fee Rule Input API processes requests asynchronously. A 202 Accepted response means your request has been queued for processing.

Step 2: Create Multiple Deposit Rules

Different container sizes often have different deposit amounts. Create rules for various sizes:

cURL

# Small bottles (up to 500ml) - €0.25 deposit
curl -X POST 'https://deposit-and-fee-rule-input.retailsvc.com/api/v1/deposit-and-fee-rules' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "pet-bottle-small-025",
    "name": "Small PET Bottle Deposit",
    "description": "Deposit for PET bottles up to 500ml",
    "type": "REFUNDABLE_DEPOSIT",
    "status": "ACTIVE",
    "amount": 0.25,
    "taxableGroupId": "Standard",
    "businessUnitGroupId": "acme-retail-group"
  }'

# Large bottles (1L+) - €0.50 deposit
curl -X POST 'https://deposit-and-fee-rule-input.retailsvc.com/api/v1/deposit-and-fee-rules' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "pet-bottle-large-050",
    "name": "Large PET Bottle Deposit",
    "description": "Deposit for PET bottles 1 liter and above",
    "type": "REFUNDABLE_DEPOSIT",
    "status": "ACTIVE",
    "amount": 0.50,
    "taxableGroupId": "Standard",
    "businessUnitGroupId": "acme-retail-group"
  }'

# Cans - €0.15 deposit
curl -X POST 'https://deposit-and-fee-rule-input.retailsvc.com/api/v1/deposit-and-fee-rules' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "can-deposit-015",
    "name": "Can Deposit",
    "description": "Deposit for aluminum cans",
    "type": "REFUNDABLE_DEPOSIT",
    "status": "ACTIVE",
    "amount": 0.15,
    "taxableGroupId": "Standard",
    "businessUnitGroupId": "acme-retail-group"
  }'

Python

deposit_rules = [
    {
        "id": "pet-bottle-small-025",
        "name": "Small PET Bottle Deposit",
        "description": "Deposit for PET bottles up to 500ml",
        "type": "REFUNDABLE_DEPOSIT",
        "amount": 0.25
    },
    {
        "id": "pet-bottle-large-050",
        "name": "Large PET Bottle Deposit",
        "description": "Deposit for PET bottles 1 liter and above",
        "type": "REFUNDABLE_DEPOSIT",
        "amount": 0.50
    },
    {
        "id": "can-deposit-015",
        "name": "Can Deposit",
        "description": "Deposit for aluminum cans",
        "type": "REFUNDABLE_DEPOSIT",
        "amount": 0.15
    }
]

for rule in deposit_rules:
    response = requests.post(
        "https://deposit-and-fee-rule-input.retailsvc.com/api/v1/deposit-and-fee-rules",
        headers={"Authorization": f"Bearer {access_token}"},
        json={
            **rule,
            "status": "ACTIVE",
            "taxableGroupId": "Standard",
            "businessUnitGroupId": "acme-retail-group"
        }
    )
    print(f"Created {rule['id']}: {response.status_code}")

Node.js

const depositRules = [
  {
    id: 'pet-bottle-small-025',
    name: 'Small PET Bottle Deposit',
    description: 'Deposit for PET bottles up to 500ml',
    type: 'REFUNDABLE_DEPOSIT',
    amount: 0.25
  },
  {
    id: 'pet-bottle-large-050',
    name: 'Large PET Bottle Deposit',
    description: 'Deposit for PET bottles 1 liter and above',
    type: 'REFUNDABLE_DEPOSIT',
    amount: 0.50
  },
  {
    id: 'can-deposit-015',
    name: 'Can Deposit',
    description: 'Deposit for aluminum cans',
    type: 'REFUNDABLE_DEPOSIT',
    amount: 0.15
  }
];

for (const rule of depositRules) {
  const response = await fetch('https://deposit-and-fee-rule-input.retailsvc.com/api/v1/deposit-and-fee-rules', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${accessToken}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      ...rule,
      status: 'ACTIVE',
      taxableGroupId: 'Standard',
      businessUnitGroupId: 'acme-retail-group'
    })
  });
  console.log(`Created ${rule.id}: ${response.status}`);
}

Java

record DepositRule(String id, String name, String description, double amount) {}

var rules = List.of(
    new DepositRule("pet-bottle-small-025", "Small PET Bottle Deposit",
                    "Deposit for PET bottles up to 500ml", 0.25),
    new DepositRule("pet-bottle-large-050", "Large PET Bottle Deposit",
                    "Deposit for PET bottles 1 liter and above", 0.50),
    new DepositRule("can-deposit-015", "Can Deposit",
                    "Deposit for aluminum cans", 0.15)
);

for (var rule : rules) {
    var payload = String.format("""
        {
          "id": "%s",
          "name": "%s",
          "description": "%s",
          "type": "REFUNDABLE_DEPOSIT",
          "status": "ACTIVE",
          "amount": %.2f,
          "taxableGroupId": "Standard",
          "businessUnitGroupId": "acme-retail-group"
        }
        """, rule.id(), rule.name(), rule.description(), rule.amount());

    var request = HttpRequest.newBuilder()
        .uri(URI.create("https://deposit-and-fee-rule-input.retailsvc.com/api/v1/deposit-and-fee-rules"))
        .header("Authorization", "Bearer " + accessToken)
        .header("Content-Type", "application/json")
        .POST(HttpRequest.BodyPublishers.ofString(payload))
        .build();

    var response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println("Created " + rule.id() + ": " + response.statusCode());
}

.NET

var depositRules = new[] {
    new { id = "pet-bottle-small-025", name = "Small PET Bottle Deposit",
          description = "Deposit for PET bottles up to 500ml", amount = 0.25m },
    new { id = "pet-bottle-large-050", name = "Large PET Bottle Deposit",
          description = "Deposit for PET bottles 1 liter and above", amount = 0.50m },
    new { id = "can-deposit-015", name = "Can Deposit",
          description = "Deposit for aluminum cans", amount = 0.15m }
};

foreach (var rule in depositRules)
{
    var payload = new {
        rule.id,
        rule.name,
        rule.description,
        type = "REFUNDABLE_DEPOSIT",
        status = "ACTIVE",
        rule.amount,
        taxableGroupId = "Standard",
        businessUnitGroupId = "acme-retail-group"
    };

    var content = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");
    var response = await httpClient.PostAsync("https://deposit-and-fee-rule-input.retailsvc.com/api/v1/deposit-and-fee-rules", content);
    Console.WriteLine($"Created {rule.id}: {response.StatusCode}");
}

Step 3: Create an Eco Tax Fee

Create a non-refundable fee for environmental taxes (e.g., tire disposal tax).

cURL

curl -X POST 'https://deposit-and-fee-rule-input.retailsvc.com/api/v1/deposit-and-fee-rules' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "eco-tax-tire",
    "name": "Tire Disposal Eco Tax",
    "description": "Environmental fee for tire disposal",
    "type": "FEE",
    "status": "ACTIVE",
    "amount": 2.50,
    "code": "ECO-TIRE",
    "taxableGroupId": "Standard",
    "isPercentage": false,
    "isIncludedInPrice": false,
    "businessUnitGroupId": "acme-retail-group"
  }'

Python

response = requests.post(
    "https://deposit-and-fee-rule-input.retailsvc.com/api/v1/deposit-and-fee-rules",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "id": "eco-tax-tire",
        "name": "Tire Disposal Eco Tax",
        "description": "Environmental fee for tire disposal",
        "type": "FEE",
        "status": "ACTIVE",
        "amount": 2.50,
        "code": "ECO-TIRE",
        "taxableGroupId": "Standard",
        "isPercentage": False,
        "isIncludedInPrice": False,
        "businessUnitGroupId": "acme-retail-group"
    }
)

Node.js

const response = await fetch('https://deposit-and-fee-rule-input.retailsvc.com/api/v1/deposit-and-fee-rules', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    id: 'eco-tax-tire',
    name: 'Tire Disposal Eco Tax',
    description: 'Environmental fee for tire disposal',
    type: 'FEE',
    status: 'ACTIVE',
    amount: 2.50,
    code: 'ECO-TIRE',
    taxableGroupId: 'Standard',
    isPercentage: false,
    isIncludedInPrice: false,
    businessUnitGroupId: 'acme-retail-group'
  })
});

Java

var payload = """
    {
      "id": "eco-tax-tire",
      "name": "Tire Disposal Eco Tax",
      "description": "Environmental fee for tire disposal",
      "type": "FEE",
      "status": "ACTIVE",
      "amount": 2.50,
      "code": "ECO-TIRE",
      "taxableGroupId": "Standard",
      "isPercentage": false,
      "isIncludedInPrice": false,
      "businessUnitGroupId": "acme-retail-group"
    }
    """;

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://deposit-and-fee-rule-input.retailsvc.com/api/v1/deposit-and-fee-rules"))
    .header("Authorization", "Bearer " + accessToken)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(payload))
    .build();

var response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

.NET

var payload = new {
    id = "eco-tax-tire",
    name = "Tire Disposal Eco Tax",
    description = "Environmental fee for tire disposal",
    type = "FEE",
    status = "ACTIVE",
    amount = 2.50,
    code = "ECO-TIRE",
    taxableGroupId = "Standard",
    isPercentage = false,
    isIncludedInPrice = false,
    businessUnitGroupId = "acme-retail-group"
};

var content = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");
var response = await httpClient.PostAsync("https://deposit-and-fee-rule-input.retailsvc.com/api/v1/deposit-and-fee-rules", content);

Fee vs Deposit

Use FEE for non-refundable charges like eco taxes, bag fees, or service charges. Use REFUNDABLE_DEPOSIT for amounts that are returned to the customer when items are returned.

Step 4: Create a Country-Specific Deposit Rule

Some countries have specific deposit regulations. Use the countryCode field to specify regional rules.

cURL

curl -X POST 'https://deposit-and-fee-rule-input.retailsvc.com/api/v1/deposit-and-fee-rules' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "no-pant-3kr",
    "name": "Norwegian Pant 3 NOK",
    "description": "Norwegian bottle deposit (pant) for large bottles",
    "type": "REFUNDABLE_DEPOSIT",
    "status": "ACTIVE",
    "amount": 3.00,
    "countryCode": "NO",
    "taxableGroupId": "Standard",
    "businessUnitGroupId": "acme-retail-group"
  }'

Python

response = requests.post(
    "https://deposit-and-fee-rule-input.retailsvc.com/api/v1/deposit-and-fee-rules",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "id": "no-pant-3kr",
        "name": "Norwegian Pant 3 NOK",
        "description": "Norwegian bottle deposit (pant) for large bottles",
        "type": "REFUNDABLE_DEPOSIT",
        "status": "ACTIVE",
        "amount": 3.00,
        "countryCode": "NO",
        "taxableGroupId": "Standard",
        "businessUnitGroupId": "acme-retail-group"
    }
)

Node.js

const response = await fetch('https://deposit-and-fee-rule-input.retailsvc.com/api/v1/deposit-and-fee-rules', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    id: 'no-pant-3kr',
    name: 'Norwegian Pant 3 NOK',
    description: 'Norwegian bottle deposit (pant) for large bottles',
    type: 'REFUNDABLE_DEPOSIT',
    status: 'ACTIVE',
    amount: 3.00,
    countryCode: 'NO',
    taxableGroupId: 'Standard',
    businessUnitGroupId: 'acme-retail-group'
  })
});

Java

var payload = """
    {
      "id": "no-pant-3kr",
      "name": "Norwegian Pant 3 NOK",
      "description": "Norwegian bottle deposit (pant) for large bottles",
      "type": "REFUNDABLE_DEPOSIT",
      "status": "ACTIVE",
      "amount": 3.00,
      "countryCode": "NO",
      "taxableGroupId": "Standard",
      "businessUnitGroupId": "acme-retail-group"
    }
    """;

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://deposit-and-fee-rule-input.retailsvc.com/api/v1/deposit-and-fee-rules"))
    .header("Authorization", "Bearer " + accessToken)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(payload))
    .build();

var response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

.NET

var payload = new {
    id = "no-pant-3kr",
    name = "Norwegian Pant 3 NOK",
    description = "Norwegian bottle deposit (pant) for large bottles",
    type = "REFUNDABLE_DEPOSIT",
    status = "ACTIVE",
    amount = 3.00,
    countryCode = "NO",
    taxableGroupId = "Standard",
    businessUnitGroupId = "acme-retail-group"
};

var content = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");
var response = await httpClient.PostAsync("https://deposit-and-fee-rule-input.retailsvc.com/api/v1/deposit-and-fee-rules", content);

Step 5: Link a Deposit Rule to an Item

After creating deposit rules, link them to Items by setting the depositAndFeeRuleId when creating or updating the Item.

cURL

curl -X POST 'https://item-input.retailsvc.com/api/v2/bu-g-items' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "cola-500ml",
    "name": "Cola 500ml PET Bottle",
    "status": "ACTIVE",
    "type": "STOCK",
    "itemCategoryId": "beverages-soft-drinks",
    "salesUnitOfMeasurement": "EA",
    "assortmentType": "IN_ASSORTMENT",
    "businessUnitGroupId": "acme-retail-group",
    "depositAndFeeRuleId": "pet-bottle-small-025"
  }'

Python

response = requests.post(
    "https://item-input.retailsvc.com/api/v2/bu-g-items",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "id": "cola-500ml",
        "name": "Cola 500ml PET Bottle",
        "status": "ACTIVE",
        "type": "STOCK",
        "itemCategoryId": "beverages-soft-drinks",
        "salesUnitOfMeasurement": "EA",
        "assortmentType": "IN_ASSORTMENT",
        "businessUnitGroupId": "acme-retail-group",
        "depositAndFeeRuleId": "pet-bottle-small-025"
    }
)

Node.js

const response = await fetch('https://item-input.retailsvc.com/api/v2/bu-g-items', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    id: 'cola-500ml',
    name: 'Cola 500ml PET Bottle',
    status: 'ACTIVE',
    type: 'STOCK',
    itemCategoryId: 'beverages-soft-drinks',
    salesUnitOfMeasurement: 'EA',
    assortmentType: 'IN_ASSORTMENT',
    businessUnitGroupId: 'acme-retail-group',
    depositAndFeeRuleId: 'pet-bottle-small-025'
  })
});

Java

var payload = """
    {
      "id": "cola-500ml",
      "name": "Cola 500ml PET Bottle",
      "status": "ACTIVE",
      "type": "STOCK",
      "itemCategoryId": "beverages-soft-drinks",
      "salesUnitOfMeasurement": "EA",
      "assortmentType": "IN_ASSORTMENT",
      "businessUnitGroupId": "acme-retail-group",
      "depositAndFeeRuleId": "pet-bottle-small-025"
    }
    """;

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://item-input.retailsvc.com/api/v2/bu-g-items"))
    .header("Authorization", "Bearer " + accessToken)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(payload))
    .build();

var response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

.NET

var payload = new {
    id = "cola-500ml",
    name = "Cola 500ml PET Bottle",
    status = "ACTIVE",
    type = "STOCK",
    itemCategoryId = "beverages-soft-drinks",
    salesUnitOfMeasurement = "EA",
    assortmentType = "IN_ASSORTMENT",
    businessUnitGroupId = "acme-retail-group",
    depositAndFeeRuleId = "pet-bottle-small-025"
};

var content = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");
var response = await httpClient.PostAsync("https://item-input.retailsvc.com/api/v2/bu-g-items", content);

POS Display

When the item is scanned at POS, the deposit amount (€0.25) will be added as a separate line on the receipt.

Step 6: Update a Deposit Rule

Use PUT to update an existing deposit rule (e.g., when deposit amounts change).

cURL

curl -X PUT 'https://deposit-and-fee-rule-input.retailsvc.com/api/v1/deposit-and-fee-rules' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "pet-bottle-small-025",
    "name": "Small PET Bottle Deposit",
    "description": "Deposit for PET bottles up to 500ml - Updated",
    "type": "REFUNDABLE_DEPOSIT",
    "status": "ACTIVE",
    "amount": 0.30,
    "taxableGroupId": "Standard",
    "businessUnitGroupId": "acme-retail-group"
  }'

Python

response = requests.put(
    "https://deposit-and-fee-rule-input.retailsvc.com/api/v1/deposit-and-fee-rules",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "id": "pet-bottle-small-025",
        "name": "Small PET Bottle Deposit",
        "description": "Deposit for PET bottles up to 500ml - Updated",
        "type": "REFUNDABLE_DEPOSIT",
        "status": "ACTIVE",
        "amount": 0.30,
        "taxableGroupId": "Standard",
        "businessUnitGroupId": "acme-retail-group"
    }
)

Node.js

const response = await fetch('https://deposit-and-fee-rule-input.retailsvc.com/api/v1/deposit-and-fee-rules', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    id: 'pet-bottle-small-025',
    name: 'Small PET Bottle Deposit',
    description: 'Deposit for PET bottles up to 500ml - Updated',
    type: 'REFUNDABLE_DEPOSIT',
    status: 'ACTIVE',
    amount: 0.30,
    taxableGroupId: 'Standard',
    businessUnitGroupId: 'acme-retail-group'
  })
});

Java

var payload = """
    {
      "id": "pet-bottle-small-025",
      "name": "Small PET Bottle Deposit",
      "description": "Deposit for PET bottles up to 500ml - Updated",
      "type": "REFUNDABLE_DEPOSIT",
      "status": "ACTIVE",
      "amount": 0.30,
      "taxableGroupId": "Standard",
      "businessUnitGroupId": "acme-retail-group"
    }
    """;

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://deposit-and-fee-rule-input.retailsvc.com/api/v1/deposit-and-fee-rules"))
    .header("Authorization", "Bearer " + accessToken)
    .header("Content-Type", "application/json")
    .PUT(HttpRequest.BodyPublishers.ofString(payload))
    .build();

var response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

.NET

var payload = new {
    id = "pet-bottle-small-025",
    name = "Small PET Bottle Deposit",
    description = "Deposit for PET bottles up to 500ml - Updated",
    type = "REFUNDABLE_DEPOSIT",
    status = "ACTIVE",
    amount = 0.30,
    taxableGroupId = "Standard",
    businessUnitGroupId = "acme-retail-group"
};

var content = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");
var response = await httpClient.PutAsync("https://deposit-and-fee-rule-input.retailsvc.com/api/v1/deposit-and-fee-rules", content);

Step 7: Delete a Deposit Rule

Delete a deposit rule when it's no longer needed.

cURL

curl -X DELETE 'https://deposit-and-fee-rule-input.retailsvc.com/api/v1/deposit-and-fee-rules/pet-bottle-small-025?businessUnitGroupId=acme-retail-group' \
  -H 'Authorization: Bearer <your-access-token>'

Python

response = requests.delete(
    "https://deposit-and-fee-rule-input.retailsvc.com/api/v1/deposit-and-fee-rules/pet-bottle-small-025",
    params={"businessUnitGroupId": "acme-retail-group"},
    headers={"Authorization": f"Bearer {access_token}"}
)

Node.js

const response = await fetch(
  'https://deposit-and-fee-rule-input.retailsvc.com/api/v1/deposit-and-fee-rules/pet-bottle-small-025?businessUnitGroupId=acme-retail-group',
  {
    method: 'DELETE',
    headers: { 'Authorization': `Bearer ${accessToken}` }
  }
);

Java

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://deposit-and-fee-rule-input.retailsvc.com/api/v1/deposit-and-fee-rules/pet-bottle-small-025?businessUnitGroupId=acme-retail-group"))
    .header("Authorization", "Bearer " + accessToken)
    .DELETE()
    .build();

var response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

.NET

var response = await httpClient.DeleteAsync(
    "https://deposit-and-fee-rule-input.retailsvc.com/api/v1/deposit-and-fee-rules/pet-bottle-small-025?businessUnitGroupId=acme-retail-group");

Items Still Linked

Before deleting a deposit rule, ensure no Items are still referencing it via depositAndFeeRuleId. Update those Items first to remove the reference or assign a different rule.

Common Deposit Configurations

Country	Container Type	Typical Deposit
Sweden	PET bottles < 1L	1 SEK
Sweden	PET bottles ≥ 1L	2 SEK
Sweden	Aluminum cans	1 SEK
Norway	Small bottles	2 NOK
Norway	Large bottles	3 NOK
Germany	Single-use bottles	0.25 EUR
Germany	Reusable bottles	0.08-0.15 EUR

Next Steps

Now that you can configure deposits and fees, you can:

1. Create Items with deposits: Link deposit rules when creating beverage items
2. Set up reverse vending: Configure deposit return workflows
3. Track deposits: Monitor deposit collections and redemptions in reports

Related Resources

• Deposit and Fee Rule API Reference
• Deposit Rule Concepts
• Items Guide
• Prices Guide

---

Next: Sales Restrictions - Learn how to configure age restrictions and sales controls for regulated products.