Merchant API reference

Last updated: 4 November 2026

Get an API key

Sign in with a merchant account, open Settings → Integrations, select the API Keys tab, and create a key. Copy it immediately: the complete key is shown only once. You can revoke keys from the same page.

Base URL and authentication

https://a.ivo.md/v1/merchant-api

Send the key with every request using either header:

X-API-Key: <YOUR_API_KEY>
Authorization: Bearer <YOUR_API_KEY>

Always send Accept: application/json, and Content-Type: application/json except for file uploads. Without the Accept header, authentication failures are returned as an HTML error page instead of JSON.

Response envelope

Important: on a 200 response the top-level status field is always the literal string success — it says the call was accepted, nothing more. Endpoints that also have work in flight report it under a key of their own: sync_status on the sync endpoints, and import_status on the import endpoints.

A 202 response is an error envelope whose message says why the answer is not ready yet: queued, processing, or pending_approval.

Check the connection

GET /check

Validates the API key and returns the merchant identity. This is the endpoint to call first when wiring up an integration.

Input: none beyond the API key header.

{
  "merchant_id": "<MERCHANT_ID>",
  "merchant_name": "My Shop",
  "status": "success"
}

Merchant points

Every offer belongs to a merchant point (a shop, warehouse or pickup location). Use the point ID returned by these endpoints as merchant_point_id. If the account has exactly one point, product sync selects it automatically and you can omit the field.

GET /merchant-points

Returns all points belonging to the authenticated merchant.

{
  "points": [
    {
      "_id": "<POINT_ID>",
      "name": "Main store",
      "contact_person": "Ion Popescu",
      "email": "shop@example.com",
      "phone": "+37360000000",
      "street_id": "<STREET_ID>",
      "number": "12",
      "city_id": "<CITY_ID>",
      "state_id": "<STATE_ID>",
      "country": "MD",
      "zip_code": "MD-2001",
      "status": "approved",
      "is_active": true
    }
  ],
  "status": "success"
}

POST /merchant-points/store

Creates a point. It is always created with status: pending and is_active: true, and stays invisible to buyers until IVO approves it.

Any field outside this list is ignored. The response is {"point": { … }, "status": "success"}, where point is the created record including its new _id.

POST /merchant-points/update/{id}

Updates a point owned by the merchant. {id} is the point ID. Accepts every creation field plus is_active (boolean — set it to false to take the location's whole stock offline without deleting anything). Returns the updated point. Unknown ID: point_not_found (404).

POST /merchant-points/delete/{id}

Removes a point owned by the merchant. Returns {"deleted": true, "status": "success"}. The record is soft-deleted, so its history is kept, but the point can no longer be used for offers.

Update an existing offer

POST /product-offer/update

Updates price or stock on an offer that already exists, without running the product import. This is the cheapest and fastest endpoint — use it for regular price and stock refreshes.

{
  "merchant_internal_id": "PRODUCT-123",
  "merchant_point_id": "<POINT_ID>",
  "price": 1999,
  "currency": "MDL",
  "availability": 5,
  "availability_on_order": 0
}

At least one of availability, availability_on_order, price, currency or promotions must be present; sending only an identifier fails with no_fields_to_update. Fields you omit keep their current value. Every change is written to the offer's price/stock history.

{
  "offer": {
    "id": "<OFFER_ID>",
    "merchant_internal_id": "PRODUCT-123",
    "product_id": "<PRODUCT_ID>",
    "merchant_point_id": "<POINT_ID>",
    "condition": "new",
    "quality": null,
    "price": 1999,
    "currency": "MDL",
    "availability": 5,
    "availability_on_order": 0,
    "promotions": []
  },
  "promotion_errors": [],
  "status": "success"
}

Errors: missing_identifier (422) — neither offer_id nor merchant_internal_id was sent; no_fields_to_update (422); offer_not_found (404) — no such offer, or it belongs to another merchant; merchant_internal_id_not_unique (409) — the SKU matches several offers, and the body carries count. Send merchant_point_id to disambiguate.

Product and offer information

GET /product/{id}/info

Use the offer ID as {id}, not a product ID. The offer must belong to the authenticated merchant.

{
  "product": {
    "id": "<OFFER_PRODUCT_ID>",
    "root_product_id": "<ROOT_PRODUCT_ID>",
    "type": "variant",
    "status": "active",
    "name": {"ro": "Nume", "en": "Name", "ru": "Название"},
    "slug": {"ro": "nume", "en": "name", "ru": "nazvanie"},
    "url": "https://ivo.md/nume/p",
    "urls": {"ro": "https://ivo.md/nume/p", "en": "https://ivo.md/en/name/p", "ru": "https://ivo.md/ru/nazvanie/p"}
  },
  "offer": {
    "id": "<OFFER_ID>",
    "price": 1999,
    "currency": "MDL",
    "availability": 5,
    "availability_on_order": 0
  },
  "history": [
    {
      "price": 2099,
      "currency": "MDL",
      "availability": 3,
      "availability_on_order": 0,
      "changed_at": "2026-08-20T11:04:35+03:00",
      "source": "merchant_api"
    }
  ],
  "status": "success"
}

Errors: offer_not_found (404); product_not_accessible (403) — the offer belongs to another merchant; product_not_found (404); pending_approval (202) — the main product is not published yet, and the body carries product_id and product_status; product_slug_missing (422).

POST /product/info-by-sku

The same detailed answer, found by your own SKU instead of an IVO ID. Use it when you do not store IVO identifiers on your side.

{
  "import_name": "daily-sync",
  "merchant_internal_id": "PRODUCT-123"
}

On success the body is identical to GET /product/{id}/info. While the product is still travelling through the pipeline, the answer is an error envelope:

Create or synchronize one product

POST /product/sync

Creates a product or updates an existing offer. Reusing the same import_name with a stable merchant_internal_id updates the same row instead of creating duplicates, so this endpoint is safe to call repeatedly for the same catalogue.

{
  "mode": "async",
  "import_name": "daily-sync",
  "merchant_internal_id": "PRODUCT-123",
  "name": "Example Phone 256 GB Black",
  "price": 1999,
  "currency": "MDL",
  "availability": 5,
  "availability_on_order": 0,
  "merchant_point_id": "<POINT_ID>",
  "brand": "Example",
  "ean": "5940000000000",
  "description": "Product description",
  "packages": [
    {"weight": 1200, "dimensions": "30x20x10 cm"}
  ],
  "images": ["https://example.com/product.jpg"]
}

packages lists the boxes the product ships in, one entry per box, each with its own weight and size; IVO counts the boxes from the list. The example above is a product in one box. A bed that ships in three boxes has three entries:

{
  "import_name": "daily-sync",
  "merchant_internal_id": "BED-160",
  "name": "Example Bed 160x200 Oak",
  "price": 8999,
  "currency": "MDL",
  "availability": 2,
  "merchant_point_id": "<POINT_ID>",
  "packages": [
    {"weight": 25000, "dimensions": "200x90x12 cm"},
    {"weight": 25000, "dimensions": "200x90x12 cm"},
    {"weight": 12000, "dimensions": "120x20x10 cm"}
  ],
  "images": ["https://example.com/bed.jpg"]
}

The bed ships in 3 boxes (62 kg in total) under one tracking number; delivery is priced on the total weight and volume. The older weight and dimensions fields still work for a product in one box, but they are deprecated: send packages.

Any other field is stored with the row but is only understood if its name matches an import column.

Boxes. The weight and boxes you send take priority: whenever they change, they replace IVO's estimate or an administrator's correction. Whatever you don't send — the size, for example — is estimated automatically. Delivery is priced on the total weight and volume of the boxes.

Recommended retail price. The retail_price you send replaces IVO's estimate, which is then never requested for that product. Whenever it changes it also replaces an administrator's correction. A product sold by several merchants keeps the price of the first merchant who sent one.

Unit of sale. unit belongs to the product, not the offer: a product is sold in the same unit whoever sells it. Send the unit it is ordered in — the one the price buys — never the content unit: a pack of 2 chairs is PA, not EA. A sync without unit leaves the unit unchanged, and EA sets it back to a piece. A product sold by several merchants keeps the unit of the first merchant who sent one.

Responses

All three are HTTP 200 with "status": "success". Which fields are present tells you what happened.

Errors: invalid_product_id (422), product_not_found (404), offer_product_not_found (404), offer_product_invalid (422) — the variant does not belong to that main product, missing_offer_product_id (422), missing_merchant_point (422) — no point could be resolved on the product_id path, invalid_price (422), unauthorized_category (403) — your account is not authorized to sell in that category, integration_not_found / integration_disabled (403) — the import_name names an integration that was deleted or switched off, and processing_failed (422) in mode: sync with error and import_id.

Synchronize multiple products

POST /product/sync-multiple

Between 1 and 100 products per request. Each entry of products takes exactly the fields of /product/sync, plus the extras below. This is the endpoint to build a full catalogue sync on.

{
  "mode": "async",
  "import_name": "daily-sync",
  "image_base_url": "https://shop.example.com/images",
  "products": [
    {
      "merchant_internal_id": "PRODUCT-123",
      "name": "Example Phone 256 GB Black",
      "price": 1999,
      "availability_by_point": {
        "<POINT_ID_1>": 5,
        "<POINT_ID_2>": 2
      }
    }
  ]
}

Response: sync_status (completed when every product was already up to date, processing when rows were queued) and import_id, plus message when work was queued. Nothing is returned per product — read individual outcomes from /product-import/status or /product/info-by-sku. A payload that fails validation is rejected as a whole with validation_failed (422) plus the index of the offending product and its errors; also invalid_product_payload (422) and products_required (422).

Upload a product file

POST /product-import/upload-and-import

Sends a whole catalogue file in one request, exactly like uploading it in the merchant panel. Use multipart/form-data.

For recurring synchronization prefer /product/sync-multiple: it updates the same rows in place, reports per-product outcomes, and needs no file.

Check import status

GET /product-import/status

Reports the progress of any import you created — through /product/sync, /product/sync-multiple or /product-import/upload-and-import — and the outcome for one product in it.

GET /product-import/status?import_name=daily-sync&merchant_internal_id=PRODUCT-123
GET /product-import/status?import_id=<IMPORT_ID>

{
  "import_id": "<IMPORT_ID>",
  "import_name": "daily-sync",
  "import_status": "processing",
  "error_type": null,
  "processed_rows": 87,
  "total_rows": 120,
  "row_count": 120,
  "row": {
    "id": "<ROW_ID>",
    "row_number": 12,
    "status": "completed",
    "error": null,
    "merchant_internal_id": "PRODUCT-123",
    "ai_product_id": "<AI_PRODUCT_ID>",
    "offer_product_id": "<VARIANT_ID>",
    "product_id": "<PRODUCT_ID>",
    "offer_id": "<OFFER_ID>",
    "product": {
      "id": "<VARIANT_ID>",
      "root_product_id": "<ROOT_PRODUCT_ID>",
      "type": "variant",
      "root_type": "main",
      "status": "active",
      "name": {"ro": "Nume", "en": "Name", "ru": "Название"},
      "slug": {"ro": "nume", "en": "name", "ru": "nazvanie"},
      "url": "https://ivo.md/nume/p",
      "urls": {"ro": "https://ivo.md/nume/p"},
      "has_public_url": true
    },
    "started_at": "2026-08-26T09:12:00+03:00",
    "ended_at": "2026-08-26T09:12:41+03:00"
  },
  "status": "success"
}

Errors: missing_identifier (422) — neither import_id nor import_name was sent, import_not_found (404), import_row_not_found (404), merchant_internal_id_required (422).

Promotional prices (Black Friday, Cyber Monday)

During a promotion an offer can sell at a lower price of your choice, kept apart from its normal price. Each promotion has its own price, so the same product can have one price for Black Friday and another for Cyber Monday.

GET /promotions

Returns the promotions you can set prices for now: those scheduled and those running. Call it regularly to learn when a new promotion appears and which code to send its prices under. A promotion that is not in the list isn't taking prices at the moment.

Input: none beyond the API key header. name and merchant_info come in English; add ?language=ro or ?language=ru to get them in Romanian or Russian.

{
  "promotions": [
    {
      "code": "black-friday-2026",
      "name": "Black Friday",
      "starts_at": "2026-11-27T00:00:00+02:00",
      "ends_at": "2026-11-28T00:00:00+02:00",
      "state": "scheduled",
      "merchant_info": "Black Friday on IVO: Friday 27 November."
    }
  ],
  "status": "success"
}

The same promotions appear in your Merchant Dashboard. You can also set prices without the API: per product, on its offers page in the dashboard, or through the price and quantity columns in your feed's Field mapping step.

Send a promotional price

Add promotions to a POST /product-offer/update call. It can be sent on its own, without price or stock:

{
  "merchant_internal_id": "PRODUCT-123",
  "merchant_point_id": "<POINT_ID>",
  "promotions": [
    {"code": "black-friday-2026", "price": 1599, "quantity": 10},
    {"code": "cyber-monday-2026", "price": 1699}
  ]
}

The answer holds offer.promotions, the offer's prices for the promotions taking prices now, and promotion_errors, the items refused. A refused item does not fail the call: the answer stays HTTP 200 and the rest of the call is saved. A shortened answer:

{
  "offer": {
    "id": "<OFFER_ID>",
    "price": 1999,
    "promotions": [
      {
        "code": "black-friday-2026",
        "price": 1599,
        "currency": "MDL",
        "quantity": 10,
        "sold": 0
      }
    ]
  },
  "promotion_errors": [
    {"code": "cyber-monday-2026", "error": "promotion_closed"}
  ],
  "status": "success"
}

What happens to the prices

• The offer sells at the promotional price only during the promotion. Before and after it, it sells at its normal price.
• It also sells at the normal price once the quantity units have sold, or if the normal price is no longer above the promotional one.
• Updating price, stock or any other field never changes a promotional price. Only the promotions you name in promotions are touched.
• Once a promotion stops taking prices, those already set stay and sell during the promotion, but they can no longer be changed or removed.

With /product/sync and /product/sync-multiple

Both accept the same promotions field, but apply it only when the call finds an existing offer. A new product has no offer yet, so send its prices once the offer exists. A call that sends product_id ignores the field. These endpoints do not report refused items: to see the answer, use POST /product-offer/update.

When an offer becomes visible

A successful call is not the same as a live product. An offer appears on ivo.md only when all of the following hold:

• the merchant account is active;
• its merchant point is approved and is_active;
• the product has passed IVO's approval and has a public page;
• price is present and greater than zero;
• availability or availability_on_order is greater than zero.

If a synced product does not appear, check these five in order before opening a support request.

Common error codes

Row-level import errors appear in row.error rather than as an HTTP status: too_generic (the name does not identify a specific product), missing_name_value, missing_category, unauthorized_category, variant_not_found, duplicate, no_availability, and missing_merchant_point.

Promotional price errors appear in promotion_errors rather than as an HTTP status. See "Promotional prices" above.