ONIX intake
An ONIX intake ingests your catalog from an ONIX 3.0 feed. We create an SFTP account and a private storage area for you and send you the password; you upload the feed and the content files there, and we create and update the products in your store from what the feed says. Use it when you are onboarding a large catalog, or when your metadata already flows to distributors and retailers as ONIX.
For how this compares with the Content API and scheduled automations, see the content publishing overview.
ONIX intake is a managed setup. Email [email protected] to have one configured. We create the SFTP account and the storage area, send you the credentials, and monitor the ingestion.
We set up your SFTP access
You do not create the server, the account, or the storage area, and you do not need a cloud provider account of your own. When we configure your intake, we create a private storage area for your catalog and one SFTP user that can reach only that area. Support then sends you three things:
| What we send | What it is |
|---|---|
| Host | The address of the SFTP server you connect to |
| Username | The SFTP user we created for you |
| Password | The password for that user, generated on our side |
Connect with any SFTP client using those three values. The server listens on port 22, the SFTP default, so most clients need no change. There is nothing to install, configure, or request access to beyond that.
Store the password in your own password manager as soon as you receive it. Treat it as a credential for your catalog: anyone holding it can upload content that reaches your store. If you lose it, or you want it rotated, ask [email protected] for a new one rather than creating a second account.
Before you start
You need:
- An ONIX 3.0 feed, one or more files with a
.xmlor.onixextension. - The content files the feed describes: PDF, EPUB, or MP3.
- An ISBN-13 or a GTIN for every product in the feed. This identifier is how we match metadata to files and how we recognize the product on later deliveries.
- An SFTP client, or publishing tooling that can upload over SFTP.
- The host, username, and password support sent you.
Deliver your files
Your SFTP user lands directly in the root of your own storage area, so the paths below are relative to wherever your client opens. You cannot see, and are not affected by, any other customer's area. Two locations matter:
| Location | What goes there |
|---|---|
data/ | Your ONIX feed files, with a .xml or .onix extension |
The root, / | The content files and cover images |
Feed files outside data/, and content files inside a subfolder, are not picked up.
Name your content files
Content files and covers are matched by the product identifier from the feed, not by anything in the file's contents. Name them accordingly:
| File | Name | Example |
|---|---|---|
{identifier}.pdf | 9781234567890.pdf | |
| EPUB | {identifier}.epub | 9781234567890.epub |
| Cover image | {identifier}.jpg or {identifier}.png | 9781234567890.jpg |
| Audiobook track | The same file name your feed advertises in ContentItem | 9781234567890_01.mp3 |
Extensions are case-insensitive, so 9781234567890.PDF resolves the same as the lowercase form.
Audiobooks need every track the feed advertises before we publish the product. We wait rather than publish a partial audiobook, because attaching the rest later is not possible through the intake. If your feed advertises no track list at all, one track named {identifier}_*.mp3 is enough to publish. Files ending in _preview.mp3 never count as content and are always ignored.
Upload order does not matter. You can send the content files before the feed, after it, or in the same session.
What happens after you upload
- Every three hours we scan
data/for feed files we have not seen before. - We split each feed into one record per product and validate the metadata.
- When a product's metadata is valid and its content files are in place, we create it in your store, or update it if we have seen the identifier before.
- A product whose content file has not arrived yet waits and is retried. It is not discarded, and you do not need to resend the feed.
Metadata requirements
These are the elements we read. A product missing a required one is not ingested.
| Data | ONIX path | Requirement |
|---|---|---|
| Identifier | ProductIdentifier | Required. ProductIDType 15 (ISBN-13) or 03 (GTIN) |
| Title | DescriptiveDetail.TitleDetail | Required. TitleType 01, up to 255 characters |
| Format | DescriptiveDetail.ProductForm | Required. EPUB, MP3, or PDF |
| Language | DescriptiveDetail.Language | Required. See supported languages |
| Author | DescriptiveDetail.Contributor | ContributorRole A01. Multiple authors are concatenated in the order received |
| Narrator | DescriptiveDetail.Contributor | ContributorRole E03 or E07, for audiobooks |
| Description | CollateralDetail.TextContent | ContentAudience 00 or 03; TextType 02 or 03; textformat 02 or 06; no Territory |
| BISAC subjects | DescriptiveDetail.Subject | SubjectSchemeIdentifier 10. Up to four codes; the first one flagged MainSubject takes priority |
| Keywords | DescriptiveDetail.Subject | SubjectSchemeIdentifier 20. Split on , or ; |
| Price | ProductSupply.SupplyDetail.Price | PriceType 01 (recommended retail price excluding tax), scoped to the WORLD territory. PriceAmount 0 makes the product free |
| Publishing status | PublishingDetail.PublishingStatus | 04 puts the product on sale. Withdrawn codes remove it from sale |
| Sales rights | PublishingDetail.SalesRights | SalesRightsType 01 or 02, with RegionsIncluded WORLD or an explicit CountriesIncluded list |
| Publication date | PublishingDetail.PublishingDate | PublishingDateRole 01, formatted YYYYMMDD |
Prices in a currency we do not support, and prices below the minimum we accept for a currency, are rejected. Ask support if you need a currency confirmed before your first delivery.
Supported languages
We ingest a curated set of languages: the ones we have confirmed work across the reading apps, search, the storefront, and the metadata. We convert the ONIX LanguageCode to its ISO 639-1 equivalent, and we accept both the bibliographic and the terminologic variant of each one, so fre and fra both resolve to French.
- Western European: English, Spanish, Portuguese, Italian, French, Catalan, Galician, German (Swiss German is stored as German), Dutch, Irish
- Nordic: Danish, Swedish, Norwegian (including Bokmal and Nynorsk), Icelandic, Faroese
- Central and Eastern European: Polish, Czech, Slovak, Slovenian, Croatian, Bosnian, Romanian, Hungarian, Bulgarian, Lithuanian, Latvian, Estonian, Finnish, Turkish
- Other: Afrikaans, Indonesian, Malay, Tagalog, Swahili, Japanese, Chinese, Bengali
A product in any other language is held, not ingested, and it shows up in our monitoring so we can tell you it is waiting. Adding a language is a small change on our side once we confirm it renders and searches correctly, and anything already delivered in that language starts ingesting as soon as it is added.
Update products
Send the product again in a later feed. The values in the most recent feed replace the previous ones, including the publishing status, so a feed is a full statement of the product's current state rather than a patch.
To replace a content file, upload the new file under the same name. We compare it against what we ingested last time and push it only when it has actually changed, so re-uploading an unchanged file costs nothing.
Audiobook tracks are the exception. Updates do not re-attach audio files, so an audiobook published with missing tracks cannot be completed by sending the tracks later. Contact support in that case.
File retention
Objects in your storage area expire 90 days after upload. The area is a delivery channel, not an archive: keep your own copy of everything you send.
Troubleshooting
| What you see | What to check |
|---|---|
| The SFTP client cannot connect or sign in | You are using the host, username, and password support sent you, over SFTP on port 22 rather than FTP. Ask support to confirm the account or reissue the password |
| The feed was uploaded but nothing happened | The file is under data/ and its extension is .xml or .onix. Discovery runs every three hours |
| A product is in the store but not on sale | PublishingStatus is 04, and there is a PriceType 01 price scoped to WORLD |
| A product never appears, others from the same feed do | The content file name matches the identifier exactly, and the file is at the root rather than in a subfolder |
| An audiobook is missing tracks | Every file name advertised in ContentItem was uploaded, and none of them ends in _preview.mp3 |
| A product in a specific language never appears | The language is on the supported list. If it is not, ask support to add it |
When you contact support, include the feed file name and the identifiers of the affected products. That is enough for us to trace what the pipeline did with them.
Getting help
Email [email protected], or check status.publica.la for service status.