Skip to main content
POST
/
contract_v2
curl --request POST \
  --url https://api.zenskar.com/contract_v2 \
  --header 'Content-Type: application/json' \
  --header 'organisation: <api-key>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "customer_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Annual Subscription - Acme Corp",
  "status": "active",
  "currency": "USD",
  "start_date": "2025-01-01T00:00:00Z",
  "end_date": "2025-12-31T23:59:59Z",
  "phases": [
    {
      "name": "Standard Phase",
      "start_date": "2025-01-01T00:00:00Z",
      "end_date": "2025-12-31T23:59:59Z"
    }
  ]
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "status": "draft",
  "currency": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "customer": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "external_id": "<string>",
    "customer_name": "<string>",
    "custom_data": {},
    "address": {
      "line1": "<string>",
      "line2": "<string>",
      "line3": "<string>",
      "city": "<string>",
      "state": "<string>",
      "zipCode": "<string>",
      "country": "<string>",
      "country_code": "<string>",
      "validation_status": "<string>",
      "connector_validation": {}
    },
    "ship_to_address": {
      "line1": "<string>",
      "line2": "<string>",
      "line3": "<string>",
      "city": "<string>",
      "state": "<string>",
      "zipCode": "<string>",
      "country": "<string>",
      "country_code": "<string>",
      "validation_status": "<string>",
      "connector_validation": {}
    },
    "tax_info": [],
    "email": "<string>",
    "custom_attributes": {},
    "phone_number": "<string>",
    "communications_enabled": true,
    "auto_charge_enabled": true,
    "business_entity_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "description": "<string>",
  "tags": [
    "<unknown>"
  ],
  "start_date": "2023-11-07T05:31:56Z",
  "end_date": "2023-11-07T05:31:56Z",
  "custom_attributes": {},
  "source": {},
  "anchor_date": "2023-11-07T05:31:56Z",
  "is_last_day_of_month": true,
  "plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "renewal_policy": "do_not_renew",
  "phases": [],
  "invoice_payer_customer": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "external_id": "<string>",
    "customer_name": "<string>",
    "custom_data": {},
    "address": {
      "line1": "<string>",
      "line2": "<string>",
      "line3": "<string>",
      "city": "<string>",
      "state": "<string>",
      "zipCode": "<string>",
      "country": "<string>",
      "country_code": "<string>",
      "validation_status": "<string>",
      "connector_validation": {}
    },
    "ship_to_address": {
      "line1": "<string>",
      "line2": "<string>",
      "line3": "<string>",
      "city": "<string>",
      "state": "<string>",
      "zipCode": "<string>",
      "country": "<string>",
      "country_code": "<string>",
      "validation_status": "<string>",
      "connector_validation": {}
    },
    "tax_info": [],
    "email": "<string>",
    "custom_attributes": {},
    "phone_number": "<string>",
    "communications_enabled": true,
    "auto_charge_enabled": true,
    "business_entity_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "current_phase": {
    "name": "<string>",
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "start_date": "2023-11-07T05:31:56Z",
    "end_date": "2023-11-07T05:31:56Z",
    "phase_type": "active",
    "phase_metadata": {}
  },
  "contract_link": "<string>",
  "bill_parent_customer": false,
  "invoice_payer_customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

Documentation Index

Fetch the complete documentation index at: https://docs2.zenskar.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
x-api-key
string
header
default:<your-api-key>
required
​
organisation
string
header
default:<your-organisation-id>
required

Body

application/json
​
name
string
default:Annual Subscription - Acme Corp
required

Human-readable name for the contract. Used for identification and reporting purposes.

​
status
enum<string>
default:active
required

Contract status. Only 'active' and 'draft' are accepted. Other statuses (expired, paused) are managed via dedicated endpoints.

Available options:
draft,
active,
paused,
expired,
disputed
​
currency
string
default:USD
required

Three-letter ISO 4217 currency code for all monetary amounts in this contract (e.g., 'USD', 'EUR', 'GBP'). Must match customer's billing currency or be explicitly configured.

​
start_date
string<date-time>
default:2025-01-01T00:00:00
required

Date when the contract becomes active and billing begins. Must be in ISO 8601 format. Used as the basis for billing cycle calculations and revenue recognition.

​
customer_id
string<uuid>
default:123e4567-e89b-12d3-a456-426614174000
required

The unique identifier of the customer who is party to this contract. Customer must exist in the system before contract creation.

​
id
string<uuid> | null

Optional contract ID to use. If not provided, one will be generated automatically.

​
description
string | null

Detailed description of the contract terms, scope, or special conditions. Displayed in contract details and reports.

​
tags
any[] | null

Optional list of tags for categorizing and filtering contracts (e.g., ['enterprise', 'annual', 'discounted']). Useful for reporting and segmentation.

​
end_date
string<date-time> | null

Optional date when the contract expires. If not provided, contract continues indefinitely until manually terminated. Must be after start_date. Used for automatic expiration and renewal calculations.

​
anchor_date
string<date-time>

Reference date for billing cycle calculations. When set, all billing cycles align to this date regardless of contract start. Useful for ensuring consistent billing dates across multiple contracts.

​
is_last_day_of_month
boolean | null

When true, billing cycles always end on the last day of the month, adjusting for varying month lengths. Commonly used for monthly subscriptions billed on the last day.

​
plan_id
string<uuid> | null

Optional reference to a predefined plan template. When provided, contract inherits phases, products, and pricing from the plan. Useful for standardized offerings.

​
custom_attributes
Custom Attributes · object

Flexible key-value store for organization-specific metadata. Can include fields like sales_rep, deal_id, region, or any custom data needed for reporting and integrations.

​
phases
CreateContractPhaseRequestSchema · object[] | null

List of contract phases defining distinct periods with different terms, products, or pricing. Common use cases include trial periods, promotional pricing, or stepped pricing models. Phases must not overlap and must fall within contract date boundaries.

​
renewal_policy
enum<string> | null

Defines contract renewal behavior. Currently only 'do_not_renew' is supported—contracts must be manually renewed or replaced. Additional renewal options coming soon.

Available options:
renew_with_default_contract,
renew_with_existing,
do_not_renew
​
contract_link
string | null

URL to external contract document, signed agreement, or related resource. Useful for maintaining references to legal documents stored in external systems.

​
bill_parent_customer
boolean | null

When true and customer has a parent relationship, invoices are sent to the parent customer instead. Used for hierarchical billing scenarios like subsidiaries or franchises.

​
invoice_payer_customer_id
string<uuid> | null

Optional customer ID who will receive and pay invoices for this contract, if different from the contract customer. Used when one entity uses services but another pays for them.

​
source
Source · object

Metadata about the originating system or process that created this contract. Commonly includes fields like 'system', 'opportunity_id', or 'contract_number' for integration tracking and audit trails.

Response

Contract created successfully

​
id
string<uuid>
required

Unique identifier for this contract

​
name
string
required

Human-readable name for the contract. Used for identification and reporting purposes.

​
status
enum<string>
required

Current status of the contract (e.g., active, draft, expired, terminated). System automatically updates to 'expired' when end_date is reached.

Available options:
draft,
active,
paused,
expired,
disputed
​
currency
string
required

Three-letter ISO 4217 currency code for all monetary amounts in this contract (e.g., 'USD', 'EUR', 'GBP').

​
created_at
string<date-time>
required

Timestamp when this contract was created in the system. Used for audit trails and reporting.

​
updated_at
string<date-time>
required

Timestamp of the last modification to this contract. Updates whenever any field or related entity changes.

​
customer_id
string<uuid>
required

Unique identifier of the customer who is party to this contract.

​
customer
CustomerResponseSchema · object
required

Complete customer details including name, contact information, and billing preferences. The customer who is party to this contract.

​
description
string | null

Detailed description of the contract terms, scope, or special conditions.

​
tags
any[] | null

List of tags for categorizing and filtering contracts. Useful for reporting and segmentation.

​
start_date
string<date-time> | null

Date when the contract became or will become active. Billing and revenue recognition calculations start from this date.

​
end_date
string<date-time> | null

Date when the contract expires. Null indicates an indefinite contract that continues until manually terminated.

​
custom_attributes
Custom Attributes · object

Organization-specific metadata stored as key-value pairs. Can include fields like sales_rep, deal_id, region, or any custom data needed for reporting and integrations.

​
source
Source · object

Metadata about the originating system or process that created this contract. Used for integration tracking and audit trails.

​
anchor_date
string<date-time>

Reference date for billing cycle calculations. When set, billing cycles align to this date regardless of contract start date.

​
is_last_day_of_month
boolean | null

When true, billing cycles always end on the last day of the month, adjusting for varying month lengths.

​
plan_id
string<uuid> | null

Reference to the plan template used to create this contract, if applicable.

​
renewal_policy
enum<string> | null
default:do_not_renew

Defines contract renewal behavior. Currently only 'do_not_renew' is supported—contracts must be manually renewed or replaced.

Available options:
renew_with_default_contract,
renew_with_existing,
do_not_renew
​
phases
ContractPhaseResponseSchema · object[] | null

List of contract phases defining distinct periods with different terms, products, or pricing. Sorted chronologically by start date.

​
invoice_payer_customer
CustomerResponseSchema · object

Customer details for the invoice payer, if different from the contract customer. Used when one entity uses services but another pays for them.

​
current_phase
PhaseDetails · object

The contract phase that is currently active based on today's date. Null if no phase is active or contract hasn't started.

​
contract_link
string | null

URL to external contract document, signed agreement, or related resource.

​
bill_parent_customer
boolean | null
default:false

When true and customer has a parent relationship, invoices are sent to the parent customer instead.

​
invoice_payer_customer_id
string<uuid> | null

Customer ID who will receive and pay invoices for this contract, if different from the contract customer.