Instances and aliases

An instance is one Recurly site. Its alias is the short name you use to talk about it — and it cannot be changed.

An instance is one Recurly site

If your company has one Recurly account, you have one instance. If you run separate Recurly sites for separate brands, countries, or a sandbox alongside production, each of those is its own instance, added separately, with its own API key.

An instance is Retrixus's record of a site: which subdomain it is, which region it lives in, whether it is a sandbox or production, and where its API key is kept. It is not a copy of your data. Every question is answered by calling Recurly at the moment you ask.

An alias is the short name you use

When you add an instance you choose an alias — acme, uk, pf-sandbox. That is how you refer to the site when you ask a question:

In acme, show me last month's failed payments.

Two to twelve characters, lowercase letters, numbers and hyphens, and it cannot start or end with a hyphen. Choose the word you would use out loud in a meeting. If your organisation has just one site, you will still use the alias, so keep it short.

The alias cannot be changed

Not "changing it is discouraged" — there is no way to do it. The console will refuse, and so will the API.

The alias is not just a label. It becomes part of the web address of that instance's settings, part of the name of the vault entry holding its API key, part of the folder structure of any files exported for it, and part of every question anyone has ever asked about it. A rename would have to be correct in all of those places at once, and any that was missed would fail silently later.

So Retrixus does not offer one. If you picked the wrong alias, delete the instance and add it again — it takes a minute, and it touches nothing inside Recurly.

The subdomain and the region are fixed for the same reason: changing either would mean the instance now points at a different Recurly site while keeping the same history, which is worse than starting again.

What can be changed

When you have more than one

Ask your assistant "which sites do I have connected?" at any time.

If you leave the alias out of an ambiguous question, you will be asked which site you meant rather than given an answer from whichever one came first. The one place that matters most is when a sandbox and a production site sit side by side — see sandbox vs production for how to keep them straight.

The two names, and why there are two

Every site has a short name and a full name, and you can use either when asking a question.

The short name is an identifier: lowercase, no spaces, two to twelve characters — uspb-dev. It is permanent. It appears in the audit log beside everything anyone does, and it is what a token's permissions are written against, which is why it cannot be changed once anything has been recorded against it.

The full name is what people call the site out loud — US Phone Book. It exists so you do not have to remember the short one. Change it whenever it stops being right.

Both address the same site:

How many active subscriptions does uspb-dev have?

How many active subscriptions does US Phone Book have?

Capitalisation, spaces and hyphens are ignored, so USPhoneBook and us phone book work too.

What does not work is a partial name. USPh will not find US Phone Book, and that is deliberate: Retrixus would rather ask which site you meant than guess and answer about the wrong one. If two sites could match what you typed, it asks.

One thing worth knowing: if a site's short name is uspb and a different site's full name is also uspb, then typing uspb means the first one. Exact short names always win. It is unlikely to come up, and if it does, the answer still tells you which site it came from.