> Documentation index: [Saleor](/llms.txt) · [This section](/developer/llms.txt)
> Source: https://docs.saleor.io/developer/bulks/bulk-orders
# Bulk Order Import
This guide describes a mutation allowing users to create multiple orders in Saleor. Purpose of this mutation could be importing orders from other systems. The main assumption is to allow the user to specify as many fields as possible and skip most of the logic and calculations that are done when creating orders from draft or checkout. Among other things, the mutation allows specifying things like: order creation date, order number, order lines with net and gross line prices, payment transactions and fulfillments.
## [`orderBulkCreate`](/api-reference/orders/mutations/order-bulk-create.md)
### Example Mutation
**Mutation**
```graphql
mutation OrderBulkCreate(
$orders: [OrderBulkCreateInput!]!
$errorPolicy: ErrorPolicyEnum
$stockUpdatePolicy: StockUpdatePolicyEnum
) {
orderBulkCreate(
orders: $orders
errorPolicy: $errorPolicy
stockUpdatePolicy: $stockUpdatePolicy
) {
count
results {
order {
id
user {
id
email
}
metadata {
key
value
}
privateMetadata {
key
value
}
lines {
id
variant {
id
}
productName
variantName
translatedVariantName
translatedProductName
productVariantId
isShippingRequired
quantity
quantityFulfilled
unitPrice {
gross {
amount
}
net {
amount
}
}
unitDiscount {
amount
}
totalPrice {
gross {
amount
}
net {
amount
}
}
undiscountedUnitPrice {
gross {
amount
}
net {
amount
}
}
metadata {
key
value
}
privateMetadata {
key
value
}
taxClass {
id
}
taxClassName
taxRate
taxClassMetadata {
key
value
}
taxClassPrivateMetadata {
key
value
}
}
billingAddress {
postalCode
}
shippingAddress {
postalCode
}
shippingMethodName
shippingTaxClass {
name
}
shippingTaxClassName
shippingTaxClassMetadata {
key
value
}
shippingTaxClassPrivateMetadata {
key
value
}
shippingPrice {
gross {
amount
}
net {
amount
}
}
total {
gross {
amount
}
net {
amount
}
}
undiscountedTotal {
gross {
amount
}
net {
amount
}
}
events {
message
user {
id
}
app {
id
}
}
weight {
value
}
externalReference
trackingClientId
displayGrossPrices
channel {
slug
}
status
created
collectionPointName
redirectUrl
origin
fulfillments {
lines {
quantity
orderLine {
id
}
}
trackingNumber
fulfillmentOrder
status
}
transactions {
id
name
pspReference
message
authorizedAmount {
amount
currency
}
canceledAmount {
currency
amount
}
chargedAmount {
currency
amount
}
refundedAmount {
currency
amount
}
events {
amount {
amount
}
type
}
}
invoices {
number
url
}
discounts {
valueType
value
reason
}
}
errors {
path
message
code
}
}
}
}
```
**Variables**
```graphql
{
"stockUpdatePolicy": "SKIP",
"errorPolicy": "REJECT_EVERYTHING",
"orders": [
{
"channel": "default-channel",
"createdAt": "2022-07-13T17:30:15+05:30",
"status": "FULFILLED",
"user": {
"email":"austin.sparks@example.com"
},
"billingAddress": {
"firstName": "John Saleor",
"lastName": "Doe",
"companyName": "Saleor Commrce",
"streetAddress1": "Tęczowa 7",
"streetAddress2": "",
"postalCode": "53-601",
"country": "PL",
"city": "Wrocław",
"countryArea": "",
"phone": "+48321321888"
},
"shippingAddress": {
"firstName": "John Saleor",
"lastName": "Doe",
"companyName": "Saleor Commrce",
"streetAddress1": "Tęczowa 7",
"streetAddress2": "",
"postalCode": "53-601",
"country": "PL",
"city": "Wrocław",
"countryArea": "",
"phone": "+48321321888"
},
"currency": "USD",
"languageCode": "PL",
"deliveryMethod": {
"shippingMethodId": "U2hpcHBpbmdNZXRob2Q6MTM=",
"shippingMethodName": "DHL",
"shippingTaxClassId": "VGF4Q2xhc3M6Mw==",
"shippingPrice": {
"gross": 120,
"net": 100
},
"shippingTaxRate": 0.2,
"shippingTaxClassMetadata": [
{
"key": "md key",
"value": "md value"
}
],
"shippingTaxClassPrivateMetadata": [
{
"key": "pmd key",
"value": "pmd value"
}
]
},
"lines": [
{
"variantId": "UHJvZHVjdFZhcmlhbnQ6MzQx",
"createdAt": "2022-07-20T17:30:15+05:30",
"productName": "Product Name",
"variantName": "Variant Name",
"translatedProductName": "Nazwa Produktu",
"translatedVariantName": "Nazwa Wariantu",
"isShippingRequired": true,
"isGiftCard": false,
"quantity": 5,
"totalPrice": {
"gross": 120,
"net": 100
},
"undiscountedTotalPrice": {
"gross": 120,
"net": 100
},
"warehouse": "V2FyZWhvdXNlOjllZjQ1MDgwLTJkMmItNDgxMi04MDVkLThmYzgyODg2MWI5Mw==",
"taxRate": 0.2,
"taxClassId": "VGF4Q2xhc3M6MQ==",
"taxClassName": "Line Tax Class Name",
"taxClassMetadata": [
{
"key": "md key",
"value": "md value"
}
],
"taxClassPrivateMetadata": [
{
"key": "pmd key",
"value": "pmd value"
}
]
}
],
"fulfillments": [
{
"trackingCode": "tracking-id-123",
"lines": [
{
"variantId": "UHJvZHVjdFZhcmlhbnQ6MzQx",
"quantity": 5,
"warehouse": "V2FyZWhvdXNlOjllZjQ1MDgwLTJkMmItNDgxMi04MDVkLThmYzgyODg2MWI5Mw==",
"orderLineIndex": 0
}
]
}
],
"transactions": [
{
"name": "Payment XYZ",
"message": "Success",
"pspReference": "PSP reference - 123",
"availableActions": [
"REFUND"
],
"amountAuthorized": {
"amount": 240,
"currency": "USD"
},
"amountCharged": {
"amount": 240,
"currency": "USD"
},
"metadata": [
{
"key": "md key",
"value": "md value"
}
],
"privateMetadata": [
{
"key": "pmd key",
"value": "pmd value"
}
]
}
],
"invoices": [
{
"number": "01/12/2020/TEST",
"url": "http://www.example.com",
"createdAt": "2022-07-13T17:30:15+05:30",
"metadata": [
{
"key": "md key",
"value": "md value"
}
],
"privateMetadata": [
{
"key": "pmd key",
"value": "pmd value"
}
]
}
],
"discounts": [
{
"valueType": "FIXED",
"value": 10,
"reason": "Black Friday"
}
],
"giftCards": ["Gift_card_1"],
"voucherCode": "FREESHIPPING",
"weight": "10.15",
"metadata": [
{
"key": "md key",
"value": "md value"
}
],
"privateMetadata": [
{
"key": "pmd key",
"value": "pmd value"
}
]
}
]
}
```
**Result**
```graphql
{
"data": {
"orderBulkCreate": {
"count": 1,
"results": [
{
"order": {
"id": "T3JkZXI6Njg3OWJlMzMtNTYzYi00NjhkLWI3ZjItZmUwYzc1ODhmOWMx",
"number": "36",
"user": {
"id": "VXNlcjoxMg==",
"email": "austin.sparks@example.com"
},
"metadata": [
{
"key": "md key",
"value": "md value"
}
],
"privateMetadata": [
{
"key": "pmd key",
"value": "pmd value"
}
],
"lines": [
{
"id": "T3JkZXJMaW5lOjRhYTJlOWJlLWIxNTgtNDNiOS1iMmM2LTg2NjYyNGQwNDY0ZQ==",
"variant": {
"id": "UHJvZHVjdFZhcmlhbnQ6MzQx"
},
"productName": "Product Name",
"variantName": "Variant Name",
"translatedVariantName": "Nazwa Wariantu",
"translatedProductName": "Nazwa Produktu",
"productVariantId": "UHJvZHVjdFZhcmlhbnQ6MzQx",
"isShippingRequired": true,
"quantity": 5,
"quantityFulfilled": 5,
"unitPrice": {
"gross": {
"amount": 24
},
"net": {
"amount": 20
}
},
"unitDiscount": {
"amount": 0
},
"totalPrice": {
"gross": {
"amount": 120
},
"net": {
"amount": 100
}
},
"undiscountedUnitPrice": {
"gross": {
"amount": 24
},
"net": {
"amount": 20
}
},
"metadata": [],
"privateMetadata": [],
"taxClass": {
"id": "VGF4Q2xhc3M6MQ=="
},
"taxClassName": "Line Tax Class Name",
"taxRate": 0.2,
"taxClassMetadata": [
{
"key": "md key",
"value": "md value"
}
],
"taxClassPrivateMetadata": [
{
"key": "pmd key",
"value": "pmd value"
}
]
}
],
"billingAddress": {
"postalCode": "53-601"
},
"shippingAddress": {
"postalCode": "53-601"
},
"shippingMethodName": "DHL",
"shippingTaxClass": null,
"shippingTaxClassName": null,
"shippingTaxClassMetadata": [
{
"key": "md key",
"value": "md value"
}
],
"shippingTaxClassPrivateMetadata": [
{
"key": "pmd key",
"value": "pmd value"
}
],
"shippingPrice": {
"gross": {
"amount": 120
},
"net": {
"amount": 100
}
},
"total": {
"gross": {
"amount": 240
},
"net": {
"amount": 200
}
},
"undiscountedTotal": {
"gross": {
"amount": 240
},
"net": {
"amount": 200
}
},
"events": [],
"weight": {
"value": 10.15
},
"externalReference": null,
"trackingClientId": "",
"displayGrossPrices": false,
"channel": {
"slug": "default-channel"
},
"status": "FULFILLED",
"created": "2022-07-13T17:30:15+05:30",
"collectionPointName": null,
"redirectUrl": null,
"origin": "BULK_CREATE",
"fulfillments": [
{
"lines": [
{
"quantity": 5,
"orderLine": {
"id": "T3JkZXJMaW5lOjRhYTJlOWJlLWIxNTgtNDNiOS1iMmM2LTg2NjYyNGQwNDY0ZQ=="
}
}
],
"trackingNumber": "tracking-id-123",
"fulfillmentOrder": 1,
"status": "FULFILLED"
}
],
"transactions": [
{
"id": "VHJhbnNhY3Rpb25JdGVtOmI3ZTM0ODQwLWYyYWQtNDMzNS1hNzk2LTU4Yjg5YTdkNjc5MA==",
"name": "Payment XYZ",
"pspReference": "PSP reference - 123",
"message": "Success",
"authorizedAmount": {
"amount": 240,
"currency": "USD"
},
"canceledAmount": {
"currency": "USD",
"amount": 0
},
"chargedAmount": {
"currency": "USD",
"amount": 240
},
"refundedAmount": {
"currency": "USD",
"amount": 0
},
"events": [
{
"amount": {
"amount": 240
},
"type": "CHARGE_SUCCESS"
},
{
"amount": {
"amount": 240
},
"type": "AUTHORIZATION_SUCCESS"
}
]
}
],
"invoices": [
{
"number": "01/12/2020/TEST",
"url": "http://www.example.com"
}
],
"discounts": [
{
"valueType": "FIXED",
"value": 10,
"reason": "Black Friday"
}
]
},
"errors": []
}
]
}
},
"extensions": {
"cost": {
"requestedQueryCost": 22,
"maximumAvailable": 50000
}
}
}
```
### Permission
Since this operation is broader in scope than regular order management, it is not automatically assigned to staff users or apps with `MANAGE_ORDERS` permission. The mutation requires a new permission: `MANAGE_ORDERS_IMPORT`.
### Input details
#### User (`OrderBulkCreateUserInput`)
To identify a user, the mutation accepts one of the following identifiers: `id`, `email` or `external_reference`. If the user associated with an order doesn’t exist in Saleor database, user's email can be provided as a reference in the order instance. If you want to skip adding user, you need to use [`IGNORE_FAILED`](/developer/bulks/error-policy.md#ignore_failed) policy.
#### Delivery method (`OrderBulkCreateDeliveryMethodInput`)
Since orders can be either shipped or collected directly from a warehouse, either `warehouseId` or `shippingMethodId` must be provided. Orders with all lines set `isShippingRequired` flag to `false` don't require physical delivery. In this case, `OrderBulkCreateDeliveryMethodInput` can be omitted.
The input also accepts arbitrary names of delivery methods (`warehouseName`and `shippingMethodName` fields) and tax class (`taxClassName`).
If `shippingPrice` is not provided, Saleor will fetch the current shipping method price from database.
#### Order line (`OrderBulkCreateOrderLineInput`)
`totalPrice` and `undiscountedTotalPrice` are the primary sources of truth about the order pricing. Based on the fields, Saleor calculates unit price, undiscounted unit price, unit discount amount, order total and subtotal.
To find product variant, the mutation accepts one of the following identifiers: `id`, `sku` or `external_reference`.
The input also accepts arbitrary names of variant (`variantName`), product (`productName`) and tax class (`taxClassName`).
`isShippingRequired` - determines if line items need to be physically shipped. If all lines of an order do not require shipping, `OrderBulkCreateInput.deliveryMethod` can be skipped.
`warehouse` - ID of the warehouse where the order line should be allocated. This field is required because Saleor performs stock allocation at the time of order creation, even if the order is unfulfilled. Allocation reserves stock in a specific warehouse to ensure availability and prevent overselling. Since allocations are immediate and fulfillment may happen later, the warehouse must be explicitly provided and cannot be omitted.
warning
If you include order lines containing product variants no longer existing in Saleor database, you need to use [`IGNORE_FAILED`](/developer/bulks/error-policy.md#ignore_failed) error policy.
#### Fulfillments (`OrderBulkCreateFulfillmentLineInput`)
Product variant is searched by one of the following identifiers: `id`, `sku` or `external_reference`.
To match fulfillment line with respective order line, `OrderBulkCreateFulfillmentLineInput` requires `orderLineIndex`. It is a 0-based index of `OrderBulkCreateInput.lines` list.
#### Notes (`OrderBulkCreateNoteInput`)
The input allows to provide a custom list of events that would be saved as `OrderEvent` instances in the order history. For each event, the user can provide a message, timestamp, and either a user or an app that is associated with the event.
#### Gift cards and vouchers
The input accepts a list of gift card codes and a single voucher code that should be associated with the order, but it doesn’t trigger any price recalculation. Prices are based only on line totals. Please note, that the voucher is not validated during import, therefore code usage will not be counted.
#### CreatedAt fields
Some systems might have incorrect time that is in the future compared to Saleor. Therefore mutation accepts future time values within 5 minutes from current time. `createdAt` is required field in following inputs:
- `OrderBulkCreateInput`
- `OrderBulkCreateOrderLineInput`
- `OrderBulkCreateInvoiceInput`
#### Billing and Shipping addresses
The provided addresses are validated according to the [validation rules](/developer/address.md#validation-rules). You can disable address validation by setting the `skipValidation` flag to `true` in the `AddressInput` (lear more [here](/developer/address.md#skipping-the-address-validation)).
Shipping and billing addresses are not stored in the user’s address book.
### Stock update policy
The policy determines how stocks should be updated, while processing an order.
- `UPDATE` (default) - only do an update, if there is enough stock. Otherwise produce an error.
- `SKIP` - stocks are not checked and not updated.
- `FORCE` - force update, if there is not enough stock.
### Error policy
`orderBulkCreate` mutation as well as other new bulk mutations accepts [`errorPolicy`](/developer/bulks/error-policy.md) argument, which determines how to handle errors. But please note, that some of errors ignore this policy and disqualify whole order:
- order number is not unique
- invalid billing address
- channel can’t be resolved
- delivery method can’t be resolved (if shipping is required)
- at least one of the order lines can’t be created
- at least one of the fulfillments can’t be created
- not enough or non-existing stocks (taking into account `stockUpdatePolicy`)
### Webhooks
If successful, the mutation will emit `ORDER_BULK_CREATE` event with a list of all created orders.