News Buyers welcome from 1 December. Sellers, list your assets now.

Home · Ingestion API

Ingestion API

The ingestion API lets an accredited seller push listings and stocks from their ERP. It goes through the same chain as the file import: same checks, same defaults.

The OpenAPI description of the API, to import into Postman, Insomnia or a Swagger editor: openapi.json, openapi.yaml (OpenAPI 3.1.0)

Authentication

Each call carries the seller's token in the Authorization header. The token files everything it pushes under the seller company that created it.

Authorization: Bearer sqh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Tokens are created and revoked in My Space, Integration, by an administrator of the team.

Try without writing anything

Add dry_run=1 to a write call: the batch is checked as it would be, and the response returns the same report (creations, updates, detailed rejections), but nothing is written, no listing, no stock, no run in the log. Any token allows it: it is the trial token of your first integration.

Create a token in My Space, save the sample batch below as lot.json, then run:

export SQH_TOKEN="sqh_..."
curl -X POST "https://sqhubb.com/api/v1/ingestion/listings?dry_run=1" \
  -H "Authorization: Bearer $SQH_TOKEN" -H "Content-Type: application/json" \
  --data @lot.json

Rules

  • 60 calls per minute and per token; beyond that, a 429 response with the Retry-After header.
  • At most 500 items per call.
  • The seller reference is mandatory. A reference you already use updates its listing: replaying a call never creates a duplicate.
  • A listing created through the API starts as a draft and goes through the marketplace moderation before publication. Only the fields sent are changed.

POST https://sqhubb.com/api/v1/ingestion/listings

Creates or updates listings, in batches.

A sample batch (lot.json): a complete listing, then a price and stock update of a reference already known.

{
  "listings": [
    {
      "reference": "SKU-001",
      "title": "Réducteur SEW R97",
      "price": 1850,
      "currency": "EUR",
      "quantity": 3,
      "condition": "new_unused",
      "incoterm": "EXW",
      "brand": "SEW",
      "model": "R97",
      "origin_country": "DE",
      "pickup_country": "FR",
      "unit_weight_kg": 120,
      "certifications": [
        "CE"
      ],
      "price_tiers": [
        {
          "min_quantity": 2,
          "unit_price": 1750
        }
      ],
      "images": [
        "https://images.example.com/sku-001-face.jpg"
      ],
      "specifications": {
        "puissance": "7,5 kW",
        "hs_code": "8483.40"
      }
    },
    {
      "reference": "SKU-002",
      "price": 940,
      "quantity": 0
    }
  ]
}
curl -X POST "https://sqhubb.com/api/v1/ingestion/listings" \
  -H "Authorization: Bearer $SQH_TOKEN" -H "Content-Type: application/json" \
  --data @lot.json

When the marketplace has opened Janus on import, add janus=1: the items become a received Janus import (taxonomy matching, enrichment), which you launch from My Space after seeing its cost.

POST https://sqhubb.com/api/v1/ingestion/listings?janus=1

Item fields

FieldTypeDescription
reference * string Your reference, mandatory and unique on your side.
title string The listing title, mandatory on creation.
description string The description, in French.
summary string A one-line summary.
category string The family: its name or identifier (slug).
condition string The condition of the item (values below).
price number The unit price excluding tax.
reference_price number The reference price (new or market), higher than the price.
currency string The currency, EUR by default.
quantity integer The available quantity.
sale_unit string The sale unit (unit, lot, tonne, kilogram, pallet...).
lot_size integer The lot size.
minimum_order_quantity integer The minimum order quantity.
packaging string The packaging (pallet, wooden_crate, big_bag...).
incoterm string The Incoterm 2020 (values below).
pickup_country string The pickup country, two-letter ISO code.
pickup_region string The pickup region.
pickup_city string The pickup city.
pickup_postal_code string The pickup postal code.
origin_country string The country of origin, two-letter ISO code.
brand string The brand.
model string The model or manufacturer reference.
year_of_manufacture integer The year of manufacture.
unit_weight_kg number The unit weight in kilograms.
length_cm integer The length in centimetres.
width_cm integer The width in centimetres.
height_cm integer The height in centimetres.
seo_title string The title for search engines.
seo_description string The description for search engines.
certifications array The list of certifications and labels, for example ["CE", "ISO 9001"].
price_tiers array Volume price tiers excl. VAT, for example [{"min_quantity": 10, "unit_price": 95}]. A tier at or above the base price is discarded.
images array The web addresses of the photos (JPEG, PNG or WebP, 10 MB at most), five at most. The first one becomes the main photo. They are downloaded after the listing is saved.
specifications object The family specifications, as a key and value object.

Conditions: new_unused, new_surplus, workshop_checked, audited, good_condition, dismantled_tagged, for_parts. Incoterms: EXW, FCA, FAS, FOB, CFR, CIF, CPT, CIP, DAP, DPU, DDP.

POST https://sqhubb.com/api/v1/ingestion/stocks

Updates the available quantity, and the price when provided, by reference. An unknown reference is rejected, never created.

curl -X POST "https://sqhubb.com/api/v1/ingestion/stocks" \
  -H "Authorization: Bearer $SQH_TOKEN" -H "Content-Type: application/json" \
  -d '{"stocks":[{"reference":"SKU-001","quantity":2},{"reference":"SKU-002","quantity":5,"price":900}]}'

GET https://sqhubb.com/api/v1/ingestion/listings/:reference

Reads a listing by its reference: status, price, stock, translations.

curl "https://sqhubb.com/api/v1/ingestion/listings/SKU-001" -H "Authorization: Bearer $SQH_TOKEN"

GET https://sqhubb.com/api/v1/ingestion/runs

The last twenty runs, through the API and through the daily synchronisation.

Response

{"run": {"id": 42, "channel": "api", "kind": "listings", "status": "partial",
         "received": 2, "created": 1, "updated": 0, "rejected": 1,
         "rejections": [{"reference": "SKU-002", "reasons": ["…"]}]}}

In dry run mode, the response also carries "dry_run": true, and the run has no identifier: it is not recorded.

  • ok : everything went through.
  • partial : part went through, the rejections are detailed.
  • failed : nothing went through.
  • unchanged : the daily feed has not changed, nothing is replayed.
  • janus_received : the Janus import is received, to launch from My Space.

Errors

HTTPerrorDescription
400invalid_jsonThe body is not readable JSON.
401unauthorizedToken missing, invalid or revoked.
403suspendedThe seller is suspended on the marketplace: its token no longer publishes until reinstatement.
403closedThe API is not open on this marketplace.
404not_foundNo listing of this seller has this reference.
422invalid_payloadInvalid body: no list, empty list, too many items, or janus and dry_run together.
429rate_limitedToo many calls: retry after the delay given by the Retry-After header.
503rate_limiter_unavailableRate limiting is temporarily unavailable: retry after the given delay.

Daily synchronisation

Instead of calling the API, you can declare in My Space the HTTPS address of a CSV or XLSX feed, with the columns of the import template. The marketplace reads it every night, does not replay an unchanged file, and logs every run.