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.

info

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.

caution

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 .xml or .onix extension.
• 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.
• A RecordReference for every product that stays the same across deliveries. It is 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
PDF	{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

1. Every three hours we scan data/ for feed files we have not seen before.
2. We split each feed into one record per product and validate the metadata.
3. 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.
4. 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
Record reference	RecordReference	Required. Must stay the same for the product on every delivery
Identifier	ProductIdentifier	Required. ProductIDType 15 (ISBN-13) or 03 (GTIN)
Title	DescriptiveDetail.TitleDetail	Required. TitleType 01, up to 255 characters
Format	DescriptiveDetail.ProductFormDetail	Required. E101 (EPUB), E107 (PDF), or A103 (MP3)
Language	DescriptiveDetail.Language	Required. See supported languages
Publisher	PublishingDetail.Publisher	Required. PublishingRole 01
Author	DescriptiveDetail.Contributor	ContributorRole A01. Every author is kept, 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 ;. Up to 200 keywords of up to 200 characters each
Price	ProductSupply.SupplyDetail.Price	Required to go on sale. PriceType 01, one price per currency. See Prices
Publishing status	PublishingDetail.PublishingStatus	04 puts the product on sale. Withdrawn codes remove it from sale
Sales rights	PublishingDetail.SalesRights	See Sales rights
Publication date	PublishingDetail.PublishingDate	PublishingDateRole 01, formatted YYYYMMDD

Prices

• Price type. We read PriceType 01 only. Prices of any other type, 02 and 42 (including tax) among them, are ignored. In the ONIX code list 01 is a price excluding tax, but we read it as the final consumer price: send under PriceType 01 the amount you would otherwise send as PriceType 42, taxes included.
• The amount is what the reader pays. We charge the PriceAmount as the final price and calculate the taxes due from it at checkout; we do not add them on top. If your store is configured to add taxes on top of the price, ask support how that applies to your feed.
• One price per currency. We do not read the Territory of a Price. If you send two prices in the same currency (for example one for Spain and one for Germany), we keep the lowest one and use it for every sale in that currency.
• Markets. If the product has one ProductSupply, we use it whatever its market. If it has several, we use only the one whose Market is WORLD; when none is, the product has no price.
• Currencies. USD, BRL, ARS, CLP, PEN, UYU, COP, MXN, BOB, EUR, ALL, AMD, AZN, BYN, BAM, BGN, CZK, DKK, GEL, HUF, ISK, MDL, MKD, NOK, PLN, RON, RUB, RSD, SEK, CHF, TRY, UAH, and GBP. Prices in any other currency are ignored.
• Format. PriceAmount uses a dot as decimal separator (9.99).
• Scheduled prices. PriceDate with PriceDateRole 14 sets when a price starts and 15 when it ends, formatted YYYYMMDD.
• Free products. A product is free only when every price you send for it is 0, and it stays free until a later delivery brings a price above 0. A price of 0 next to a price above 0 is discarded, so a temporary free period (a price of 0 with an end date followed by a future price) is not supported.
• Minimum price. A price below the minimum for its currency (USD 0.50 or its equivalent) is stored, but the product is not offered to other stores in the marketplace until its prices reach the minimum.

A product that is not withdrawn and has no price left after these rules is not ingested. Ask support if you need a currency confirmed before your first delivery.

Sales rights

• SalesRightsType 01 or 02 with RegionsIncluded WORLD sells everywhere; with a CountriesIncluded list, it sells only in those countries. CountriesExcluded removes countries from either.
• A SalesRightsType 03 (not for sale) block lists the countries where the product is not sold. Pair it with ROWSalesRightsType 01 or 02 so the product sells in the rest of the world.
• Regions other than WORLD are not supported. If your sales rights use them, or a 03 block comes without ROWSalesRightsType, we do not apply any geographic restriction to the product.

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.

Replace a content file or cover

This applies to the files named after the product identifier (the PDF, EPUB, or cover image; see Name your content files), not to the feed itself. Feed files under data/ are never replaced; every delivery there is a new file.

Deliver the replacement exactly like the original: same location, same name. There is no separate directory, no versioned file name, and no need to delete the old file first.

1. Upload the new file to the root of your storage area, under the exact name of the file it replaces; the new 9781234567890.epub overwrites the previous one in place.
2. Include the product in a later feed. Processing that feed record is what applies the replacement; a new content file on its own, with no later feed mentioning the product, is not picked up.

When we process the product again, we compare each of its files against what we ingested last time and push only the ones that actually changed. Re-uploading an identical file, or re-sending a product whose files did not change, costs nothing.

caution

Audiobook tracks are the exception: updates can replace the cover but never the audio files, so an audiobook published with missing or wrong tracks cannot be fixed by uploading new ones. 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 the feed has a PriceType 01 price in a supported currency (see Prices)
A product sells at a different price than the feed says	There is a single price per currency in the feed, and the amount is the final price the reader pays (see Prices)
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
You replaced a content file but the product still serves the old one	The new file has the exact same name as the old one, and the product appears in a feed delivered after the upload. The replacement is applied when that feed record is processed
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.