---
title: "Update a contract"
method: PATCH
path: "/api/v1/contracts/{id}"
tags: ["Contracts"]
---

# Update a contract

`PATCH /api/v1/contracts/{id}`

Updates a contract's metadata (name, PO number, activation dates) and optionally re-links its subscriptions. Best-effort re-syncs the change to the connected billing provider.

## Path parameters

- `id` string, required

## Headers

- `X-ACCOUNT-ID` string
- `X-ENVIRONMENT-ID` string

## Request body

- UpdateContractRequestDto — Input for updating a contract and optionally re-linking its subscriptions.
  - `name` string, nullable — New contract name
  - `poNumber` string, nullable — New purchase-order number
  - `activationStartDate` string, date-time — New activation start date
  - `activationEndDate` string, date-time — New activation end date
  - `subscriptionIds` string[] — When provided, replaces the set of subscriptions linked to the contract (subscription ref IDs)
  - `setupBilling` boolean — Enable billing on a provision-access-only contract by creating a billing contract in the connected billing provider. Only takes effect when true and the contract has no billing yet; omitting it leaves billing unchanged. Billing is never removed by an update.

## Response `200`

The updated contract.

- ContractResponseDto — Response object
  - `data` object, required — A billing contract as reported by the connected billing provider.
    - `contractId` string, required — The Stigg contract ref ID (the key used to fetch/update/delete this contract)
    - `billingId` string, nullable, required — The billing provider (Received) contract ID; null until the contract has synced to the billing provider
    - `id` string, nullable, required — The persisted Stigg contract id (matches a subscription’s contractId; present for Stigg-managed contracts)
    - `refId` string, nullable, required — The Stigg contract ref ID (present for Stigg-managed contracts; the key used to update/delete)
    - `poNumber` string, nullable, required — Purchase-order number, when set on the contract
    - `externalId` string, required — The external identifier of the contract
    - `customerExternalId` string, nullable, required — The external identifier of the customer the contract belongs to
    - `name` string, nullable, required — The contract name (the purchase-order number when set, otherwise the contract/customer name)
    - `state` 'DRAFT' | 'ACTIVE' | 'CANCELED' | 'END_BILLING', required — The current state of the contract
    - `billingState` 'DRAFT' | 'ACTIVE' | 'CANCELED' | 'END_BILLING', nullable, required — The current state of the contract
    - `activationStartDate` string, date-time, nullable, required — The date the contract becomes active
    - `activationEndDate` string, date-time, nullable, required — The date the contract activation ends
    - `createdAt` string, date-time, nullable, required — The date the contract was created
    - `nextInvoice` object, nullable, required — A preview of the contract's upcoming invoice, or null when none is available
      - `amount` object, required — The total amount of the upcoming invoice
        - `amount` number, required — The price amount
        - `currency` 'usd' | 'aed' | 'all' | 'amd' | 'ang' | 'aud' | 'awg' | 'azn' | 'bam' | 'bbd' | 'bdt' | 'bgn' | 'bif' | 'bmd' | 'bnd' | 'bsd' | 'bwp' | 'byn' | 'bzd' | 'brl' | 'cad' | 'cdf' | 'chf' | 'cny' | 'czk' | 'dkk' | 'dop' | 'dzd' | 'egp' | 'etb' | 'eur' | 'fjd' | 'gbp' | 'gel' | 'gip' | 'gmd' | 'gyd' | 'hkd' | 'hrk' | 'htg' | 'idr' | 'ils' | 'inr' | 'isk' | 'jmd' | 'jpy' | 'kes' | 'kgs' | 'khr' | 'kmf' | 'krw' | 'kyd' | 'kzt' | 'lbp' | 'lkr' | 'lrd' | 'lsl' | 'mad' | 'mdl' | 'mga' | 'mkd' | 'mmk' | 'mnt' | 'mop' | 'mro' | 'mvr' | 'mwk' | 'mxn' | 'myr' | 'mzn' | 'nad' | 'ngn' | 'nok' | 'npr' | 'nzd' | 'pgk' | 'php' | 'pkr' | 'pln' | 'qar' | 'ron' | 'rsd' | 'rub' | 'rwf' | 'sar' | 'sbd' | 'scr' | 'sek' | 'sgd' | 'sle' | 'sll' | 'sos' | 'szl' | 'thb' | 'tjs' | 'top' | 'try' | 'ttd' | 'tzs' | 'uah' | 'uzs' | 'vnd' | 'vuv' | 'wst' | 'xaf' | 'xcd' | 'yer' | 'zar' | 'zmw' | 'clp' | 'djf' | 'gnf' | 'ugx' | 'pyg' | 'xof' | 'xpf', required — ISO 4217 currency code
      - `dueDate` string, date-time, nullable, required — The date the upcoming invoice is due
      - `periodStart` string, date-time, nullable, required — The start of the billing period the upcoming invoice covers
      - `periodEnd` string, date-time, nullable, required — The end of the billing period the upcoming invoice covers
    - `latestInvoice` object, nullable, required — The most recent non-draft invoice for this contract (open, paid, or canceled), or null when none exists
      - `billingId` string, required — Invoice billing ID
      - `status` 'OPEN' | 'CANCELED' | 'PAID', required — Invoice status
      - `createdAt` string, date-time, required — Invoice creation date
      - `total` number, nullable — Total amount
      - `amountDue` number, nullable — Amount due
      - `currency` string, nullable — Invoice currency
      - `pdfUrl` string, nullable — Invoice PDF URL
      - `requiresAction` boolean, required — Whether payment requires action
      - `billingReason` 'BILLING_CYCLE' | 'SUBSCRIPTION_CREATION' | 'SUBSCRIPTION_UPDATE' | 'MANUAL' | 'MINIMUM_INVOICE_AMOUNT_EXCEEDED' | 'OTHER', nullable — Billing reason
    - `subscriptions` object[], required — The custom subscriptions attached to this contract (empty when none)
      - `subscriptionId` string, required — The subscription ref ID (use it to deep-link to the subscription)
      - `planDisplayName` string, nullable, required — Display name of the subscription plan
      - `productDisplayName` string, nullable, required — Display name of the product the subscription plan belongs to

## Other responses

- `400` — bad request.
- `401` — User is not authenticated.
- `403` — User is not allowed to access this resource.
- `404` — Contract not found.
- `429` — Too many requests.

---

[API](https://skmtc.net/stiggio/apis/stigg-api.md) · [All operations](https://skmtc.net/stiggio/apis/stigg-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/stiggio/stigg-api/versions/ffc977f1c07e/schema)