# Submit a licensing request (target contract)

> Documentation Preview — target API contract; endpoints may not be operational.

`POST /api/integrations/v1/licensing-requests`

The Seller executes its PO, contract or invoice **outside LicenChain**, then submits approved order
**data** (never the PO document). LicenChain returns a single-use Buyer onboarding link that the
Seller distributes to the Buyer contact. Product terms are predefined on the registered product; the
Buyer accepts the applicable terms version inside LicenChain (no second checkout).

## Rules

- Authenticate with a Seller/marketplace-scoped **server-side** API key: `Authorization: Bearer <key>`.
  The key determines the Seller. Seller or marketplace IDs in a body are never trusted.
- Send `Idempotency-Key` (UUID v4 recommended) on every request; reuse it when retrying the same order.
  Same key + same body returns the original result with `200` and `Idempotent-Replayed: true`.
  Same key + different body returns `409 idempotency_key_reused`.
  A new key for an already submitted `externalOrderId` returns `409 duplicate_external_order` with `existingRequestId`.
- `price.netLicensedAmount` is the net amount **excluding VAT**, a decimal string with exactly two fraction digits.
- `validity.validFrom` (inclusive) and `validity.validUntil` (exclusive) are UTC timestamps ending in `Z`.
- One product per request. No named users are required; the Buyer is an organization with a contact email.
- Each request results in exactly **one** corporate license with one `licenceKey`. Optional `quantity` is
  the seat or unit allowance *within* that license (omit it when not applicable); it never creates one
  license per seat and LicenChain derives no amount from it. It is returned as `seatLimit` in `licence.issued`.
- `externalOrderId` is unique per Seller; one order = one product = one request in this version. Multi-line
  POs are a future, additive extension; no line reference exists yet.
- The onboarding URL is a bearer secret: send it only to the Buyer contact and never log it.

## Request

```json
{
  "externalOrderId": "SELLER-PO-EXAMPLE-001",
  "productRef": "ai-specialist-standard",
  "buyer": {
    "organizationName": "Example Research Cooperative",
    "contactEmail": "licensing@example.com"
  },
  "price": {
    "currency": "EUR",
    "netLicensedAmount": "1200.00"
  },
  "validity": {
    "validFrom": "2027-01-01T00:00:00Z",
    "validUntil": "2028-01-01T00:00:00Z"
  },
  "quantity": 25
}
```

## Response 201

```json
{
  "schemaVersion": "1.0",
  "requestId": "lreq_7Q2M9K4X8P3D",
  "externalOrderId": "SELLER-PO-EXAMPLE-001",
  "productRef": "ai-specialist-standard",
  "termsVersion": "2026.2",
  "status": "awaiting_buyer",
  "onboarding": {
    "url": "https://sandbox.licenchain.example/onboarding/REDACTED-ONE-TIME-TOKEN",
    "expiresAt": "2026-12-08T09:00:00Z"
  },
  "createdAt": "2026-11-08T09:00:00Z"
}
```

## Errors

400 validation_failed, 401 unauthenticated, 403 forbidden, 404 product_not_found,
409 duplicate_external_order / idempotency_key_reused, 429 rate_limited (Retry-After),
503 service_unavailable (Retry-After). Retry 429/503 and network errors with the **same** Idempotency-Key.

```json
{
  "type": "https://developers.licenchain.io/api/docs/errors/#validation_failed",
  "title": "Request validation failed",
  "status": 400,
  "code": "validation_failed",
  "detail": "One or more fields are invalid.",
  "traceId": "trc_4H8K2M6Q9R",
  "errors": [
    {
      "field": "price.netLicensedAmount",
      "code": "invalid_decimal",
      "message": "Use a decimal string with exactly two fraction digits, for example \"1200.00\"."
    }
  ]
}
```

## cURL

```bash
curl --request POST "$LICENCHAIN_API_BASE_URL/api/integrations/v1/licensing-requests" \
  --header "Authorization: Bearer $LICENCHAIN_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: 5d1f8a3c-2b7e-4c49-9f0a-6e3b2d4c8a17" \
  --data '{
  "externalOrderId": "SELLER-PO-EXAMPLE-001",
  "productRef": "ai-specialist-standard",
  "buyer": {
    "organizationName": "Example Research Cooperative",
    "contactEmail": "licensing@example.com"
  },
  "price": {
    "currency": "EUR",
    "netLicensedAmount": "1200.00"
  },
  "validity": {
    "validFrom": "2027-01-01T00:00:00Z",
    "validUntil": "2028-01-01T00:00:00Z"
  },
  "quantity": 25
}'
```