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:

1. calculate_shipping
2. calculate_tax_rates
3. authorize_payments
4. process_order
5. send_to_platform
6. charge_payments

note

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.

1. Bold creates two groups of payments: those with amounts, and those without.
2. 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.
   1. 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.
   2. If a payment method is a gift card, Bold uses whichever is smaller: the payment amount or the remaining gift card balance.
3. 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.
   1. If a payment method is a gift card, Bold uses whichever is smaller: the remaining order total or the remaining gift card balance.
4. If the sum of payments is not enough to cover the order total, the order will fail during the Process Order step.

note

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:

1. Verify that inventory is able to fulfill the order (optional, based on platform settings).
2. Finalize and apply discounts.
3. If you have a tax integration (i.e., TaxJar or Vertex), confirm order creation and taxes.
4. Delete abandoned carts associated with customer email address.
5. Clear the customer's cart.
6. 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 and customer.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