Every category and collection carries a list of countries it is available in. You set that list when you write the row, read it back on any response, and filter the catalog to a single country when you read it. This guide covers all three, for both categories and collections — they behave identically here.
How the country list works
On any response, the row’s availability is the countries field: an array of ISO country codes.
An empty countries array is not “available nowhere” — it means unrestricted: the row is available in every country the company sells in. A non-empty array restricts availability to exactly those countries.
Set the countries for a row
Availability is written with the country_isos field on create and update. It maps to the countries field you read back.
Two behaviors matter when writing country_isos:
- Sending an empty array (
"country_isos": []) clears all restrictions, making the row unrestricted (available everywhere the company sells).
- Omitting the key entirely leaves the existing countries unchanged. Because updates use PATCH semantics, this is how you edit other fields without touching availability.
To make a category available everywhere, clear the list:
You can also set country_isos at creation time — see Find and create categories and collections.
Read a row’s countries
The countries array is present on every category and collection response, so reading a row’s availability is just a lookup. Use the company show endpoint to see it for any row regardless of lifecycle:
The public catalog and public slug endpoints also return countries on every row they expose. Exposure differs by surface: the public catalog and the category slug expose only live rows, while a collection slug also resolves draft, scheduled, and inactive collections — see Rename, publish, and schedule.
Filter the catalog by country
To ask “which categories are available in this country?”, pass filter[country] with an ISO-2 code. It works on both the public catalog and the company index.
filter[country] uses “OR-empty” semantics: it returns rows explicitly available in that country plus every unrestricted row (rows with an empty country list), since an unrestricted row is available in that country too.
The same filter applies to the company index and to collections:
For categories and collections, country availability is written with country_isos and queried with filter[country]. Do not use the country query parameter for this — country is a product-only parameter that selects country-relative pricing, and it does not filter category or collection availability.
Collections
Collections handle country availability exactly like categories: read countries, write country_isos (empty array clears, omitted key leaves unchanged), and filter with filter[country]. Use /api/v202604/company/collections/{id} to write and /api/v202604/collections to read the public catalog.
Next steps
