Change organization settings

Settings describes your organization: the name customers see and how they pay, where its storefront lives and how it looks, the legal details printed on invoices and statements, how invoices are made, how its email leaves and how that email looks. Each has a page under Settings in the organization's menu: General, Storefront, Invoicing, Email sending, SEO, Customer accounts and Tags and pixels. Set your search appearance covers the SEO page. Owners and admins also find Support mailbox, Email design, API keys and Webhooks there. Each card on a page saves on its own. The quickest way in is the sidebar: your organization's block lists Settings, which folds open to these pages (Your organization in the sidebar).

Every member can open these pages and read the values, except Support mailbox, Email design, API keys and Webhooks, which only owners and admins see. Changing them takes the Owner or Admin role. Any other member sees each page with the note Changing these settings needs an owner or admin. and nothing to press. Only the owner can hand the organization to another member or delete it.

1. Go to Organizations, open your organization and choose Settings. It opens on General. In the sidebar, select Settings in your organization's block.
2. On the Organization card, change the Name. It must be at least two characters.
3. Choose the Billing mode: Platform merchant of record, Own gateway or Hybrid. Organization billing explains each one; the own gateway modes need a PayNow store.
4. Choose Save changes, or Discard to put the card back as it was. The footer counts the changes you have not saved.

The card also shows what Coritan sets for you: the Slug, the Tier, your Limits, the Platform cut (a line for each tier, such as "Under $2,000 a month: 3.5%") and Hosting you resell (how far below list price you buy it). A Coritan organization shows None for the cut and List price for hosting, since it pays neither. Contact support to change your tier or limits; the cut and the wholesale discount are the same for every organization (The reseller program's terms).

Under the Organization card, General holds two more cards.

Billing basis

Whether you pay Coritan for compute on Plans or on Usage, and since when. While you are on Plans it shows the last three months of Plan wholesale beside what your customers' use would have cost, and the owner can select Switch to usage billing…. The switch needs the slug typed, and takes effect on the 1st of the next month. Cancel the switch… puts a waiting switch off. Other members read the card and cannot switch.

Monthly usage budget

An optional cap on what your customers' use costs you each month, on the Usage basis. The owner, admins and billing members select Set a budget… or Edit budget…, enter the amount in dollars and select Save budget. We tell you at 80% and 100%, and at 100% new orders pause.

When new orders are paused, General starts with New orders are paused and the reason. See what your customers' use costs you explains all three.

Two cards hold the details your customers and the tax office read. Each has its own Save changes button.

Legal entity, on General

The Trading name, Legal name, Registration number, Tax / VAT ID, the two-letter Country code, the Billing email and the Registered address. Invoice PDFs name the legal name (or the trading name when there is none), the registered address and the tax ID. Statements need the registered address.

Branding, on Storefront

The Logo URL and Favicon URL, the Primary colour and Secondary colour as hex codes such as #0F2A57 (the swatch beside each one opens a colour picker), the Support email, and the Terms of service URL and Privacy policy URL. Your storefront reads these through the Storefront API.

The custom domain has a card of its own on Storefront (Set your custom domain), and analytics and ad tags have an editor of their own (Add analytics and ad tags). Below them, Features & mail presentation lists the features Coritan has turned on for your organization and the host names your mail customers see. It is read only; ask support to change it.

Google Analytics 4 and the pixels for Google Ads, Meta, TikTok, Microsoft Advertising, Reddit, X and Google Tag Manager are set together, one ID for each platform, on the Tags and pixels page. Add analytics and ad tags to your storefront says where to find each ID, which settings to change in Google Analytics, how to check that a platform receives visits, and what visitors are asked before an ad tag loads. A brand that set Google Analytics here before keeps it: the first save of the editor moves the ID into the new settings.

Emails to your customers and staff link to pages on your custom domain: invoices, password resets, email verification and sign-in. With no custom domain, those links go to Coritan's own site. Customer sign-in lists the pages your storefront needs for those links.

1. Open your organization, then Settings, then Storefront.
2. On the Custom domain card, enter the Custom domain, such as portal.example.com, and choose Save changes. The card's badge says Not verified.
3. The card shows a TXT record named _coritan-org. followed by your domain, with the value to give it. Publish that record where the domain's DNS is hosted. It proves the domain is yours.
4. Choose Check domain. When we find the record, the badge says Verified. When we do not, the card says We did not find the record yet; DNS changes can take a while to reach us, so check again once the record is published.

A different domain is Not verified again, with a new record to publish. Emails link to the domain from the moment you save it, verified or not.

The TXT record proves the domain; it does not point it at your storefront. Coritan serves a storefront only on the hostnames it has added for your organization, so no DNS record you publish can do that, and the card says where the domain stands:

• Coritan serves your storefront on portal.example.com.: links to the domain open your storefront.
• Not pointed at your storefront: the card names the host your storefront answers on. Ask support to add your domain once it is Verified. Until then, the links in your emails do not open your storefront.
• Point it at your own storefront: Coritan does not host a storefront for your organization, so point the domain at the site you run on the Organization API (Build a storefront on the Organization API).

1. Open your organization, then Settings, then Invoicing.
2. On the Invoicing card, set:
   • the Invoice prefix that starts every invoice number, such as INV-;
   • the Currency of new invoices;
   • the Tax rate added to order and renewal invoices, from 0 to 100%;
   • the Payment terms in days, from 0 to 365;
   • the Timezone, as an IANA name such as Europe/Paris;
   • an Invoice footer for bank details, a thank-you or legal notes.
3. Choose Save changes.

Payment terms also decide how early we invoice a renewal: a service is invoiced once its next due date is that many days away. The timezone is saved, but statements use UTC.

A new order's invoice (a server, a basket or an add-on, which starts once it is paid) is due after the payment terms too, unless Coritan has set a shorter window for your organization in features.new_orders.pay_within_hours, from 1 to 720 hours. Renewals always keep the payment terms. Ask Coritan support to set or change the window.

Under the fields, the card says whether a customer who downgrades or cancels gets credit for the time they had paid for and not used. Coritan sets both for your organization; where it has not, the platform's default applies.

Invoices, receipts, ticket replies and your customers' account emails (address verification, password resets and the link to choose a password after checkout) leave through an SMTP account or through the in-house mail platform. Both cards are under Settings, then Email sending.

To check that an email left, and read it as the customer got it, open Sent email under Customers.

The Outgoing email (SMTP) card holds the SMTP account: SMTP host, Port, Username, Password, From address and From name. We store the password encrypted and never show it again; the hint under Password says whether one is stored, and leaving the field empty keeps it. With no SMTP host, we send your email through Coritan's own SMTP service.

The Outbound transport card decides which way mail leaves:

For the two in-house transports, fill in:

• Mail tenant: the name of the SMTP Relay tenant that carries your mail. It must be one of your organization's relay tenants. The dashboard does not show tenant names, so ask support for it.
• Sending domain: the envelope sender domain, such as send.example.com. It must be a domain on that tenant.
• Envelope local part: the part before the @ that bounces return to. It defaults to noreply.
• Visible From: Your From address keeps the From address as you set it; The sending subdomain puts From on the sending domain and your address in Reply-To.

Choose Save changes. The card then shows the Effective route your mail takes right now and, for the in-house transports, whether the tenant, its sending domain, its DKIM record and its relay credential are ready.

When your team answers a ticket, we email the customer. If your organization keeps its mail somewhere else, such as Google Workspace, you can connect a mailbox there so that the customer's reply to that email lands on the ticket. This is the other way to take email replies: Answer customer conversations describes both.

• You need the Owner or Admin role. Each change asks you to confirm it is you, with your password, and the confirmation lasts ten minutes.
• Make a separate mailbox for tickets in your mail provider, such as tickets@example.com. It must be a mailbox of its own, not an alias of another one.
• Turn on IMAP for that mailbox. With Google Workspace, turn on 2-step verification for the account first, then make an app password in your Google account.
• Check that your outgoing email works under Email sending. The confirmation email leaves through it.
• Your organization must not have a support address that Coritan runs for you. You can use one or the other, and saving a mailbox while we run one answers 409.
• Another organization on Coritan must not use the same login. One mailbox belongs to one organization, and an organization has one mailbox.

1. Open your organization, then Settings, then Support mailbox.
2. Choose the Provider: Google Workspace or Gmail, or Another provider. Google fills in IMAP server and IMAP port for you.
3. Enter the Mailbox address.
4. For Another provider, enter the IMAP server, such as imap.example.com. The IMAP port is 993: we read mailboxes over TLS on that port and no other.
5. Enter the App password. We store it encrypted and never show it again. The field says Saved once one is stored, and leaving it empty keeps it.
6. To sign in with a name other than the address, or to change the start of the reply address, choose Advanced settings and fill in Login and Reply address start. Login defaults to the mailbox address. Reply address start defaults to the part of the address before the @.
7. Choose Save changes. The page then shows its status, Waiting for confirmation.
8. On the Check it works card, choose Test the connection. We sign in, open the inbox and count its messages, and change nothing. A failure tells you what the server said.
9. Choose Send the confirmation email. We sign in once more, then send one email through your organization's outgoing email to a reply address made for the confirmation, such as tickets+verify-3f9a1c@example.com. When we read it from the mailbox, the status changes to Active. The page checks again every few seconds while it waits, and we read the mailbox every minute.

Saving a new address, server, login or app password starts the check again: the status goes back to Waiting for confirmation, and you test and confirm once more.

Ticket emails to your customers now carry a reply address on your mailbox, in the form <reply address start>+<ticket number>-<code>@<domain>, such as tickets+1042-k3x9q2@example.com. Google delivers an address with a + tag to the mailbox itself, so the customer's reply reaches it.

We read the mailbox's inbox every minute. We never mark, move or delete a message, and we never import mail that was in the mailbox before you connected it.

Two checks stop a forged reply. A reply counts when its address carries the ticket's own code. Without the code, a reply counts only when it comes from the ticket's customer and Google reports that the message passed its sender checks (SPF, DKIM or DMARC); only the Google Workspace or Gmail provider can vouch for a sender, so with Another provider a reply needs the code. We also ignore our own notification emails and automatic mail, such as bounces, out-of-office replies and mailing lists.

The Check it works card shows the Status, a Reply address example, the Last check, the Last successful check and how many messages we handled in the last 24 hours.

On the Remove the mailbox card, choose Remove the mailbox… and type the mailbox address to confirm. We stop reading it and delete the saved password. Nothing in the mailbox changes, and replies we already added stay on their tickets. Ticket emails then carry no reply address, so customers answer in your storefront until you connect a mailbox again. If Coritan turns your mailbox off, the page shows it as Not set up and you can connect it again the same way.

Every email your organization sends its customers uses one design: invoices, receipts, password resets, order emails and replies to their tickets. We write the words of each email, and you choose how it looks.

1. Open your organization, then Settings, then Email design.
2. Choose a Palette: Light or Dark. Then set any of Background, Card, Text and Accent as a hex code such as #0F2A57, or pick it with the swatch beside the field. An empty field uses the palette's colour, and an empty Accent uses the Primary colour from Storefront. The accent colours the buttons, the links and the line along the top of each email.
3. Choose the Corners and the Font. Emails do not download fonts, so a reader who does not have the font installed sees their own.
4. Choose the Header, and a Logo URL if the email should show another logo than the one on Storefront. The address must start with https://.
5. Add a Footer line of up to 200 characters, and up to 3 Footer links with Add a link, each with a label of up to 30 characters and an https:// or mailto: address. Every email already links to your support email and the customer's account.
6. Tick Legal name and address in the footer to print the legal name and registered address from General under every email. You need to set one of them first.
7. Choose Save changes, or Discard to put the form back as it was saved.

We draw the logo in its own proportions whichever header you choose. With By the logo's shape, a logo we cannot load shows as the first letter of your organization's name instead.

The preview beside the form is a real email from your organization in the design on screen, and it changes as you edit. Choose Welcome, Invoice, Suspension or Reply to see another one. Send me a test sends the email on screen to your own address, saved or not, so you can check it in your own mail app. Each member can send 10 tests an hour.

Every email sent after you save uses the new design. If your brand has a staff console, its emails tab edits the same design (Design your emails). Each save is recorded in the audit log as settings.email_design.updated, with each field's old and new value.

Settings, then Customer accounts holds what a customer record carries beyond the standard details, and the applications registered for customer sign-in. Its Custom fields card lists the extra details a customer record can hold, such as a VAT number: every member can see them, and owners and admins add and delete them. Values arrive through the API, and deleting a field keeps the values stored under its key. Its OAuth clients card, which only owners and admins see, registers an application with a client ID and a secret; Coritan does not run a customer sign-in for these clients yet. Add a custom field and Create an OAuth client explain both.

The Danger zone card at the bottom of General is the owner's. Its Transfer ownership row hands the organization to another member (Hand the organization to another member). Its Delete organization row lists what still stops a deletion, then deletes the organization (Delete an organization). Other members see who the owner is, and no buttons.

Your storefront, invoices and emails use the new details from the next page load, invoice or message.

That domain is in use on the platform.

Another organization has saved that custom domain. Use a domain of your own, or ask support if the domain is yours.

We did not find the record yet

The TXT record is not published, or DNS has not reached us yet. Check that the record's name and value match the card exactly, wait a while, then choose Check domain again. You can check 12 times an hour.

Another organization already connected this mailbox login.

One mailbox login belongs to one organization. Use a mailbox of your own.

This organization already receives ticket replies at a Coritan address.

Coritan runs a support address for your organization, and a mailbox of your own cannot be used beside it. Contact support to remove ours first.

Cannot sign in

The mail server refused the login. For Google Workspace, check that 2-step verification is on and make a new app password, then enter it under App password and choose Save changes. Google may lock an account that fails to sign in many times, so we stop reading until you save a new password.

Test the connection fails

The message on the card is what the server said. Check the IMAP server, that IMAP is turned on for the mailbox, and the App password. The port is always 993.

The status stays Waiting for confirmation

Check that your outgoing email works under Email sending, then choose Send the confirmation email again. The mailbox is a separate mailbox, not an alias, and your provider must deliver an address with a + tag to it. Google does.

The mailbox is already confirmed and active.

Send the confirmation email answers this once the mailbox is active. The API takes resend=1 to send it again.

We could not send the confirmation message.

Your outgoing email did not accept it. Fix Email sending, then try again. We also sign in before we send, so a refused login answers with the server's reason instead.

You hit a limit

You can save or remove the mailbox 20 times an hour, test it 10 times an hour and send 10 confirmation emails an hour. Each mail server also takes 30 checks an hour from your organization. Repeated failed sign-ins can lock a Google account, so wait before you try again.

A reply did not reach its ticket

Check that the status is Active and that the Last successful check is recent. Then check that the customer replied to the ticket email, so that the reply address with the code is in the message. A message from a customer with no code is added to the ticket only when Google reports that its sender checks passed.

mail tenant ... does not exist or ... is not a relay tenant

Check the Mail tenant name with support. It must be an SMTP Relay tenant, not a Mail Hosting one.

... is not a domain on mail tenant ...

Add the sending domain to the relay tenant and verify it first. See Add a sending domain to SMTP Relay.

Enter a Google Analytics 4 measurement ID: G- and then six to twenty letters or digits, such as G-ABC123DEF4.

The google_analytics field of the API got an ID that is not a Google Analytics 4 one. Copy it from your web stream in Google Analytics, under Admin, then Data streams. An older UA- ID does not work.

Add the measurement ID before turning Google Analytics on.

The same field was sent enabled: true with no ID, saved or sent.

The card says the in-house route is not ready

Read the reason on the card. Usually the sending domain's records have not verified yet. With In-house, SMTP as fallback, mail keeps flowing through SMTP meanwhile. With In-house only, or with no SMTP host on your organization or on Coritan, we send no verification or password reset emails until the route is ready, and POST /auth/resend-verification answers email_unavailable.

• Organization billing
• Create organization API keys
• Receive organization webhooks
• Delete an organization
• How SMTP Relay works

The changes need an owner's or admin's access token, sent as Authorization: Bearer $CORITAN_TOKEN. Any member can read the settings.

PATCH /api/v1/orgs/{org_slug} changes the organization itself: name (2–255 characters) and billing_mode (platform_mor, own_gateway or hybrid).

GET /api/v1/orgs/{org_slug}/settings reads the settings, and PATCH on the same path changes only the fields you send:

The answer leaves out smtp_pass and says with smtp_pass_set whether one is stored. It also carries custom_domain_verified, domain_verification, domain_pointing, features, self_serve_downgrade_credit and self_serve_cancellation_credit, which Coritan sets, except features.google_analytics and features.tags, which you set yourself. Send null to clear a field, except primary_color, secondary_color, invoice_prefix, default_currency, tax_rate, payment_terms_days, timezone and smtp_port, which always need a value: null for one of them answers 422 with a sentence that names it, such as timezone cannot be null., and saves nothing.

mail_outbound is merged into the transport you have saved, so you can send only the keys that change. The result must still name one of your relay tenants and a domain on it unless its transport is smtp; otherwise the answer is 422 with the reason, and nothing is saved. google_analytics is merged the same way: its measurement_id must be a Google Analytics 4 ID (G- and six to twenty letters or digits), null or "" removes it, and enabled: true needs an ID, saved or sent. Each change is recorded in the audit log as settings.updated, with the names of the fields you sent but not their values; a Google Analytics change also records the ID and whether it is on.

curl -X PATCH "https://api.coritan.com/api/v1/orgs/acme/settings" \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"support_email": "help@example.com", "invoice_prefix": "ACME-", "payment_terms_days": 14}'

The dashboard checks each value before it saves; the API stores what you send, so check currencies, rates and colours yourself. A custom_domain another organization has saved answers 409 That domain is in use on the platform.

domain_verification is the record that proves you hold the custom domain, such as {"type": "TXT", "name": "_coritan-org.portal.example.com", "value": "..."}, or null without a custom domain. Once it is published, check it:

curl -X POST "https://api.coritan.com/api/v1/orgs/acme/settings/custom-domain/verify" \
  -H "Authorization: Bearer $CORITAN_TOKEN"

The answer is the settings, as GET answers them, and custom_domain_verified says whether the check passed. It answers 422 Set a custom domain first. without a custom domain, 409 when the domain changed during the check, and 429 past 12 checks an hour.

domain_pointing says whether Coritan serves your storefront on the custom domain, such as {"served": false, "storefront_host": "shop.example.com"}. storefront_host is the host name your storefront is served on, or null when Coritan does not host it.

GET /api/v1/orgs/{org_slug}/settings/mail-outbound answers the saved transport with effective, the route mail takes now (such as own SMTP, platform SMTP or in-house), smtp_configured, and an inhouse object with ready and a reason when it is not.

GET /api/v1/orgs/{org_slug}/staff/settings/email-design reads the email design, and only owners and admins may call it. It answers the saved design, the defaults an empty field falls back to (accent_color, logo_url, each theme's colours in palettes, and has_address) and the options each field takes. PATCH on the same path changes only the fields you send: theme (light or dark), accent_color, background_color, surface_color (the card), text_color, radius (sharp, soft or round), font (system, inter or plex), header (auto, mark_and_name, logo or name), logo_url, footer_text, links (a list of label and url) and show_address. Send null to return a field to its default. A value it cannot use answers 400 with a sentence that names the field, such as Accent color must be six hex digits after #, such as #1ad76f, and saves nothing.

curl -X PATCH "https://api.coritan.com/api/v1/orgs/acme/staff/settings/email-design" \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"theme": "light", "radius": "round", "header": "logo", "footer_text": "Hosting from Lyon."}'

POST /api/v1/orgs/{org_slug}/staff/settings/email-design/preview takes an email_design (the fields above, or null for the saved design) and a sample (welcome, invoice, action or reply), and answers the sample email as HTML. POST /api/v1/orgs/{org_slug}/staff/settings/email-design/test takes the same body, sends that email to your own address and answers sent, to and sample. It answers 429 past 10 tests an hour.

These calls need an owner's or admin's access token. A write needs a fresh confirmation of your password, made in the last ten minutes, and each one is recorded in the audit log as settings.support_mailbox.updated, .deleted, .tested or .verification_sent, with the names of the fields and never the password.

GET /api/v1/orgs/{org_slug}/settings/support-mailbox reads it. The answer holds configured, presets (the providers: key, label, imap_host and imap_port) and mailbox, which is null until one is saved, and after a removal. A saved mailbox has:

PUT on the same path saves it and answers like GET. It does not sign in. Send:

• address (required): the mailbox, such as tickets@example.com.
• preset: gmail (the default) or other.
• imap_host and imap_port: for other, the server and 993. The gmail preset fixes imap.gmail.com.
• imap_password: required the first time. Leave it out to keep the stored one.
• imap_user: the login. It defaults to address.
• reply_local: the Reply address start. It defaults to the part of address before the @.

A new mailbox, or a change to the address, reply name, server, login or password, sets the status to pending and starts afresh: mail already in the mailbox is not imported. Saving the same details again after auth_failed or error puts the status back.

curl -X PUT "https://api.coritan.com/api/v1/orgs/acme/settings/support-mailbox" \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"preset": "gmail", "address": "tickets@example.com", "imap_password": "abcdefghijklmnop"}'

A value we cannot use answers 422 with detail.field and detail.message: a bad address, a provider that is not in presets, a port other than 993, a missing password, or a server that is not a public mail server. It answers 409 with detail.error set to hosted_ticket_address when Coritan runs a ticket address for your organization, and to login_in_use when another organization uses the login.

POST /api/v1/orgs/{org_slug}/settings/support-mailbox/test signs in, opens the inbox and changes nothing. It tests the saved login. A body with any of preset, imap_host, imap_port, imap_user and imap_password tests that login instead, taking whatever you leave out from the saved mailbox, and saves nothing. It answers {"imap": {"ok": true, "message": "Signed in. The Inbox holds 42 messages.", "messages": 42}}, with ok false and the server's reason in message when the sign-in fails, 404 when there is nothing to test, and 429 past 10 tests an hour.

POST /api/v1/orgs/{org_slug}/settings/support-mailbox/verify signs in, then sends the confirmation email through your organization's outgoing email, and answers {"sent": true, "address": "tickets@example.com"}. The status becomes active when we read that email from the mailbox. It answers 404 with no saved mailbox, and 409 with detail.error set to already_verified (add ?resend=1 to send it again), login_failed, changed or not_sent. It allows 10 a hour.

DELETE /api/v1/orgs/{org_slug}/settings/support-mailbox stops reading the mailbox, deletes the saved password and answers {"ok": true}. It is not an error when no mailbox is saved. Replies we already added stay on their tickets.