> ## Documentation Index > Fetch the complete documentation index at: https://docs.stigg.io/llms.txt > Use this file to discover all available pages before exploring further. # Add contract line items > Appends priced line items to the contract's billing. Each item is priced by one of the environment's pricing models, supplying only the row inputs that model exposes — quantity, price, tier bounds, package size. Additive: items already on the contract are left untouched. Requires a contract that has billing set up. ## OpenAPI ````yaml /openapi/stigg-api.documented.yml post /api/v1/contracts/{id}/billing/items openapi: 3.0.0 info: title: Stigg API description: Stigg API documentation version: 8.56.0 contact: {} servers: - url: https://api.stigg.io description: Production security: - ApiKeyAuth: [] tags: - name: Customers description: Operations related to customers - name: Subscriptions description: Operations related to subscriptions - name: Coupons description: Operations related to coupons - name: Bulk Import description: Operations related to import of customers and subscriptions - name: Usage description: Operations related to usage & metering - name: Promotional Entitlements description: Operations related to promotional entitlements - name: Products description: Operations related to products - name: Features description: Operations related to features - name: Addons description: Operations related to addons - name: Plans description: Operations related to plans - name: Credit grants description: Operations related to credit grants - name: Credit ledger description: Operations related to credit ledger - name: Custom currencies description: Operations related to custom currencies paths: /api/v1/contracts/{id}/billing/items: post: tags: - Contracts summary: Add contract line items description: >- Appends priced line items to the contract's billing. Each item is priced by one of the environment's pricing models, supplying only the row inputs that model exposes — quantity, price, tier bounds, package size. Additive: items already on the contract are left untouched. Requires a contract that has billing set up. operationId: ContractController_addContractItems parameters: - name: id required: true in: path description: The unique identifier of the entity schema: minLength: 1 maxLength: 255 type: string - name: X-ACCOUNT-ID in: header description: >- Account ID — optional when authenticating with a user JWT (Bearer token); falls back to the user's first membership. Ignored for API-key auth. required: false schema: type: string - name: X-ENVIRONMENT-ID in: header description: >- 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). required: false schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AddContractItemsRequestDto' responses: '200': description: The contract's recomputed totals, including total contract value. content: application/json: schema: $ref: '#/components/schemas/ContractSummaryResponseDto' '400': description: bad request. content: application/json: schema: $ref: '#/components/schemas/BadInputErrorResponseDto' '401': description: User is not authenticated. content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedErrorResponseDto' '403': description: User is not allowed to access this resource. content: application/json: schema: $ref: '#/components/schemas/ForbiddenErrorResponseDto' '404': description: Contract not found. content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponseDto' '429': description: Too many requests. content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponseDto' components: schemas: AddContractItemsRequestDto: type: object properties: lineItems: type: array items: type: object properties: name: type: string maxLength: 255 description: Line item title shown on the contract externalId: type: string maxLength: 255 description: >- Your own id for this line item. Optional, but it is how the item is addressed later for an update or a delete — assign one when the item may need changing. Without it, use the itemId the summary reports itemName: type: string maxLength: 255 description: >- Catalog item name to price. Resolved by name; created if it does not exist pricingModelId: type: string maxLength: 255 description: >- ID of the pricing model to price this line item with, from the pricing-models endpoint. Omitted, the Flat rate model is used rows: type: array items: type: object properties: quantity: type: number description: >- Committed quantity for the row. Not available on a pay-as-you-go item, whose quantity comes from reported usage — express a committed volume as a tier's from/to instead price: type: number description: Unit price for the row from: type: number description: 'Tiered models: lower bound of the tier' to: type: number description: >- Tiered models: upper bound of the tier. Omit or null for an open-ended top tier nullable: true packageSize: type: number description: 'Package models: how many units one package covers' additionalProperties: false title: ContractItemRow description: >- Values for one row of a line item's pricing model. Which fields apply depends on the model — see editableInputs on the pricing model. Fields the model does not expose are ignored. billingCycleUnit: type: string maxLength: 255 description: Billing cycle for this line item, e.g. monthly or yearly billingCycleCount: type: number description: Number of billing-cycle units per cycle (default 1) paymentTime: type: string enum: - IN_ADVANCE - IN_ARREARS description: >- Charge type: IN_ADVANCE (prepaid, billed at the start of the period) or IN_ARREARS (postpaid, billed once consumption is known). Omit and the pricing model picks — in arrears for pay-as-you-go, in advance otherwise. Pay-as-you-go is always in arrears and rejects IN_ADVANCE discount: type: number description: Discount percentage applied to this line item tax: type: number description: Tax percentage applied to this line item netTerms: type: number description: Net payment terms in days for this line item separateInvoice: type: boolean description: >- Bill this item on its own invoice rather than the contract-wide invoice required: - name additionalProperties: false title: ContractItem description: >- A priced line item on a contract, using one of the environment's pricing models. minItems: 1 currency: type: string maxLength: 255 description: Currency for the added items. Defaults to the contract currency legalEntityId: type: string maxLength: 255 description: Legal entity the added items invoice from activationStartDate: type: string format: date-time description: >- Activation period start for the added items. Defaults to the contract's existing period activationEndDate: type: string format: date-time description: Activation period end for the added items. Defaults as above required: - lineItems additionalProperties: false title: AddContractItemsRequest description: >- Input for appending priced line items to a contract. Additive — items already on the contract are left untouched. ContractSummaryResponseDto: type: object properties: data: type: object properties: contractId: type: string maxLength: 255 description: Billing contract ID externalId: type: string maxLength: 255 description: External ID for the contract currency: type: string maxLength: 255 description: Contract currency nullable: true activationStartDate: type: string format: date-time description: >- Start of the contract period, reported when every line item agrees on it. Absent means unset, or that line items carry different periods. nullable: true activationEndDate: type: string format: date-time description: >- End of the contract period, reported when every line item agrees on it nullable: true netTerms: oneOf: - type: number description: >- Payment terms — days, or a named term — reported when every line item agrees on it - type: string maxLength: 255 description: >- Payment terms — days, or a named term — reported when every line item agrees on it nullable: true legalEntityId: type: string maxLength: 255 description: >- Legal entity the contract bills from, reported when every line item agrees on it nullable: true paymentAccountId: type: string maxLength: 255 description: >- Payment account the contract collects into, reported when every line item agrees on it nullable: true subTotal: type: number description: Amount before discount and tax totalDiscount: type: number description: Discount amount (not the percentage) totalTax: type: number description: Tax amount, charged on the discounted subtotal total: type: number description: Total contract value items: type: array items: type: object properties: itemId: type: string maxLength: 255 description: >- The line item's id, used to address it for an update or a delete name: type: string maxLength: 255 description: Line item name subTotal: type: number description: Amount before discount and tax discount: type: number description: Discount amount (not the percentage) tax: type: number description: Tax amount, charged on the discounted subtotal total: type: number description: Total contract value required: - itemId - name - subTotal - discount - tax - total required: - contractId - externalId - subTotal - totalDiscount - totalTax - total - items title: ContractSummary description: >- A contract's pre-publish totals, with a per line item breakdown — read this before publishing, since after publishing these are the figures the customer is invoiced. required: - data title: Response description: Response object BadInputErrorResponseDto: type: object properties: message: type: string code: type: string enum: - BadUserInput - BillingContractOperationRejected - DuplicateIntegrationNotAllowed - EntityIsArchivedError - IntegrityViolation - FreePlanCantHaveCompatiblePackageGroupError - SubscriptionMustHaveSinglePlanError - AddonIsCompatibleWithPlan - AddonIsCompatibleWithGroup - DuplicateAddonProvisionedError - ScheduledMigrationAlreadyExistsError - SubscriptionAlreadyOnLatestPlan - EntityIdDifferentFromRefIdError - UnsupportedFeatureType - UnsupportedVendorIdentifier - UnsupportedSubscriptionScheduleType - InvalidEntitlementResetPeriod - IncompatibleSubscriptionAddon - UnPublishedPackage - MeteringNotAvailableForFeatureType - AuthCustomerMismatch - AuthCustomerReadonly - FetchAllCountriesPricesNotAllowed - MemberInvitationError - PlansCircularDependencyError - NoFeatureEntitlementInSubscription - CheckoutIsNotSupported - UnsupportedParameter - PricingModelNotSupportedByBillingIntegration - BillingIntegrationMissing - BillingIntegrationAlreadyExistsError - InvalidMemberDelete - PackageAlreadyPublished - DraftPlanCantBeArchived - DraftAddonCantBeArchived - PlanWithChildCantBeDeleted - PlanCannotBePublishWhenBasePlanIsDraft - PlanCannotBePublishWhenCompatibleAddonIsDraft - PlanIsUsedAsDefaultStartPlan - PlanIsUsedAsDowngradePlan - InvalidAddressError - InvalidQuantity - BillingPeriodMissingError - DowngradeBillingPeriodNotSupportedError - CustomerAlreadyUsesCouponError - CustomerAlreadyHaveCustomerCoupon - SubscriptionAlreadyCanceledOrExpired - TrialMustBeCancelledImmediately - SubscriptionDoesNotHaveBillingPeriod - InvalidCancellationDate - FailedToImportCustomer - FailedToImportSubscriptions - PackagePricingTypeNotSet - InvalidSubscriptionStatus - InvalidArgumentError - EditAllowedOnDraftPackageOnlyError - ResyncAlreadyInProgress - ArchivedCouponCantBeApplied - ImportAlreadyInProgress - AddonHasToHavePriceError - SelectedBillingModelDoesntMatchImportedItemError - CannotArchiveProductError - CannotUnarchiveProductError - CannotDeleteCustomerError - CannotRemovePaymentMethodFromCustomerError - CannotDeleteFeatureError - CannotArchiveFeatureError - InvalidUpdatePriceUnitAmountError - ExperimentAlreadyRunning - ExperimentStatusError - OperationNotAllowedDuringInProgressExperiment - EntitlementsMustBelongToSamePackage - CanNotUpdateEntitlementsFeatureGroup - MeterMustBeAssociatedToMeteredFeature - CannotUpdateMeterOfFeatureInUse - CannotEditPackageInNonDraftMode - CannotAddOverrideEntitlementToPlan - MissingEntityIdError - NoProductsAvailable - PromotionCodeNotForCustomer - PromotionCodeNotActive - PromotionCodeMaxRedemptionsReached - PromotionCodeMinimumAmountNotReached - PromotionCodeCustomerNotFirstPurchase - AddonWithDraftCannotBeDeletedError - CannotReportUsageForEntitlementWithMeterError - RecalculateEntitlementsError - ImportSubscriptionsBulkError - InvalidMetadataError - CannotUpsertToPackageThatHasDraft - IntegrationValidationError - AwsMarketplaceIntegrationValidationError - AwsMarketplaceIntegrationError - DataExportIntegrationError - HubspotIntegrationError - DuplicateProductValidationError - AmountTooLarge - CustomerHasNoEmailAddress - MergeEnvironmentValidationError - EntitlementLimitExceededError - EntitlementUsageOutOfRangeError - UsageMeasurementDiffOutOfRangeError - AddonQuantityExceedsLimitError - AddonDependencyMissingError - PackageGroupMinItemsError - CannotUpdateUnitTransformationError - SingleSubscriptionCantBeAutoCancellationTargetError - MultiSubscriptionCantBeAutoCancellationSourceError - ChangingPayingCustomerIsNotSupportedError - RequiredSsoAuthenticationError - InvalidDoggoSignatureError - InvalidReceivedSignatureError - CannotDeleteDefaultIntegration - CannotChangeBillingIntegration - FailedToResolveBillingIntegration - WorkflowTriggerNotFound - DeprecatedEstimateSubscriptionError - FeatureConfigurationExceededLimitError - FeatureNotBelongToFeatureGroupError - FeatureGroupMissingFeaturesError - VersionExceedsMaxValueError - CannotUpdateExpireAtForExpiredCreditGrantError - ExpireAtMustBeLaterThanEffectiveAtError - OfferAlreadyExists - DraftAlreadyExists - CreditGrantAlreadyVoided - CreditGrantCannotBeVoided - InvalidTaxId - ObjectAlreadyBeingUsedByAnotherRequestError - TooManySubscriptionsPerCustomer - TooManyCustomCurrencies - StripeError - SchedulingAtEndOfBillingPeriod - ApiKeyExpired - ApiKeyHasExpiry - OveragePriceNotSupportedOnAddon - OveragePriceRequiresUsageLimit - InvalidCreditOverageBillingModel - CreditOveragePriceCurrencyNotFound - InvoicePreviewNotAvailableForDraftContract nullable: true reason: type: string maxLength: 255 description: >- The billing side's machine-readable code for a billing-contract refusal. Present only when the code is BillingContractOperationRejected and the refusal carried one. required: - message - code UnauthenticatedErrorResponseDto: type: object properties: message: type: string code: type: string enum: - Unauthenticated nullable: true required: - message - code ForbiddenErrorResponseDto: type: object properties: message: type: string code: type: string enum: - IdentityForbidden - AccessDeniedError - NoFeatureEntitlementError - GovernanceNotEnabled nullable: true required: - message - code NotFoundErrorResponseDto: type: object properties: message: type: string code: type: string enum: - CustomerNotFound - CustomCurrencyNotFound - CreditGrantNotFound - ContractNotFound - InvoiceNotFound - MemberNotFound - PackageGroupNotFound - AddonNotFound - AddonsNotFound - EnvironmentMissing - IntegrationNotFound - VendorIsNotSupported - CouponNotFound - FutureUpdateNotFound - CustomerNoBillingId - SubscriptionNoBillingId - StripeCustomerIsDeleted - InitStripePaymentMethodError - PreparePaymentMethodFormError - AccountNotFoundError - ExperimentNotFoundError - NoDraftOfferFound - PromotionCodeNotFound - FailedToCreateCheckoutSessionError - PaymentMethodNotFoundError - ProductNotFoundError - ProductNotPublishedError - MissingBillingInvoiceError - BillingInvoiceStatusError - FeatureGroupNotFoundError - CannotArchiveFeatureGroupError - OfferNotFound - CustomerResourceNotFound - FeatureNotFound - PriceNotFound - NoActiveSubscriptionForCustomer - PlanNotFound - PromotionalEntitlementNotFoundError - SubscriptionNotFound - ApiKeyNotFound nullable: true required: - message - code TooManyRequestsErrorResponseDto: type: object properties: message: type: string code: type: string enum: - RateLimitExceeded nullable: true required: - message - code securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY description: Server API Key ```` ## Related topics - [Setting up a contract](/documentation/managing-customers-and-subscriptions/contracts/setup-flow.md) - [Delete contract line item](/api-reference/contracts/delete-contract-line-item.md) - [Delete contract line item row](/api-reference/contracts/delete-contract-line-item-row.md) - [Update a contract](/api-reference/contracts/update-a-contract-1.md) - [Get a list of contracts](/api-reference/contracts/get-a-list-of-contracts-1.md)