Before you start
-
Your token needs company admin access with permission to update countries, languages, agreements, forms, and products. Translating also needs the permissions listed in Add a language. Your own sign-in with
fluid loginworks if you are a company admin. -
Decide how you will operate in the country. The atlas describes three modes, and a company uses exactly one per country:
fluid countries atlas <iso>shows each mode’s overview for the market, with its typical setup time and cost, and its launch checklist. - For NFR or OTG, know which warehouse fulfills the country’s orders. For OTG, have your local tax or business registration number if you already have one.
- Install and sign in to the CLI:
fluid countries and fluid translations command prints JSON. Failures print a JSON error on stderr and exit with a non-zero code. Countries are given by their two-letter ISO code, such as DE or JP; UK is accepted for the United Kingdom.
Steps
1
Preview the setup
open will save, each of the market’s major languages and whether your company has it on, each atlas agreement and whether you already have one with that title, your warehouses, and the mode’s launch checklist. If alreadyOpen names a country, the country is open already: skip to step 3.If Fluid has no atlas for the market, the command says so and stops. Open the country by hand in Settings > Countries instead, and don’t assume tax, legal, or agreement defaults for it.2
Open the country
This changes live configuration: it adds the country to your company.The country is seeded from the atlas: its currency, the operating mode, the tax name, whether prices include tax, whether tax invoices are required, whether card payments need 3-D Secure, the legal settings (cooling-off period, warranty period, cookie consent, subscription disclosure), the checkout address layout with local labels, and the order checkout ranks payment methods in.Add what the atlas can’t know with flags:
--warehouse-id for the fulfilling warehouse, --business-id and --entity-registered for an OTG entity, and --settlement-currency if you settle in a different currency from the one you charge in. Override any seeded value with --set, for example --set tax_inclusive_pricing=false or --set legal_settings.cooling_off_period_days=30.The atlas’s agreements replace Fluid’s generic country agreements and forms, which this step skips. Pass --legacy-defaults to add those as well. Fluid has them for nine countries: the United States, Canada, Mexico, Spain, Germany, Turkey, Australia, New Zealand, and the Philippines. For each of these, it adds:- Fluid’s checkout and enrollment agreements for the country, active and titled with the country’s name, such as
Datenschutzerklärung / Privacy Policy - Germany. - An active Post Purchase enrollment form named for the country, such as
Germany Enrollment Form, with required fields. Germany’s asks for a date of birth, a tax ID, and an IBAN.
--legacy-defaults off when you build the country’s form yourself or with step 6.If your company uses per-country test mode, the new country starts in it and takes no live payments until you turn test mode off. If the country is already open, open changes nothing; --reseed writes the atlas values over its current settings, replacing changes an admin made.3
Convert your prices
Preview first. This changes nothing:For every variant of your active products, the preview takes its price in the United States, multiplies it by an exchange rate, and rounds it to the country’s currency: to the cent for euros, to whole units for currencies such as yen. It shows the rate, the rounding, how many variants it would convert, how many it would skip and why, and a sample of prices before and after. Without It converts the retail price, the subscription price, and the compare-at price. Add the wholesale prices with
--rate, it uses the European Central Bank’s reference rate for the day.Then save the prices, with the rate you reviewed. This changes live prices:--fields price,subscription_price,compare_price,wholesale,wholesale_subscription_price. Convert from another of your countries with --from-country, and include draft products with --status draft.It’s safe to run again. A variant that already has a price in the country is skipped, so a price is never converted twice; --overwrite replaces existing prices. Each variant is saved on its own, and any the API refuses are listed under failed with the reason, while the rest are saved. Converted prices don’t put a product on sale in the country; pass --activate to do that as well.If your prices are managed in the price editor, priceEditor is true. The prices are saved into the price editor, and any it can’t take are listed with refusedByPriceEditor. --overwrite isn’t available then, so prices set in the price editor are never replaced. Change those in the price editor.4
Enable the market's languages
See which of the market’s major languages your company doesn’t have on yet:Then turn them on. This changes live configuration: it turns languages on for your whole company, not just this country.
next in the first command’s output is the enable command with every language that’s off. Enable the languages before you create the agreements, because each agreement translation is saved in its own language.5
Create the agreements
This changes live configuration: it creates agreements and puts them on the country.Each atlas agreement you don’t already have is created from the atlas’s legal text, with its checkout settings (required, shown at checkout, checked by default), in every language the atlas has it in. An agreement whose title matches one you already have is skipped, never duplicated. Run it without
--create to see each agreement’s status first, or pass --only agreement_2 to create one at a time.Have someone qualified review the agreements before you launch. The atlas text is a starting point, not legal advice for your business.6
Set up the enrollment form
See which of the atlas’s enrollment fields the country’s enrollment already asks for. This changes nothing:After payment, enrollment shows every active Post Purchase form for the country. The report lists those forms, marking one that also covers other countries with It creates
shared: true. It gives each atlas field a state: collected when an active form asks for it, inDraft when only a draft form has it, missing, or byHand with a reason. plan is what --create would send.Then create the form. This changes live configuration: it creates or changes a form.Enrollment - Germany, a Post Purchase form for this country alone, as a draft with the missing fields. If that form already exists, as a draft or active, it adds only the missing fields and leaves the fields already on it, and their IDs, as they are. Pass --form 812 to add them to another Post Purchase form that covers only this country. A form shared with other countries is never changed.A draft doesn’t reach enrollment. Review its labels in Forms and make it active there, or pass --activate to publish it in the same run. Once it’s active, everyone who enrolls in the country is asked its fields.Some fields stay with you, listed as byHand with the reason:- A field the atlas asks only of some member types, such as reps. A Post Purchase form reaches everyone who enrolls in the country, so this covers most tax questions and the date of birth.
- A Social Security number, and any field that takes a value and whose label names a national or tax ID number, bank or card details, or a password. Enrollment forms must not collect these. Collect them through your tax or payout provider.
- A multiple choice the atlas gives no choices for. Add it in the form builder.
--skip-sensitive to create the other fields; it lists the ones it left out under skippedSensitive.7
Translate the storefront
Shoppers need the storefront in their language, even when your company already had that language on. For each of the market’s languages, see what isn’t translated yet, then machine-translate it:This changes live content. It covers products and the rest of your storefront, navigation, your theme’s strings, agreements, and product labels. Run
auto again until remaining is 0 for every type. Add a language explains the report, how to review and correct translations, and what still has to be translated by hand.8
Check the setup
ok and a detail. It also checks that every variant of your active products has a price in the country, counting a bundle by the price checkout charges for it (prices), and that something is on sale there (on_sale). It checks that enrollment asks for every atlas field a Post Purchase form can collect (enrollment_form), and enrollmentForm gives the commands for step 6. done is true when every check passes. prices and translations give the commands for steps 3 and 7. byHand lists the work no command does for you, and launchChecklist is the atlas’s checklist for your mode: the registrations, licences, and filings to complete before you launch. Work through both.What the status means
What stays with you
The commands don’t do these;status lists them under byHand:
- Payment methods. The atlas recommends methods for the market in order. Connect each provider in Settings > Payments; that needs your account details with the provider.
- Enrollment form fields step 6 leaves to you.
byHand.enrollmentFieldslists them, each with itslabel, itscomponent, whether it’srequired, and thereason. If your token can’t read forms, it lists every atlas field instead.fluid countries atlas <iso>adds each field’s description and who it’s meant for. A form asks every enrollee in its countries, whatever they enroll as. A field the atlas means for reps only, such as Germany’s tax number, would be asked of customers who enroll too. - Putting products on sale. Converted prices don’t put a product on sale in the country unless you passed
--activate. Turn on the products you will sell there. - Content no API translates. Promotions, enrollment form fields, and theme settings written as plain text. See Add a language.
- The mode’s own work. OTG means registering for local tax and setting up local invoicing; USD means checking whether the country taxes cross-border digital sales.
fluid countries compliance <iso>lists the market’s disclosure pages, cookie rule, and how prices must be shown.
Troubleshooting
open fails with a 422. The country couldn’t be saved. The error’s details name the setting the API refused. Fix it with --set and run the step again; nothing was saved.
open --reseed fails with a 409. Someone changed the country while you were working. Run it again to start from the current settings.
A price is listed under failed. The API refused that variant, for example because the price editor couldn’t place it in a price list for the country. The reason is in error and details. Fix it, or set that price in the admin, then run step 3 again; variants already saved are skipped.
--write needs the rate you reviewed. Saving prices needs --rate. Run the preview, check the rate, and pass it.
An agreement’s failedTranslations says the locale is unsupported. That language isn’t on for your company. The agreement itself was created. Run step 4, then fluid countries agreements DE --translate --yes to write the atlas translations onto the agreements already on the country.
isn't open for this company yet. agreements needs the country. Run step 2 first.
forms --create says your token can’t create fields marked sensitive. Nothing was saved. Use a role with the permission to mark form fields as sensitive, or run it again with --skip-sensitive.
forms --form is refused. --form takes only a Post Purchase form that covers this country alone. Leave it out to use the country’s own Enrollment - <Country> form.
--form, --activate and --skip-sensitive go with --create. Those flags only apply when you create or change the form. Add --create --yes.
A 403 from any command. Your token lacks permission for that step. See Before you start.
Use the API directly
The CLI reads the public Country Atlas at/api/v202604/country/atlas/{iso}, which needs no token, and calls company operations authenticated with a Bearer token:
-
List company countries —
GET /api/settings/company_countries, to see whether the country is already open. -
Create a company country —
POST /api/settings/company_countries, with the atlas values as the country’s own. Sendseed_legacy_defaultsasfalseto skip Fluid’s generic agreements and forms. -
Update a company country —
PUT /api/settings/company_countries/{id}. Send therevisionyou read asexpected_revision, and a concurrent change answers409instead of being overwritten. -
List company languages and Configure company language —
GETandPOST /api/settings/languages. -
Creates an agreement, then Updates an agreement with the language’s ISO code as the
language_isoquery parameter for each translation. -
List warehouses —
GET /api/settings/warehouses, to choose the warehouse. -
Enrollment forms: List forms shows the forms you already have, and Create a form and Update a form build the country’s Post Purchase form. List form elements describes the element types. A form’s countries are Fluid country IDs, the
country.idin each company country. Build a form through the API walks through the requests. The CLI maps each atlascomponentto one form component:It never creates aSocialSecurityNumberfield. When it adds fields to an existing form, it reads the form again and sends every current component back with itsid, so nothing on the form is deactivated. - Prices are saved one variant at a time through the variants API, in the variant’s price row for the country. The CLI reads the products with their variants and prices first, and checks the company profile for whether the price editor manages your prices.
fluid countries atlas where you can.