Create CoworkerContract

Create a new CoworkerContract record.

POST /api/billing/coworkercontracts

Create CoworkerContract

cURL

curl --request POST \
  --url https://spaces.nexudus.com/api/billing/coworkercontracts \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "IssuedById": 123,
  "CoworkerId": 123,
  "TariffId": 123,
  "BillingDay": 123,
  "Quantity": 123
}
'

200

{
  "Status": 123,
  "Message": "<string>",
  "Value": "<any>",
  "WasSuccessful": true,
  "Errors": [
    {
      "AttemptedValue": "<any>",
      "Message": "<string>",
      "PropertyName": "<string>"
    }
  ]
}

A CoworkerContract is the foundation for automatic billing. It links a customer (Coworker) to a plan (Tariff) that drives the billing frequency, benefits and default settings for the contract. A customer can hold as many contracts as needed, each pointing to the same or different plans.

A customer with at least one active contract is regarded as a Member; customers with no active contracts are Contacts. Nexudus uses this distinction to enforce policies on products, resources, events, pricing and many other entities that expose OnlyForMembers or OnlyForContacts properties.

Pricing — The contract price can be fixed (Price is not null) or derived from the plan it is for. The Value field is used in reporting to compare with the actual price. Automatic price adjustments over time can be set up via ContractSchedule child entities.

Billing cycle — RenewalDate is the date on which the contract will next be automatically invoiced; it advances automatically each time the contract is invoiced. InvoicedPeriod is the period the next invoice will cover. For a new contract these two dates are usually the same. If Tariff.AdvanceInvoiceCycles is greater than 1, Nexudus invoices several periods in one go the first time, pushing InvoicedPeriod ahead of RenewalDate from the first invoice onwards. When the contract is cancelled, Nexudus stops invoicing once InvoicedPeriod reaches the cancellation date.

Benefits — The plan may include benefits (booking credits, time passes, etc.) which are released and assigned to the contract-holder customer based on the contract cycle or other expiration criteria (month, week, day, etc.).

Cancellation — Contracts support minimum contract length (ContractTerm), cancellation policies (CancellationLimitDays, ProRateCancellation) and cancellation reasons. CancelTeamContracts can cascade cancellation to team members.

Additional charges — Contracts can optionally include products (ContractProduct entities) to be billed alongside the plan, as well as security deposits/retainers (ContractDeposit entities).

Authentication

This endpoint requires OAuth2 authentication. Include a valid bearer token in the Authorization header. The authenticated user must be a full unrestricted administrator or have the CoworkerContract-Create role.

Enums

eCancellationReason

Value	Name
1	PriceTooHigh
2	NewJobRelocation
3	MovedToOtherSpace
4	ChangeWorkEnvironment
5	LackCommunityInterations
6	PoorSpaceCondition
7	OtherMembers
8	Rellocated
9	BusinessExpansion
10	Pause
11	Renewed
12	Upgraded
13	Downgraded
19	Covid19
99	Other

eDeliveryHandlingPreference

Value	Name
1	StoreForCollection
2	Forward
3	OpenScanForward
4	OpenScanRecycle
5	OpenScanShred
6	OpenScanStoreForCollection
7	Recycle
8	ReturnToSender
9	Shred
10	DepositCheck
11	Unknown

Request Body

Required Fields

IssuedById · integer · required

Issued By Id.

CoworkerId · integer · required

Coworker Id.

TariffId · integer · required

Tariff Id.

BillingDay · integer · required

Day of month on which billing occurs.

Quantity · integer · required

Quantity.

Optional Fields

NextTariffId · integer

Next Tariff Id.

Notes · string

Free-text notes for this contract.

StartDate · string

Contract start date.

RenewalDate · string

Date on which the contract will next be automatically invoiced. Updated automatically every time the contract is invoiced, advancing by the plan’s renewal period.

InvoicedPeriod · string

Period the next invoice will cover. For new contracts this equals RenewalDate. If Tariff.AdvanceInvoiceCycles > 1, Nexudus invoices several periods at once on the first invoice, pushing InvoicedPeriod ahead of RenewalDate. Nexudus stops invoicing when InvoicedPeriod reaches the cancellation date.

ContractTerm · string

Minimum contract length end date. Defines the earliest date at which the contract can be cancelled without penalty.

Price · number

Fixed price override for this contract. If null, the contract uses the plan’s default price (TariffPrice).

Value · number

Contract value used in reporting to compare against the actual invoiced price.

Desks · integer[]

Desks.

Variants · integer[]

Variants.

PurchaseOrder · string

Purchase order.

IncludeSignupFee · boolean

Whether to include the plan’s signup fee when creating this contract.

InvoiceAdvancedCycles · boolean

Whether to invoice multiple billing cycles in advance on the first invoice, as configured by Tariff.AdvanceInvoiceCycles.

ApplyProRating · boolean

Whether to pro-rate the first invoice based on the contract start date relative to the billing cycle.

NextAutoInvoice · string

Date of the next automatic invoice generation for this contract.

PricePlanTermsAccepted · boolean

Whether the customer has accepted the plan’s terms and conditions.

CancellationDate · string

Date on which the contract will be cancelled. Nexudus stops invoicing when InvoicedPeriod reaches this date.

CancellationLimitDays · integer

Minimum number of days’ notice required before cancellation takes effect.

ProRateCancellation · boolean

Whether to pro-rate the final invoice when the contract is cancelled mid-cycle.

CancelTeamContracts · boolean

Whether to cascade cancellation to contracts of team members under this customer.

CancellationReason · integer

Reason for cancellation. See eCancellationReason? enum above.

CancellationNotes · string

Free-text notes about the cancellation.

DeliveryHandlingPreferenceChecks · integer

Delivery handling preference for checks. See eDeliveryHandlingPreference? enum above.

DeliveryHandlingPreferenceMail · integer

Delivery handling preference for mail. See eDeliveryHandlingPreference? enum above.

DeliveryHandlingPreferenceParcels · integer

Delivery handling preference for parcels. See eDeliveryHandlingPreference? enum above.

DeliveryHandlingPreferencePublicity · integer

Delivery handling preference for publicity. See eDeliveryHandlingPreference? enum above.

DeliveryInstructions · string

Free-text delivery instructions for this contract’s mail handling.

IdentityChecksDueOn · string

Date by which identity verification checks must be completed for this contract.

AddressChecksDueOn · string

Date by which address verification checks must be completed for this contract.

StartDateLocal · string

Start Date Local.

RenewalDateLocal · string

Renewal Date Local.

NextAutoInvoiceLocal · string

Next Auto Invoice Local.

PricePlanTermsAcceptedOnLocal · string

Price Plan Terms Accepted On Local.

CancellationDateLocal · string

Cancellation Date Local.

ContractTermLocal · string

Contract Term Local.

InvoicedPeriodLocal · string

Invoiced Period Local.

PoBoxNumber · string

PO box number.

Children

ContractSchedules · object[]

Scheduled future price changes for this contract. Each entry sets a new Price to apply on a given date

Show child attributes

Price · number

The new contract price to apply on the scheduled date.

ApplyOn · string · required

Date on which the system will automatically update the contract price to the value in Price.

Code Examples

cURL

curl -X POST \
  "https://spaces.nexudus.com/api/billing/coworkercontracts" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "IssuedById": 0,
    "CoworkerId": 0,
    "TariffId": 0,
    "BillingDay": 0,
    "Quantity": 0,
    "ContractSchedules": [
        {
            "Price": null,
            "ApplyOn": "2025-01-15T10:30:00Z"
        }
    ]
}'

Response

200

Status · integer

HTTP status code. 200 on success.

Message · string

A human-readable message confirming the creation.

Value · object

Contains the Id of the newly created record.

WasSuccessful · boolean

true if the coworkercontract was created successfully.

Errors · array

null on success.

Example Response

{
  "Status": 200,
  "Message": "CoworkerContract was successfully created.",
  "Value": {
    "Id": 87654321
  },
  "OpenInDialog": false,
  "OpenInWindow": false,
  "RedirectURL": null,
  "JavaScript": null,
  "UpdatedOn": "2025-01-15T10:30:00Z",
  "UpdatedBy": "[e-mail]",
  "Errors": null,
  "WasSuccessful": true
}

400

Message · string

A summary of the validation error(s), in the format PropertyName: error message.

Value · any

null on validation failure.

Errors · object[]

Array of validation errors.

Show child attributes

AttemptedValue · any

The value that was submitted for the field, or null if missing.

Message · string

The validation error message.

PropertyName · string

The name of the property that failed validation.

WasSuccessful · boolean

false when the request fails validation.

Example Response

{
  "Message": "PriceWithProductsAndDeposits: is a required field",
  "Value": null,
  "Errors": [
    {
      "AttemptedValue": null,
      "Message": "is a required field",
      "PropertyName": "PriceWithProductsAndDeposits"
    }
  ],
  "WasSuccessful": false
}