Is there a way to create an order (or update it later) using the BigCommerce API and set the payment status to complete? The documentation says that the field payment_status is read only. But I am thinking that perhaps there is some other update that one can do that would have the effect of setting payment_status.
What I want to do is create an order have marked as payment completed.
You cannot currently set the 'payment_status' parameter on an order to any value. An order created via the API will show a blank value for 'payment_status' unless you go into the Control Panel and manually process the order. Beyond changing that 'payment_status' parameter value though, if your goal is to make your store treat an API submitted order as paid, you can do that by changing the 'status_id' parameter.
If you create or update an order via the API to have a 'status_id' value of 2 or 10 ('Shipped' and 'Completed' statuses, respectively), then the store will consider that order paid. What this means is that store statistics will incorporate the details of that order into order statistics. At this time the 'payment_status' really only tells you if an order was paid using the store's built-in payment integrations. This detail will only matter if you do take payments external to Bigcommerce in some way and then submit them via API.
So if your goal was simply to change the 'payment_status' and has nothing to do with your store recognizing the order as paid, then that is not currently possible using only actions on the API. You cannot capture or take a payment using built-in payment integrations via actions taken on the API, but you can record a payment taken externally into the system.
Here are some other notes for people taking payments external to their Bigcommerce store and submitting those completed (paid) orders via the API:
Setting the order to status ID 2 (Shipped) or status ID 10 (Completed) is functionally the same in the system. Orders can be created with these statuses outright and the store will treat them as paid and completed orders for statistics. This is good if your order has been paid and shipped before submission but often people have taken payment but want to submit the order pre-shipment. Submitting order pre-shipment puts it in the queue to have shipment processed like all of your normal orders.
The common process to follow for this use case is to create the order with an 'Awaiting Fulfillment' status (ID 11), just like how orders submitted through the store front will display in store. You can then process the shipment in the Control Panel or using a 3rd party shipping manager like with all standard orders. You could even submit an order as 'Awaiting Fulfillment' and then add shipments via the API. If you add shipments that account for all of the products in the order then the order status will automatically be updated to 'Shipped' status. If you add a shipment that only accounts for a subset of the order's products then the status is automatically changed to 'Partially Shipped'.
Other useful parameter that can be set for someone submitting orders via API are:
payment_method
payment_provider_id
external_source
All of the above parameters will accept a string which then attaches to the order and displays in the Control Panel on the order. There are no strict definitions on what values should go in there but the general usage of those fields by the cart is as follows. The 'payment_method' will hold the name of the payment gateway used or the method in which payment was taken. The 'payment_provider_id' will receive the transaction or reference ID of the order at the payment provider. The 'external_source' is used to identify who has submitted this order over the API.
I hope the above helps you better understand how to best utilize the Bigcommerce API for submitting orders.