Manage customer services

A customer service is one product a customer holds at one price. Services appear when customers order on your storefront, and you can also order one for a customer yourself, for example to replace a service or to set up a customer by hand. Services lists every service your customers hold, and each service has a page where your team suspends it, restores it, tags it or cancels it.

Any member can open the list and a service's page. What else each task needs:

When the dashboard asks you to confirm it is you, enter your Coritan password in Confirm it is you or, when your account has two-factor sign-in, a code from your authenticator or a recovery code, then select Confirm. Manage customers explains it.

To order, you need an active customer and a product that is on sale, with at least one plan on sale. See Set up products and pricing.

1. In the dashboard, open the organization, then Customers, then Services.
2. Type in Search hostname, customer or tag. The search also matches the customer's email or company, the product or plan name and the service number.
3. Choose a status in Any status, or a product in Any product.
4. Select a column heading to sort the services on the page by it.
5. Select a service to open its page.

The list shows 50 services to a page, newest first. Each row shows the service's hostname and product, its Status, its Customer, its Price with the plan, and when it Renews, or the day it ends once it is cancelled at the end of its term. The search, the filters, the sort and the page stay in the page's address, so a reload or a link you share opens the list as you left it, and All services on a service's page takes you back to it. When nothing matches, Reset filters shows every service again.

A customer's page links to their services with the list filtered to them. The filter shows as a button with the customer's name, and selecting it shows every customer's services again. View services on a product's page opens the list filtered to that product. Like the other filters, the product filter looks through every service, and each status in Any status then counts that product's services.

The heading shows the service's hostname, or its number when it has none, with its status, the product and plan, the customer, the day it was ordered and its number. A note under it says when the service is suspended, when it is being cancelled, or the day it ends.

Service

The Product, which opens the product's page, the Plan, Price and Billing cycle, when it is Next due, or the day it Ends on once it is cancelled at the end of its term, when it was Ordered and Set up, and the Platform service: the Coritan service behind a linked product, or Not set up when there is none. Below come the settings it was ordered with, under Configuration.

Customer

The customer's Name, Email and Status. Open customer opens their page.

Tags

The labels your team searches by, as Tag a service describes.

The actions are at the top of the page: Suspend… or Unsuspend, and the service's actions menu with Open in the staff console and Cancel service…. Each appears only to the roles that can use it. Once your storefront has a domain, Open in the staff console opens the service's order in the staff console in a new tab (Look after an order).

A service cancelled at the end of its term keeps its status until that day, with an Ending badge beside it.

Tags are short labels your team searches by, such as vip or eu-west. The search on Services matches them.

1. Open the service. The Tags card lists its tags.
2. Type in New tag, then press Enter or select Add tag. We save the tag in lowercase, with hyphens for spaces.
3. To take a tag off, select the remove button on it.

A tag takes letters, digits, hyphens and underscores, up to 128 characters, and starts with a letter or a digit. A service takes up to 50 tags.

Ordering opens a page with the heading Order a service. Only owners and admins can use it; anyone else who opens its address sees "Ordering a service needs an owner or admin" and a link back.

1. On Services, select Order service…. From a customer's page, choose Order service… in their actions menu instead, or select it on their Services card while they have none, and the customer is chosen for you.
2. Under Customer, choose the customer. When you have many customers, type in Find a customer to search for them. Only active customers can be chosen.
3. Under Product, choose a product that is on sale. A product with no plan on sale is greyed out and says so.
4. Under Plan, choose one of the product's plans on sale. Each card shows its price and billing cycle, such as €15.99/mo.
5. Enter a Hostname if you want one, up to 100 characters. It is the name the service goes by in lists and on the customer's account, or the hostname for a server.
6. Check the This order card beside the form, which names the customer, the product, the plan, the price and the hostname, then select Order service.

The service's page opens, and the service starts as Pending. Cancel or the back link returns you to the list or the customer you came from, with its filters as you left them. If the order is refused, an alert titled "Could not order the service" gives the reason and every choice stays as you made it.

For a linked product, Coritan starts setting it up straight away, on your Coritan account. Coritan charges your organization for it below its list price: for a compute service on the Usage billing basis, by what the server uses, from the day it starts, and otherwise its wholesale price each time the customer's invoice for it is paid (what the hosting costs you). An order placed here counts like any other order. Ordering here does not charge the customer. Your webhooks receive service.ordered once the order is saved; an order that fails is never announced.

1. Open the service and select Suspend….
2. Confirm with Suspend service.

The service stops for the customer, and for a linked product Coritan suspends what it runs on. No renewal invoice is raised for it while it is suspended. The customer receives your organization's suspension email, and your webhooks receive service.suspended.

To restore it, select Unsuspend. It needs no confirmation. The service becomes Active again, what it runs on starts again, the customer receives your organization's email that it is back, and your webhooks receive service.unsuspended.

Cancelling opens one page with the heading Cancel this service, whether the service ends at the end of its term or now.

1. Open the service and choose Cancel service… in its actions menu. The entry is there for Tier 3 support and above.
2. Under When, choose At the end of its term or Now. A choice your role cannot use, or that does not fit the service, is greyed out and says why: ending now needs an owner or admin, and a service already set to end offers only Now.
3. Read What happens and the This cancellation card beside the form, then choose the reason as the next two sections describe.
4. Select Cancel at end of term or Cancel service now. Keep service and the back link leave without cancelling.

A service that has already ended has nothing to cancel, so its cancel page says so and offers no form.

Tier 3 support and above can choose At the end of its term.

1. Under When, keep At the end of its term.
2. Read what happens: the service keeps running, or stays suspended, until the end of the term the customer paid for, and is not renewed. The page says whether it is then removed or moves to your free plan at no charge, when your organization sells one.
3. Enter a Reason if you like. It is kept in the audit log, and the customer does not see it.
4. Select Cancel at end of term.

The dashboard confirms the day it ends and opens the service, which shows Ending until then. Its unpaid invoices are cancelled straight away (an unpaid invoice that also bills other services drops only this service's lines and keeps the rest), and the customer receives an email that says the day it ends.

Owners and admins can choose Now.

1. Under When, choose Now.
2. Under Why it ends now, choose Abuse or fraud, Refunded already, Not paid for or The customer asked. The page asks for one before it goes on.
3. Under Customer email, tick Email the customer that it ended if they should hear from you. Leave it off for abuse or fraud.
4. Select Cancel service now. A confirmation asks you to type the service's name, which is its hostname, or its number for a service without one, such as Service #12. Then select Cancel service.
5. Confirm it is you if the dashboard asks.

An unpaid invoice that also bills other services, such as a basket of store items, is not cancelled: it drops this service's lines, and its total is worked out again for the rest.

The service shows Cancelling while what it ran on is deleted, then Cancelled. The reason is kept in the audit log.

Customer not found or inactive

The customer is suspended or closed. Set their status back to Active on their page under Customers first.

Product not found or inactive or Pricing plan not found or inactive

The product is hidden, or the plan is retired. Check them under Catalogue, then Products.

Your organization cannot sell the free plan. Contact support to have it switched on.

The product is linked to Coritan's free plan, which only organizations Coritan has allowed can sell.

Service limit reached (500/500)

Your organization holds as many services as Coritan allows it. Ask support to raise the limit.

Service is not active or Service is not suspended

Only an active service can be suspended, and only a suspended one unsuspended.

422 with errors

For a linked server or instance, the location or the configuration cannot be ordered, for example because the location has no capacity. The message names the problem.

• Set up products and pricing
• Manage customers
• Manage customer invoices
• Handle billing in the staff console

List services, newest first. The query takes q, status_filter, customer_id, org_product_id, tag, limit, offset and with_total=true, as the customer list does. With with_total=true, counts holds each status for the same customer, product, tag and search, whatever status_filter says. Another organization's customer or product matches nothing, and an org_product_id that is not a whole number above zero answers 422. Each service carries its product_name, plan_name, currency, and its customer's customer_name, customer_email and customer_status.

curl "https://api.coritan.com/api/v1/orgs/acme/services?customer_id=812&status_filter=active" \
  -H "Authorization: Bearer $CORITAN_TOKEN"

Order a service with customer_id, org_product_id and org_pricing_id, and optionally hostname (up to 100 characters) and config for a linked product that takes options:

curl -X POST https://api.coritan.com/api/v1/orgs/acme/services \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": 812, "org_product_id": 5, "org_pricing_id": 11, "hostname": "survival-smp"}'

The answer is 201 with the service, including status, billing_cycle, amount, platform_service_id and next_due_date. Read one with GET /services/{service_id}, and suspend or restore it with POST /services/{service_id}/suspend and POST /services/{service_id}/unsuspend.

The cancellations use the staff routes, which a member's access token reaches too:

• GET /staff/services/{service_id}/cancel-preview?immediate=false says what a cancellation at the end of the term leads to: falls_back_to_free and free_plan_name when it moves to your free plan.
• POST /staff/services/{service_id}/cancel with {"immediate": false, "reason": "Not needed any more"} cancels at the end of the term and answers the termination_date. Tier 3 support and above.
• POST /staff/services/{service_id}/terminate with a reason of 3–500 characters and notify_customer (false by default) ends the service now with no credit. It takes an admin, and answers 403 with reauth_required until you have confirmed it is you in the last 10 minutes, as the customer routes describe.

The Tags card on a service page uses these routes. {source_type} is org_service for a customer service, and the tag API also takes vps for a Cloud Compute instance and container_server.

• GET /tags/vocabulary?source_type=org_service lists every tag in use.
• GET /tags/sources/org_service/{service_id} reads a service's tags.
• POST on the same path with {"tag": "vip"} adds one, and PUT with {"tags": ["vip", "eu"]} replaces them all.
• DELETE /tags/sources/org_service/{service_id}/vip removes one.