1. Order
  2. Sales Order

Sales Order POST

URI

https://{DATACENTER}.brightpearlconnect.com/public-api/{ACCOUNT}
/order-service/sales-order/

Refer to our documentation on URI syntax for more information on how to construct URIs.

Description

This message enables you to create new sales orders in Brightpearl.

Field Summary:

Field Description Data Type Required Values
customer.id The ID of the customer you wish this order to be created for. Note that this field is also accepted (and returned by GET) at the top level as "customerId" for backward-compatibility. int Yes
customer.address Override the address of the customer for this order. If not specified, the customer's default address from the contact record will be used. address object (see later)
billing.contactId The ID of the customer you wish to use as the billing contact for this order. If not specified, the primary contact of the customer's organization will be used. int
billing.address Override the billing address for this order. If not specified, the billing address of the billing.contactId will be used. address object (see later)
ref The customer reference you wish to assign to this order. string
placedOn The date this order was placed on. If this is not specified today's date will be used. string. ISO8601 format date.
taxDate This is the tax date of the order. If this is not specified today's date will be used. string. ISO 8601 format date.
parentId You can use parentId if you want to link your new order to an existing order in Brightpearl. string
statusId

The ID of the status you wish to assign to this order. If no status ID is specified then the configured default is used.

int
warehouseId

The ID of the warehouse which will be used by default for fulfilment.

int
channelId

The ID of the channel you wish to assign this order to.

int
externalRef The external reference you wish to assign to this order. When both externalRef and installedIntegrationInstanceId are provided they form a unique compound key. If another order is posted with the same combination it will be assumed to be a duplicate and result in a 200 response. No changes will be made to the order in this case. string
installedIntegrationInstanceId The installed integration instance this order is associated with. When both installedIntegrationInstanceId and externalRef are provided they form a unique compound key. If another order is posted with the same combination it will be assumed to be a duplicate and result in a 200 response. No changes will be made to the order in this case. int
staffOwnerId

The ID of the staff member who owns this order. If you do not specify this value then it will be set automatically if you have the auto assign property enabled in your sales settings.

int
projectId

The ID of the project you wish to assign this order to.

int
leadSourceId

The ID of the lead source you wish to assign this order to. If not specified the default for the customer is used.

int
teamId

The ID of the team you wish to assign this order to.

int
priceListId

The ID of the price list you wish to use for this order. If no price list ID is provided the customer's assigned price list is used.

int
priceModeCode

'INC' or 'EXC'. Allows you to override the price list's price mode.

string 'INC' or 'EXC'
currency.code

The currency you wish to set this order to be. If not specified the default for the customer is used.

string. 3 chars.
currency.fixedExchangeRate

If this parameter is true (or not given at all), then the exchange rate that is set when the order is created will be used when the order is invoiced. This exchange rate can either be sent in the exchangeRate field of the POST, or determined automatically by Brightpearl. If this is set to false, then the exchange rate will be determined by Brightpearl when the order is invoiced.

boolean
currency.exchangeRate

The exchange rate to use when calculating base currency amounts from the order currency. This parameter can only be used if the fixedExchangeRate parameter is true.

string. A number with up to six decimal places.
delivery.date The date you wish to have the order delivered on. string. ISO8601 format date.
delivery.address The delivery address for the order address object (see later)
delivery.shippingMethodId The ID of the shipping method to be used to fulfil this order. int
rows An array of order rows associated with this order array

Field Summary: rows

Field Description Data Type Required Values
productId The ID of the product you wish to add to the order. int If name not supplied
name The name of the product or description of the row. string If productId not supplied
quantity The quantity of items in this row. string Yes Must be an integer for stock-tracked product or bundle rows. Can be up to 4dp otherwise.
taxCode The tax code for this row. string Yes
net The net value of this row. string If using a net value Max precision of 4dp.
tax The tax value of this row. string If using a net value Max precision of 4dp.
nominalCode The nominal code for this row.
If you do not provide a nominal code, then the following rules will be used to determine which nominal code will be applied to the row
  • The nominal code associated to the customer will be used
  • If the customer does not have a nominal code, the nominal code associated with the product will be used
  • If the product does not have a nominal code or it is not a Brightpearl product the default sales nominal code is used
 string
sequence

Used to define a sorting order (ascending) for rows. Please note that the Brightpearl back-office can be configured to display rows in a number of different sort orders other than this sequence value, including name and product SKU etc. - this is visible as a property of the account configuration.

If a value is not provided, a sequence number which is greater than the highest number already on the order will be used. When sorting by sequence, the row will therefore appear as the last item on the order.

int

Field summary: addresses

Where the type 'address object' appears in the table above, the following fields may be used. Fields marked as required are only required if the address object is supplied (which may or may not be required)

Field Description Data Type Required
addressFullName The full name of the person associated with this address. string
companyName The name of the company associated with the address. string
addressLine1 The first line of the address (e.g. street) string
addressLine2 The second line of the address (e.g. suburb) string
addressLine3 The third line of the address (e.g. city) string
addressLine4 The fourth line of the address (e.g. state / province) string
postalCode The postal/zip code of the address string
countryIsoCode ISO-3166 code for the country in the address string Yes
telephone Telephone number associated with the address string
mobileTelephone Mobile/cell number associated with the address string
fax Fax number associated with the address string
email Email address associated with the postal address string

Additional Information

  • Tax date for the created order is set to today's date.
  • Payment due date is set today's date plus the customer's credit terms.
  • If a department ID is supplied or inherited from a customer then the warehouse assigned to this department will be used for this order. If one is not found then this defaults to your default warehouse.
  • Price mode can be supplied, inherited from the order's price list or inherited from the customer's price list.
  • Delivery address set to delivery address of customer.
  • Note that when adding a product which is a bundle to an order, the children are automatically added as individual order lines. This relationship can be seen in the read-only properties bundleChild, bundleParent and parentRowId on a sales order GET request.

Example

Creating a new sales order.

Request URI

/sales-order/

Request body

{
	"customer": {
		"id": 203
	},
	"ref": "Created via new Sales Order POST endpoint",
	"placedOn": "2016-09-29T11:12:24.000+01:00",
	"taxDate": "2016-06-08T12:57:25+00:00",
	"parentId": 206,
	"statusId": 1,
	"warehouseId": 2,
	"staffOwnerId": 204,
	"projectId": 1,
	"channelId": 2,
	"externalRef": "hsdf74-2js7-jdsfi38-73jsd8",
	"installedIntegrationInstanceId": 23,
	"leadSourceId": 4,
	"teamId": 1000,
	"priceListId": 2,
	"priceModeCode": "INC",
	"currency": {
		"code": "GBP",
		"fixedExchangeRate": true,
		"exchangeRate": "1"
	},
	"delivery": {
		"date": "2016-09-29T11:12:24.000+01:00",
		"address": {
			"addressFullName": "John Doe",
			"companyName": "BrightPearl",
			"addressLine1": "First floor",
			"addressLine2": "New Bond House",
			"addressLine3": "Bristol",
			"addressLine4": "near Cabot Circus",
			"postalCode": "BS2 9AG",
			"countryIsoCode": "GBR",
			"telephone": "01234 567890",
			"mobileTelephone": "070707070707",
			"email": "john.doe@brightpearl.com"
		},
		"shippingMethodId": 6
	},
	"rows": [
		{
			"productId": 1007,
			"name": "Nerf darts",
			"quantity": "1000",
			"taxCode": "T20",
			"net": "100",
			"tax": "20",
			"nominalCode": "4000",
			"externalRef": "723423-234-234dsdwe3-fsfefe4f-dfse3"
		},
		{
			"productId": 1008,
			"name": "Nerf guns",
			"quantity": "20",
			"taxCode": "T20",
			"net": "200",
			"tax": "40",
			"nominalCode": "4000",
			"externalRef": "7hgfjksdf-234sfd-w34-sdf-w234"
		},
		{
			"productId": 1000,
			"name": "Shipping",
			"quantity": "1",
			"taxCode": "T20",
			"net": "20",
			"tax": "10",
			"nominalCode": "4000",
			"externalRef": "fsd639sdf-sdf7w3hsdf-2w347sdhf"
		}
	]
}

Response

{
	"response": 42
}