Skip to main content

create-contract 

dci create-contract <customerID> [body]

Creates a draft contract for the specified customer. Requires the caller to be the direct parent (T1 for a T2-level contract, T2 for a T3-level contract). Write access requires a role without contractsReadOnly; user API tokens must include the matching permission in their scope.

  • customerID — The customer (tenant) the contract is created for.

Pass the request body as name: value arguments or pipe JSON on stdin — see Command structure.

Examples​

# Create a draft contract from a JSON file; activate it with `dci activate-contract`.
dci create-contract <customer-id> < contract.json
# contract.json
{"name": "Acme AWS resale FY27", "renewalPolicy": "auto",
  "startDate": "2026-10-01T00:00:00Z", "endDate": "2027-09-30T00:00:00Z",
  "doitInvoicingEnabled": true,
  "invoicesEmail": "[email protected]", "contractUpdatesEmail": "[email protected]"}
# The minimum inline body — name, renewal policy, and start date.
dci create-contract <customer-id> name: "Acme AWS resale FY27", renewalPolicy: manual, startDate: "2026-10-01T00:00:00Z"
# Keep the new `contractId` for the activate step, for scripts.
dci create-contract <customer-id> --fields contractId,status --output json < contract.json

Request​

Content-Type: application/json

FieldTypeRequiredDescription
templateIdstringID of a contract template owned by the authenticated tenant. When specified, the template's billing rules, price books, and custom line items are copied onto the new contract. Mutually exclusive with billingRules, priceBooks, and customLineItems in the request body.
namestringyes
startDatestring (date-time)yes
endDatestring (date-time)
renewalPolicystringyesOne of: "auto", "manual", "fixed".
doitInvoicingEnabledbooleanWhether DoiT generates invoices for this contract. Disabling suppresses invoice generation from that point forward while billing calculations and pipeline outputs continue. Omitting the field leaves invoicing enabled. Default: true.
invoicesEmailstring (email)Required for an end-customer contract with doitInvoicingEnabled set to true; optional otherwise.
contractUpdatesEmailstring (email)Required for an end-customer contract with doitInvoicingEnabled set to true; optional otherwise.
billingProfileobjectThe billing profile (name, country, state, city, address, zip). Required for an end-customer contract with doitInvoicingEnabled set to true; optional otherwise.
managementAccountsarray of string
billingRulesarray of object
priceBooksarray of object
customLineItemsarray of object
Raw JSON schema
{
  "allOf": [
    {
      "type": "object",
      "description": "Contract create/update payload. Full field-level validation is applied server-side.",
      "required": [
        "name",
        "startDate",
        "renewalPolicy"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "startDate": {
          "type": "string",
          "format": "date-time"
        },
        "endDate": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "renewalPolicy": {
          "type": "string",
          "enum": [
            "auto",
            "manual",
            "fixed"
          ]
        },
        "doitInvoicingEnabled": {
          "type": "boolean",
          "default": true,
          "description": "Whether DoiT generates invoices for this contract. Disabling suppresses invoice generation from that point forward while billing calculations and pipeline outputs continue. Omitting the field leaves invoicing enabled."
        },
        "invoicesEmail": {
          "type": "string",
          "format": "email",
          "description": "Required for an end-customer contract with doitInvoicingEnabled set to true; optional otherwise."
        },
        "contractUpdatesEmail": {
          "type": "string",
          "format": "email",
          "description": "Required for an end-customer contract with doitInvoicingEnabled set to true; optional otherwise."
        },
        "billingProfile": {
          "type": "object",
          "description": "The billing profile (name, country, state, city, address, zip). Required for an end-customer contract with doitInvoicingEnabled set to true; optional otherwise."
        },
        "managementAccounts": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "billingRules": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "priceBooks": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "customLineItems": {
          "type": "array",
          "items": {
            "type": "object"
          }
        }
      }
    },
    {
      "type": "object",
      "properties": {
        "templateId": {
          "type": "string",
          "description": "ID of a contract template owned by the authenticated tenant. When specified, the template's billing rules, price books, and custom line items are copied onto the new contract. Mutually exclusive with billingRules, priceBooks, and customLineItems in the request body."
        }
      }
    }
  ]
}

Output​

Created - The contract draft was created.

By default dci renders the result as a table. Use --output json to get the full structure described below — see Output formats.

FieldTypeDescription
contractIdstring
versioninteger
statusstring
messagestring
timestampstring (date-time)
Raw JSON schema
{
  "type": "object",
  "description": "The result of creating a contract or contract version.",
  "properties": {
    "contractId": {
      "type": "string"
    },
    "version": {
      "type": "integer"
    },
    "status": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "timestamp": {
      "type": "string",
      "format": "date-time"
    }
  }
}

Errors​

On failure, dci prints a single error message — with a hint when one is available — and exits with a typed code your scripts can branch on. See Errors and exit codes for the full contract.

HTTP status to exit code mapping
HTTP statusExit codeError codeMeaning
40030VALIDATION_ERRORThe arguments or request body were rejected. Review the command's flags and payload.
40110AUTHENTICATION_FAILEDNot signed in, or the API token is invalid. Run dci login or check DCI_API_KEY.
40311PERMISSION_DENIEDThe DoiT user or the active customer context does not have access.

Aliases: createcontract