Ozon API (jackoman69/ozon-api-spec)

Ozon API

https://github.com/jackoman69/ozon-api-spec
Admin
Provides the API specification for Ozon, an e-commerce platform.

Tokens:16,778
Snippets:60
Trust Score:5.8
Update:3 months ago
Show doc for...
Context Summary (auto-generated)
Raw
# Ozon Seller API

The Ozon Seller API is a comprehensive REST API that enables sellers to integrate their systems with the Ozon marketplace. It provides programmatic access to manage products, inventory, orders, pricing, promotions, warehouses, and analytics. The API supports multiple fulfillment schemes including FBO (Fulfillment by Ozon), FBS (Fulfillment by Seller), and rFBS (real Fulfillment by Seller) for different logistics and delivery scenarios.

The API allows sellers to automate critical e-commerce operations that would otherwise require manual updates through the seller dashboard. This includes bulk product uploads, real-time inventory synchronization, order processing workflows, price management, promotional campaigns, and access to financial reports. All endpoints use POST requests with JSON payloads and require authentication via Client-Id and Api-Key headers. The base URL is `https://api-seller.ozon.ru` and the current version is 2.1.

## Authentication

All API requests require authentication headers with your seller credentials.

```bash
# Required headers for all requests
curl -X POST "https://api-seller.ozon.ru/v1/seller/info" \
  -H "Client-Id: YOUR_CLIENT_ID" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{}"

# Expected response
{
  "result": {
    "company_id": 12345,
    "name": "Your Company Name",
    "is_enabled": true
  }
}
```

## Get Category Tree

Retrieve the hierarchical category structure for product classification on Ozon marketplace.

```bash
curl -X POST "https://api-seller.ozon.ru/v1/description-category/tree" \
  -H "Client-Id: YOUR_CLIENT_ID" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "DEFAULT"
  }'

# Response
{
  "result": [
    {
      "description_category_id": 17027492,
      "category_name": "Office Supplies",
      "disabled": false,
      "children": [
        {
          "description_category_id": 17029016,
          "category_name": "Stamps and Seals",
          "disabled": false,
          "children": [
            {
              "type_name": "Label Gun",
              "type_id": 970778135,
              "disabled": false,
              "children": []
            }
          ]
        }
      ]
    }
  ]
}
```

## Get Category Attributes

Retrieve required and optional attributes for a specific product category and type.

```bash
curl -X POST "https://api-seller.ozon.ru/v1/description-category/attribute" \
  -H "Client-Id: YOUR_CLIENT_ID" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description_category_id": 200000933,
    "type_id": 93080,
    "language": "DEFAULT"
  }'

# Response
{
  "result": [
    {
      "id": 31,
      "attribute_complex_id": 0,
      "name": "Brand",
      "description": "Specify the brand name",
      "type": "string",
      "is_collection": false,
      "is_required": true,
      "is_aspect": false,
      "dictionary_id": 28732849,
      "category_dependent": true
    }
  ]
}
```

## Get Attribute Values

Retrieve dictionary values for attributes that have predefined options.

```bash
curl -X POST "https://api-seller.ozon.ru/v1/description-category/attribute/values" \
  -H "Client-Id: YOUR_CLIENT_ID" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "attribute_id": 85,
    "description_category_id": 17054869,
    "type_id": 97311,
    "language": "DEFAULT",
    "limit": 100,
    "last_value_id": 0
  }'

# Response
{
  "result": [
    {
      "id": 5055881,
      "value": "Samsung",
      "info": "",
      "picture": "https://cdn1.ozone.ru/s3/multimedia-i/6010930878.jpg"
    },
    {
      "id": 5056737,
      "value": "Apple",
      "info": "Electronics",
      "picture": "https://cdn1.ozone.ru/s3/multimedia-v/6088253599.jpg"
    }
  ],
  "has_next": true
}
```

## Create or Update Product

Create new products or update existing ones with full product information including attributes, images, and pricing.

```bash
curl -X POST "https://api-seller.ozon.ru/v3/product/import" \
  -H "Client-Id: YOUR_CLIENT_ID" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "offer_id": "SKU-12345",
        "name": "Wireless Bluetooth Headphones",
        "description_category_id": 17028922,
        "type_id": 91565,
        "barcode": "4607086560000",
        "price": "2999",
        "old_price": "3499",
        "currency_code": "RUB",
        "vat": "0.2",
        "weight": 250,
        "weight_unit": "g",
        "depth": 80,
        "width": 180,
        "height": 200,
        "dimension_unit": "mm",
        "primary_image": "https://example.com/images/headphones-main.jpg",
        "images": [
          "https://example.com/images/headphones-side.jpg",
          "https://example.com/images/headphones-back.jpg"
        ],
        "attributes": [
          {
            "id": 85,
            "complex_id": 0,
            "values": [
              {
                "dictionary_value_id": 5060050,
                "value": "Sony"
              }
            ]
          },
          {
            "id": 10096,
            "complex_id": 0,
            "values": [
              {
                "dictionary_value_id": 61576,
                "value": "black"
              }
            ]
          }
        ]
      }
    ]
  }'

# Response
{
  "result": {
    "task_id": 172549793
  }
}
```

## Check Product Import Status

Check the status of a product import task to verify successful creation or identify errors.

```bash
curl -X POST "https://api-seller.ozon.ru/v1/product/import/info" \
  -H "Client-Id: YOUR_CLIENT_ID" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": 172549793
  }'

# Response
{
  "result": {
    "items": [
      {
        "offer_id": "SKU-12345",
        "product_id": 223681945,
        "status": "imported",
        "errors": []
      }
    ],
    "total": 1
  }
}
```

## Get Product List

Retrieve a paginated list of products with optional filtering by visibility status.

```bash
curl -X POST "https://api-seller.ozon.ru/v3/product/list" \
  -H "Client-Id: YOUR_CLIENT_ID" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "visibility": "ALL"
    },
    "limit": 100,
    "last_id": ""
  }'

# Response
{
  "result": {
    "items": [
      {
        "product_id": 223681945,
        "offer_id": "SKU-12345",
        "is_fbo_visible": true,
        "is_fbs_visible": true,
        "archived": false,
        "is_discounted": false
      }
    ],
    "total": 150,
    "last_id": "223681945"
  }
}
```

## Get Product Information

Retrieve detailed information about specific products by their IDs.

```bash
curl -X POST "https://api-seller.ozon.ru/v3/product/info/list" \
  -H "Client-Id: YOUR_CLIENT_ID" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": [223681945, 223681946],
    "sku": []
  }'

# Response
{
  "items": [
    {
      "id": 223681945,
      "name": "Wireless Bluetooth Headphones",
      "offer_id": "SKU-12345",
      "barcode": "4607086560000",
      "created_at": "2024-01-15T10:30:00Z",
      "images": ["https://cdn.ozon.ru/image1.jpg"],
      "visible": true,
      "price": "2999.00",
      "old_price": "3499.00",
      "stocks": {
        "present": 100,
        "reserved": 5
      }
    }
  ]
}
```

## Update Product Stocks

Update inventory quantities for products on specific warehouses (FBS/rFBS schemes).

```bash
curl -X POST "https://api-seller.ozon.ru/v2/products/stocks" \
  -H "Client-Id: YOUR_CLIENT_ID" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "stocks": [
      {
        "offer_id": "SKU-12345",
        "product_id": 223681945,
        "stock": 50,
        "warehouse_id": 12850503335000
      },
      {
        "offer_id": "SKU-12346",
        "product_id": 223681946,
        "stock": 25,
        "warehouse_id": 12850503335000
      }
    ]
  }'

# Response
{
  "result": [
    {
      "product_id": 223681945,
      "offer_id": "SKU-12345",
      "warehouse_id": 12850503335000,
      "updated": true,
      "errors": []
    }
  ]
}
```

## Update Product Prices

Update pricing information for products including regular price, discounted price, and minimum price.

```bash
curl -X POST "https://api-seller.ozon.ru/v1/product/import/prices" \
  -H "Client-Id: YOUR_CLIENT_ID" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prices": [
      {
        "product_id": 223681945,
        "price": "2499",
        "old_price": "2999",
        "min_price": "2199",
        "currency_code": "RUB"
      }
    ]
  }'

# Response
{
  "result": [
    {
      "product_id": 223681945,
      "offer_id": "SKU-12345",
      "updated": true,
      "errors": []
    }
  ]
}
```

## Get Warehouse List

Retrieve list of warehouses configured for your seller account.

```bash
curl -X POST "https://api-seller.ozon.ru/v1/warehouse/list" \
  -H "Client-Id: YOUR_CLIENT_ID" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{}"

# Response
{
  "result": [
    {
      "warehouse_id": 12850503335000,
      "name": "Main Warehouse",
      "is_rfbs": false,
      "has_entrusted_acceptance": true,
      "first_mile_type": "DropOff",
      "can_print_act_in_advance": true
    }
  ]
}
```

## Get FBS Unfulfilled Postings

Retrieve list of pending FBS orders that need to be processed and shipped.

```bash
curl -X POST "https://api-seller.ozon.ru/v3/posting/fbs/unfulfilled/list" \
  -H "Client-Id: YOUR_CLIENT_ID" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dir": "ASC",
    "filter": {
      "status": "awaiting_packaging"
    },
    "limit": 50,
    "offset": 0,
    "with": {
      "analytics_data": true,
      "financial_data": true
    }
  }'

# Response
{
  "result": {
    "postings": [
      {
        "posting_number": "24319409-0021-1",
        "order_id": 24319409,
        "order_number": "24319409-0021",
        "status": "awaiting_packaging",
        "in_process_at": "2024-01-20T08:30:00Z",
        "shipment_date": "2024-01-21T18:00:00Z",
        "products": [
          {
            "sku": 223681945,
            "name": "Wireless Bluetooth Headphones",
            "quantity": 1,
            "offer_id": "SKU-12345",
            "price": "2499.00"
          }
        ],
        "customer": {
          "name": "John Doe",
          "phone": "+7********90"
        }
      }
    ],
    "has_next": false
  }
}
```

## Get FBS Posting Details

Get detailed information about a specific FBS posting/order.

```bash
curl -X POST "https://api-seller.ozon.ru/v3/posting/fbs/get" \
  -H "Client-Id: YOUR_CLIENT_ID" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "posting_number": "24319409-0021-1",
    "with": {
      "analytics_data": true,
      "financial_data": true,
      "translit": true
    }
  }'

# Response
{
  "result": {
    "posting_number": "24319409-0021-1",
    "status": "awaiting_packaging",
    "substatus": "",
    "in_process_at": "2024-01-20T08:30:00Z",
    "shipment_date": "2024-01-21T18:00:00Z",
    "products": [...],
    "requirements": {
      "products_requiring_gtd": [],
      "products_requiring_country": [],
      "products_requiring_mandatory_mark": []
    },
    "analytics_data": {
      "region": "Moscow",
      "city": "Moscow",
      "delivery_type": "PVZ"
    }
  }
}
```

## Ship FBS Posting

Confirm order assembly and mark posting as ready for shipment.

```bash
curl -X POST "https://api-seller.ozon.ru/v4/posting/fbs/ship" \
  -H "Client-Id: YOUR_CLIENT_ID" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "posting_number": "24319409-0021-1",
    "packages": [
      {
        "products": [
          {
            "product_id": 223681945,
            "quantity": 1
          }
        ]
      }
    ],
    "with": {
      "additional_data": true
    }
  }'

# Response
{
  "result": [
    {
      "posting_number": "24319409-0021-1",
      "additional_data": []
    }
  ]
}
```

## Create Shipment Act

Create a shipment document after packing orders for delivery to Ozon.

```bash
curl -X POST "https://api-seller.ozon.ru/v2/posting/fbs/act/create" \
  -H "Client-Id: YOUR_CLIENT_ID" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "delivery_method_id": 12345678,
    "departure_date": "2024-01-22T10:00:00Z"
  }'

# Response
{
  "result": {
    "id": 987654321
  }
}
```

## Get Package Labels

Generate and download package labels for FBS postings.

```bash
curl -X POST "https://api-seller.ozon.ru/v2/posting/fbs/package-label" \
  -H "Client-Id: YOUR_CLIENT_ID" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "posting_number": ["24319409-0021-1", "24319409-0022-1"]
  }'

# Response: PDF binary content with package labels
```

## Cancel FBS Posting

Cancel an FBS posting with a specified reason.

```bash
curl -X POST "https://api-seller.ozon.ru/v2/posting/fbs/cancel" \
  -H "Client-Id: YOUR_CLIENT_ID" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "posting_number": "24319409-0021-1",
    "cancel_reason_id": 352,
    "cancel_reason_message": "Out of stock"
  }'

# Response
{
  "result": true
}
```

## Get FBO Postings

Retrieve FBO (Fulfillment by Ozon) postings with filtering options.

```bash
curl -X POST "https://api-seller.ozon.ru/v2/posting/fbo/list" \
  -H "Client-Id: YOUR_CLIENT_ID" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dir": "DESC",
    "filter": {
      "since": "2024-01-01T00:00:00Z",
      "to": "2024-01-31T23:59:59Z",
      "status": ""
    },
    "limit": 100,
    "offset": 0,
    "with": {
      "analytics_data": true,
      "financial_data": true
    }
  }'

# Response
{
  "result": {
    "postings": [
      {
        "posting_number": "0012345678-0001-1",
        "order_number": "0012345678-0001",
        "status": "delivered",
        "created_at": "2024-01-15T14:30:00Z",
        "products": [...],
        "analytics_data": {...}
      }
    ]
  }
}
```

## Get Available Promotions

Retrieve list of available promotional campaigns for your products.

```bash
curl -X POST "https://api-seller.ozon.ru/v1/actions" \
  -H "Client-Id: YOUR_CLIENT_ID" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{}"

# Response
{
  "result": [
    {
      "id": 12345,
      "title": "Winter Sale",
      "description": "Up to 50% off",
      "action_type": "SALE",
      "date_start": "2024-01-20T00:00:00Z",
      "date_end": "2024-02-10T23:59:59Z",
      "is_participating": false,
      "products_count": 0,
      "is_voucher_action": false
    }
  ]
}
```

## Add Products to Promotion

Activate products in a promotional campaign with specified promotional prices.

```bash
curl -X POST "https://api-seller.ozon.ru/v1/actions/products/activate" \
  -H "Client-Id: YOUR_CLIENT_ID" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action_id": 12345,
    "products": [
      {
        "product_id": 223681945,
        "action_price": "1999.00"
      }
    ]
  }'

# Response
{
  "result": {
    "products": [
      {
        "product_id": 223681945,
        "added": true
      }
    ]
  }
}
```

## Get Finance Transactions

Retrieve financial transaction details for accounting and reconciliation.

```bash
curl -X POST "https://api-seller.ozon.ru/v3/finance/transaction/list" \
  -H "Client-Id: YOUR_CLIENT_ID" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "date": {
        "from": "2024-01-01T00:00:00Z",
        "to": "2024-01-31T23:59:59Z"
      },
      "transaction_type": "all"
    },
    "page": 1,
    "page_size": 100
  }'

# Response
{
  "result": {
    "operations": [
      {
        "operation_id": 123456789,
        "operation_type": "OperationAgentDeliveredToCustomer",
        "operation_date": "2024-01-15T12:00:00Z",
        "posting_number": "24319409-0021-1",
        "amount": 2499.00,
        "items": [...]
      }
    ],
    "page_count": 5,
    "row_count": 487
  }
}
```

## Get Analytics Data

Retrieve analytics metrics for products and sales performance.

```bash
curl -X POST "https://api-seller.ozon.ru/v1/analytics/data" \
  -H "Client-Id: YOUR_CLIENT_ID" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "date_from": "2024-01-01",
    "date_to": "2024-01-31",
    "metrics": [
      "revenue",
      "ordered_units",
      "hits_view_pdp",
      "session_view_pdp"
    ],
    "dimension": [
      "sku"
    ],
    "filters": [],
    "sort": [
      {
        "key": "revenue",
        "order": "DESC"
      }
    ],
    "limit": 100,
    "offset": 0
  }'

# Response
{
  "result": {
    "data": [
      {
        "dimensions": [{"id": "223681945", "name": "SKU-12345"}],
        "metrics": [125000.00, 50, 1500, 1200]
      }
    ],
    "totals": [500000.00, 200, 6000, 4800]
  }
}
```

## Get Chat List

Retrieve list of customer chats for your seller account.

```bash
curl -X POST "https://api-seller.ozon.ru/v3/chat/list" \
  -H "Client-Id: YOUR_CLIENT_ID" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "chat_status": "All",
      "unread_only": false
    },
    "limit": 30,
    "offset": 0
  }'

# Response
{
  "chats": [
    {
      "chat_id": "b646d975-0c9c-4872-9f41-8b1e57181063",
      "chat_type": "Buyer_Seller",
      "created_at": "2024-01-15T10:30:00Z",
      "unread_count": 2,
      "last_message_id": "3000000000817031942"
    }
  ],
  "total_chats_count": 15,
  "total_unread_count": 5
}
```

## Send Chat Message

Send a message to a customer in an existing chat.

```bash
curl -X POST "https://api-seller.ozon.ru/v1/chat/send/message" \
  -H "Client-Id: YOUR_CLIENT_ID" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "b646d975-0c9c-4872-9f41-8b1e57181063",
    "text": "Hello! Thank you for your order. Your package will be shipped tomorrow."
  }'

# Response
{
  "result": {
    "message_id": "3000000000817031943",
    "created_at": "2024-01-20T14:25:00Z"
  }
}
```

## Get Returns List

Retrieve list of product returns with status information.

```bash
curl -X POST "https://api-seller.ozon.ru/v1/returns/list" \
  -H "Client-Id: YOUR_CLIENT_ID" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "status": "returned_to_ozon"
    },
    "limit": 50,
    "offset": 0
  }'

# Response
{
  "returns": [
    {
      "id": 98765432,
      "posting_number": "24319409-0021-1",
      "status": "returned_to_ozon",
      "return_reason": "Product defect",
      "created_at": "2024-01-18T16:00:00Z",
      "products": [...]
    }
  ]
}
```

## Get Seller Rating

Retrieve current seller performance ratings and metrics.

```bash
curl -X POST "https://api-seller.ozon.ru/v1/rating/summary" \
  -H "Client-Id: YOUR_CLIENT_ID" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{}"

# Response
{
  "groups": [
    {
      "group_name": "Delivery Quality",
      "items": [
        {
          "rating_name": "On-time delivery rate",
          "current_value": 98.5,
          "past_value": 97.2,
          "change": 1.3,
          "status": "OK"
        }
      ]
    }
  ]
}
```

## Summary

The Ozon Seller API provides comprehensive coverage for all marketplace operations. Primary use cases include automated product catalog management (creating, updating, and archiving products), real-time inventory synchronization across multiple warehouses, order fulfillment workflows for FBS and rFBS schemes, dynamic pricing and promotional campaign management, and financial reporting. Sellers typically integrate these endpoints into their ERP systems, inventory management software, or custom dashboards to maintain synchronization between their internal systems and the Ozon marketplace.

Integration patterns commonly involve periodic polling of order endpoints (unfulfilled postings) combined with webhook/push notifications for real-time updates, batch processing for bulk product and price updates, and event-driven workflows for order state transitions. The API enforces rate limits of 50 requests per second per Client ID, and individual endpoints may have additional restrictions (e.g., stock updates limited to once per 30 seconds per SKU). Sellers should implement proper error handling for common scenarios including rate limiting, validation errors, and transient failures, using exponential backoff for retries. OAuth tokens are supported for third-party application integrations through public or private applications registered in the Ozon developer portal.