Order API - Create Order

Create order

Endpoint: POST *base*/order
Authentication: API Key

This will insert a new order directly into Centra bypassing any needs of a payment. This API could be used to directly import orders from external systems. The API-plugin needs to have "Allow Order Create" set as true to allow this call to be made.

Remember that payments for these orders will not be handled at all by Centra. You must make sure the payments are handled and captured elsewhere.

Parameters

Here are the parameters allowed to create an order. There are some fields specific for B2B and B2C defined below.

invoiceAddress deliveryAddress address
object
optional

For B2B the address object is not required as it will then use default address of the B2B-account. If invoiceAddress and deliveryAddress are the same, address can be used instead.

email
string
required

Customer e-mail

firstName lastName
string
optional

Customer name

tele cell
string
optional

Customer telephone / cellphone

attn
string
optional

Attention (addressing memorandum)

address coaddress city zipcode
string
optional

Street Address

state
string
optional

Country state, might be required by the country

country
string
required

ISO-Alpha-2 (SE, US, GB etc)

pricelistId
int
optional

ID of pricelist to use for the order, if not provided, the pricelist for the current country will be used.

pricelist
string
optional

Name of pricelist to use for the order. Will only be used if pricelistId is not provided. If not provided, the pricelist for the current country will be used.

marketId
int
optional

ID of the market to use for the order. If not provided, the market for the current country will be used.

market
string
optional

Name of the market to use for the order. Will only be used if marketId is not provided. If not provided, the market for the current country will be used.

customerRegister
boolean
optional

Default false. If true, the order will attach to the customer registered with the same e-mail provided in the API-call. If customerRegister is false, the order will be created as a auto-created one and will not be visible by the signed in customer having the same e-mail.

customerId
int
optional

If this one is set, the customer ID will be used as the way to attach the order to a customer, independently of the e-mail provided.

customerSetNewPassword
boolean
optional

Default false. Will flag the customer so the customer will receive a password reset e-mail when they try to sign in. This can be used when migrating customers over from another system.

createdFromOrigin
object
optional

Specifies the origin that the order was created from. If used, it needs to refer to an internal object in Centra.

type
string
required

Type of origin the order was created from. Allowed types: return, order and plugin

id
int
required

ID of internal origin of the origin type. If Return #123 was used to create the order, id should be 123.

extraAttributes
object
optional

Object for sending in custom order attributes.

attributeName_elementName
any
optional

List of key-value pairs for every attribute element you want to set. Send it as an empty string to remove the current content.

accountId
int
optional

Account ID for B2B-customer. Required if order is placed for B2B.

buyerId
int
optional

Buyer ID for B2B-customer. If not provided, the default buyer of the account will be used.

buyerName
string
optional

Name of the buyer that placed the order.

deliveryWindow
string
optional

Name of the Delivery Window being used when placing the order. Depending if the products are set to preorder or not, the order might extract stock or not.

products
object
required

Contains the products for the order.

qty
int
required

Quantity ordered for this product.

id
int
optional

ID specific to the product size. Either id, ean or sku must be used.

ean
string
optional

EAN of product item. Either id, ean or sku must be used.

sku
string
optional

SKU of product item. Should either be the Size SKU or a combination of Product SKU + Variant SKU + Size SKU. Either id, ean or sku must be used.

unitPrice
decimal2 (0.00)
optional

Unit price used for the sale of this product. If not set, the pricelist value (in combination with current campaign discounts set up in Centra) will be used.

originalPrice
decimal2 (0.00)
optional

The original unit price used for the product. Will calculate what discount the customer got when the order was placed. If not set, the price from the current pricelist will be used.

comment
string
optional

A specific comment for the product. Can be used to define a specific date for each product, or a customized comment. Will show up on delivery notes and pack-lists.

itemText
object
optional

Ability to define every column specifying the product information. Very useful when importing old orders for products not in Centra.

sku
string
optional

The SKU for this product.

brand
string
optional

The Brand name for this product.

product
string
optional

Product name.

variant
string
optional

The variant name of the product.

size
string
optional

The size name for this product. To make sure all visual representations in Centra looks good, please make sure this size exists on the sizechart selected for the product you used inside id, ean or sku.

shippingList
string
optional

Shipping option URI, for example: ups-standard, without this one, the default shipping option for the products and country will be used.

shippingValue
decimal2 (0.00)
optional

Shipping cost, for example: 12.43, without this one, the default shipping cost for the products and country will be used.

voucherValue
decimal2 (0.00)
optional

Voucher value, should be a positive value or zero, even though the value ends up reducing the order value.

orderNumber
int
optional

Explictly set the order number for the order. Will only work if the order does not already exist in Centra.

sendEmail
boolean
optional

Send order confirmation or not, if not provided, the store settings will be used.

adjustStock
boolean
optional

Default true. Extract products from stock and fail with error if stock does not exist. If deliveryWindow is set as preorder this setting will not matter.

forceCreate
boolean
optional

Default false. Create the order even though products did not exist. These products will be marked as back ordered.

comment
string
optional

Text to place inside the "Other Information" field. Might show up on pack-lists and delivery notes depending on store settings.

internalComment
string
optional

Text for the "Internal comment"-field. Will only be shown internally in Centra.

poNumber
string
optional

PO number used when placing the order. Will be visible on delivery notes and invoices.

orderDate
date/datetime
optional

The time when the order was placed. Timezone is based on the location of the organization's Centra settings.

deliveryDate
date/datetime
optional

Expected time of delivery.

cancelDate
date/datetime
optional

Date when order should be cancelled if not confirmed.

warehouseGroup
string
optional

Used to define which allocation rule (previously known as "warehouse group") it should use. Default will use the one set for the market.

createOnly
boolean
optional

Default false. Only prepare the order with all data, can be finalized later using :doc:completeOrder </reference/stable/order-api/complete-order>.

internalOrder
boolean
optional

Default false. Mark the order as internal, will show up in reports as an internal order.

payment
object
optional

Will contain information that should be inserted in regards to how the payment was handled outside of Centra.

id
int
optional

The ID of the payment plugin used from Centra. If not used, the order will not be marked with a payment type at all.

auth / capture
object
optional

Information about the authorization and capture of the order. Authorization was the reservation of the order, capture is when the value also has been charged. You can add separate information via payment.auth and payment.capture objects.

response
string
optional

The response string from the payment type. Will be shown verbose inside Centra.

status
int
required

If the authorization/capture went through or not. 0 means pending, 1 means success, 2 means failed.

transaction
string
optional

The transaction ID of the authorization/capture.

method
string
optional

Will be shown on reports to summarize what payment method was used.

amount
decimal2 (0.00)
required

The amount that was authorized.

external_url
string
optional

If an external invoice was created, insert the URL to the invoice here.

applyVouchers
boolean
optional

Default true. If Centra should calculate the voucher value depending on automatic voucher rules.

voucherCodes
array
optional

Array of voucher codes to apply on the order.

Request example

POST <base>/order HTTP/1.1
Content-type: application/json

{
  "invoiceAddress": {
      "country": "SE",
      "firstName": "John",
      "lastName": "Smith",
      "address": "12 Alto Road",
      "coaddress": "c/o Peter",
      "zipcode": "90212",
      "city": "San Francisco",
      "email": "x@example.com"
  },
  "deliveryAddress": {
      "country": "US",
      "firstName": "John",
      "lastName": "Smith",
      "address": "1500 California St",
      "coaddress": "c/o Peter",
      "zipcode": "90210",
      "city": "San Francisco",
      "state": "CA"
  },
  "products": [
      {
          "qty": 2,
          "ean": "ABCDEFGHIJKL",
          "unitPrice": 14.11,
          "originalPrice": 100.11,
          "itemText" : {
            "sku": "SPECIAL-SKU-FOR-THIS-ONE",
            "product": "A special product",
            "variant": ""
          }
      },
      {
          "qty": 1,
          "sku": "SKUASKUBSKUC",
          "unitPrice": 12.11,
          "originalPrice": 50.22
      }
  ],
  "payment": {
      "id": 36,
      "auth": {
          "status": 1,
          "transaction": "894751945132",
          "method": "cc",
          "amount": 26.22
      },
      "capture": {
          "status": 1,
          "transaction": "154342468439",
          "method": "cc",
          "amount": 26.22
      }
  },
  "voucherCodes": ["MyFirstGiftcard", "New10PercentOff"]
}

The response will return an array of orders when the call was successful (unless you used createOnly set as true). This is because the order might have been split into different orders depending on rules inside Centra.

Response

200 Content-type: application/json

status
string
required

ok if success, else no.

order
int
optional

Will return if createOnly was set as true.

orders
array of int
optional

List of order numbers created. An order might split up in multiple orders after completing it, this is why you might get multiple orders back.

msg
string
optional

If status returns no, this value should send back a message why it failed.

Response examples

HTTP/1.1 200 OK
Content-type: application/json

{
  "status": "ok",
  "orders": [
    1234
  ]
}

If createOnly is set to true, the response looks like this:

{
  "status": "ok",
  "order": 1234
}

Error example

Errors will always be returned with "status" as "no" it will also contain a code and a message with more details the codes and their general meaning is as follows

Code Description
-1 Some of the provided products are not possible to add to the order, product status, market or pricelist might not be properly configured inside centra.
-2 Stock error, one or more products are missing stock
-3 Order is empty
-4 One or more required fields are missing
-5 An order with the provided order number already exists
-6 Customer registration failed
-7 General error, see message for details
{
  "status": "no",
  "code": -7,
  "msg": "Message about why the order failed to be created."
}

Previous article: Order API reference