Skip to content
UltimateTeam.ai Docs

Turn

POST
/api/v1/commerce/negotiations/{nid}/turn
curl --request POST \
  --url https://api.ultimateteam.ai/api/v1/commerce/negotiations/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/turn \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "content": "example", "terms": { "buyer_contact_email": "hello@example.com", "buyer_tenant_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "cancellation_terms": "example", "currency": "usd", "delivery": { "acceptance_criteria": "example", "artifact_sha256": "example", "description": "example", "due_at": "2026-04-15T12:00:00Z", "kind": "digital", "quantity": 1, "service_role": "coo", "service_type": "analysis_report", "shipping_address": { "additionalProperty": "example" }, "sku": "example" }, "expires_at": "2026-04-15T12:00:00Z", "livemode": true, "platform_fee_cents": 1, "seller_account_id": "example", "seller_contact_email": "hello@example.com", "seller_tenant_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "subtotal_cents": 1, "tax_cents": 1, "tax_description": "example", "title": "example" }, "terms_digest": "example", "type": "counter_offer", "version": 1 }'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters”
nid
required
Nid
string format: uuid

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
NegotiationTurn
object
content
required
Content
string
>= 1 characters <= 4000 characters
terms
Any of:
CommerceTerms
object
buyer_contact_email
required
Buyer Contact Email
string format: email
buyer_tenant_id
required
Buyer Tenant Id
string format: uuid
cancellation_terms
required
Cancellation Terms
string
>= 5 characters <= 2000 characters
currency
Currency
string
default: usd
Allowed value: usd
delivery
required
DeliveryTerms
object
acceptance_criteria
required
Acceptance Criteria
string
>= 10 characters <= 4000 characters
artifact_sha256
Any of:
string
/^[a-f0-9]{64}$/
description
required
Description
string
>= 10 characters <= 4000 characters
due_at
required
Due At
string format: date-time
kind
required
Kind
string
Allowed values: digital service physical
quantity
Quantity
integer
default: 1 >= 1 <= 100000
service_role
Any of:
string
Allowed values: coo cto cmo cio
service_type
Any of:
string
Allowed value: analysis_report
shipping_address
Any of:
object
key
additional properties
string
sku
Any of:
string
<= 255 characters
expires_at
required
Expires At
string format: date-time
livemode
required
Livemode
boolean
platform_fee_cents
required
Platform Fee Cents
integer
<= 99999999
seller_account_id
required
Seller Account Id
string
/^acct_[A-Za-z0-9]+$/
seller_contact_email
required
Seller Contact Email
string format: email
seller_tenant_id
required
Seller Tenant Id
string format: uuid
subtotal_cents
required
Subtotal Cents
integer
>= 50 <= 99999999
tax_cents
required
Tax Cents
integer
<= 99999999
tax_description
required
Tax Description
string
>= 5 characters <= 1000 characters
title
required
Title
string
>= 1 characters <= 255 characters
terms_digest
required
Terms Digest
string
/^[a-f0-9]{64}$/
type
required
Type
string
Allowed values: counter_offer accept reject question
version
required
Version
integer
>= 1

Responses

Section titled “ Responses ”

200

Section titled “200”

Successful Response

Media typeapplication/json
NegotiationResponse
object
approvals
required
Approvals
Array<object>
ApprovalResponse
object
created_at
required
Created At
string format: date-time
owner_id
required
Owner Id
string format: uuid
tenant_id
required
Tenant Id
string format: uuid
terms_digest
required
Terms Digest
string
version
required
Version
integer
id
required
Id
string format: uuid
listing_id
required
Listing Id
string format: uuid
messages
required
Messages
Array<object>
object
key
additional properties
any
next_tenant_id
required
Any of:
string format: uuid
seller_tenant_id
required
Seller Tenant Id
string format: uuid
status
required
Status
string
tenant_id
required
Tenant Id
string format: uuid
terms
required
CommerceTerms
object
buyer_contact_email
required
Buyer Contact Email
string format: email
buyer_tenant_id
required
Buyer Tenant Id
string format: uuid
cancellation_terms
required
Cancellation Terms
string
>= 5 characters <= 2000 characters
currency
Currency
string
default: usd
Allowed value: usd
delivery
required
DeliveryTerms
object
acceptance_criteria
required
Acceptance Criteria
string
>= 10 characters <= 4000 characters
artifact_sha256
Any of:
string
/^[a-f0-9]{64}$/
description
required
Description
string
>= 10 characters <= 4000 characters
due_at
required
Due At
string format: date-time
kind
required
Kind
string
Allowed values: digital service physical
quantity
Quantity
integer
default: 1 >= 1 <= 100000
service_role
Any of:
string
Allowed values: coo cto cmo cio
service_type
Any of:
string
Allowed value: analysis_report
shipping_address
Any of:
object
key
additional properties
string
sku
Any of:
string
<= 255 characters
expires_at
required
Expires At
string format: date-time
livemode
required
Livemode
boolean
platform_fee_cents
required
Platform Fee Cents
integer
<= 99999999
seller_account_id
required
Seller Account Id
string
/^acct_[A-Za-z0-9]+$/
seller_contact_email
required
Seller Contact Email
string format: email
seller_tenant_id
required
Seller Tenant Id
string format: uuid
subtotal_cents
required
Subtotal Cents
integer
>= 50 <= 99999999
tax_cents
required
Tax Cents
integer
<= 99999999
tax_description
required
Tax Description
string
>= 5 characters <= 1000 characters
title
required
Title
string
>= 1 characters <= 255 characters
terms_digest
required
Terms Digest
string
transaction
required
Any of:
TransactionResponse
object
checkout_url
Any of:
string
fulfillment_status
required
Fulfillment Status
string
id
required
Id
string format: uuid
last_error
required
Any of:
string
outcome
required
Any of:
object
key
additional properties
any
outcome_status
required
Outcome Status
string
payment_status
required
Payment Status
string
receipt
required
Any of:
object
key
additional properties
any
status
required
Status
string
turn_count
required
Turn Count
integer
version
required
Version
integer
Example
{
  "terms": {
    "currency": "usd",
    "delivery": {
      "kind": "digital",
      "quantity": 1,
      "service_role": "coo",
      "service_type": "analysis_report"
    }
  }
}

422

Section titled “422”

Validation Error

Media typeapplication/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
ctx
Context
object
input
Input
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
Examplegenerated
{
  "detail": [
    {
      "ctx": {},
      "input": "example",
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ]
}