1. Order
  2. Sales Credit

Sales Credit POST

URI

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

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

Description

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

Field Summary:

Field Description Data Type Required Values
customer.id The ID of the customer you wish this credit 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 credit. 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 credit. If not specified, the primary contact of the customer's organization will be used. int
billing.address Override the billing address for this credit. 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 credit. string
placedOn The date this credit 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 credit. 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 credit to an existing order in Brightpearl. string
statusId

The ID of the status you wish to assign to this credit. 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 credit to.

int
externalRef The external reference you wish to assign to this credit. When both externalRef and installedIntegrationInstanceId are provided they form a unique compound key. If another credit 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 credit in this case. string
installedIntegrationInstanceId The installed integration instance this credit is associated with. When both installedIntegrationInstanceId and externalRef are provided they form a unique compound key. If another credit 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 credit in this case. int
staffOwnerId

The ID of the staff member who owns this credit. 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 credit to.

int
leadSourceId

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

int
teamId

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

int
priceListId

The ID of the price list you wish to use for this credit. 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 credit 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 credit is created will be used when the credit 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 credit is invoiced.

boolean
currency.exchangeRate

The exchange rate to use when calculating base currency amounts from the credit 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 credit delivered on. string. ISO8601 format date.
delivery.address The delivery address for the credit address object (see later)
delivery.shippingMethodId The ID of the shipping method to be used to fulfil this credit. int
rows An array of order rows associated with this credit array

Field Summary: rows

Field Description Data Type Required Values
productId The ID of the product you wish to add to the credit. 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 credit will be used. When sorting by sequence, the row will therefore appear as the last item on the credit.

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 No
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 credit 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 credit. If one is not found then this defaults to your default warehouse.
  • Price mode can be supplied, inherited from the credits's price list or inherited from the customer's price list.
  • Default address set to default address of customer.
  • Delivery address set to delivery address of customer.
  • The billing address is set to the billing address of the customer who is the primary contact for the company.
  • 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 credit GET request.

Example

Creating a new sales credit.

Request URI

/sales-credit/

Request body

{
	"customerId": 203,
	"ref": "Created via new Sales Credit 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
}