---
title: "Create a customer and place an order"
method: POST
path: "/v1/partner/provision"
tags: ["Partner Provisioning"]
---

# Create a customer and place an order

`POST /v1/partner/provision`

## Request

- Base URL: `https://developers.servera.lt`
- URL: `https://developers.servera.lt/v1/partner/provision`
- Auth: HTTP bearer

Create (or identify) an end customer and place a **PENDING** order with an
**UNPAID proforma** invoice, in a single call, for partner-allowed products only.

Does not charge or provision anything on its own — the invoice is settled by the
end customer via the returned `pay_url` (or bank transfer), and everything after
(invoicing, payment reconciliation, renewals) is handled automatically.

An **`Idempotency-Key`** header is REQUIRED — send your own order id; a retry with
the same key returns the original result instead of creating a duplicate.

Returns `customer_id`, `customer_created`, `order_number`, `status` (`pending`),
`invoice_id`, `invoice_number` (the proforma), `total`, `currency` and `pay_url`.

## Headers

- `Idempotency-Key` string, nullable

## Request body

- PartnerProvisionBody
  - `customer` PartnerCustomer, required
    - `email` string, required: End-customer email (used to create/identify the account).
    - `first_name` string, nullable
    - `last_name` string, nullable
    - `company_name` string, nullable
    - `company_number` string, nullable: Company registration code.
    - `tax_id` string, nullable: VAT / tax id, e.g. LT100000000000.
    - `phone` string, nullable
    - `country` string, nullable: ISO country code, e.g. LT.
    - `language` string, nullable: Preferred language, e.g. lt or en.
    - `vat_validated` boolean, nullable: Set true if YOU (the partner) already validated this VAT number via VIES at registration. Servera then records the validation so the invoice applies 0% reverse charge for a valid intra-EU B2B customer (e.g. an LV company billed by the LT company). Send ONLY when the VIES check actually returned valid.
    - `vat_validated_name` string, nullable: Company name returned by VIES for that VAT number (optional; stored with the validation).
  - `items` PartnerItem[], required: Products to order.
    - `product_id` integer, required: Allowed product id.
    - `billing_cycle` string, required: 'onetime' for hardware, or monthly/quarterly/semiannually/annually/biennially/triennially for a subscription.
    - `quantity` integer: How many.
    - `giveaway` boolean: If true, this line is a 100% giveaway (e.g. a free device bundled with a subscription): billed at full price with a -100% discount line on the invoice, netting to 0. The partner decides eligibility.
    - `giveaway_name` string, nullable: Localized label for the giveaway discount line (e.g. 'Dovana - irenginys nemokamai'). Shown on the invoice. Defaults to a generic label when omitted.
  - `reference` string, nullable: Your own order reference (also used as idempotency anchor in notes).
  - `send_emails` boolean: Send the end customer the verification + order emails.
  - `link_if_exists` boolean: If a customer with this email already exists in Servera but is not yet owned by this partner, link (adopt) it and place the order instead of returning 409. Use for returning customers who already have a Servera account.
  - `start_date` string, nullable: Optional service start date (YYYY-MM-DD) for the whole order. When set, recurring services are billed from this date (registration + next_due anchor here, and the invoice period shows [start_date, start_date+cycle)) instead of the payment date. Must be today or later. Omit to start billing from the payment date.

## Response `200`

Successful Response

- PartnerOrderResult
  - `customer_id` integer, required
  - `customer_created` boolean
  - `order_id` integer, required
  - `order_number` string, required
  - `status` 'pending' | 'active' | 'cancelled' | 'refunded', required
  - `invoice_id` integer, nullable
  - `invoice_number` string, nullable
  - `total` number, required
  - `currency` string
  - `pay_url` string, nullable
  - `reference` string, nullable

## Other responses

- `400`: Bad request — error is one of: no_items, too_many_items, product_not_allowed, invalid_cycle_for_product, product_not_found, idempotency_key_required
- `401`: Unauthorized — missing or invalid API key
- `403`: Forbidden — error is insufficient_scope (needs the partner:provision scope) or no_products_assigned
- `409`: Conflict — error is customer_exists_not_owned (retry with link_if_exists=true, or an admin links via /admin/customers/partner-link)
- `422`: Validation Error

---

[API](https://skmtc.dev/servera/apis/servera-developers-api-2.md) · [All operations](https://skmtc.dev/servera/apis/servera-developers-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/servera/apis/servera-developers-api-2/revisions/2e744791e77f?raw)