Upgrade a service order's options

curl --request POST \
  --url https://api.clemta.com/v1/companies/{companyID}/service-orders/{orderID} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "options": {
    "turnaround": "expedited"
  },
  "accept_quote": true
}
'

import requests

url = "https://api.clemta.com/v1/companies/{companyID}/service-orders/{orderID}"

payload = {
    "options": { "turnaround": "expedited" },
    "accept_quote": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({options: {turnaround: 'expedited'}, accept_quote: true})
};

fetch('https://api.clemta.com/v1/companies/{companyID}/service-orders/{orderID}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.clemta.com/v1/companies/{companyID}/service-orders/{orderID}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'options' => [
        'turnaround' => 'expedited'
    ],
    'accept_quote' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.clemta.com/v1/companies/{companyID}/service-orders/{orderID}"

	payload := strings.NewReader("{\n  \"options\": {\n    \"turnaround\": \"expedited\"\n  },\n  \"accept_quote\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.clemta.com/v1/companies/{companyID}/service-orders/{orderID}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"options\": {\n    \"turnaround\": \"expedited\"\n  },\n  \"accept_quote\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.clemta.com/v1/companies/{companyID}/service-orders/{orderID}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"options\": {\n    \"turnaround\": \"expedited\"\n  },\n  \"accept_quote\": true\n}"

response = http.request(request)
puts response.read_body

{
  "object": "service_order",
  "id": "so_0346sFPEvSkJvY8vt14NNw",
  "company": "<string>",
  "product_key": "ein",
  "status": "received",
  "unit_amount": 7900,
  "currency": "usd",
  "created_at": "2023-11-07T05:31:56Z",
  "interval": "one_time",
  "options": {
    "llc_members": "multi_member"
  },
  "form_required": true,
  "workflow_status": "<string>",
  "form": {
    "fields": [
      {
        "field_name": "<string>",
        "field_type": "text",
        "key": "<string>",
        "required": true,
        "options": [
          "<string>"
        ],
        "guidance": "<string>",
        "help": "<string>",
        "note": "<string>",
        "placeholder": "<string>",
        "info_points": [
          "<string>"
        ],
        "conditional": {
          "field": "<string>",
          "values": [
            "<string>"
          ]
        },
        "validation": {
          "pattern": "<string>",
          "min_length": 123,
          "max_length": 123,
          "min": 123,
          "max": 123
        },
        "file": {
          "accepted_types": [
            "<string>"
          ],
          "max_size_bytes": 123
        }
      }
    ],
    "title": "<string>",
    "warning": "<string>"
  },
  "quote": {
    "state": "pending",
    "unit_amount": 123,
    "currency": "<string>",
    "quoted_at": "2023-11-07T05:31:56Z",
    "expires_at": "2023-11-07T05:31:56Z",
    "accepted_at": "2023-11-07T05:31:56Z"
  },
  "shareholder": "<string>",
  "outcome": "<string>",
  "included_in": "<string>",
  "fees": [
    {
      "kind": "state_fee",
      "unit_amount": 30000,
      "currency": "usd"
    }
  ],
  "next_renewal_at": "2023-11-07T05:31:56Z",
  "renewal_cancel_requested_at": "2023-11-07T05:31:56Z",
  "renewal_canceled_at": "2023-11-07T05:31:56Z",
  "renewal_ends_at": "2023-11-07T05:31:56Z",
  "canceled_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z"
}

{
  "type": "https://docs.clemta.com/partner/errors#resource_already_exists",
  "title": "<string>",
  "status": 349,
  "code": "api_key_invalid",
  "detail": "<string>",
  "request_id": "<string>",
  "errors": [
    {
      "reason": "<string>",
      "location": "<string>",
      "validation_type": "<string>",
      "how_to_fix": "<string>"
    }
  ]
}

{
  "type": "https://docs.clemta.com/partner/errors#resource_already_exists",
  "title": "<string>",
  "status": 349,
  "code": "api_key_invalid",
  "detail": "<string>",
  "request_id": "<string>",
  "errors": [
    {
      "reason": "<string>",
      "location": "<string>",
      "validation_type": "<string>",
      "how_to_fix": "<string>"
    }
  ]
}

{
  "type": "https://docs.clemta.com/partner/errors#resource_already_exists",
  "title": "<string>",
  "status": 349,
  "code": "api_key_invalid",
  "detail": "<string>",
  "request_id": "<string>",
  "errors": [
    {
      "reason": "<string>",
      "location": "<string>",
      "validation_type": "<string>",
      "how_to_fix": "<string>"
    }
  ]
}

{
  "type": "https://docs.clemta.com/partner/errors#resource_already_exists",
  "title": "<string>",
  "status": 349,
  "code": "api_key_invalid",
  "detail": "<string>",
  "request_id": "<string>",
  "errors": [
    {
      "reason": "<string>",
      "location": "<string>",
      "validation_type": "<string>",
      "how_to_fix": "<string>"
    }
  ]
}

{
  "type": "https://docs.clemta.com/partner/errors#resource_already_exists",
  "title": "<string>",
  "status": 349,
  "code": "api_key_invalid",
  "detail": "<string>",
  "request_id": "<string>",
  "errors": [
    {
      "reason": "<string>",
      "location": "<string>",
      "validation_type": "<string>",
      "how_to_fix": "<string>"
    }
  ]
}

Service orders

Upgrade a service order's options

Changes an in-flight order’s variant choices and bills you the price DIFFERENCE - for example moving an ein order’s processing from standard to expedited after the fact. Only upgrades are accepted (the new choice must not price below the current one), the order must not be completed or canceled, and the product’s available_when must still hold for the company as it stands now - an ein upgrade is refused once the company’s EIN is recorded. One upgrade may stand at a time. Choices that add a companion service attach it automatically.

POST

companies

{companyID}

service-orders

{orderID}

Upgrade a service order's options

curl --request POST \
  --url https://api.clemta.com/v1/companies/{companyID}/service-orders/{orderID} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "options": {
    "turnaround": "expedited"
  },
  "accept_quote": true
}
'

import requests

url = "https://api.clemta.com/v1/companies/{companyID}/service-orders/{orderID}"

payload = {
    "options": { "turnaround": "expedited" },
    "accept_quote": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({options: {turnaround: 'expedited'}, accept_quote: true})
};

fetch('https://api.clemta.com/v1/companies/{companyID}/service-orders/{orderID}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.clemta.com/v1/companies/{companyID}/service-orders/{orderID}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'options' => [
        'turnaround' => 'expedited'
    ],
    'accept_quote' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.clemta.com/v1/companies/{companyID}/service-orders/{orderID}"

	payload := strings.NewReader("{\n  \"options\": {\n    \"turnaround\": \"expedited\"\n  },\n  \"accept_quote\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.clemta.com/v1/companies/{companyID}/service-orders/{orderID}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"options\": {\n    \"turnaround\": \"expedited\"\n  },\n  \"accept_quote\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.clemta.com/v1/companies/{companyID}/service-orders/{orderID}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"options\": {\n    \"turnaround\": \"expedited\"\n  },\n  \"accept_quote\": true\n}"

response = http.request(request)
puts response.read_body

{
  "object": "service_order",
  "id": "so_0346sFPEvSkJvY8vt14NNw",
  "company": "<string>",
  "product_key": "ein",
  "status": "received",
  "unit_amount": 7900,
  "currency": "usd",
  "created_at": "2023-11-07T05:31:56Z",
  "interval": "one_time",
  "options": {
    "llc_members": "multi_member"
  },
  "form_required": true,
  "workflow_status": "<string>",
  "form": {
    "fields": [
      {
        "field_name": "<string>",
        "field_type": "text",
        "key": "<string>",
        "required": true,
        "options": [
          "<string>"
        ],
        "guidance": "<string>",
        "help": "<string>",
        "note": "<string>",
        "placeholder": "<string>",
        "info_points": [
          "<string>"
        ],
        "conditional": {
          "field": "<string>",
          "values": [
            "<string>"
          ]
        },
        "validation": {
          "pattern": "<string>",
          "min_length": 123,
          "max_length": 123,
          "min": 123,
          "max": 123
        },
        "file": {
          "accepted_types": [
            "<string>"
          ],
          "max_size_bytes": 123
        }
      }
    ],
    "title": "<string>",
    "warning": "<string>"
  },
  "quote": {
    "state": "pending",
    "unit_amount": 123,
    "currency": "<string>",
    "quoted_at": "2023-11-07T05:31:56Z",
    "expires_at": "2023-11-07T05:31:56Z",
    "accepted_at": "2023-11-07T05:31:56Z"
  },
  "shareholder": "<string>",
  "outcome": "<string>",
  "included_in": "<string>",
  "fees": [
    {
      "kind": "state_fee",
      "unit_amount": 30000,
      "currency": "usd"
    }
  ],
  "next_renewal_at": "2023-11-07T05:31:56Z",
  "renewal_cancel_requested_at": "2023-11-07T05:31:56Z",
  "renewal_canceled_at": "2023-11-07T05:31:56Z",
  "renewal_ends_at": "2023-11-07T05:31:56Z",
  "canceled_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z"
}

{
  "type": "https://docs.clemta.com/partner/errors#resource_already_exists",
  "title": "<string>",
  "status": 349,
  "code": "api_key_invalid",
  "detail": "<string>",
  "request_id": "<string>",
  "errors": [
    {
      "reason": "<string>",
      "location": "<string>",
      "validation_type": "<string>",
      "how_to_fix": "<string>"
    }
  ]
}

{
  "type": "https://docs.clemta.com/partner/errors#resource_already_exists",
  "title": "<string>",
  "status": 349,
  "code": "api_key_invalid",
  "detail": "<string>",
  "request_id": "<string>",
  "errors": [
    {
      "reason": "<string>",
      "location": "<string>",
      "validation_type": "<string>",
      "how_to_fix": "<string>"
    }
  ]
}

{
  "type": "https://docs.clemta.com/partner/errors#resource_already_exists",
  "title": "<string>",
  "status": 349,
  "code": "api_key_invalid",
  "detail": "<string>",
  "request_id": "<string>",
  "errors": [
    {
      "reason": "<string>",
      "location": "<string>",
      "validation_type": "<string>",
      "how_to_fix": "<string>"
    }
  ]
}

{
  "type": "https://docs.clemta.com/partner/errors#resource_already_exists",
  "title": "<string>",
  "status": 349,
  "code": "api_key_invalid",
  "detail": "<string>",
  "request_id": "<string>",
  "errors": [
    {
      "reason": "<string>",
      "location": "<string>",
      "validation_type": "<string>",
      "how_to_fix": "<string>"
    }
  ]
}

{
  "type": "https://docs.clemta.com/partner/errors#resource_already_exists",
  "title": "<string>",
  "status": 349,
  "code": "api_key_invalid",
  "detail": "<string>",
  "request_id": "<string>",
  "errors": [
    {
      "reason": "<string>",
      "location": "<string>",
      "validation_type": "<string>",
      "how_to_fix": "<string>"
    }
  ]
}

Authorizations

Authorization

string

header

required

Your API key, e.g. Authorization: Bearer clmt_test_. Live keys use the clmt_live_ prefix.

Headers

Clemta-Version

string

Date-based API version to run this request against.

Example:

"2026-08-13"

Path Parameters

companyID

string

required

ID of the company.

Pattern: ^cmp_[0-9A-Za-z]{22}$

orderID

string

required

ID of the service order.

Pattern: ^so_[0-9A-Za-z]{22}$

Body

application/json

Two order actions share this endpoint: upgrading the order's options, and accepting a Clemta-set quote. Send exactly one of them.

options

object

The order's new variant choices, complete - the same shape the create call takes. Unchanged keys may be repeated. The change must not lower the price, and an option marked fixed in the catalog cannot change.

Show child attributes

Example:

{ "turnaround": "expedited" }

accept_quote

boolean

Accept the Clemta-set price on a quote_pending order. The quoted amount becomes the order's price and is billed at that moment. Refused before a price exists or after quote.expires_at. Idempotent once accepted.

Response

The upgraded service order, at its new price.

One product ordered on a company. Billed to you when created (or at each period end for arrears products). Reversed by a credit if cancelled before fulfilment starts. An active recurring order can be cancelled to stop renewing at the period end.

object

enum<string>

required

Entity name.

Available options:

service_order

string

required

Pattern: ^so_[0-9A-Za-z]{22}$

Example:

"so_0346sFPEvSkJvY8vt14NNw"

company

string

required

The company this order is on.

Pattern: ^cmp_[0-9A-Za-z]{22}$

product_key

string

required

Example:

"ein"

status

enum<string>

required

Fulfilment status, derived from where Clemta has the order: received until fulfilment starts (a cancellable state), quote_pending while a priced-by-quote product waits for the price and your acceptance (also cancellable - cancelling declines the quote), in_progress while Clemta works, requires_action while the current step waits on a form from you or your client (an open form requirement says which), completed once the final step is reached - terminal, completed_at is set and service_order.completed fires once - and canceled.

Available options:

received,

quote_pending,

in_progress,

requires_action,

completed,

canceled

unit_amount

integer<int64>

required

The wholesale price you were billed, in the currency's smallest unit (cents).

Example:

7900

currency

string

required

Example:

"usd"

created_at

string<date-time>

required

interval

enum<string>

Billing cadence - one_time, or recurring monthly/yearly.

Available options:

one_time,

monthly,

yearly

options

object

The variant choices this order was placed with (option key -> value).

Show child attributes

Example:

{ "llc_members": "multi_member" }

form_required

boolean

True when fulfilment needs a form from the client (e.g. an ITIN or BOI service). Known once the order reaches fulfilment.

workflow_status

string

The live fulfilment step (e.g. "Application In Progress", "Signature Request"). Present once the order is being fulfilled.

form

object

The form the current step is waiting on, when form_required is true - the fields to submit next via the form endpoint. Present on the single-order view.

Show child attributes

quote

object

The negotiated-price lifecycle on a product priced per order (for example, catch-up bookkeeping). pending until Clemta reviews the work and sets the amount, quoted while the price waits for your accept_quote, accepted once you took it and the charge landed. Nothing is billed before acceptance.

Show child attributes

shareholder

string

The company owner this order is for (products ordered per owner, e.g. an ITIN).

outcome

string

How a completed order ended, where completion alone does not say - a bank application's approved or declined, a good-standing check's not eligible. Recorded by Clemta. A decline is a delivered service, not a credit. Absent while the work runs and on orders whose completion is the whole answer.

included_in

string

Present when this order was attached by a bundle order (the formation's included services) - it names the bundle product. Included orders bill nothing of their own. A paid option choice bills only the difference.

fees

object[]

Pass-through lines this order carried beside unit_amount - the state's own charge and the processing fee, frozen at their order-time amounts. Each appears as its own line on your statement.

Show child attributes

next_renewal_at

string<date-time>

When the next period bills (for a product billed in arrears, the end of the running period). Only on recurring orders. Absent once renewals end.

renewal_cancel_requested_at

string<date-time>

When you requested cancellation. The request awaits a Clemta decision - renewals keep billing until it is approved. You hear the outcome as service_order.renewal_canceled or service_order.renewal_cancel_denied.

renewal_canceled_at

string<date-time>

When the cancellation was approved. The order stops billing at renewal_ends_at. Fulfilment status is unaffected.

renewal_ends_at

string<date-time>

The period end the service runs to after a renewal cancel. An arrears product still bills this period at that moment, then stops.

canceled_at

string<date-time>

completed_at

string<date-time>

When the order first reached completed. service_order.completed announces this moment, and it does not change afterward.

Identity

Accounts

Companies

Officers & directors

Products and pricing

Service orders

Tax filings

Fixed assets

Requirements

Verification and signing

Files

File links

Calendar

Status tracking

Events

Hosted links

Sandbox

Webhook events

Upgrade a service order's options

Authorizations

Headers

Path Parameters

Body

Response