Skip to main content

Import an order

note

The channelCode, warehouseCode, carrierServiceIdentifier and sku values in the examples are placeholders — use real values from your channel configuration. Channel codes are provided by Calicantus during onboarding: if you do not have yours, contact developers@calicant.us.

Use orderImport mutation to submit a new order for a channel.

The mutation accepts an OrderImportInput object, with nested OrderImportBillingInput, OrderImportLineInput, OrderImportShippingInput, OrderImportShippingOrderLineInput and OrderImportParcelInput — their references list all the available fields.

Minimal example​

The smallest payload accepted: the required fields only, one line and one shipping (see the field notes below for the rules that the schema alone does not tell).

Request
mutation orderImport {
  orderImport(
    input: {
      channelCode: "ECOM"
      number: "123456789"
      deliveryId: "123456789"
      createdAt: "2026-06-25T10:30:00.000Z"
      currency: "EUR"
      totalNetAmount: 100.0
      totalVatAmount: 22.0
      totalGrossAmount: 122.0
      totalPaidAmount: 122.0
      billing: {
        firstName: "Mario"
        lastName: "Rossi"
        address1: "Via Roma 1"
        city: "Milano"
        isoCountry: "IT"
        province: "MI"
        zipCode: "20100"
      }
      lines: [
        {
          kind: item
          sku: "SKU-1"
          skuDescription: "Example product"
          quantity: 1
          originalUnitaryPrice: 100.0
          discountedUnitaryPrice: 100.0
          vatPercentage: 22.0
        }
      ]
      shippings: [
        {
          firstName: "Mario"
          lastName: "Rossi"
          address1: "Via Roma 1"
          city: "Milano"
          isoCountry: "IT"
          zipCode: "20100"
          carrierServiceIdentifier: "STANDARD"
        }
      ]
    }
  ) {
    id
    number
    deliveryId
    status
  }
}
Open in playground
Response
{
  "data": {
    "orderImport": {
      "id": "12346",
      "number": "123456789",
      "deliveryId": "123456789",
      "status": "acquiring"
    }
  },
  "extensions": {
    "queryComplexity": 5,
    "bucketBalance": 9995,
    "bucketRestoreRate": 100
  }
}

After the import​

A successful import returns the created order with status: acquiring: that is the success outcome, no further action is required from the integration. OMS then runs its own checks and calculations asynchronously (for example the line VAT amounts): while the order is acquiring, do not rely on the values computed by OMS. If the checks detect an issue the order moves to with_anomalies, handled by the Calicantus customer care, and then to ready once resolved. The full order lifecycle is documented in Order and shipping statuses.

Field notes​

Order (root fields)​

  • number is the order identifier assigned by the integration that submits the order and must be unique within the channel: a duplicate is rejected with the error code DUPLICATED_ORDER (see Errors), so it can be intercepted without parsing the message. A number that still has a pending import submission is rejected as well.
  • deliveryId is the order identifier as the customer sees it in the e-shop, in almost all cases the same value as number.
  • documentationLanguage is one of de, en, es, fr or it (case-insensitive, stored uppercase); any other value is rejected. It defaults to en.
  • invoiceRequired is forced to true when billing.vatNumber is populated (see B2B orders below).
  • note carries the note written by the buyer when placing the order.
  • totalNetAmount, totalGrossAmount and totalVatAmount are recomputed from the lines during the acquisition (net prices, plus VAT on top): always send values consistent with the line prices. totalPaidAmount is stored as provided.

billing​

  • The billing address and fiscal data. The address fields address1, city, province, zipCode and isoCountry are required.
  • It must identify a recipient: provide either companyName, or both firstName and lastName, otherwise the import fails with Billing recipient is required.
  • A populated vatNumber triggers the B2B handling (VIES validation, possible reverse charge): see B2B orders below.

lines​

  • The order lines; at least one is required. kind is item, shipping_charge, payment_charge or coupon.
  • Prices are net prices, excluding VAT. Both originalUnitaryPrice (the full price) and discountedUnitaryPrice (the final unit price after every discount applied to the line, line-level coupons included) must always be populated: when no discount applies, send the same value in both.
  • An order-level coupon is a coupon line with a negative price (the same negative value in both price fields): OMS subtracts it from the order totals. Negative prices are accepted only on coupon lines.
  • The sku is not checked against the channel catalogue at import time, so make sure it is correct.

shippings​

  • The shipping destinations; at least one is required. Each shipping must identify a recipient with the same rule as billing (Shipping recipient is required).
  • carrierServiceIdentifier is an arbitrary string identifying the shipping method (we recommend it includes the shipping zone and the service/carrier type); OMS maps it to a specific carrier.
  • warehouseCode is required on multi-warehouse channels (Shipping warehouse code is required) and must belong to the channel; on a single-warehouse channel it can be omitted.
  • lines splits the item line quantities across shippings (non-item lines such as shipping_charge are attached automatically to the first shipping). It is required when there is more than one shipping and can be omitted for a single shipping that dispatches the whole order. Each lineNumber must match an item order line number, and the quantities of each item line across all shippings must add up to exactly the ordered quantity.
  • parcels contains optional parcel details: kind is box or pallet, dimensions (length, width, height) are in centimeters and weight in grams (e.g. weight: 5000 is 5 kg).

B2B orders: vatNumber and reverse charge​

This section only matters when you submit a billing.vatNumber; B2C orders are not affected.

Any non-empty vatNumber forces invoiceRequired to true. OMS validates the number against VIES: when it is valid and the billing country is an EU country different from the seller's, the order is treated as a B2B sale under reverse charge, so vatPercentage becomes 0 on every line and the line prices are converted to their VAT-inclusive value (a 100.0 line at 22.0% becomes 122.0), keeping the order total unchanged.

caution

For B2B orders whose prices are already VAT-free, send the lines with vatPercentage: 0 and the final prices: the reverse charge conversion leaves them unchanged. Do not send the product's usual VAT rate "for information": an order actually paid 100.0 submitted with vatPercentage: 22.0 is stored with a line price of 122.0 and an order total of 122.0, while totalPaidAmount stays 100.0.

Full example​

An order with every field populated, split across two shippings: the item line (quantity 2) is shipped 1 + 1 from two dispatches, each with its own parcels and lines. shippings.lines is only needed in this multi-shipping case.

Request
mutation orderImport {
  orderImport(
    input: {
      channelCode: "ECOM"
      number: "123456789"
      deliveryId: "123456789"
      createdAt: "2026-06-25T10:30:00.000Z"
      currency: "EUR"
      paymentMethod: "credit_card"
      invoiceRequired: true
      documentationLanguage: "it"
      totalNetAmount: 110.0
      totalGrossAmount: 134.2
      totalVatAmount: 24.2
      totalPaidAmount: 134.2
      billing: {
        firstName: "Mario"
        lastName: "Rossi"
        companyName: "Rossi Srl"
        fiscalCode: "RSSMRA80A01H501U"
        city: "Milano"
        address1: "Via Roma 1"
        isoCountry: "IT"
        province: "MI"
        zipCode: "20100"
        telephone: "+390212345678"
        email: "mario.rossi@example.com"
        pec: "rossi@examplepec.it"
        destinationCode: "ABC1234"
        vatNumber: "IT12345678901"
      }
      lines: [
        {
          number: "1"
          kind: item
          sku: "SKU-1"
          skuDescription: "Example product"
          quantity: 2
          originalUnitaryPrice: 55.0
          discountedUnitaryPrice: 50.0
          vatPercentage: 22.0
        }
        {
          number: "2"
          kind: shipping_charge
          sku: "SHIP"
          skuDescription: "Shipping charge"
          quantity: 1
          originalUnitaryPrice: 10.0
          discountedUnitaryPrice: 10.0
          vatPercentage: 22.0
        }
      ]
      shippings: [
        {
          number: "SHP-1"
          firstName: "Mario"
          lastName: "Rossi"
          address1: "Via Roma 1"
          zipCode: "20100"
          province: "MI"
          city: "Milano"
          isoCountry: "IT"
          email: "mario.rossi@example.com"
          telephone: "+390212345678"
          warehouseCode: "MIL"
          carrierServiceIdentifier: "DHL_EXPRESS"
          parcels: [
            {
              kind: box
              length: 30.0
              width: 20.0
              height: 10.0
              weight: 2500.0
              tailLiftRequired: false
            }
          ]
          lines: [
            { lineNumber: "1", quantity: 1 }
          ]
        }
        {
          number: "SHP-2"
          firstName: "Mario"
          lastName: "Rossi"
          address1: "Via Roma 1"
          zipCode: "20100"
          province: "MI"
          city: "Milano"
          isoCountry: "IT"
          email: "mario.rossi@example.com"
          telephone: "+390212345678"
          warehouseCode: "MIL"
          carrierServiceIdentifier: "DHL_EXPRESS"
          parcels: [
            {
              kind: box
              length: 30.0
              width: 20.0
              height: 10.0
              weight: 2500.0
              tailLiftRequired: false
            }
          ]
          lines: [
            { lineNumber: "1", quantity: 1 }
          ]
        }
      ]
    }
  ) {
    id
    number
    deliveryId
    status
  }
}
Open in playground
Response
{
  "data": {
    "orderImport": {
      "id": "12345",
      "number": "123456789",
      "deliveryId": "123456789",
      "status": "acquiring"
    }
  },
  "extensions": {
    "queryComplexity": 5,
    "bucketBalance": 9995,
    "bucketRestoreRate": 100
  }
}

Relevant permissions

The operations in this page require the following permissions on the API credentials — they are configured for you by Calicantus.

  • order:mutation:order_import
  • order:read