4.90 & 4.91 API changes requiring action

Over the next few months we’re going to be making some significant changes to the Brightpearl API as we introduce new features and add full multi-currency support to our accounting system. The changes will be rolled out across two Brightpearl releases; 4.90 and 4.91.

Changes to the way orders are marked as paid

Before 4.90, you created a Sales Receipt (via accounting-service/sales-receipt POST) to pay a sales order. This created an accounting entry called a “journal” which was included in the calculation of payments against an order.

From 4.90, we are introducing two new entities called Customer Payment and Supplier Payment which will be used to pay orders. There are two new endpoints used to create these:

accounting-service/customer-payment POST

accounting-service/supplier-payment POST

This first creates a Customer/Supplier Payment entry, and then (depending on which Payment Method you use) Brightpearl will automatically create the Sales Receipt or Purchase Payment journal so that accounting is also correct. Read more about this in the Order Payments release notes and support documentation.

Just like with the Sales Receipt POST you’re currently using, Customer and Supplier Payments all have to be in BASE currency, regardless of the order currency (since for 4.90, Brightpearl accounting is still all base currency). However, at some point after 4.91 we will activate multi-currency (“MC”) after which, all order payments need to be in the ORDER currency. So if you’re going to be updating your integrations or apps to use these new endpoints, make sure that they are MC aware (see later). Not all Brightpearl accounts are updated at the same time, so your app will need to read the MC status of the account in question.

Payment methods

Each Customer/Supplier payment needs to have a Payment Method. If the Payment Method matches one that exists in Brightpearl it will be used to select the bank account used for the payment accounting. The Payment Method does not need to exist in Brightpearl but if doesn’t you won’t get a Sales Receipt following the Customer/Supplier Payment. In addition, if the Brightpearl Payment Method has no bank account assigned, no accounting will be created. There are some new endpoints that let you manage Payment Methods:

accounting-service/payment-method GET, POST, PUT

Payment totals

The total amount paid against an order is calculated using the sum of payments of type RECEIPT, PAYMENT or (for sales) CAPTURE. We have two endpoints that return the payment total against an order. Since order payments can be either base currency or (after MC is activated) foreign currency, the currency of the payments for the order is also given.

Note that all payments for an order must be in the same currency, so if you part paid a foreign currency order before MC was turned on, subsequent payments for that order will also need to be in base currency even after MC is turned on. Use the payment currency in the endpoints below to determine the payment currency for an order that already has payments.

accounting-service/sale-payment-total GET

accounting-service/purchase-payment-total GET

Backwards compatibility … for a while

If you continue to use the deprecated accounting-service/sales-receipt POST and you pass an order ID, we will create a Customer/Supplier Payment for you to make sure that the order is marked as paid. This will only work in base currency.

Multi-currency

At some point after 4.91 is release, we will activate multi-currency for all Brightpearl accounts. The main change for app developers is that order payments (see above) need to be made in the order currency if multi-currency is turned on. If you are creating journals, then the existing accounting endpoints will still be available, but will only work in base currency.

To see whether your Brightpearl account has MC turned on, use the multiCurrency field in the

integration-service/account-configuration GET

We have written a full set of new accounting endpoints that support multi-currency, and have deprecated the old, base-currency only ones.

New endpoints

Contact journals:

These have a lot of logic built in to deal with clearing invoices, exchange rate variance calculation and so on.

accounting-service/invoice/sales-invoice POST

accounting-service/invoice/sales-credit POST

accounting-service/invoice/sales-receipt POST

accounting-service/invoice/purchase-invoice POST

accounting-service/invoice/purchase-credit POST

accounting-service/invoice/purchase-payment POST

Other journals:

This should be used for all other accounting creation; banking, expenses etc.

accounting-service/journal-entry POST

Deprecated endpoints

accounting-service/sales-receipt POST

accounting-service/account-payment POST (will be deleted in 4.91)

accounting-service/purchase-payment POST (will be deleted in 4.91)

All the Payment Authorization endpoints, SEARCH, GET, POST

New journal type codes

If you are creating or reading accounting journals, you need to be aware of the changes we have made to journal type codes. These changes are active from 4.90. Read more here.

Changed accounting method for Amazon payments

Prior to 4.90, we created a single SR journal for each payment against Amazon orders. If there was a fee, then this was included in the same SR journal. From 4.90, since we create a Customer Payment which is linked to the SR journal, we create a separate Bank Payment (BP) journal for the fee. If you’re doing any reporting on Amazon accounting data, you might need to update your App.

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.