Skip to main content
POST
/
contract_v2
/
{contract_id}
/
phases
Create contract phase
curl --request POST \
  --url https://api.zenskar.com/contract_v2/{contract_id}/phases \
  --header 'Content-Type: application/json' \
  --header 'organisation: <api-key>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "Standard Phase",
  "description": "<string>",
  "start_date": "2023-11-07T05:31:56Z",
  "end_date": "2023-11-07T05:31:56Z",
  "pricings": [
    {
      "pricing_id": "6cd431e4-d3d4-43dc-b0c4-9c6988a6c1b3",
      "product_id": "c19a0ece-63c3-412b-8549-e722bc28605d"
    }
  ],
  "features": {
    "pricing_data": {
      "unit_amount": 123,
      "dimensions": [
        {
          "name": "<string>",
          "column_name": "<string>"
        }
      ],
      "prices": [
        1
      ],
      "display_alias": [
        "<string>"
      ],
      "pricing_type": "<string>",
      "currency": "<string>",
      "label": "<string>",
      "unit": "<string>",
      "pricing_period": {
        "cadence": "<string>"
      }
    },
    "name": "<string>",
    "description": "<string>",
    "quantity": {
      "type": "metered",
      "label": "<string>",
      "quantity": 123,
      "unit": "<string>",
      "aggregate_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "quantity_entries": [
        {
          "value": 123,
          "effective_from": "2023-12-25",
          "created_at": "2023-11-07T05:31:56Z",
          "description": "<string>"
        }
      ],
      "trigger_event": "invoice_approval",
      "expires_at": "end_of_product_billing_period",
      "expiry_period": "<string>",
      "grant_frequency_same_as_product": true,
      "grant_frequency": "<string>",
      "feature_option_value": "<string>",
      "numeric_value": 123,
      "allow_mid_cycle_cancellation": false,
      "constraints": {
        "min": 1,
        "max": 1
      }
    },
    "grants": [
      {
        "unit_amount": 123,
        "entitlement_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "type": "Feature",
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "identifier": "<string>",
        "priority": 123,
        "label": "<string>",
        "trigger_event": "invoice_approval",
        "expires_at": "end_of_product_billing_period",
        "expiry_period": "<string>",
        "grant_frequency_same_as_product": true,
        "grant_period": "<string>",
        "unit": "<string>",
        "period": {
          "cadence": "<string>"
        },
        "start_date": "2023-11-07T05:31:56Z",
        "feature_option_value": "<string>",
        "numeric_value": 123
      }
    ],
    "consumptions": [
      {
        "entitlement_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "type": "Feature",
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "identifier": "<string>",
        "priority": 123,
        "label": "<string>",
        "unit": "<string>",
        "show_additional_info": false,
        "trigger_event": "invoice_approval"
      }
    ],
    "link_id": "<string>",
    "free_units": [
      {
        "unit_amount": 123,
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "identifier": "<string>",
        "priority": 123,
        "label": "<string>",
        "unit": "<string>",
        "period": {
          "cadence": "<string>"
        }
      }
    ],
    "discounts": [
      {
        "type": "fixed",
        "unit_amount": 123,
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "identifier": "<string>",
        "priority": 123,
        "pricing_period": {
          "cadence": "<string>"
        },
        "label": "<string>"
      }
    ],
    "commitments": [
      {
        "type": "minimum_spend",
        "unit_amount": 123,
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "identifier": "<string>",
        "priority": 123,
        "currency": "<string>",
        "label": "<string>",
        "period": {
          "cadence": "<string>"
        },
        "charge_full_amount": false,
        "skip_zero_amount": false
      }
    ],
    "taxes": [
      {
        "type": "manual",
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "identifier": "<string>",
        "priority": 123,
        "label": "<string>",
        "code": "<string>",
        "unit_amount": 123
      }
    ],
    "payment_terms": [
      {
        "payment_term_type": "on_approval",
        "due_days": 123,
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "identifier": "<string>",
        "priority": 123,
        "label": "<string>",
        "payment_term_mode": "relative",
        "last_day_of_month": false
      }
    ],
    "service_fees": [
      {
        "type": "fixed",
        "unit_amount": 1,
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "identifier": "<string>",
        "priority": 123,
        "pricing_period": {
          "cadence": "<string>"
        },
        "label": "<string>"
      }
    ],
    "execution_logic": {
      "additional_steps": [
        {
          "node_type": "<string>",
          "inputs": {},
          "step_name": "<string>",
          "id": "<string>"
        }
      ]
    },
    "is_recurring": true,
    "billing_period": {
      "offset": "prepaid",
      "cadence": "<string>"
    },
    "add_to_catalog": true,
    "usage_report_configs": [
      {
        "aggregate_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "config": {},
        "is_default": false,
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      }
    ],
    "overage_pricing": {
      "pricing_data": {
        "unit_amount": 123,
        "dimensions": [
          {
            "name": "<string>",
            "column_name": "<string>"
          }
        ],
        "prices": [
          1
        ],
        "display_alias": [
          "<string>"
        ],
        "pricing_type": "<string>",
        "currency": "<string>",
        "label": "<string>",
        "unit": "<string>",
        "pricing_period": {
          "cadence": "<string>"
        }
      },
      "name": "<string>",
      "description": "<string>",
      "quantity": {
        "type": "metered",
        "label": "<string>",
        "quantity": 123,
        "unit": "<string>",
        "aggregate_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "quantity_entries": [
          {
            "value": 123,
            "effective_from": "2023-12-25",
            "created_at": "2023-11-07T05:31:56Z",
            "description": "<string>"
          }
        ],
        "trigger_event": "invoice_approval",
        "expires_at": "end_of_product_billing_period",
        "expiry_period": "<string>",
        "grant_frequency_same_as_product": true,
        "grant_frequency": "<string>",
        "feature_option_value": "<string>",
        "numeric_value": 123,
        "allow_mid_cycle_cancellation": false,
        "constraints": {
          "min": 1,
          "max": 1
        }
      },
      "grants": [
        {
          "unit_amount": 123,
          "entitlement_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "type": "Feature",
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "identifier": "<string>",
          "priority": 123,
          "label": "<string>",
          "trigger_event": "invoice_approval",
          "expires_at": "end_of_product_billing_period",
          "expiry_period": "<string>",
          "grant_frequency_same_as_product": true,
          "grant_period": "<string>",
          "unit": "<string>",
          "period": {
            "cadence": "<string>"
          },
          "start_date": "2023-11-07T05:31:56Z",
          "feature_option_value": "<string>",
          "numeric_value": 123
        }
      ],
      "consumptions": [
        {
          "entitlement_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "type": "Feature",
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "identifier": "<string>",
          "priority": 123,
          "label": "<string>",
          "unit": "<string>",
          "show_additional_info": false,
          "trigger_event": "invoice_approval"
        }
      ],
      "link_id": "<string>",
      "free_units": [
        {
          "unit_amount": 123,
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "identifier": "<string>",
          "priority": 123,
          "label": "<string>",
          "unit": "<string>",
          "period": {
            "cadence": "<string>"
          }
        }
      ],
      "discounts": [
        {
          "type": "fixed",
          "unit_amount": 123,
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "identifier": "<string>",
          "priority": 123,
          "pricing_period": {
            "cadence": "<string>"
          },
          "label": "<string>"
        }
      ],
      "commitments": [
        {
          "type": "minimum_spend",
          "unit_amount": 123,
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "identifier": "<string>",
          "priority": 123,
          "currency": "<string>",
          "label": "<string>",
          "period": {
            "cadence": "<string>"
          },
          "charge_full_amount": false,
          "skip_zero_amount": false
        }
      ],
      "taxes": [
        {
          "type": "manual",
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "identifier": "<string>",
          "priority": 123,
          "label": "<string>",
          "code": "<string>",
          "unit_amount": 123
        }
      ],
      "payment_terms": [
        {
          "payment_term_type": "on_approval",
          "due_days": 123,
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "identifier": "<string>",
          "priority": 123,
          "label": "<string>",
          "payment_term_mode": "relative",
          "last_day_of_month": false
        }
      ],
      "service_fees": [
        {
          "type": "fixed",
          "unit_amount": 1,
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "identifier": "<string>",
          "priority": 123,
          "pricing_period": {
            "cadence": "<string>"
          },
          "label": "<string>"
        }
      ],
      "execution_logic": {
        "additional_steps": [
          {
            "node_type": "<string>",
            "inputs": {},
            "step_name": "<string>",
            "id": "<string>"
          }
        ]
      },
      "is_recurring": true,
      "billing_period": {
        "offset": "prepaid",
        "cadence": "<string>"
      },
      "add_to_catalog": true,
      "usage_report_configs": [
        {
          "aggregate_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "config": {},
          "is_default": false,
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        }
      ],
      "products": [
        {
          "product_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "product_pricing_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "product_pricing_data": "<unknown>"
        }
      ]
    },
    "products": [
      {
        "product_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "product_pricing_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "product_pricing_data": "<unknown>"
      }
    ]
  },
  "source_plan_phase_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "phase_type": "active",
  "phase_metadata": {}
}
'
{
  "name": "<string>",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "contract_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "description": "<string>",
  "start_date": "2023-11-07T05:31:56Z",
  "end_date": "2023-11-07T05:31:56Z",
  "features": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "pricing_data": {
      "unit_amount": 123,
      "dimensions": [
        {
          "name": "<string>",
          "column_name": "<string>"
        }
      ],
      "prices": [
        1
      ],
      "display_alias": [
        "<string>"
      ],
      "pricing_type": "<string>",
      "currency": "<string>",
      "label": "<string>",
      "unit": "<string>",
      "pricing_period": {
        "cadence": "<string>"
      }
    },
    "name": "<string>",
    "description": "<string>",
    "quantity": {
      "type": "metered",
      "label": "<string>",
      "quantity": 123,
      "unit": "<string>",
      "aggregate_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "quantity_entries": [
        {
          "value": 123,
          "effective_from": "2023-12-25",
          "created_at": "2023-11-07T05:31:56Z",
          "description": "<string>"
        }
      ],
      "trigger_event": "invoice_approval",
      "expires_at": "end_of_product_billing_period",
      "expiry_period": "<string>",
      "grant_frequency_same_as_product": true,
      "grant_frequency": "<string>",
      "feature_option_value": "<string>",
      "numeric_value": 123,
      "allow_mid_cycle_cancellation": false,
      "constraints": {
        "min": 1,
        "max": 1
      },
      "aggregate": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "<string>",
        "dataschema": "<string>",
        "aggregation_query": "<string>",
        "cust_agg_query": "<string>",
        "visual_query_builder": {},
        "datasource": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "created_at": "2023-11-07T05:31:56Z"
      }
    },
    "grants": [],
    "consumptions": [],
    "link_id": "<string>",
    "free_units": [],
    "discounts": [],
    "commitments": [],
    "taxes": [],
    "payment_terms": [],
    "service_fees": [],
    "execution_logic": {
      "additional_steps": [
        {
          "node_type": "<string>",
          "inputs": {},
          "step_name": "<string>",
          "id": "<string>"
        }
      ]
    },
    "is_recurring": true,
    "billing_period": {
      "offset": "prepaid",
      "cadence": "<string>"
    },
    "add_to_catalog": true,
    "overage_pricing": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "pricing_data": {
        "unit_amount": 123,
        "dimensions": [
          {
            "name": "<string>",
            "column_name": "<string>"
          }
        ],
        "prices": [
          1
        ],
        "display_alias": [
          "<string>"
        ],
        "pricing_type": "<string>",
        "currency": "<string>",
        "label": "<string>",
        "unit": "<string>",
        "pricing_period": {
          "cadence": "<string>"
        }
      },
      "name": "<string>",
      "description": "<string>",
      "quantity": {
        "type": "metered",
        "label": "<string>",
        "quantity": 123,
        "unit": "<string>",
        "aggregate_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "quantity_entries": [
          {
            "value": 123,
            "effective_from": "2023-12-25",
            "created_at": "2023-11-07T05:31:56Z",
            "description": "<string>"
          }
        ],
        "trigger_event": "invoice_approval",
        "expires_at": "end_of_product_billing_period",
        "expiry_period": "<string>",
        "grant_frequency_same_as_product": true,
        "grant_frequency": "<string>",
        "feature_option_value": "<string>",
        "numeric_value": 123,
        "allow_mid_cycle_cancellation": false,
        "constraints": {
          "min": 1,
          "max": 1
        },
        "aggregate": {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "name": "<string>",
          "dataschema": "<string>",
          "aggregation_query": "<string>",
          "cust_agg_query": "<string>",
          "visual_query_builder": {},
          "datasource": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "created_at": "2023-11-07T05:31:56Z"
        }
      },
      "grants": [],
      "consumptions": [],
      "link_id": "<string>",
      "free_units": [],
      "discounts": [],
      "commitments": [],
      "taxes": [],
      "payment_terms": [],
      "service_fees": [],
      "execution_logic": {
        "additional_steps": [
          {
            "node_type": "<string>",
            "inputs": {},
            "step_name": "<string>",
            "id": "<string>"
          }
        ]
      },
      "is_recurring": true,
      "billing_period": {
        "offset": "prepaid",
        "cadence": "<string>"
      },
      "add_to_catalog": true,
      "usage_report_configs": []
    },
    "usage_report_configs": []
  },
  "pricings": [],
  "source_plan_phase_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "phase_type": "active",
  "phase_metadata": {}
}

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

Path Parameters

​
contract_id
string<uuid>
required

Body

application/json
​
name
string
default:Standard Phase
required

Human-readable name for this phase (e.g., 'Trial Period', 'Standard Pricing', 'Promotional Discount'). Used for identification in reports and UI.

​
description
string | null

Detailed description of what this phase represents, including any special terms, conditions, or business context.

​
start_date
string<date-time> | null

Date when this phase begins. Must be within contract date boundaries and not overlap with other phases. If not provided, inherits from contract start or previous phase end.

​
end_date
string<date-time> | null

Date when this phase ends. Must be after start_date and within contract boundaries. If not provided, phase continues until contract end or next phase start.

​
pricings
CreateContractPhasePricingRequestSchema · object[] | null

List of product-pricing associations for this phase. Each entry links a product with its specific pricing configuration, start/end dates, and any phase-specific terms.

​
features
CreateProductPricingRequestSchema · object

Optional feature pricing configuration applied to all products in this phase. Used for phase-wide features, add-ons, or entitlements.

​
source_plan_phase_id
string<uuid> | null

Reference to the plan phase template used to create this phase, if applicable. Maintains linkage for plan-based contracts.

​
phase_type
enum<string> | null

Type of phase indicating its purpose. 'active' for standard billing phases, 'trial' for trial periods, 'paused' for suspended phases.

Available options:
active,
pause,
trial
​
phase_metadata
Phase Metadata · object

Flexible key-value store for phase-specific metadata. Can include campaign codes, discount reasons, or any phase-specific tracking data.

Response

Successful Response

​
name
string
required

Human-readable name for this phase. Used for identification in reports and UI.

​
id
string<uuid>
required

Unique identifier for this contract phase

​
created_at
string<date-time>
required

Timestamp when this phase was created. Used for audit trails.

​
updated_at
string<date-time>
required

Timestamp of the last modification to this phase or its nested entities.

​
contract_id
string<uuid>
required

Unique identifier of the parent contract this phase belongs to

​
description
string | null

Detailed description of what this phase represents, including any special terms or conditions.

​
start_date
string<date-time> | null

Date when this phase begins. All billing and pricing in this phase start from this date.

​
end_date
string<date-time> | null

Date when this phase ends. Null indicates this phase continues until contract end or next phase start.

​
features
ProductPricingResponseSchema · object

Feature pricing configuration applied to all products in this phase, if applicable.

​
pricings
ContractPhasePricingResponseSchema · object[] | null

List of product-pricing associations active during this phase. Each defines a product, its pricing, and any phase-specific terms.

​
source_plan_phase_id
string<uuid> | null

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

​
phase_type
enum<string> | null
default:active

Type of phase indicating its purpose (e.g., active, trial, paused).

Available options:
active,
pause,
trial
​
phase_metadata
Phase Metadata · object

Phase-specific metadata stored as key-value pairs. Can include campaign codes, discount reasons, or tracking data.