Connect your shop with our API.

Send listing batches for a provider you have access to. Asynchronous batches, the recommended way, are admitted at once and processed for you; synchronous batches return completed write results.

Manage access tokensOpen API documentation(opens in a new tab)
Typical flowTwo modes
  1. 01Send up to 100 entriesPOST · PATCH · PUT · DELETE
  2. 02
    AsynchronousRecommendedAdmitted for processingHTTP 202
    SynchronousWrites completedHTTP 200
  3. 03
    AsynchronousNothing to poll; we take it from hereno follow-up needed
    SynchronousRetry failed entries only[] = all written

I — How batches work

Two ways to send a batch.

Both modes take the same listing batches for the same provider: up to 100 entries, POST to create, PATCH to update, PUT to upsert and DELETE to withdraw. They differ in what the response confirms; asynchronous is the recommended default.

AsynchronousRecommendedHTTP 202
Send the batch and move on: admitted entries are processed for you, with nothing to poll or confirm.
SynchronousHTTP 200
Choose it when your system needs each entry's write result before it continues.

AsynchronousRecommended

HTTP 202 · Admitted

Admitted now, processed for you.

Endpoint · POST · PATCH · PUT · DELETE/v1/listing-sources/{listingSourceId}/product-listings/async
The response
HTTP 202 returns an admission report: submissionId, acceptedCount and one failure for each entry not confirmed admitted.
When entries fail
Admitted entries go ahead. Listing existence, auctions and provider authority are checked during processing, not in the response. With nothing admitted, 400, 413, 500 or 503 returns the same report.
Retry
After a lost or uncertain response, resend the unchanged batch with the same Idempotency-Key. Fix invalid entries in a new batch with a new key.
Afterwards
Nothing to poll: once admitted, an entry is in our hands and processed for you. To look anyway, read listings back with GET; delegated tokens also need product-listings:read.

Synchronous

HTTP 200 · Completed

Completed writes, in the response.

Endpoint · POST · PATCH · PUT · DELETE/v1/listing-sources/{listingSourceId}/product-listings
The response
HTTP 200 lists failed entries only; [] means every entry completed, an empty batch included.
When entries fail
Each entry has its own transaction, so completed writes stay committed. If every entry fails, a problem response is returned instead.
Retry
Correct and resend only the failed entries.
Afterwards
Search visibility follows separately; a completed write is not yet visible in search.

II — Set-up guide

From access token to first listing batch.

A practical setup flow for connecting a custom shop system to Aura Historia, in either mode.

  1. Step 1

    Select a provider you can access

    Select a provider you currently have access to for this integration. Access does not establish ownership or permission to edit provider details.

    What to checkUse the provider's canonical ID for the integration; both modes use the same one.

  2. Step 2

    Create a user access token

    Create a user access token with product-listings:write for an account currently granted access to the target provider. The same token works for both modes.

    What to checkCopy the token immediately: it is shown only once. Store it securely and send it as a Bearer token with every API request.

    Name
    Custom API product sync
    Scope
    product-listings:write
    Provider
    Not selected
  3. Step 3

    Prepare and send your first product request

    Asynchronous is selected; switch to synchronous if you need write results in the response. The URL uses the selected provider's listingSourceId. Replace YOUR_USER_ACCESS_TOKEN on your server, for async also YOUR_BATCH_KEY, and POST the example batch.

    What to checkAsynchronous: check HTTP 202, acceptedCount and failures; admitted entries are then processed for you. Synchronous: check HTTP 200 and the failure array.

    cURL · POST
    curl --request POST \
  --url 'https://api.aura-historia.com/v1/listing-sources/YOUR_LISTING_SOURCE_ID/product-listings/async' \
  --header 'Authorization: Bearer YOUR_USER_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: YOUR_BATCH_KEY' \
  --data '[
  {
    "sourceListingId": "demo-violin-001",
    "title": {
      "text": "Baroque Violin",
      "language": "en"
    },
    "description": {
      "text": "A baroque violin with a carved scroll.",
      "language": "en"
    },
    "price": {
      "type": "MONETARY",
      "currency": "EUR",
      "amount": 420000
    },
    "availability": null,
    "url": "https://example-shop.com/products/demo-violin-001",
    "images": [
      "https://example-shop.com/images/demo-violin.jpg"
    ]
  }
]'

    Returns 202 · admitted, processed for you

  4. Step 4

    Read the result for your mode

    Asynchronous: acceptedCount plus failures equals the entries sent, each failure at its original index; admitted entries need no follow-up. Synchronous: [] means every entry completed; a partial result names only failed entries; an all-failure batch returns a problem response.

    What to checkStore responses securely. Resend an uncertain asynchronous batch unchanged under the same key; resend only synchronous failures that can be corrected.

    Relevant endpoints
    async/v1/listing-sources/{listingSourceId}/product-listings/async
    sync/v1/listing-sources/{listingSourceId}/product-listings

    Asynchronous · admitted for processing

    All admitted
    202 · report
    Partly admitted
    202 · failures
    None admitted
    4xx · 5xx · report

    Synchronous · completed writes

    All written
    200 · []
    Partial
    200 · failures
    All failed
    problem+json

III — Reference

Partner product API reference.

The rules each method follows in both modes, then the embedded OpenAPI reference for the asynchronous and synchronous batch endpoints.

  • ASYNC

    Admission outcomes

    POST, PATCH, PUT and DELETE on /product-listings/async take the same entries, maxItems 100. HTTP 202 means at least one entry was confirmed admitted, or the batch was empty; admitted entries are then processed for you, with nothing to poll. The report is { submissionId, acceptedCount, failures }: acceptedCount plus failures equals the entries sent, and each failure has index, error, retryable and, when safe to echo, sourceListingId. With nothing admitted: 503 for unconfirmed, retryable or blocked sends; otherwise 500 for internal failures; 413 when only size failed; otherwise 400. Listing existence, auctions and provider authority are checked during processing.

  • ASYNC

    Idempotency and retries

    Send one Idempotency-Key header: 1–128 visible ASCII characters, no comma. Without one, a key is generated and echoed on the report; if that response is lost, the key cannot be recovered. After a lost or uncertain response, resend the exact batch, unchanged and in the same order, with the same key, rejected entries included. retryable marks failures where that resend is appropriate (ENQUEUE_UNCONFIRMED may already be queued); validation and size errors are not retryable. Correct invalid entries in a new request with a new key, leaving out admitted and uncertain ones. submissionId is for correlation only. To look at listings yourself, use GET on /product-listings; delegated tokens also need product-listings:read.

  • SYNC

    Completed-write outcomes

    POST, PATCH, PUT and DELETE on /product-listings: maxItems 100; [] returns HTTP 200 with []. Each entry runs in its own transaction. On partial success, HTTP 200 returns only failures as { listingSourceId, sourceListingId, error }. If every non-empty entry fails, the first failure becomes an application/problem+json response. Do not replay successful entries.

  • POST

    Create fields and prices

    POST requires sourceListingId, url and images; include localized title and description when available (the current contract allows omission or null). Seller and address fields are not supported. Availability is nullable. Asking price is { type: MONETARY, currency: EUR, amount: 420000 } in minor currency units, or { type: ON_REQUEST }; null records no price.

  • PATCH

    Preserve or clear

    Omitted members preserve existing facts. null clears title, description, availability, price and each price estimate. url: null, images: null and auction: null are invalid (400 BAD_BODY_VALUE). images: [] clears images. The complete batch contract is validated before entry transactions begin.

  • PUT

    Upsert semantics

    For existing listings, omit title, description, availability or prices to preserve, send null to clear or a value to set. Omit images to preserve, [] to clear, or an array to replace; null is invalid. Omit url or send null to preserve; a URL replaces it. New listings require sourceListingId, url and images; omitted/null title, description, availability and prices record no value.

  • AUCTION

    Auction membership and lot timing

    Omit auction to preserve its context; auction: null is invalid. Within auction, auctionId must identify an existing auction for the same provider: omit to preserve membership, null to clear, an ID to set. For lotNumber, cataloguePosition and each timing leaf (biddingOpens, scheduledCloses, reportedClosedAt), omit to preserve, null to clear, or supply a value to set. Timing values are RFC3339 instants.

  • DELETE

    Batch withdrawal and restoration

    DELETE takes an array of { sourceListingId } on either path. It withdraws listings, which is reversible, and preserves their history; PUT restores a withdrawn listing before applying current facts. Read the outcome by your mode: the admission report for asynchronous, failed entries for synchronous.

OpenAPI · Partner productsFull docs(opens in a new tab)

Partner product API reference