--- title: "Create contract" method: POST path: "/api/v1/contracts" tags: ["Contracts"] --- # Create contract `POST /api/v1/contracts` Creates a contract for a customer together with all of its (custom) subscriptions in a single atomic operation. Every new subscription is created inside one transaction — any validation or creation failure rolls the whole contract back. Each subscription entry is either a new subscription to create or a reference to an existing custom subscription. Returns the created contract. ## Headers - `X-ACCOUNT-ID` string - `X-ENVIRONMENT-ID` string ## Request body - CreateContractRequestDto — Input for creating a contract and its subscriptions atomically. - `customerId` string, required — The customer ref ID the contract belongs to - `name` string, nullable — Optional contract name - `poNumber` string, nullable — Optional purchase-order number - `activationStartDate` string, date-time — Optional contract activation start date - `activationEndDate` string, date-time — Optional contract activation end date - `setupBilling` boolean — Whether to set up billing for the contract by creating a billing contract in the connected billing provider. When false, the contract only provisions access (grants entitlements) and no billing contract is created. Defaults to true. - `subscriptions` object[], required — The subscriptions to attach to the contract (must be non-empty). Each entry is either a new subscription to create or a reference to an existing custom subscription. - `newSubscription` object — A new subscription to create, using the same body the provision-subscription endpoint accepts - `id` string — Unique identifier for the subscription - `customerId` string, required — Customer ID to provision the subscription for - `planId` string, required — Plan ID to provision - `payingCustomerId` string, nullable — Optional paying customer ID for split billing scenarios - `resourceId` string, nullable — Optional resource ID for multi-instance subscriptions - `billingPeriod` 'MONTHLY' | 'ANNUALLY' — Billing period (MONTHLY or ANNUALLY) - `addons` object[] - `id` string, required — Addon ID - `quantity` integer, required — Number of addon instances - `charges` object[] - `type` 'FEATURE' | 'CREDIT', required — Charge type - `id` string, required — Charge ID - `quantity` number, required — Charge quantity. Minimum is 0 (zero is allowed). - `startDate` string, date-time — Subscription start date - `cancellationDate` string, date-time — Subscription cancellation date - `billingInformation` object - `taxRateIds` string[] — Tax rate identifiers to apply - `taxPercentage` number — Tax percentage (0-100) - `billingAddress` object — Billing address for the subscription - `city` string - `country` string - `line1` string - `line2` string - `postalCode` string - `state` string - `metadata` object — Additional metadata for the subscription - `chargeOnBehalfOfAccount` string, nullable — Stripe Connect account to charge on behalf of - `isBackdated` boolean — Whether the subscription is backdated - `isInvoicePaid` boolean — Whether the invoice is marked as paid - `invoiceDaysUntilDue` number — Number of days until invoice is due - `integrationId` string, nullable — Billing integration identifier - `prorationBehavior` 'INVOICE_IMMEDIATELY' | 'CREATE_PRORATIONS' | 'NONE' — How to handle proration for billing changes - `taxIds` object[] — Customer tax identification numbers - `type` string, required — The type of tax exemption identifier, such as VAT. - `value` string, required — The actual tax identifier value - `billingId` string, nullable — External billing system identifier - `billingCountryCode` string, nullable — The ISO 3166-1 alpha-2 country code for billing - `entitlements` union[] - union - object — Feature entitlement configuration for a subscription - `type` 'FEATURE', required — SubscriptionFeatureEntitlementRequest - `id` string, required — The feature ID to attach the entitlement to - `usageLimit` integer — Maximum allowed usage for the feature - `hasUnlimitedUsage` boolean — Whether usage is unlimited - `hasSoftLimit` boolean — Whether the usage limit is a soft limit - `resetPeriod` 'YEAR' | 'MONTH' | 'WEEK' | 'DAY' | 'HOUR' — Period at which usage resets - `yearlyResetPeriodConfiguration` object, nullable — Configuration for yearly reset period - … - `monthlyResetPeriodConfiguration` object, nullable — Configuration for monthly reset period - … - `weeklyResetPeriodConfiguration` object, nullable — Configuration for weekly reset period - … - object — Credit entitlement configuration for a subscription - `type` 'CREDIT', required — SubscriptionCreditEntitlementRequest - `id` string, required — The custom currency ID for the credit entitlement - `amount` number, required — Credit grant amount - `cadence` 'MONTH' | 'YEAR', required — Credit grant cadence (MONTH or YEAR) - `trialOverrideConfiguration` object — Trial period override settings - `isTrial` boolean, required — Whether the subscription should start with a trial period - `trialEndBehavior` 'CONVERT_TO_PAID' | 'CANCEL_SUBSCRIPTION' — Behavior when trial ends: CONVERT_TO_PAID or CANCEL_SUBSCRIPTION - `trialEndDate` string, date-time — Custom trial end date - `scheduleStrategy` 'END_OF_BILLING_PERIOD' | 'END_OF_BILLING_MONTH' | 'IMMEDIATE' — Strategy for scheduling subscription changes - `checkoutOptions` object — Checkout page configuration for payment collection - `successUrl` string, uri, required — URL to redirect to after successful checkout - `cancelUrl` string, uri, required — URL to redirect to if checkout is canceled - `allowPromoCodes` boolean — Allow promotional codes during checkout - `allowTaxIdCollection` boolean — Allow tax ID collection during checkout - `collectBillingAddress` boolean — Collect billing address during checkout - `referenceId` string, nullable — Optional reference ID for the checkout session - `collectPhoneNumber` boolean — Collect phone number during checkout - `metadata` object — Additional metadata for the subscription - `salesforceId` string, nullable — Salesforce ID - `budget` object, nullable - `limit` number, required — Maximum spending limit - `hasSoftLimit` boolean, required — Whether the budget is a soft limit - `minimumSpend` object, nullable — Minimum spend amount - `amount` number — 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' — The price currency - `priceOverrides` object[] - `amount` number — 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' — The price currency - `featureId` string, nullable — Feature identifier for the price override - `addonId` string, nullable — Addon identifier for the price override - `baseCharge` boolean — Whether this is a base charge override - `billingCountryCode` string — The billing country code of the price - `blockSize` number — Block size for pricing - `tiers` object[] — Pricing tiers configuration - `upTo` number — The up to quantity of the price tier - `unitPrice` object — The unit price of the price tier - `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 - `flatPrice` object — The flat fee price of the price tier - `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 - `creditRate` object - `amount` number, required — The credit rate amount - `currencyId` string, required — The custom currency refId for the credit rate - `costFormula` string, nullable — A custom formula for calculating cost based on single event dimensions - `creditGrantCadence` 'BEGINNING_OF_BILLING_PERIOD' | 'MONTHLY' - `paymentCollectionMethod` 'CHARGE' | 'INVOICE' | 'NONE' — How payments should be collected for this subscription - `appliedCoupon` object — Coupon configuration - `couponId` string — Stigg coupon ID - `billingCouponId` string — Billing provider coupon ID - `promotionCode` string — Promotion code to apply - `discount` object — Ad-hoc discount configuration - `name` string — Discount name - `description` string — Ad-hoc discount - `durationInMonths` number — Duration in months - `percentOff` number — Percentage discount - `amountsOff` object[], nullable — Fixed amounts off by currency - `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 - `configuration` object — Coupon timing configuration - `startDate` string, date-time — Coupon start date - `awaitPaymentConfirmation` boolean — Whether to wait for payment confirmation before returning the subscription - `unitQuantity` integer — Unit quantity for per-unit pricing. Minimum is 0 (zero is allowed). - `billingCycleAnchor` 'UNCHANGED' | 'NOW' — Billing cycle anchor behavior for the subscription - `existingSubscriptionId` string — The subscription ref ID of an already-created custom subscription to link ## Response `201` The created contract, including the custom subscriptions attached to it. - 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. - `409` — Contract conflict error. - `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/3e2c8cfcd035/schema)