Base URL

All endpoints are served over HTTPS from https://api.youbega.com. Paths in this documentation are relative to this address: GET /products means GET https://api.youbega.com/products.

API key

Every request must carry your API key in the X-Api-Key header. The key belongs to your seller account: you can only read and change the data of that account. A missing or wrong key returns 401 Unauthorized with an empty body.

GET /products HTTP/1.1
Host: api.youbega.com
X-Api-Key: <YOUR_API_KEY>

Content type per endpoint

Typical integration

1. Read the category tree with GET /products/categories and choose a category path for each of your products.
2. Read your shipping methods with GET /shippingMethods; create missing ones with POST /shippingMethods or on the website.
3. Read your locations with GET /locations or create them with POST /locations. Instead of locations you can send country codes.
4. Create products with POST /products and store the returned id with your own product record.
5. Keep prices and stock up to date with PUT /products. Read its rules first: some fields are reset when they are not sent.
6. Fetch new and changed orders with GET /orders and startDate.

Test your key

This request returns your first product and changes nothing:

curl -H "X-Api-Key: <YOUR_API_KEY>" "https://api.youbega.com/products?page=1&pageSize=1"

Values in angle brackets, such as <YOUR_API_KEY>, are placeholders for your own values. The curl examples break lines with \ (bash). In Windows call curl.exe and put the command on one line, or end the lines with ^ (cmd) or ` (PowerShell).

multipart/form-data

POST /products and PUT /products accept only multipart/form-data, because they carry files. Every field is a separate part of the form; a file is a part with a file name and a content type.

Field names

Field names are not case-sensitive (Name and name are the same field), but use the spelling of this documentation. Unknown names are ignored without an error, so a typo silently loses the value — Files instead of AdvertisementFiles ends with “At least one product photo is required”.

Values

Omitted fields, empty values and null

A form has no null. A field is sent with a value, sent empty (Name=) or not sent at all:

Arrays

Send array items with an index starting at 0 — Tags[0], Tags[1] — or repeat the same field name (Tags, Tags). Do not skip index numbers.

Not supported: one comma-separated value such as CategoriesIds=1,2,3 (returns 400 with an empty body) and empty brackets such as CategoriesIds[]=1 (the values are ignored).

Parameters (objects in an array)

A product parameter has the parts Name, Value and, on PUT, Id. Use dot notation with an index:

Parameters[0].Name=Color
Parameters[0].Value=Red
Parameters[1].Name=Material
Parameters[1].Value=Steel

Parameters[0][Name] and Parameters.Name are ignored without an error: the request succeeds, but the parameters are not saved.

Limits

• All files of one request together — photos, GPSR files, videos and posters — may total at most 19 MB (19,922,944 bytes); more returns 400 with a Files error. A request so large that it cannot be read at all returns 413 with an HTML body.
• Name: up to 255 characters. Every tag, parameter name and parameter value: up to 128 characters.
• CategoriesIds: 1 to 4 ids. GET /products: up to 100 products per page.

Where to get IDs

Values in angle brackets in the examples, such as <LOCATION_ID>, are placeholders. 00000000-0000-0000-0000-000000000000 is never a valid id.

Category path

Category ids are unique only within their level, so the same number can stand for different categories: 9 is real_estate at the top level and c_aircraft_and_flying_objects under category 1. That is why CategoriesIds holds the whole path, from the top-level category down to the chosen one:

CategoriesIds[0]=1     car_bike_boat_plane
CategoriesIds[1]=9     c_aircraft_and_flying_objects
CategoriesIds[2]=96    ca_balloon

The path can end on any level (1 to 4 ids); choose the most specific category. A path that does not exist in GET /products/categories returns a CategoriesIds validation error.

Enumerations

Requests accept the number or, where a name is listed, the name. Responses always contain the number.

Currencies

The most used currency ids, accepted in CurrencyId of products and in currencyId of shipping methods. Without CurrencyId a new product gets the currency of your account.

Status codes

400 response bodies

Validation errors (application/problem+json) — products, POST /shippingMethods and the paging of GET /products. errors lists every rejected field at once, named as in this documentation:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "Name": ["Name is required."],
    "BasePrice": ["BasePrice is required for a fixed price and a price range."],
    "CategoriesIds": ["CategoriesIds must hold 1 to 4 ids that form one path in GET /products/categories, starting with a top-level category."],
    "AdvertisementFiles": ["At least one product photo is required."]
  },
  "traceId": "00-5c16ab5119028926975b93863c4d2128-fb9ea7c01dc64bdc-00"
}

Empty body — a value could not be read: text in a number field, an empty number, boolean, GUID or enum, an unknown enum name, CategoriesIds=1,2,3, a multipart body without a boundary. Check the formats in Request format.

errorMessages list (application/json) — validation of POST /locations and rejected files:

{"errorCodes": ["NotEmptyValidator"], "errorMessages": ["City is required."]}

{"errorCodes": null, "errorMessages": ["UnsupportedContentTypeException | Content type image/jpg is not supported. Thumbnail cannot be generated."]}

Plain text “The request could not be processed.” — an unexpected error inside the API. Repeat the request later; if the error stays, contact support.

When you contact support, include the time of the request and, if present, the traceId.

Description

Returns the products of your account page by page: active, inactive and sold-out products. Deleted products are not included. The order is stable (by product id) but not chronological.

The response contains no photos, GPSR documents, product state or video.

Query parameters

To read all products, request page 1, 2, 3, … until a page holds fewer products than pageSize.

Example request

curl -H "X-Api-Key: <YOUR_API_KEY>" "https://api.youbega.com/products?page=1&pageSize=100"

Response

200 with a JSON array; an empty array when the page has no products.

[
  {
    "id": "0033b403-a763-48f9-b416-0a9695f60116",
    "name": "API docs test product - ignore",
    "description": "<p>Test product created while checking the API documentation.</p>",
    "quantity": 5,
    "basePrice": 19.99,
    "urlSlug": "api-docs-test-product-ignore-0033b403",
    "maxPrice": null,
    "currencyId": 2,
    "listingTypeId": 1,
    "priceTypeId": 2,
    "personalPickup": true,
    "itemCondition": 1,
    "categoriesIds": [3, 24],
    "countryCodes": ["PL"],
    "locationsIds": ["b6433351-6f44-4242-aa75-e9d5ba1f240b"],
    "shippingMethodsIds": ["58ced0c2-8da1-44f8-93e1-11c64f7230c2"],
    "tags": ["api-docs", "test"],
    "paymentCapabilities": [2],
    "manufacturerInfo": "Example Manufacturer Sp. z o.o., ul. Przykładowa 1, 00-001 Warszawa",
    "responsiblePersonInfo": "Example Importer GmbH, Musterstraße 1, 10115 Berlin",
    "parameters": [
      { "id": 695642, "name": "Color", "value": "Red" },
      { "id": 695643, "name": "Material", "value": "Steel" }
    ]
  }
]

Description

Creates a product for your account. The product is active immediately and visible to buyers.

Request body

multipart/form-data, see Request format. Required are Name, PriceTypeId, CategoriesIds, CountryCodes or LocationsIds, and at least one photo.

Example request

curl -X POST https://api.youbega.com/products \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -F "Name=Steel bathroom shelf" \
  --form-string "Description=<p>Wall shelf made of stainless steel, 60 cm.</p>" \
  -F "PriceTypeId=2" \
  -F "BasePrice=19.99" \
  -F "CurrencyId=2" \
  -F "Quantity=5" \
  -F "PersonalPickup=true" \
  -F "ItemCondition=New" \
  -F "CategoriesIds[0]=3" \
  -F "CategoriesIds[1]=24" \
  -F "CountryCodes[0]=PL" \
  -F "LocationsIds[0]=<LOCATION_ID>" \
  -F "ShippingMethodsIds[0]=<SHIPPING_METHOD_ID>" \
  -F "Tags[0]=bathroom" \
  -F "PaymentCapabilities[0]=BankTransfer" \
  -F "Parameters[0].Name=Color" \
  -F "Parameters[0].Value=Silver" \
  -F "Parameters[1].Name=Material" \
  -F "Parameters[1].Value=Steel" \
  -F "ManufacturerInfo=Example Manufacturer Sp. z o.o., ul. Przykładowa 1, 00-001 Warszawa" \
  -F "ResponsiblePersonInfo=Example Importer GmbH, Musterstraße 1, 10115 Berlin" \
  -F "AdvertisementFiles=@shelf-front.jpg;type=image/jpeg" \
  -F "AdvertisementFiles=@shelf-side.jpg;type=image/jpeg" \
  -F "GpsrFiles=@safety-information.pdf;type=application/pdf"

Replace the placeholders with your ids. The category path 3 › 24 (house_and_garden › h_bathroom) is only an example — take yours from GET /products/categories. The files are read from the current folder. The description is sent with --form-string, because -F reads a value that starts with < or @ from a file.

Postman

Import the ready-made collection youbega-public-api.postman_collection.json (Postman → Import), or set up the request by hand:

1. Choose the method and the URL https://api.youbega.com/products. In the collection, set the variable apiKey to your key once.
2. Headers: add only X-Api-Key. Do not add Content-Type — Postman sets it with the boundary when it sends the form.
3. Body → form-data: one row per field. Key = field name as in the table, for example CategoriesIds[0] or Parameters[0].Name; Value = the value.
4. For AdvertisementFiles, GpsrFiles, VideoFiles and VideoPosterFiles switch the row type from Text to File and select the file. Add one row per file with the same key.
5. Send. A new product returns 201 Created with its id.

Response

201 Created. Store the id: you need it for PUT /products. The Location header only repeats the id — there is no endpoint that returns a single product.

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Location: /products/0033b403-a763-48f9-b416-0a9695f60116

{"id": "0033b403-a763-48f9-b416-0a9695f60116"}

If the request is rejected, nothing is saved and uploaded files are discarded. See Errors & status codes.

Description

Updates one product of your account, identified by Id. This is not a partial update: some fields are reset when you do not send them, others keep their stored value. Returns 201 Created, like POST.

Safe pattern: read the product with GET /products, change what you need and send Quantity, PersonalPickup, the prices and CountryCodes on every PUT.

Request body

multipart/form-data — also when you send no file, see Request format. Field formats and limits are the same as for POST /products.

Examples

Update price and stock, keep everything else

curl -X PUT https://api.youbega.com/products \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -F "Id=<PRODUCT_ID>" \
  -F "Name=Steel bathroom shelf" \
  -F "PriceTypeId=2" \
  -F "BasePrice=17.49" \
  -F "Quantity=8" \
  -F "PersonalPickup=true" \
  -F "CountryCodes[0]=PL"

Description, category, locations, shipping methods, tags, parameters, GPSR data, photos and videos stay as they are.

Replace all photos

curl -X PUT https://api.youbega.com/products \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -F "Id=<PRODUCT_ID>" \
  -F "Name=Steel bathroom shelf" \
  -F "PriceTypeId=2" \
  -F "BasePrice=17.49" \
  -F "Quantity=8" \
  -F "PersonalPickup=true" \
  -F "CountryCodes[0]=PL" \
  -F "AdvertisementFiles=@shelf-new-front.jpg;type=image/jpeg" \
  -F "AdvertisementFiles=@shelf-front.jpg;type=image/jpeg" \
  -F "AdvertisementFiles=@shelf-side.jpg;type=image/jpeg"

The product then has exactly these three photos in this order; the first one is the main photo. Videos stay after the photos.

Change parameters

curl -X PUT https://api.youbega.com/products \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -F "Id=<PRODUCT_ID>" \
  -F "Name=Steel bathroom shelf" \
  -F "PriceTypeId=2" \
  -F "BasePrice=17.49" \
  -F "Quantity=8" \
  -F "PersonalPickup=true" \
  -F "CountryCodes[0]=PL" \
  -F "Parameters[0].Id=<PARAMETER_ID>" \
  -F "Parameters[0].Name=Color" \
  -F "Parameters[0].Value=Black" \
  -F "Parameters[1].Name=Width" \
  -F "Parameters[1].Value=60 cm"

<PARAMETER_ID> is parameters[].id from GET /products. Color is updated, Width is added, and every other stored parameter is deleted.

Response

201 Created with the product id, as for POST /products. If the request is rejected, the product stays unchanged.

{"id": "0033b403-a763-48f9-b416-0a9695f60116"}

Accepted files

The content type of the file part counts, not the file extension. image/jpg does not exist (use image/jpeg) and is rejected with 400. curl takes the type from the extension; to be sure, set it: -F "AdvertisementFiles=@photo.jpg;type=image/jpeg".

All files of one request — photos, GPSR files, videos and posters — may total at most 19 MB. There is no fixed maximum number of photos.

Creating a product

POST /products needs at least one photo. Photos keep the order in which they are sent; the first photo is the main photo. GPSR files and videos are optional; videos are shown after the photos.

Updating a product

• PUT /products without AdvertisementFiles: all photos stay as they are.
• With one or more AdvertisementFiles: the photos are replaced by exactly these files, in this order. Videos stay and follow the photos.
• To add a photo, send all photos you want to keep plus the new one. To remove a photo, send the other ones again. The API does not return photo URLs, so keep your original files. The gallery cannot be emptied.
• GpsrFiles follow the same rule: not sent — kept; sent — all GPSR documents replaced.
• If the request fails, nothing changes and the uploaded files are discarded.

Video

A product can have up to 2 uploaded videos and up to 2 YouTube videos. They are always shown after the photos, so the first photo stays the main photo.

• File (VideoFiles): MP4 with H.264 video, up to 8 MB each. HEVC (H.265) is rejected because not every browser plays it. iPhones record HEVC by default: set the camera format to “Most Compatible” or export the video as H.264.
• Send videos only in VideoFiles: a video in AdvertisementFiles is rejected.
• Poster (VideoPosterFiles): the image shown before the video starts — one per video, in the same order, JPG, PNG or WEBP of up to 25 megapixels. Images wider than 1280 px are reduced to 1280 px. Without a poster the first photo of the same request that is a readable image of up to 25 megapixels is used; if there is none, a dark grey image.
• YouTube (YoutubeVideoIds[i]): the 11-character id from the link, for example dQw4w9WgXcQ from https://www.youtube.com/watch?v=dQw4w9WgXcQ. A link is rejected; the same id sent twice counts once.
• PUT /products: without VideoFiles and YoutubeVideoIds all videos stay. With either of them, all videos — uploaded and YouTube — are replaced by those in the request; the photos stay. Videos cannot be removed completely through the API.

Add a video to an existing product

curl -X PUT https://api.youbega.com/products \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -F "Id=<PRODUCT_ID>" \
  -F "Name=Steel bathroom shelf" \
  -F "PriceTypeId=2" \
  -F "BasePrice=17.49" \
  -F "Quantity=8" \
  -F "PersonalPickup=true" \
  -F "CountryCodes[0]=PL" \
  -F "VideoFiles=@shelf-assembly.mp4;type=video/mp4" \
  -F "VideoPosterFiles=@shelf-assembly-poster.jpg;type=image/jpeg" \
  -F "YoutubeVideoIds[0]=dQw4w9WgXcQ"

The photos stay as they are; the product then has the uploaded video with its poster and the YouTube video after the photos. A PUT without video fields keeps both.

Description

Returns the whole category tree. Use it to build the CategoriesIds path of a product, see Category path.

Example request

curl -H "X-Api-Key: <YOUR_API_KEY>" https://api.youbega.com/products/categories

Response

200 with a JSON array of top-level categories (shortened):

[
  {
    "id": 1,
    "categoryCode": "car_bike_boat_plane",
    "subCategories": [
      {
        "id": 9,
        "categoryCode": "c_aircraft_and_flying_objects",
        "subCategories": [
          { "id": 96, "categoryCode": "ca_balloon", "subCategories": [] }
        ]
      }
    ]
  },
  {
    "id": 3,
    "categoryCode": "house_and_garden",
    "subCategories": [
      { "id": 24, "categoryCode": "h_bathroom", "subCategories": [] }
    ]
  }
]

Description

Returns the locations of your account, newest first. Locations deleted on the website are not included.

Example request

curl -H "X-Api-Key: <YOUR_API_KEY>" https://api.youbega.com/locations

Response

[
  {
    "id": "b6433351-6f44-4242-aa75-e9d5ba1f240b",
    "address": "Warszawa, PL",
    "countryCode": "PL"
  }
]

Description

Creates a location of your account from an address. The address is looked up on OpenStreetMap, and the location is saved with the place that was found. If your account already has a location for that place, its id is returned and no duplicate is created.

Request body

application/json. Field names are not case-sensitive.

The fields name, address and zip from earlier versions of this documentation do not exist.

Example request

curl -X POST https://api.youbega.com/locations \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"countryCode": "PL", "postalCode": "00-110", "city": "Warszawa", "streetName": "Plac Defilad", "streetNumber": "1"}'

Response

200. Only id is meaningful: address and countryCode are not filled in this response — read them with GET /locations.

{"id": "b6433351-6f44-4242-aa75-e9d5ba1f240b", "address": ", ", "countryCode": ""}

Description

Returns all shipping methods of your account, including those created on the website or by a shop or feed integration. Deleted methods are not included; the order is not defined.

Example request

curl -H "X-Api-Key: <YOUR_API_KEY>" https://api.youbega.com/shippingMethods

Response

[
  {
    "id": "58ced0c2-8da1-44f8-93e1-11c64f7230c2",
    "name": "Courier",
    "price": 12.500000000000000000,
    "description": "Delivery to the door in 1-2 working days",
    "countryCode": "PL",
    "currencyId": 2
  }
]

There are no fields cost or estimatedDeliveryDays; earlier versions of this documentation listed them by mistake. Delivery time and carrier settings are set only on the website and are not returned.

Description

Creates a shipping method of your account for one destination country; to ship to several countries, create one method per country. The method is active immediately and can be changed or deleted only on the website. Every call creates a new method, so check GET /shippingMethods first to avoid duplicates.

Request body

application/json. Field names are not case-sensitive.

The fields cost, estimatedDeliveryDays and isActive from earlier versions of this documentation do not exist and are ignored; a request that sends cost instead of price is rejected because price is missing.

Example request

curl -X POST https://api.youbega.com/shippingMethods \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Courier", "description": "Delivery to the door in 1-2 working days", "price": 12.5, "countryCode": "PL", "currencyId": 2}'

Response

200 with the id of the new method as a JSON string, not as an object:

"58ced0c2-8da1-44f8-93e1-11c64f7230c2"

A missing or invalid field returns 400 with a message per field, for example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "Price": ["Price is required. Send 0 for free shipping."],
    "CountryCode": ["Unknown country code UK. Use an ISO 3166-1 alpha-2 code, e.g. PL, DE or GB."]
  }
}

A body that is not valid JSON, or a value of the wrong type (for example text in price), returns 400 with an empty body.

Description

Returns the orders in which you are the seller, page by page, for synchronization with external systems (ERP, accounting, marketplaces). Each order includes the buyer's shipping and invoice addresses, the items and the total. Orders of all statuses are returned, including unpaid ones.

Query parameters

Example request

curl -H "X-Api-Key: <YOUR_API_KEY>" "https://api.youbega.com/orders?page=0&pageSize=20&startDate=2026-01-01T00:00:00Z"

Response

JSON object with the orders of the page and the total count.

{
  "orders": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "clusteredId": 12345,
      "displayId": "20260115-12345",
      "orderStatus": 3,
      "orderStatusName": "Payment Received",
      "modifiedOn": "2026-01-15T10:30:00+00:00",
      "summarizedPrice": 149.99,
      "currencyId": 1,
      "shippingAddress": {
        "firstName": "John",
        "lastName": "Doe",
        "companyName": null,
        "street": "Main Street",
        "streetNumber": "10",
        "houseNumber": "5",
        "city": "Warsaw",
        "district": null,
        "postalCode": "00-001",
        "province": "Mazowieckie",
        "countryCode": "PL",
        "phoneNumber": "+48123456789",
        "taxpayerNumber": null
      },
      "invoiceAddress": {
        "firstName": "John",
        "lastName": "Doe",
        "companyName": "Doe Ltd.",
        "street": "Main Street",
        "streetNumber": "10",
        "houseNumber": "5",
        "city": "Warsaw",
        "district": null,
        "postalCode": "00-001",
        "province": "Mazowieckie",
        "countryCode": "PL",
        "phoneNumber": "+48123456789",
        "taxpayerNumber": "PL1234567890"
      },
      "items": [
        {
          "productId": "0033b403-a763-48f9-b416-0a9695f60116",
          "name": "Steel bathroom shelf",
          "urlSlug": "steel-bathroom-shelf-0033b403",
          "quantity": 2,
          "pricePerPiece": 74.99,
          "currencyId": 1
        }
      ]
    }
  ],
  "pageNumber": 0,
  "pageSize": 1,
  "totalCount": 137
}

Order statuses

orderStatus is a numeric code; orderStatusName is its label (always in English).