---
title: "Create operation"
method: POST
path: "/operations"
tags: ["Operations"]
---

# Create operation

`POST /operations`

Perform operation in UDS. On success operation appears in operations list in UDS Admin and customer receives
push notification about purchase.

### Marketing policy

Depends on company discount policy (`baseDiscountPolicy` field) in company settings. Two values are supported:

* `APPLY_DISCOUNT` — reduce the bill amount: the customer receives a discount in currency units at the rate specified in `participant.discountRate`;
* `CHARGE_SCORES` — accrue bonus points: the customer receives bonus points at the rate specified in `participant.cashbackRate`.

### Key points
* Fields `total` and `points` should come from user input but `cash` field should be calculated using POST `/operations/calc`;
* Customer will be identified with either promo code passed in parameter `code` or with participant uid in parameter `participant -> uid`
  or by participant's phone in parameter `participant -> phone`;
  Difference between them is that with `participant -> uid` or `participant -> phone` is not permitted to withdraw points;
  If given parameter is `participant -> uid` or `participant -> phone` then `points` must be equal to `0.0`;
  Otherwise an error will occurs with code `withdrawNotPermitted`;
* Only one identifier parameter must be passed: either `code`, or `phone`, or `uid`;
* All numbers should be scaled to two decimal places with "round half up" method. The `points` value can only be rounded **down**;
* `cash`, `points` and `total` fields MUST correlate with the "Discount method" setting in UDS;
* The `nonce` field is a UUID-like string that can only be used once. It is recommended to prevent duplicate operations in case of request retries;
* The `externalId` field is the cashier identifier. It may only contain Latin letters, digits, and the characters `_`, `-`;
* If the register sends cashier information, enable the [Staff](https://store.uds.app/modules/staff) module in UDS to view detailed cashier data;
* If UDS returns an error, do not finalize the payment in your system until the issue is corrected and a new request is sent successfully.

### Errors
Status | Error Code | Description
------ | ---------- | -----------
`400` | `badRequest` | Form validation errors occurred. See JSON `errors` property for detailed information about errors.
`400` | `invalidChecksum` | Given `total`, `cash` and `points` fields don't correlate with company marketing settings.
`400 `| `withdrawNotPermitted` | Method was called with `participant -> uid` or `participant -> phone` parameter and `points` field doesn't equal to `0.0`.
`400` | `insufficientFunds` | Given `points` value greater than actual customer reward point balance.
`400` | `priceListOnly` | Company marketing settings forbid purchases with using reward points, except of price list operations.
`400` | `discountLimitExceed` | Given `points/total` rate more than allowed by marketing settings.
`400` | `purchaseByPhoneDisabled` | Trying to make purchase by phone when it is disabled in company settings.
`401` | `unauthorized` | Invalid company ID or API Key.
`404` | `notFound` | Customer related to given code or ID is not found.
`404` | `cashierNotFound` | `externalCashierId` is specified but cashier related to it is not found.

## Request body

- CreateOperation — Request body for creating a purchase operation. Identify the customer via promo code, UID, or phone number. The `receipt.cash` value must come from POST /operations/calc — do not calculate it manually.
  - `code` string, nullable — UDS promo-code.
  - `participant` object, nullable — Customer information.
    - `uid` string, nullable — Customer ID in the UDS.
    - `phone` string, nullable — Customer phone number.
  - `nonce` string, nullable — Nonce for operation (UUID)
  - `cashier` object, nullable — Cashier information.
    - `externalId` string — Cashier identifier.
    - `name` string, nullable — Cashier name.
  - `receipt` object, required — Receipt information.
    - `total` number, required — Total receipt amount (in currency units).
    - `cash` number, required — Payment amount (in currency units).
    - `points` number, required — Points amount.
    - `number` string, nullable — Receipt number.
    - `skipLoyaltyTotal` number, nullable — A part of the bill amount for which cashback is not credited and to which the discount does not apply (in currency units).
    - `unredeemableTotal` number, nullable — A part of total that cannot be redeemed with points
  - `tags` TagId[], nullable — List of tag ids to be set to customer, null means no changes
  - `items` OperationItem[], nullable — List of receipt line items (products/services).
    - `itemId` string, nullable — Item identifier.
    - `itemCode` string, nullable — Item code.
    - `type` string, nullable — Item type (e.g. "product", "service").
    - `name` string, nullable — Item name.
    - `measure` string, nullable — Unit of measure (e.g. "pcs", "kg", "litre").
    - `vatCode` string, nullable — VAT code (e.g. "vat20", "vat10", "vat0").
    - `price` number, required — Unit price (in currency units).
    - `discountPrice` number, nullable — Discounted unit price (in currency units). If set, this price is used instead of `price`.
    - `qty` number, required — Quantity.
    - `sku` string, nullable — Stock keeping unit.
    - `isAlcohol` boolean, nullable — Whether the item is an alcohol product.
    - `isTobacco` boolean, nullable — Whether the item is a tobacco product.
    - `excise` number, nullable — Excise tax amount.
    - `classificationCode` string, nullable — Item classification code.
    - `modifiers` object[], nullable — Item modifiers as a list of key-value pairs.
      - `key` string
      - `value` string
    - `attributes` object, nullable — Arbitrary key-value attributes for the item.

## Response `200`

Operation

- Operation — A completed loyalty transaction (purchase, refund, or reward). Contains transaction details, customer info, cashier info, and point movements. Uses discriminator on `action` field.
  - `id` integer — Transaction ID in the UDS database.
  - `dateCreated` string, date-time — Transaction date.
  - `action` 'PURCHASE', required — Transaction type.
  - `state` 'NORMAL' | 'CANCELED' | 'REVERSAL' — Transaction lifecycle status: * `NORMAL` — active transaction, loyalty benefits applied * `CANCELED` — transaction was canceled, no loyalty impact * `REVERSAL` — transaction was refunded, loyalty benefits reversed (points returned, cashback deducted)
  - `customer` object — Customer information.
    - `id` integer — Customer ID in the company.
    - `displayName` string — Customer name.
    - `uid` string, nullable — Customer ID in UDS (UID).
    - `membershipTier` MembershipTier — Membership tier (loyalty level) configuration. Defines the discount/cashback rate and automatic upgrade conditions based on spending or referral count.
      - `uid` string — Tier ID.
      - `name` string, required — Tier name.
      - `rate` number, required — Tier rate.
      - `maxScoresDiscount` number, nullable — The maximum discount (in percentage) allowed when redeeming points.
      - `conditions` object — Conditions to upgrade customer tiers automatically.
        - `totalCashSpent` object, nullable — Upgrade to tier when customer reaches target `cashSpent`.
          - `target` number — Amount of cash spent.
        - `effectiveInvitedCount` object, nullable — Upgrade to tier when customer reaches target `effectiveInvitedCount`.
          - `target` integer — Amount of invited count.
  - `cashier` object, nullable — Cashier information.
    - `id` integer — Cashier ID.
    - `displayName` string — Cashier name.
  - `branch` object, nullable — Branch information.
    - `id` integer — Branch ID.
    - `displayName` string — Branch name.
  - `points` number — The amount of points which changed customer balance as a result of the operation. A negative value means write-off of bonus points and a positive value means point accrual.
  - `certificatePoints` number, nullable — Number of deducted certificate points.
  - `receiptNumber` string, nullable — Receipt number.
  - `origin` object, nullable — Reference to origin operation (for operations in state REVERSAL).
    - `id` integer — Origin transaction ID.

---

[API](https://skmtc.dev/uds/apis/uds-api.md) · [All operations](https://skmtc.dev/uds/apis/uds-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/uds/uds-api/revisions/6fbbbc79e671/schema)