Create contract

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.

POST /api/v1/contracts

JavaScript

JavaScript

import Stigg from '@stigg/typescript';

const client = new Stigg({
  apiKey: process.env['STIGG_API_KEY'], // This is the default and can be omitted
});

const contract = await client.v1.contracts.create({
  customerId: 'customerId',
  subscriptions: [{}],
});

console.log(contract.data);

import os
from stigg import Stigg

client = Stigg(
    api_key=os.environ.get("STIGG_API_KEY"),  # This is the default and can be omitted
)
contract = client.v1.contracts.create(
    customer_id="customerId",
    subscriptions=[{}],
)
print(contract.data)

package main

import (
	"context"
	"fmt"

	"github.com/stiggio/stigg-go"
	"github.com/stiggio/stigg-go/option"
)

func main() {
	client := stigg.NewClient(
		option.WithAPIKey("My API Key"),
	)
	contract, err := client.V1.Contracts.New(context.TODO(), stigg.V1ContractNewParams{
		CustomerID:    "customerId",
		Subscriptions: []stigg.V1ContractNewParamsSubscription{{}},
	})
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", contract.Data)
}

package io.stigg.example;

import io.stigg.client.StiggClient;
import io.stigg.client.okhttp.StiggOkHttpClient;
import io.stigg.models.v1.contracts.ContractCreateParams;
import io.stigg.models.v1.contracts.ContractCreateResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        StiggClient client = StiggOkHttpClient.fromEnv();

        ContractCreateParams params = ContractCreateParams.builder()
            .customerId("customerId")
            .addSubscription(ContractCreateParams.Subscription.builder().build())
            .build();
        ContractCreateResponse contract = client.v1().contracts().create(params);
    }
}

require "stigg"

stigg = Stigg::Client.new(api_key: "My API Key")

contract = stigg.v1.contracts.create(customer_id: "customerId", subscriptions: [{}])

puts(contract)

using System;
using System.Collections.Generic;
using Stigg.Client;
using Contracts = Stigg.Client.Models.V1.Contracts;

StiggClient client = new();

Contracts::ContractCreateParams parameters = new()
{
    CustomerID = "customerId",
    Subscriptions =
    [
        new()
        {
            ExistingSubscriptionID = "existingSubscriptionId",
            NewSubscription = new()
            {
                CustomerID = "customerId",
                PlanID = "planId",
                ID = "id",
                Addons =
                [
                    new()
                    {
                        ID = "id",
                        Quantity = 0,
                    },
                ],
                AppliedCoupon = new()
                {
                    BillingCouponID = "billingCouponId",
                    Configuration = new()
                    {
                        StartDate = DateTimeOffset.Parse("2019-12-27T18:11:19.117Z"),
                    },
                    CouponID = "couponId",
                    Discount = new()
                    {
                        AmountsOff =
                        [
                            new()
                            {
                                Amount = 0,
                                Currency = Contracts::Currency.Usd,
                            },
                        ],
                        Description = "description",
                        DurationInMonths = 1,
                        Name = "name",
                        PercentOff = 1,
                    },
                    PromotionCode = "promotionCode",
                },
                AwaitPaymentConfirmation = true,
                BillingCountryCode = "billingCountryCode",
                BillingCycleAnchor = Contracts::BillingCycleAnchor.Unchanged,
                BillingID = "billingId",
                BillingInformation = new()
                {
                    BillingAddress = new()
                    {
                        City = "city",
                        Country = "country",
                        Line1 = "line1",
                        Line2 = "line2",
                        PostalCode = "postalCode",
                        State = "state",
                    },
                    ChargeOnBehalfOfAccount = "chargeOnBehalfOfAccount",
                    IntegrationID = "integrationId",
                    InvoiceDaysUntilDue = 0,
                    IsBackdated = true,
                    IsInvoicePaid = true,
                    Metadata = new Dictionary<string, string>()
                    {
                        { "foo", "string" }
                    },
                    ProrationBehavior = Contracts::ProrationBehavior.InvoiceImmediately,
                    TaxIds =
                    [
                        new()
                        {
                            Type = "type",
                            Value = "value",
                        },
                    ],
                    TaxPercentage = 0,
                    TaxRateIds =
                    [
                        "string"
                    ],
                },
                BillingPeriod = Contracts::BillingPeriod.Monthly,
                Budget = new()
                {
                    HasSoftLimit = true,
                    Limit = 0,
                },
                CancellationDate = DateTimeOffset.Parse("2019-12-27T18:11:19.117Z"),
                Charges =
                [
                    new()
                    {
                        ID = "id",
                        Quantity = 0,
                        Type = Contracts::Type.Feature,
                    },
                ],
                CheckoutOptions = new()
                {
                    CancelUrl = "https://example.com",
                    SuccessUrl = "https://example.com",
                    AllowPromoCodes = true,
                    AllowTaxIDCollection = true,
                    CollectBillingAddress = true,
                    CollectPhoneNumber = true,
                    ReferenceID = "referenceId",
                },
                Entitlements =
                [
                    new Contracts::Feature()
                    {
                        ID = "id",
                        HasSoftLimit = true,
                        HasUnlimitedUsage = true,
                        MonthlyResetPeriodConfiguration = new(
                            Contracts::AccordingTo.SubscriptionStart
                        ),
                        ResetPeriod = Contracts::ResetPeriod.Year,
                        UsageLimit = 0,
                        WeeklyResetPeriodConfiguration = new(
                            Contracts::WeeklyResetPeriodConfigurationAccordingTo.SubscriptionStart
                        ),
                        YearlyResetPeriodConfiguration = new(
                            Contracts::YearlyResetPeriodConfigurationAccordingTo.SubscriptionStart
                        ),
                    },
                ],
                Metadata = new Dictionary<string, string>()
                {
                    { "foo", "string" }
                },
                MinimumSpend = new()
                {
                    Amount = 0,
                    Currency = Contracts::MinimumSpendCurrency.Usd,
                },
                PayingCustomerID = "payingCustomerId",
                PaymentCollectionMethod = Contracts::PaymentCollectionMethod.Charge,
                PriceOverrides =
                [
                    new()
                    {
                        AddonID = "addonId",
                        Amount = 0,
                        BaseCharge = true,
                        BillingCountryCode = "billingCountryCode",
                        BlockSize = 0,
                        CreditGrantCadence = Contracts::CreditGrantCadence.BeginningOfBillingPeriod,
                        CreditRate = new()
                        {
                            Amount = 1,
                            CurrencyID = "currencyId",
                            CostFormula = "costFormula",
                        },
                        Currency = Contracts::PriceOverrideCurrency.Usd,
                        FeatureID = "featureId",
                        Tiers =
                        [
                            new()
                            {
                                FlatPrice = new()
                                {
                                    Amount = 0,
                                    Currency = Contracts::FlatPriceCurrency.Usd,
                                },
                                UnitPrice = new()
                                {
                                    Amount = 0,
                                    Currency = Contracts::UnitPriceCurrency.Usd,
                                },
                                UpTo = 0,
                            },
                        ],
                    },
                ],
                ResourceID = "resourceId",
                SalesforceID = "salesforceId",
                ScheduleStrategy = Contracts::ScheduleStrategy.EndOfBillingPeriod,
                StartDate = DateTimeOffset.Parse("2019-12-27T18:11:19.117Z"),
                TrialOverrideConfiguration = new()
                {
                    IsTrial = true,
                    TrialEndBehavior = Contracts::TrialEndBehavior.ConvertToPaid,
                    TrialEndDate = DateTimeOffset.Parse("2019-12-27T18:11:19.117Z"),
                },
                UnitQuantity = 0,
            },
        },
    ],
};

var contract = await client.V1.Contracts.Create(parameters);

Console.WriteLine(contract);

stigg v1:contracts create \
  --api-key 'My API Key' \
  --customer-id customerId \
  --subscription '{}'

curl --request POST \
  --url https://api.stigg.io/api/v1/contracts \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "customerId": "<string>",
  "subscriptions": [
    {
      "existingSubscriptionId": "<string>"
    }
  ],
  "name": "<string>",
  "poNumber": "<string>",
  "activationStartDate": "2023-11-07T05:31:56Z",
  "activationEndDate": "2023-11-07T05:31:56Z",
  "setupBilling": true
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.stigg.io/api/v1/contracts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'customerId' => '<string>',
    'subscriptions' => [
        [
                'existingSubscriptionId' => '<string>'
        ]
    ],
    'name' => '<string>',
    'poNumber' => '<string>',
    'activationStartDate' => '2023-11-07T05:31:56Z',
    'activationEndDate' => '2023-11-07T05:31:56Z',
    'setupBilling' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

201

{
  "data": {
    "contractId": "contract-acme-2026",
    "billingId": "ct_1a2b3c4d",
    "id": "3452155b-deca-4d7f-91e5-82d486dc8bb0",
    "refId": "contract-acme-2026",
    "poNumber": "PO-4821",
    "externalId": "contract-acme-2026",
    "customerExternalId": "customer-acme",
    "name": "PO-4821",
    "state": "ACTIVE",
    "activationStartDate": "2026-01-01T00:00:00.000Z",
    "activationEndDate": "2026-12-31T00:00:00.000Z",
    "createdAt": "2025-12-15T09:30:00.000Z",
    "nextInvoice": {
      "amount": {
        "amount": 4900,
        "currency": "usd"
      },
      "dueDate": "2026-08-01T00:00:00.000Z",
      "periodStart": "2026-07-01T00:00:00.000Z",
      "periodEnd": "2026-08-01T00:00:00.000Z"
    },
    "latestInvoice": {
      "billingId": "inv_abc123",
      "status": "OPEN",
      "createdAt": "2026-07-01T00:00:00.000Z",
      "total": 4900,
      "amountDue": 4900,
      "currency": "usd",
      "pdfUrl": null,
      "requiresAction": false,
      "billingReason": null
    },
    "subscriptions": [
      {
        "subscriptionId": "subscription-acme-platform",
        "planDisplayName": "Enterprise Platform",
        "productDisplayName": "Revvenu"
      }
    ]
  }
}

{
  "message": "<string>"
}

{
  "message": "<string>",
  "code": "Unauthenticated"
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "message": "<string>",
  "code": "RateLimitExceeded"
}

Authorizations

X-API-KEY · string · header · required

Server API Key

Headers

X-ACCOUNT-ID · string

Account ID — optional when authenticating with a user JWT (Bearer token); falls back to the user's first membership. Ignored for API-key auth.

X-ENVIRONMENT-ID · string

Environment ID — required when authenticating with a user JWT (Bearer token) on environment-scoped endpoints. Ignored for API-key auth (env is intrinsic to the key).

Body

application/json

Input for creating a contract and its subscriptions atomically.

customerId · string · required

The customer ref ID the contract belongs to

Required string length: 1 - 255

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.@-]*$

subscriptions · ContractSubscriptionEntry · 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.

Minimum array length: 1

Show child attributes

name · string | null

Optional contract name

Maximum string length: 255

poNumber · string | null

Optional purchase-order number

Maximum string length: 255

activationStartDate · string<date-time>

Optional contract activation start date

activationEndDate · string<date-time>

Optional contract activation end date

setupBilling · boolean · default: true

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.

Response

201

application/json

The created contract, including the custom subscriptions attached to it.

Response object

data · Contract · object · required

A billing contract as reported by the connected billing provider.

Show child attributes