What to expect after the SP-API migration

Once you have reauthorized Amazon, you will be moved across onto the new API. You will receive two emails: the first to tell you when to expect to be moved, and the second to confirm the move has taken place. 

Most of the Amazon connector functionality will remain the same, but there are a few important changes to order downloads to be aware of.

Order row prices and tax amounts

Due to limitations in Amazon's API for the Europe region, prices and tax amounts are handled differently between the European and North American Amazon marketplaces.

North America Amazon region

  • Item prices are imported as net (excluding tax) as standard. 
  • Tax amounts are imported as sent by Amazon, not recalculated from the Brightpearl tax code. Note the Brightpearl tax code is still applied to the order row using the existing integration tax rules.
    See the rules for sales tax here.

Note: We believe Amazon has a defect relating to withheld taxes for Canadian provinces. We are verifying this with Amazon.

Europe Amazon region (includes UK)

  • Item prices are calculated as net (excluding tax). However, Amazon's API only provides item prices including tax, without specifying the tax amount for the order. Therefore Brightpearl must recalculate the net amount using the tax code applied to the order.
  • Tax amounts are recalculated using the Brightpearl tax code. Because Amazon does not provide any granular tax information via the API, Brightpearl must calculate the expected tax value using the tax code applied to the order row. The tax code is determined using the existing integration tax rules. See the rules for VAT here.

Warning: Because Brightpearl must recalculate the tax amount, we cannot guarantee the amount of tax set on the order will match Amazon's tax calculation. We are in contact with Amazon to request the tax amount be included in the API in order to improve the accuracy of our tax data.

Withheld tax

The way Brightpearl handles Amazon orders containing withheld tax has been improved across both regions to ensure payments match order totals. 

  • When Amazon withholds taxes, the tax amount is set to 0.00 on the order. Brightpearl only does this when Amazon tells us in the order data that they withheld taxes, as Brightpearl does not have the required information to guess this important information.

Important: Amazon has a defect in the SP-API for orders where certain cross-border shipping scenarios have withheld tax shown in Amazon Seller Central, but this information isn’t sent via the order API. We are working with them to understand timelines to fix or if workarounds are possible.

You can identify the affected sales orders by waiting for the settlement report to download, then going to Sales > Recent sales and filtering for:

  • Channel: Amazon channels
  • Payment: Partially paid

To correct them, remove the tax amount from each order row so the order total matches the payment total. Alternatively, you can mark them paid for the difference, then post a bank payment to the sales tax nominal code in order to correct the accounts.

Pending order contact details

If you are downloading pending orders, you need to make sure that the placeholder contact you have set up has the following key fields populated:

  • First and last name
  • Email address
  • Address
    • First line
    • City
    • Postcode/ZIP code
    • Country

As these details will never be used except during the pending order stage, you can use any placeholder text that is valid (i.e. an email in the form of text@example.com and a valid postcode/ZIP code format), as long as the fields are populated.

Order download performance

The order downloader has been improved to make it faster and more reliable. However, to fix some defects the "Number of days to attempt to create order for" setting has been removed.

Investigation has found that orders very rarely fail repeatedly then recover much later on, as the technical causes of failure either resolve soon after or not at all. However, attempting to handle this scenario caused orders without issues to be delayed without explanation.

To reduce missed orders, the ability to specify how long to attempt order creation has been removed.

Orders are still retried by the downloader in case of short-term errors, and the order reconciliation process runs nightly, looking back on the previous 36 hours for missed orders.

Once that time frame has passed, orders that are missed will need to be manually added.

Note that this change does not impact checking for changes to pending orders. Pending orders are checked every 21 days. This change only impacts cases where Brightpearl is unable to process brand new data (e.g. being informed of a brand new order, or a cancellation or shipping status update for an existing pending order).

Known issues to be aware of

Pending FBA orders are not automatically cancelled

If you have download pending orders enabled and a customer places an FBA order, the FBA order will download into Brightpearl in a pending state. If this order is then cancelled, the pending order in Brightpearl should also be cancelled. However, we have identified a long-standing issue that means these orders are not being automatically cancelled.

While this issue is being addressed, any pending orders related to cancelled FBA orders will have to be cancelled in Brightpearl manually.

Old orders being created in Brightpearl

Amazon occasionally sends Brightpearl details of old orders. When this happens, the order may be created in Brightpearl despite being several years old. The team are working on implementing changes to prevent these orders from being created in Brightpearl.

Bulk inventory last run time not updating

When running a bulk inventory update, the last run time and the number of tries left do not update. This is a cosmetic issue which will be addressed. We have confirmed the inventory update still runs.

Orders for buyers whose names contain emoji are not downloading

Brightpearl does not support the use of emoji in contact records. If a customer with an emoji in their name places an order, the contact record and therefore the order cannot be created. The team are planning to add functionality to the Amazon connector to handle situations where a buyer's name contains emoji.

Have more questions? Submit a request