Order POST

URI

https://{DATACENTER}.brightpearl.com/public-api/{ACCOUNT}
/order-service/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/credits and purchase orders/credits in your Brightpearl system.

Field Summary:

Field Description Data Type Required Values
orderTypeCode

Specifies what type of order you are creating.

String True
  • SO - Sales Order
  • SC - Sales Credit
  • PO - Purchase Order
  • PC - Purchase Credit
reference

The customer/supplier reference you wish to assign to this order.

String False
parentOrderId

You can use parentOrderId if you want to link your new order to an existing order in Brightpearl. This is useful for creating returns against an original sale, or a back-to-back purchase order against a sales order.

String False
priceListId

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

int False
priceModeCode

'INC' or 'EXC'. Allows you to override the price list's price mode. SO/SC only.

String False 'INC' or 'EXC'
placedOn

The date this order was placed on. If this is not specified today's date will be used.

String. ISO8601 format date. False
orderStatus.orderStatusId

The ID of the status you wish to assign to this order. Note SO/SC/PO/PC all have their own statuses. If no status ID is specified then the configured default is used.

int False
delivery.deliveryDate

The date you wish to have the order delivered on. If not specified and this order is a PO this defaults to today's Date plus the contact's lead time.

String. ISO8601 format date. False
delivery.shippingMethodId

The ID of the shipping method to be used to fulfil this order.

int False
invoices

Array of invoice objects.

Array False
invoices.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. False
currency.orderCurrencyCode

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

String. 3 chars. False
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 False
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. False
contactId

The ID of the contact you wish this order to be created for.

NOTE.
  • For SO/SC the block containing the contactId is called 'customer'.
  • For PO/PC it's called 'supplier'.
int True
parties

This block contains the details about the various contacts involved in the order.

Object False
parties.delivery

This block contains the delivery details.

NOTE.
  • this block is optional, however in order to add a delivery address there are some minimum required fields.
Object False
parties.delivery.addressFullName

The full name of the contact associated with this address.

String False
parties.delivery.companyName

The name of the company associated with the address.

String False
parties.delivery.addressLine1

The first line of the delivery address.

String True
parties.delivery.addressLine2

The second line of the delivery address.

String False
parties.delivery.addressLine3

The third line of the delivery address.

String False
parties.delivery.addressLine4

The fourth line of the delivery address.

String False
parties.delivery.postalCode

The post code of the delivery address.

String False
parties.delivery.countryId

The country ID of the country.

NOTE.
  • this field is not optional if countryIsoCode is not provided
String False
parties.delivery.countryIsoCode

The ISO 3166 code of the country.

NOTE.
  • this field is not optional if countryId is not provided so one of the two must be provided
String False
parties.delivery.telephone

The telephone number associated with the delivery address.

String False
parties.delivery.mobileTelephone

The mobile telephone number associated with the delivery address.

String False
parties.delivery.fax

The fax number associated with the delivery address.

String False
parties.delivery.email

The email address associated with the delivery address.

String False
assignment

Holds details of the assignment of the order such as which staff member is assigned to the order.

Object False
assignment.current

Holds the details of the current assignment of the order.

Object False
assignment.current.channelId

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

int False
assignment.current.leadSourceId

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

int False
assignment.current.projectId

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

int False
assignment.current.staffOwnerContactId

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

int False
assignment.current.teamId

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

int False
warehouseId

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

int False

Additional Information

  • Tax date for the created order is set to today's date.
  • Payment due date is set today's date plus the contact credit terms.
  • If a department ID is supplied or inherited from a contact 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.
Sales Order / Sales Credit Purchase Order / Purchase Credit
Price mode can be supplied, inherited from the order's price list or inherited from the customer's price list. Price mode is set to tax excluded (EXC).
Default address set to default address of customer. Default address set to default address of supplier.
Delivery address set to delivery address of customer. Delivery address set to your Brightpearl account's address as defined in your settings.
The billing address is set to the billing address of the contact who is the primary contact for the company. Billing address set to same address.

Example 1

Creating a new sales order.

Request URI

/order/

Request body

{
	"orderTypeCode": "SO",
	"reference": "order#001",
	"priceListId": 2,
	"invoices": [
		{
			"taxDate": "2012-06-08T12:57:25+00:00"
		}
	],
	"placedOn": "2011-09-29T11:12:24.000+01:00",
	"orderStatus": {
		"orderStatusId": 1
	},
	"delivery": {
		"deliveryDate": "2011-09-29T11:12:24.000+01:00",
		"shippingMethodId": 2
	},
	"currency": {
		"orderCurrencyCode": "GBP",
		"fixedExchangeRate": true,
		"exchangeRate": 0.773200
	},
	"parties": {
		"customer": {
			"contactId": 204
		}
	},
	"assignment": {
		"current": {
			"channelId": 1,
			"leadSourceId": 1,
			"projectId": 1,
			"staffOwnerContactId": 501,
			"teamId": 2
		}
	}
}

Response

{
	"response": 42
}

Example 2

Creating a new purchase order.

Request URI

/order/

Request body

{
	"orderTypeCode": "PO",
	"reference": "parts#33345",
	"priceListId": 5,
	"placedOn": "2011-09-29T11:12:24.000+01:00",
	"orderStatus": {
		"orderStatusId": 6
	},
	"delivery": {
		"deliveryDate": "2011-09-29T11:12:24.000+01:00",
		"shippingMethodId": 1
	},
	"currency": {
		"orderCurrencyCode": "GBP"
	},
	"parties": {
		"supplier": {
			"contactId": 204
		}
	},
	"assignment": {
		"current": {
			"channelId": 1,
			"leadSourceId": 1,
			"projectId": 1,
			"staffOwnerContactId": 501
		}
	}
}

Response

{
	"response": 59
}

Example 3

Creating a new sales order with a delivery address.

Request URI

/order/

Request body

{
	"orderTypeCode": "SO",
	"reference": "order#001",
	"priceListId": 2,
	"placedOn": "2011-11-23T11:12:24.000+01:00",
	"orderStatus": {
		"orderStatusId": 1
	},
	"delivery": {
		"deliveryDate": "2011-11-23T11:12:24.000+01:00",
		"shippingMethodId": 2
	},
	"currency": {
		"orderCurrencyCode": "GBP"
	},
	"parties": {
		"customer": {
			"contactId": 210
		},
		"delivery": {
			"addressFullName": "Some one",
			"companyName": "BrightPearl",
			"addressLine1": "Brightpearl HQ",
			"addressLine2": "New Bond House",
			"addressLine3": "Bristol",
			"addressLine4": "near Cabot Circus",
			"postalCode": "BS2 9AG",
			"countryIsoCode": "GBR",
			"telephone": "01234 567890",
			"mobileTelephone": "37127361",
			"email": "will@waccorp.com"
		}
	}
}

Response

{
	"response": 228
}