Orders

Create an array of 1 to 100 CONFIRMED Orders atomically. If any order fails, none are stored. Every order requires at least one service* or at least one product*; both arrays cannot be empty or omitted. * At least one of products or services must be provided; one of the two is required. When active Picking is included in the confirmed workflow, every product must have a positive quantity. Orders and workflows are created in the same transaction. An externalId already used by a non-deleted Order returns ORDER_ALREADY_EXISTS; the repeated request does not update the existing Order.

POSThttp://localhost:3000/api/v1/orders
Method
POST
Content type
application/json
Authentication
Required · active locations · non-expired key
Maximum payload
1 MiB
Request frequency
30 requests per 60 seconds

Request headers

Send these headers with every POST request.

Content-Type: application/json
Authorization: Bearer y3m_ABCD2345_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

To get the authorization key, open Dashboard, use the three-dot menu on the company card, and select API integrations. Under Secret keys, select Create secret key, enable the Orders scope, and assign at least one active location. Copy the full key when it is created because it is shown only once, then send it after Bearer in the Authorization header.

Request fields

Required and optional fields accepted in the JSON request body. Unknown fields are rejected at every level.

FieldTypeRequirementDescription
externalIdstringRequiredCaller-controlled source-system identifier; it does not need to be a UUID. A value already used by a non-deleted Order returns ORDER_ALREADY_EXISTS. A value used only by deleted Orders creates a new Order with a new internal Y3M UUID v7.
orderobject | nullOptionalOptional external order identity.
order.codestringOn createRequired when order is provided on create.
order.typestringOptionalOptional external order type.
order.namestringOptionalOptional external order name.
datesobject | nullOptionalOptional document dates.
dates.invoicedateOn createRequired when dates is provided on create.
packagesobject | nullOptionalOptional package count and type.
packages.type"box" | "pallet"On createPackage type. Required when packages is provided on create.
packages.valueintegerOn createNon-negative package count. Required when packages is provided on create.
discountobject | nullOptionalOptional percentage or fixed-amount discount.
discount.type"percent" | "amount"On createDiscount type. Required when discount is provided on create.
discount.valuedecimal stringOn createNon-negative discount value with up to three decimal places. Required when discount is provided on create.
descriptionstring | nullOptionalOptional order note.
amountobject | nullOptionalOptional subtotal, total and currency amounts.
amount.subtotaldecimal stringOptionalSubtotal amount.
amount.totaldecimal stringOn createRequired when amount is provided on create.
amount.currency"UAH" | "EUR" | "USD" | "PLN"OptionalOptional amount currency. Allowed values: UAH, EUR, USD, PLN.
weightobject | nullOptionalOptional weight in kilograms.
weight.type"kg"On createWeight unit. Required when weight is provided on create.
weight.valuedecimal stringOn createWeight value. Required when weight is provided on create.
volumeobject | nullOptionalOptional volume in cubic metres.
volume.type"m3"On createVolume unit. Required when volume is provided on create.
volume.valuedecimal stringOn createVolume value. Required when volume is provided on create.
customerobject | nullOptionalOptional customer reference resolved by externalId.
customer.externalIdstringOn createRequired when customer is provided on create.
productsarrayOn create** At least one of products or services must be provided on create; one of the two is required.
products[].externalIdstringOn createProduct external identifier required on create.
products[].positionintegerOptionalOptional line position.
products[].quantityobject | nullOptionalRequired with a positive value for every product when active Picking is included in the confirmed workflow; otherwise optional.
products[].quantity.valuedecimal stringOn createQuantity value required on create when quantity is provided.
products[].quantity.unit"pcs"On createQuantity unit required on create when quantity is provided.
products[].pricedecimal stringOptionalOptional unit price.
products[].amountdecimal stringOptionalOptional line amount.
products[].storagearrayOptionalOptional storage locations.
products[].storage[].type"shelf" | "pallet"On createStorage type required on create when storage is provided.
products[].storage[].valuestringOn createStorage identifier required on create when storage is provided.
servicesarrayOn create** At least one of products or services must be provided on create; one of the two is required.
services[].externalIdstringOn createService external identifier required on create.
services[].positionintegerOptionalOptional line position.
services[].quantityobject | nullOptionalService quantity.
services[].quantity.valuedecimal stringOn createQuantity value required on create when quantity is provided.
services[].quantity.unit"service"On createQuantity unit required on create when quantity is provided.
services[].pricedecimal stringOptionalOptional unit price.
services[].amountdecimal stringOptionalOptional line amount.

Error responses

Possible errors returned by this endpoint and how to resolve them.

StatusCodeMeaningResolution
400INVALID_JSONThe request body is not valid JSON.Send one correctly formatted JSON array.
400INVALID_PAYLOADThe JSON body is not an array.Send a root JSON array containing between 1 and 100 objects.
401UNAUTHORIZEDThe Authorization header is missing, malformed, or contains an invalid API key.Send a valid API key using the Bearer authorization scheme.
401API_KEY_EXPIREDThe API key has reached its expiration date.Create a new API key and retry the request.
403FORBIDDENThe API key cannot access this module or is not assigned to an active company location.Assign an active location, enable the required module, or use another key.
409CUSTOMER_DELETEDA customer referenced by externalId is deleted.Restore the customer in Y3M, then retry the request.
409ORDER_ALREADY_EXISTSA non-deleted Order already uses this externalId.Use another externalId or delete the existing Order before creating a new one.
409ORDER_WORKFLOW_CANCELEDThe Order workflow is canceled.Restore the Order to CONFIRMED before retrying.
409ORDER_WORKFLOW_STAGE_MISMATCHThe workflow state does not allow the operation or changed concurrently.Check the workflow state and retry if appropriate.
409PRODUCT_DELETEDA product referenced by externalId is deleted.Restore the product in Y3M, then retry the request.
409SERVICE_DELETEDA service referenced by externalId is deleted.Restore the service in Y3M, then retry the request.
413PAYLOAD_TOO_LARGEThe request body exceeds the 1 MiB limit.Reduce the JSON payload size to 1 MiB or less.
415UNSUPPORTED_MEDIA_TYPEThe Content-Type header is not application/json.Send Content-Type: application/json.
422VALIDATION_ERRORThe JSON is valid but one or more fields do not satisfy the endpoint contract.Use each { path, message } entry in error.details to correct the specified field.
429RATE_LIMIT_EXCEEDEDMore than 30 requests were sent within 60 seconds.Wait for the number of seconds specified by the Retry-After header.
500INTERNAL_ERRORRequest infrastructure, authentication, or rate-limit processing is temporarily unavailable.Retry later. Contact support if the error continues.
500STORAGE_ERRORThe validated payload could not be stored.Retry later. Contact support if the error continues.

Example request

Send this JSON array in the POST request body.

[
  {
    "externalId": "ORDER-001",
    "order": {
      "code": "962",
      "type": "Пн",
      "name": "МПП Черкаси-Кропивницький"
    },
    "dates": {
      "invoice": "2026-10-26"
    },
    "packages": {
      "type": "box",
      "value": 3
    },
    "discount": {
      "type": "percent",
      "value": "5.000"
    },
    "description": "Order note",
    "amount": {
      "subtotal": "225.830",
      "total": "214.540",
      "currency": "UAH"
    },
    "weight": {
      "type": "kg",
      "value": "17.493"
    },
    "volume": {
      "type": "m3",
      "value": "0.079"
    },
    "customer": {
      "externalId": "CUSTOMER-123"
    },
    "products": [
      {
        "externalId": "PRODUCT-001",
        "position": 1,
        "quantity": {
          "value": "2.000",
          "unit": "pcs"
        },
        "price": "150.000",
        "amount": "300.000",
        "storage": [
          {
            "type": "shelf",
            "value": "A-01-02"
          }
        ]
      }
    ],
    "services": [
      {
        "externalId": "SERVICE-001",
        "position": 1,
        "quantity": {
          "value": "1.000",
          "unit": "service"
        },
        "price": "50.000",
        "amount": "50.000"
      }
    ]
  }
]