ONIX Support for Publishers

Send us an ONIX for Books XML file to add metadata to books already in your Cashmere catalog. ONIX does not create a book or upload its content. We match each product to a book in your organization by its ISBN-13, GTIN-13, or proprietary ID, and apply the metadata when that book is available.

How to send ONIX

Send an uncompressed XML file by either route:

• SFTP: Connect an SFTP Server, then place the file in the configured directory. The filename must end in .xml for the ONIX route.
• API: Use a publisher organization's read/write API key with access to metadata-records. To list a book's records with GET /api/v2/omnipub/{uuid}/metadata-records, the key also needs access to omnipub. Send a multipart file upload to POST /api/v2/metadata-records, or send JSON with a public HTTP(S) file_url pointing to the XML. The API recognizes ONIX from the XML content, regardless of the filename extension. Private or internal URLs are refused.

For example, upload a local file with:

curl -X POST "https://cashmere.io/api/v2/metadata-records" \
  -H "Authorization: Bearer YOUR_PUBLISHER_API_KEY" \
  -F "file=@publisher_onix_20260930.xml"

The API also accepts Content-Type: application/json with {"file_url":"https://publisher.example.com/publisher_onix_20260930.xml"}. Use a descriptive filename such as publisher_onix_YYYYMMDD.xml: the API returns its basename as source_file, which helps you trace a submission or record back to a feed. For a file_url submission, source_file stays null until the background job has downloaded the file. Submit the XML itself; compressed files are not accepted as ONIX inputs by the API.

What to send

• ONIX 2.1, 3.0, or 3.1 XML, using reference tags or short tags, with or without an ONIX namespace. Use an <ONIXMessage> or <ONIXmessage> root.
• Declare the XML encoding. UTF-8 is preferred; ISO-8859-1 and UTF-16 are also recognized during delivery.
• A ProductIdentifier with ProductIDType 15 (ISBN-13) for every product. Use the same ISBN-13 as the book in your catalog. We also read GTIN-13 (03) and proprietary (01) identifiers, but an ISBN-13 is the reliable way to match a book. If a product has more than one proprietary ID, only the first is used, so list your own ID first. ISBN-10 (02) alone cannot identify a product for delivery. For ONIX 2.1, put identifiers in ProductIdentifier composites; the flat ISBN and EAN13 elements are not read.
• Send descriptions in TextContent with TextType 03 (full description) or 02 (short annotation). We use 03 when both are present. Send publication dates as YYYYMMDD (dateformat 00); other formats are retained as supplied rather than normalized.
• As a delivery guideline, keep each uncompressed XML file at or below 40 MB and split larger catalogs into multiple messages. This is not a hard limit; large API submissions can take many minutes and the background job has a one-hour timeout.

For edited volumes, contributors inside ContentItem are treated as chapter contributors, not book creators, and a ContentItem's descriptions and subjects are not used for the book, so chapter subjects do not become book tags. Series editors and subjects inside Collection (ONIX 2.1 Series) are not used for the book either.

Metadata we use

When a product matches a book, these nonempty values can update its main book details:

We also keep these details with the book's ONIX metadata: record reference, notification type, publishing status, product form, product form detail and description, imprint, copyright year, description (TextType 03 or 02), series, identifiers, and subjects. A series title comes from a Collection or TitleElementLevel 02; it does not replace the product title. The description is retained as ONIX metadata rather than replacing a main book field.

ONIX codes and how we handle them

Supported coded subjects can become book tags. Keywords (20) are kept as metadata but do not become tags. Other subject schemes, including Thema qualifiers and proprietary schemes, are not extracted.

We do not use prices, availability, supply details, measurements, extent, audience, rights territories, ProductFormFeature, related products, or ONIX 2.1 OtherText descriptions. Other identifier types can be retained in the ONIX metadata but cannot be used to identify a delivery record.

What happens after delivery

Each product with a usable identifier is stored as a metadata record. Applied means we found an active book with the matching ISBN in your organization and updated its metadata. Received means we stored the record but did not apply it yet, usually because no matching active book is available. Received records can be applied when a matching book arrives, including when a book is replaced. A record matches a book by ISBN-13, or by a proprietary ID or GTIN-13 equal to the book's external_id. Superseded means an older ONIX record was replaced when a newer record applied for the same identifier or book. Sending the same file again creates new record rows; an older received record is superseded only once a newer record applies. Delete notices (NotificationType 05) also count as received; they are never applied as deletions.

A product without an ISBN-13, GTIN-13, or proprietary identifier is not stored. It may count as a product error, or be skipped if no main book details were found. Valid products in a mixed file can still be received or applied. For SFTP, a file with no products or no usable identifiers is recorded as an ONIX ingest error. For the API, a file whose products all lack usable identifiers can still show succeeded with errors equal to records. Check the counts, not only the submission status.

Check an API submission

POST /api/v2/metadata-records returns HTTP 202 with a submission id. Processing runs in the background and may take many minutes. Poll GET /api/v2/metadata-records/submissions/{id}: the status moves from queued to running, then succeeded or failed. The records, applied, received, and errors counts are null until processing finishes. A failed submission includes an error message.

Use GET /api/v2/metadata-records?submission_id={id} to list the records from that submission. The list can also be filtered by record_type, status, or identifier; use the normalized ISBN-13 without hyphens for an ISBN filter. GET /api/v2/metadata-records/{record_id} includes the normalized ONIX payload. To see records for one book, use GET /api/v2/omnipub/{uuid}/metadata-records.