Products

A product is a record in your organization's catalog that describes something you sell: its name, NUPCO code, catalogue number, registration details, packing and prices. What you save here is read by the rest of the platform: the product matches new tenders, fills the NUPCO files and quotations, and supplies the VAT rate on each line. A product also has links to manufacturers and to NUPCO codes, and those have their own tools below. This is the same catalog the Products guide describes.

A product has one cost price and one sale price, each stated per one level. price_basis says whether they are per unit (unit), per pack (pack), per case (case) or per one unit of what a unit holds (content, such as a price per test). From that one price, pricing from the catalog and pricing by margin work out each tender line's price in the line's own unit: 150 SAR per carton of 1,000 gloves becomes 15 per box of 100 and 0.15 per glove. With no level stated, the price is used as it is on every line, as it was before these fields. So send price_basis with every price, and never divide a price yourself.

Reading the catalog

Three tools read the catalog: a searchable list, one product with all its details, and a full export.

products_list

Lists the products in your organization's catalog, newest first, each with links to its photos. It searches with plain words or with the catalog's field syntax, can limit the results to one manufacturer, and adds each product's linked manufacturers when you ask. Products in the trash are not listed.

Read-only · scope products.read · all roles · Pro and Enterprise plans

{
  "q": "manufacturer:acme -gauze",
  "include_manufacturers": true,
  "page_size": 50
}

Returns: A page of products in data, with total, page, page_size and total_pages. Each product carries its record fields and photo_urls, the links to its photos.

• With group_by the reply has groups instead of data. Each group has nupco_code (null for the products with no code), product_count, offset and products, and each product in it carries nupco_codes, all its codes. The reply adds total (the products matched), total_codes, products_without_code and total_rows. Pages count rows, not groups, so a group can continue on the next page, where its offset is above zero.
• Photo links are temporary, so fetch them when you need them and do not store them.
• Results are filtered by role: price fields do not come back to a role that may not see them (see the introduction).

products_get

Returns one product with all its fields, its photo links and a list of its attachments. Use it when you need the details of a product whose ID you got from the list.

Read-only · scope products.read · all roles · Pro and Enterprise plans

Returns: The product record, with photo_urls and attachments. Each attachment has category (one of sfda_cert, catalog or other), name, size, uploaded_at and url.

• The tool answers 404 when the product does not exist or is in the trash. To find a product in the trash, use `products_trash_list`.
• Photo and attachment links are temporary, so fetch them when you need them and do not store them.

products_similar

Lists the other products in your catalog that carry one of this product's NUPCO codes, its primary code or a linked one. It is the card on the product page, and the same products the grouped list shows under the code.

Read-only · scope products.read · all roles · Pro and Enterprise plans

{
  "id": 42
}

Returns: codes, the product's own codes with the primary first, and products, most shared codes first. Each product carries its record fields, shared_codes, nupco_codes, photo_urls and manufacturers.

• Codes are compared after trimming and normalizing their spelling, so a code as Excel mangles it matches the original.
• Results are filtered by role: price fields do not come back to a role that may not see them (see the introduction).

catalog_files_list

Searches your organization's document library in one list: product photos and attachments (SFDA certificate, catalog, other), manufacturer attachments (catalog, SFDA AR license, ISO certificate, authorization letter) and the documents filed on sales orders (the customer's purchase order). It is the Document library page of the app.

Read-only · scope products.read · all roles · Pro and Enterprise plans

{
  "q": "syringe cert",
  "scope": "products",
  "page_size": 20
}

Returns: A page of files in data, with total, page, page_size and total_pages. Each file has owner_kind (product, manufacturer or sales_order), owner_id, owner_name, nupco_code, catalogue_number (a sales order's customer PO number), customer_name, manufacturer_names, category, name, size, mime_type, uploaded_at and url.

• Manufacturer files appear only when the key also has the manufacturers.read scope, and sales order documents only when it has orders.read and its owner's role may open sales order documents (every role but Technical and Purchasing). Open what a file belongs to with `products_get`, manufacturers_get or `sales_orders_get`.
• Links are temporary and expire after an hour, so fetch them when you need them and do not store them.

products_export_csv

Exports your organization's whole catalog, every row rather than one page, as CSV text that Claude can read in the reply itself. Owner and admin only.

Read-only · scope export · roles: owner, admin · Pro and Enterprise plans

No parameters.

Returns: CSV text in UTF-8 with a byte order mark at the start: a header row, then one row per product. It is text in the reply, not a file.

• The headers are in English and match the labels that `sheet_import` reads, so the file can be edited and imported back.
• A price that was never entered is an empty cell, not a zero. A semicolon (;) separates manufacturers, and separates keywords, within one cell.
• Photo links are not exported because they expire.

products_import_template

Downloads the Excel template for importing products: a Products sheet with the import's main columns, and an instructions sheet that explains each column with an example and lists every further column the import accepts. Hand it to the catalog's owner to fill in.

Read-only · scope products.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

{
  "locale": "ar"
}

Returns: The xlsx file encoded in base64, with its name, type and size.

• The template's headers are the import's own, so a filled copy given to `sheet_import` with the products target is mapped from its headers with no detection step. It holds no example row, since an example left on the sheet would be imported as a product.
• Pricing columns the key owner's role may not see are left out of the template.

Creating and changing products

Creating and changing work one product at a time or in batches. The single-product tools accept every field; the batch tools accept a smaller set.

products_create

Adds a product to your organization's catalog. The name is the only required field, and the rest can be filled in later. A nupco_product_code is also added to the product's NUPCO code links. The tool answers with a 402 when your organization has reached its plan's product limit.

Changes data · scope products.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

{
  "product_name": "Disposable syringe 5 ml, Luer lock",
  "nupco_product_code": "4111610529900",
  "catalogue_number": "SYR-5-LL",
  "keywords": [
    "syringe",
    "luer lock"
  ],
  "unit_of_measure": "Piece",
  "package_type": "Box",
  "package_size": 100,
  "units_per_case": 1000,
  "country_of_origin_code": "DE",
  "is_medical": true,
  "vat_percent": 0,
  "price_basis": "pack",
  "cost_price": 12,
  "cost_currency": "USD",
  "sale_price_sar": 55
}

Returns: The new product in a 201 reply, with all its fields, its new id and an empty photo_urls.

• When the limit is reached, the 402 reply carries error: plan_limit_reached, limit and current.
• Fields your role cannot see are ignored on write, so sales does not save cost_price or cost_currency.
• Marking a product medical with this tool does not change vat_percent. Set it yourself: 0 for medical products that qualify for zero-rating.
• Send price_basis with the prices, and the level's count with it: price_basis: "case" with units_per_case. A level missing its count is refused with a 400 (price_basis_level_missing) that names the field, and content_quantity without content_unit with a 400 (content_incomplete).
• To import a list from an Excel or CSV file, use `sheet_import` with the products target.

products_update

Changes fields of a product; only what you send changes. Send null to clear a field that can be empty. A new NUPCO code is added to the product's links, and the old links stay until you remove them with `product_nupco_unlink`.

Changes data · scope products.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

{
  "id": 1207,
  "price_basis": "pack",
  "reprice": "convert",
  "package_size": 100
}

Returns: The product after the change, with photo_urls.

• The tool answers 404 when the product does not exist or is in the trash.
• A call that carries no field your role may write is refused with a 400 (No fields to update).
• Sending a new nupco_product_code adds a link and does not remove the old one, and sending null clears the field and leaves the links as they are.
• Marking a product medical here does not change vat_percent: set it yourself.
• Stating price_basis on a product that had none does not change the numbers: it only says what they meant. A price you send is taken for the level as the same call leaves it. A role that cannot see the cost price (sales) cannot change price_basis or send reprice: the server ignores them from it.
• The tool refuses with a 400 and writes nothing, and the message names the field and the path that works: price_basis_level_missing when the stated level's count is empty (set package_size, units_per_case or content_quantity in the same call, or choose another level), content_incomplete when one of content_quantity and content_unit comes without the other, reprice_required when a stated level changes or is cleared on a product with a saved price you do not resend (send reprice or the new prices), and converted_price_out_of_range when a converted price would pass 9,999,999.99 (send the prices yourself or reprice: "keep").

products_bulk_create

Creates up to 500 products in one call. The product rows are saved together: if any check fails, such as an unknown manufacturer or the plan limit, nothing is created. You can link every new product to one manufacturer, or name manufacturers per row: names are matched to your own manufacturers ignoring case, and a name you do not have yet is created.

Changes data · scope products.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

{
  "products": [
    {
      "product_name": "Disposable syringe 5 ml, Luer lock",
      "nupco_product_code": "4111610529900",
      "catalogue_number": "SYR-5-LL",
      "cost_price": 0.12,
      "cost_currency": "USD",
      "sale_price_sar": 0.55,
      "is_medical": true
    },
    {
      "product_name": "Surgical gloves, sterile, size 7.5",
      "catalogue_number": "GLV-S-75",
      "manufacturer_names": [
        "Acme Medical Supplies"
      ]
    }
  ],
  "manufacturer_id": 88
}

Returns: A 201 reply with created (for each product its index in your list, id, product_name and nupco_product_code), created_count, and manufacturers_created, the names of manufacturers the call added to your directory. manufacturer_links_failed: true appears only when linking failed.

• The products are saved first and the manufacturer links applied afterwards. If linking fails, the products stay and manufacturer_links_failed appears. Link them with `product_manufacturer_bulk_link` and do not repeat the call, which would create the products twice.
• A batch that would pass your plan's product limit is refused whole with a 402, and an unknown manufacturer_id is refused with a 400 (manufacturer_not_found).
• A row carries every field of the product form. Only keywords and the agency filter are set afterwards with `products_update`.
• The server ignores the cost fields for the sales role.
• A row stating price_basis without its count, or sending half of content_quantity and content_unit, refuses the whole batch with a 400 before anything is written, and rows names each refused row by its index, the field and the fix.

products_bulk_update

Changes up to 200 products in one call, all or nothing, the way the catalog grid saves. Every row must carry the grid's columns: the name, catalogue number, NUPCO code, cost, cost currency and sale price. An ID that does not match a live product of your organization rejects the whole batch.

Changes data · scope products.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

{
  "updates": [
    {
      "id": 1207,
      "product_name": "Disposable syringe 5 ml, Luer lock",
      "catalogue_number": "SYR-5-LL",
      "nupco_product_code": "4111610529900",
      "cost_price": 0.12,
      "cost_currency": "USD",
      "sale_price_sar": 0.6,
      "units_per_case": 1000,
      "is_medical": true
    }
  ]
}

Returns: The number of products changed, in updated.

• Each row replaces the fields it sends, and null clears one. units_per_case and is_medical keep their stored values when you leave them out. To change one field and nothing else, use `products_update`.
• A field your role cannot see keeps its stored value whatever you send, so a sales call leaves each product's cost and currency as they are.
• An unknown ID, or one in the trash, rejects the whole batch with a 400 (product_not_found).
• A new NUPCO code is added to the product's links, and the old links stay.
• The prices here are per each product's price_basis, which this tool does not change (change it with `products_update` and reprice). A row emptying a count its stated level needs, such as clearing units_per_case on a product priced per case, refuses the whole batch with a 400 (price_basis_level_missing) and rows naming each product.

The trash

Deleting takes two steps: a move to the trash, then a permanent delete. A product in the trash can be restored until it is permanently deleted.

products_delete

Moves a product to the trash. It leaves the lists, links and alerts and frees its slot in your plan, but nothing is erased, and `products_restore` brings it back.

Deletes or overwrites data · scope products.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

Returns: { "success": true }.

• The tool answers 404 when the product does not exist or is already in the trash.

products_trash_list

Lists the products in the trash, most recently deleted first. Use it to find the ID of a product you want to restore or delete permanently.

Read-only · scope products.read · all roles · Pro and Enterprise plans

Returns: A page of products in data, with total, page, page_size and total_pages, in the same shape as `products_list`.

• Price fields are left out according to your role, as in the list.

products_restore

Moves a product from the trash back into the catalog. It counts against your plan's product limit again, so the tool answers with a 402 if the limit is reached.

Changes data · scope products.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

Returns: The restored product, with photo_urls.

• The tool answers 404 when the product is not in the trash.

products_purge

Permanently deletes one product from the trash, or everything in it, along with the photos and files. This cannot be undone. A product that was chosen for a tender item is never deleted, because the tender's history needs it.

Deletes or overwrites data · scope products.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

{
  "all": true
}

Returns: success and removed, the number deleted, plus blocked_ids when a product was kept because tender items use it. removed is 0 when nothing in the trash matched.

• The tool answers 409 (referenced_by_tender_items, with blocked_ids) only when every target is blocked. If only some are blocked, the rest are deleted and the reply succeeds with blocked_ids, so always check it.
• To free a blocked product, clear its selection on the tender items with `tender_item_product_selection_clear` and try again.
• An ID that is not in the trash is no error and deletes nothing. A call with neither id nor all is refused with a 400.

Manufacturer links

A product can have one or more manufacturers from those registered in your organization. The manufacturers themselves are created and edited with the manufacturer tools.

product_manufacturer_link

Links a product to one of your organization's manufacturers. Linking a pair that is already linked changes nothing, and keeps whether that manufacturer is the product's default.

Changes data · scope products.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

Returns: The link: id, product_id, manufacturer_id, is_default and created_at.

• A product that does not exist or is in the trash (product_not_found) and a manufacturer that is not in your organization (manufacturer_not_found) are refused with a 400.

product_manufacturer_unlink

Removes the link between a product and a manufacturer. Both records stay. If the manufacturer was the product's default, the product is left without a default.

Deletes or overwrites data · scope products.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

Returns: { "success": true }.

• Unlinking a pair that is not linked is no error and changes nothing.

product_manufacturer_bulk_link

Links up to 500 existing products to one manufacturer in a single call. Pairs that are already linked are left as they are.

Changes data · scope products.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

{
  "manufacturer_id": 88,
  "product_ids": [
    1207,
    1208,
    1215
  ]
}

Returns: { "linked": n }, the number of distinct products in the call, including any that were already linked.

• A product ID that does not exist or is in the trash rejects the whole batch with a 400 (product_not_found), and an unknown manufacturer gives manufacturer_not_found.

product_manufacturer_set_default

Chooses which of a product's linked manufacturers is its default, or clears the choice. A product has at most one default, and choosing a new one replaces the old. Generated documents and quotation lines pick a manufacturer in this order: the one set on the line, then the default, then the only linked manufacturer.

Changes data · scope products.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

{
  "product_id": 1207,
  "manufacturer_id": 88
}

Returns: The link after the change: id, product_id, manufacturer_id, is_default and created_at.

NUPCO codes

NUPCO codes are what tie a product to tender items. A product has a primary code in its nupco_product_code field and can be linked to further codes.

product_nupco_link

Links a product to a NUPCO material code. A product can carry several codes, and the linked codes are what match tender items to the product, drive its alerts and gather its price history. Linking the same pair again changes nothing.

Changes data · scope products.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

Returns: The link: id, product_id, nupco_code, is_default and created_at.

• The nupco_product_code field links itself when the product is saved, so there is no need to link the primary code with this tool.
• A product that does not exist or is in the trash is refused with a 400 (product_not_found). The same code may be linked to several products.

product_nupco_unlink

Removes one link between a product and a NUPCO code. It removes the link only: the product's own nupco_product_code field stays as it is, and the product still matches by that code if it is the primary one.

Deletes or overwrites data · scope products.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

Returns: { "success": true }.

• To stop matching by the primary code, clear it from the field with `products_update` (nupco_product_code: null) and then unlink it here.
• The code is matched exactly after trimming, and unlinking a pair that is not linked is no error.

Price history and tender alerts

Three read tools: the prices suppliers have quoted your organization, what NUPCO tenders were awarded at, and the open tenders that match your catalog. All three belong to the Pro and Enterprise plans.

products_sourcing_history

Lists every supplier price your organization has recorded for this product across all tenders and standalone RFQs, newest first. A price counts for the product when it was entered on the product itself, on a tender item you chose this product for, or on an item carrying one of the product's linked NUPCO codes.

Read-only · scope products.read · roles: owner, admin, purchasing, viewer · Pro and Enterprise plans

Returns: { "quotes": [...] }. Each entry has unitPriceUsd, unitPriceSar, quotedUnitPrice in the supplier's currency, fxRate, vendorName, leadTimeDays, submittedAt and tenderLabel, plus matchBasis, which is product or code and says how the price was tied to the product.

• At most 50 entries come back, and lines with no price are left out.
• These are cost-side prices, so the sales role cannot reach them. The tool answers 404 when the product does not exist or is in the trash.

products_historical_prices

Lists the published NUPCO award results for this product: every award row whose material code matches the product's own code or one of its linked codes, from all vendors. Rows your organization won are flagged with awarded_to_us.

Read-only · scope products.read · roles: owner, admin, sales, purchasing, viewer · Pro and Enterprise plans

Returns: { "prices": [...], "prices_hidden": null }. Each row has unit_price, currency, uom, vendor_name, manufacturer, country, catalog_no, source_tender_number, award_date, awarded_to_us and price_hidden, plus price_hidden_reason on a row hidden until the subscription is paid. prices_hidden is unpaid when prices are hidden for that reason.

• Rows run from the newest award period to the oldest, cheapest first within a period. At most 50 rows come back.
• unit_price is null when the award announcement named the winner but published no price. null means not published, never zero, and those rows come after the priced ones.
• Until your organization's first subscription payment clears, rows may come back without prices: a row hidden for that reason has unit_price null, price_hidden set to true and price_hidden_reason set to unpaid, and rows within a period are ordered by vendor. The price exists and is hidden; it is not an unpublished one.
• A row with price_hidden set to true and no price_hidden_reason has a price your organization does not see, ranked with the rows that have no price. The price exists and is hidden; it is not an unpublished one.
• Each read counts against your organization's per-minute budget for searches of tenders and price history, shared by every key, connector and the web app. When it runs out the tool answers 429 rate_limited with the seconds to wait.
• A product with no NUPCO code returns an empty list, and the tool answers 404 when the product does not exist.

products_alerts_list

Lists the open tenders that match your catalog, grouped by tender with the products that matched it. No tool creates a product alert: a product starts matching when it has a search query (search_query on products_update) or a linked NUPCO code (product_nupco_link), and its matches then appear here and in notifications.

Read-only · scope products.read · all roles · Pro and Enterprise plans

No parameters.

Returns: tenders: a list of { tender, products }, the nearest deadline first and at most 200 tenders. Each entry in products has product (id and product_name) and via_item, which is true when the match came through an item of the tender rather than its own text. products_total is the number of products in your catalog.

• A product matches tenders through its query or its linked NUPCO codes, never by its name or its keywords. agency_filter narrows the matches by text in the agency's name.
• The list is prepared ahead and refreshed after each tender scrape, and a change to a product shows in the next call.

The compliance letter

One letter, generated on request and never stored.

product_compliance_letter_pdf

Generates a PDF of the compliance letter that stands in for the product's MDMA certificate in a tender submission, printed on your organization's letterhead with its stamp. Nothing is stored: each call renders a new letter. When you leave out letter_type the tool chooses: under_registration when the MDMA status is under registration or the product is medical, otherwise non_medical_attestation.

Read-only · scope products.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

{
  "id": 1207,
  "letter_type": "under_registration",
  "notes": "The MDMA application was filed in March 2026."
}

Returns: A PDF file with filename, content_type, size_bytes and base64, as described in Files and background jobs.

• The under_registration letter has two pages, English then Arabic, and cites the MDMA number as the registration reference when the product has one. The non_medical_attestation letter is one English page attesting regulatory compliance outside the medical device regime.
• The letter prints your organization's English name, logo, stamp and registration details from the organization settings. The tool needs the products.write scope and a role that edits products, although it changes nothing.
• It works for a product in the trash too, and answers 404 when the product does not exist. A file over 4 MB is not returned in the reply.