Programmatically Create an Order
Bold provides the Create Order endpoint for you to create an order and carry the order through all steps needed to complete it.
Use cases
The Create Order endpoint is very flexible, but it was designed with the following use cases in mind:
- When you want to populate all order details and complete order processing in a single API call.
- When you want to batch-create many draft orders at once.
Create Order vs Initialize Order
The Initialize Order endpoint can also be used to initiate and populate an order. While these endpoints are similar, they differ in key ways:
Create Order | Initialize Order |
---|---|
Request body requires only an idempotency_key . | Request body has no required fields. |
Can perform order processing and other functions (see Order creation commands). | Requires additional calls to finalize and process order. |
Does not create a JSON Web Token (JWT). | Creates a JWT that can be used throughout the checkout process. |
For more information about the Initialize Order endpoint, refer to Initialize, Populate, and Process a Checkout Order.
Create Order sample request
The following code snippet is an example request body for the Create Order endpoint:
Expand to view example.
{
"cart_items": [
{
"sku": "KLS_472945",
"quantity": 2,
"line_item_key": "db3b1963-6ddd-4115-9f45-64c7edb3867d"
}
],
"customer": {
"first_name": "John",
"last_name": "Doe",
"email_address": "[email protected]",
"accepts_marketing": false,
"public_id": "EYRJPZwuC6obRHgGn2x2oQiGMaw9N7DM7QtII7g0sJYYDcKYpyNkGvv4ddJM7I0I"
},
"shipping_address": {
"first_name": "John",
"last_name": "Doe",
"address_line_1": "50 Fultz Blvd",
"address_line_2": "Suite 200",
"city": "Winnipeg",
"province": "Manitoba",
"province_code": "MB",
"country": "Canada",
"country_code": "CA",
"postal_code": "R3Y0L6"
},
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"address_line_1": "50 Fultz Blvd",
"address_line_2": "Suite 200",
"city": "Winnipeg",
"province": "Manitoba",
"province_code": "MB",
"country": "Canada",
"country_code": "CA",
"postal_code": "R3Y0L6"
},
"discounts": [
{
"discount_code": "SPRINGSALE2022_Q8RT4"
}
],
"payments": [
{
"public_payment_method_id": "ftziZRlloXJhR8emShyZePgaZxFTp9TN6Ai0tVWOB223g9qCGQQFA27ccW2fx72U"
}
],
"currency": "CAD",
"idempotency_key": "2b268b6f-b3c0-4efb-9c43-1aa59d535182",
"send_receipt": true,
"commands": {
"0": "calculate_shipping",
"1": "calculate_tax_rates",
"2": "authorize_payments",
"3": "process_order",
"4": "send_to_platform",
"5": "charge_payments"
}
}
Order creation commands
In the request body of Create Order, Bold accepts an array of order creation commands
, which Bold completes in the specified order.
While Bold can complete these commands in any order, the following sequence is recommended in order to minimize errors:
calculate_shipping
calculate_tax_rates
authorize_payments
process_order
send_to_platform
charge_payments
If you provide certain information about the order, such as shipping or taxes, but also ask Bold to calculate that information, Bold will use its own calculation.
If any step fails, Bold responds with a 422
error containing details about the response and command that created the response.
The following sections dive into these commands and their preconditions in more detail.
Calculate shipping
Use the calculate_shipping
command to use Bold's shipping calculation logic to determine the cost of shipping. This calculation is based on the shipping address and available shipping lines. If any shipping information exists on the order when this command is executed, Bold overwrites the existing information with the new calculation.
Preconditions
For Bold to successfully execute this command, the order in your request must have the following information:
shipping_address
Calculate tax rates
Use the calculate_tax_rates
command to use Bold's tax calculation logic to determine the taxes on the cart. If any tax information exists on the order when this command is executed, Bold overwrites the existing information with the new calculation.
Preconditions
For Bold to successfully execute this command, the order in your request must have the following information:
shipping_address
Authorize payments
Use the authorize_payments
command to place an authorization hold on the funds required to pay for the order. This command does not complete the charge, and you must call this command before calling the charge_payments
command.
You can provide a payment method to the Create Order endpoint in one of the following two ways:
- Via a customer's default payment method. When provided
payments[].public_customer_id
, Bold uses that customer's saved default payment method. - Via a customer's non-default saved payment method. When provided
payments[].public_payment_method_id
, Bold uses the payment method provided.
In all cases, the payment must be one of an authorized customer's saved payment methods. Bold identifies authorized customers by either the presence of customer.public_id
or customer.platform_id
on the request.
Each payment method can have an optional amount
. The following diagram and steps outline the process Bold uses to apply payments to the order.
- Bold creates two groups of payments: those with amounts, and those without.
- Bold first applies all payments with amounts, in the order they were given in the request. If these payments cover the full order cost, Bold applies payments up to the full order total.
- For example, if Bold receives two $50 payments for a $75 order, the full $50 from the first payment is used and only $25 from the second is used.
- If a payment method is a gift card, Bold uses whichever is smaller: the payment
amount
or the remaining gift card balance.
- If there is a remaining balance, Bold uses the payments without amounts to pay the remaining balance. If there is no remaining balance, no charges are applied to those payments.
- If a payment method is a gift card, Bold uses whichever is smaller: the remaining order total or the remaining gift card balance.
- If the sum of payments is not enough to cover the order total, the order will fail during the Process Order step.
Bold recommends providing at least one payment method that does not have an amount in order to cover the entirety of the order total.
If you provide only payments with amounts, Bold assumes that this payment amount is final, and Bold cannot apply any more payments to cover the gap. This means that if Bold has to change the order total at a later point due to tax, shipping, or other calculations, it is possible that the order total will change and the existing payment amounts will not be sufficient to cover the full order.
Preconditions
For Bold to successfully execute this command, the order in your request must have the following information:
customer.email_address
billing_address
Process order
Use the process_order
command to check the validity of the order and finalize it.
During processing, Bold completes the following steps:
- Verify that inventory is able to fulfill the order (optional, based on platform settings).
- Finalize and apply discounts.
- If you have a tax integration (i.e., TaxJar or Vertex), confirm order creation and taxes.
- Delete abandoned carts associated with customer email address.
- Clear the customer's cart.
- If any are registered, send a series of webhooks and plugin events.
Preconditions
For Bold to successfully execute this command, the order in your request must have the following information:
customer.email_address
shipping_address
- An array of
payments
that covers the order total. - A shipping line that applies to the shipping address, if required.
Send to platform
Use the send_to_platform
command to push the order details to the given platform.
Preconditions
For Bold to successfully execute this command, the order in your request must have the following information:
customer
andcustomer.email_address
shipping_address
- A shipping line that applies to the shipping address, if required.
- One or more items in the order.
Charge payments
Use the charge_payments
command to charge the payments that Bold previously authorized.
Preconditions
For Bold to successfully execute this command, the order in your request must have the following information:
customer.email_address
billing_address