Skip to main content

Populate a Checkout Order

When a customer is ready to check out, you can kick off the checkout process by initializing an order. The request body of this endpoint is flexible — you can leave it blank and populate it later, or use dynamic data from the platform to provide information about the cart and customer.

This page leads you through the scenario in which you initialize an empty order and populate it using the Checkout Frontend API as the customer moves through the checkout process. The following steps outline a suggested flow for populating a checkout order:

  1. Add items
  2. Add a guest or authenticated customer
  3. Set the shipping address
  4. Set the shipping line
  5. Set the billing address
  6. Apply a discount, if applicable
  7. Generate taxes
  8. Get the iframe
  9. Process the order
note
  • There are various ways to call the Checkout Frontend API based on your business logic and checkout requirements. The instructions presented on this page are simply one recommendation.
  • Refer to Checkout Frontend API Responses for details about what to expect from the responses to these API calls.

Prerequisites​

  1. Complete the steps outlined in the Checkout Getting Started guide.
  2. Initialize an empty order. More information about this command can be found in Create a Headless Checkout. In order to make the calls outlined in this document, you need the JWT returned by the Initialize Order endpoint.

Add items​

If you chose not to dynamically load cart data when you initialize an order, you can manually add line items to the order via the Add Line Item endpoint.

note
  • This endpoint requires either the sku or platform_id (also known as platform_variant_id) of the product to be added. These values can be found by calling any endpoint that deals with products or their variants, such as the List Product Variants endpoint.
  • The line_item_key is a user-defined unique identifier for each line item in the order. After you add the product to the order, you can later manipulate the line item using endpoints such as Update Line Item.

The following cURL command demonstrates how to add an item to the order with this endpoint:

curl --request POST 'https://api.boldcommerce.com/checkout/storefront/{shop_identifier}/{public_order_id}/items' \
     --header 'Authorization: Bearer {JWT}' \
     --header 'Bold-API-Version-Date: 2022-05-01' \
     --header 'Content-Type: application/json' \
     --data '{
         "platform_id": "71",
         "sku": "CLC",
         "quantity": 1,
         "line_item_key": "key1"
     }'

Add customer​

If a customer is logged in when they enter the checkout flow, you can authenticate their identity using your platform and include their information in the Initialize Order request body.

However, if the customer does not have an account with your store or logs in later in the process, you can add a customer to an existing order. The following sections show you how to add a guest or authenticated customer after the order has already been created.

Add a guest customer​

The following cURL command demonstrates a call to the Add Guest Customer endpoint:

curl --request POST 'https://api.boldcommerce.com/checkout/storefront/{shop_identifier}/{public_order_id}/customer/guest' \
     --header 'Authorization: Bearer {JWT}' \
     --header 'Bold-API-Version-Date: 2022-05-01' \
     --header 'Content-Type: application/json' \
     --data '{
         "first_name": "John",
         "last_name": "Doe",
         "email_address": "john.doe@example.com",
         "accepts_marketing": true
     }'

Add an authenticated customer​

The following cURL command demonstrates a call to the Add Authenticated Customer endpoint. You can retrieve the customer's information from the platform or alternate user management system your store uses.

curl --request POST 'https://api.boldcommerce.com/checkout/orders/{shop_identifier}/{public_order_id}/customer/authenticated' \
     --header 'Authorization: Bearer {JWT}' \
     --header 'Bold-API-Version-Date: 2022-05-01' \
     --header 'Content-Type: application/json' \
     --data '{
         "first_name": "Jane",
         "last_name": "Doe",
         "email_address": "jane.doe@example.com",
         "platform_id": "string",
         "public_id": "string",
         "accepts_marketing": true,
         "saved_addresses": [
             {
                 "first_name": "Jane",
                 "last_name": "Doe",
                 "address_line_1": "50 Fultz Blvd",
                 "address_line_2": "",
                 "province": "Manitoba",
                 "city": "Winnipeg",
                 "country_code": "CA",
                 "country": "Canada",
                 "province_code": "MB",
                 "postal_code": "R3Y0L6",
                 "business_name": "",
                 "phone_number": "800-555-0100"
             }
         ]
     }'
note

If the customer is authenticated and has a saved address, you can populate their saved address in the UI and ask them to confirm the accuracy of the address. If they confirm it, you can then add the saved address as a shipping or billing address.

Set the shipping address​

Next, call the Set Shipping Address endpoint. Complete this step before adding a shipping line and calculating taxes.

The following cURL command demonstrates how to make this call:

curl --request POST 'https://api.boldcommerce.com/checkout/storefront/{shop_identifier}/{public_order_id}/addresses/shipping' \
     --header 'Authorization: Bearer {JWT}' \
     --header 'Bold-API-Version-Date: 2022-05-01' \
     --header 'Content-Type: application/json' \
     --data '{
         "first_name": "John",
         "last_name": "Doe",
         "address_line_1": "50 Fultz Blvd",
         "address_line_2": "",
         "province": "Manitoba",
         "city": "Winnipeg",
         "country_code": "CA",
         "country": "Canada",
         "province_code": "MB",
         "postal_code": "R3Y0L6",
         "business_name": "",
         "phone_number": "800-555-0101"
     }'

Set the shipping line​

Shipping lines represent shipping methods that are available to your customers. You can configure shipping lines in the Bold Checkout app by navigating to Shipping, then Shipping Zones.

Call the List Shipping Lines endpoint to determine the shipping lines that are available to your customer based on the shipping address they previously entered.

The following cURL command demonstrates a call to this endpoint:

curl --request GET 'https://api.boldcommerce.com/checkout/storefront/{shop_identifier}/{public_order_id}/shipping_lines' \
     --header 'Authorization: Bearer {JWT}' \
     --header 'Bold-API-Version-Date: 2022-05-01'

Calling this endpoint populates the available_shipping_lines object in the order's application_state object.

note

If there is only one available shipping line, the selected_shipping object automatically populates with the shipping line details and you can skip the remainder of this section.

When the customer selects how they would like their item to be shipped, use the index of the chosen shipping line to call the Set Shipping Line endpoint.

The following cURL command demonstrates how to select the shipping line at an index of 0:

curl --request POST 'https://api.boldcommerce.com/checkout/storefront/{shop_identifier}/{public_order_id}/shipping_lines' \
     --header 'Authorization: Bearer {JWT}' \
     --header 'Bold-API-Version-Date: 2022-05-01' \
     --header 'Content-Type: application/json' \
     --data '{
         "index": "0"
     }'

Set the billing address​

Next, call the Set Billing Address endpoint.

note

You might choose to include a checkbox that a customer can mark to indicate that their shipping and billing addresses are the same. If the customer marks the box, trigger the Set Billing Address endpoint using the address you previously collected.

The following cURL command demonstrates an example of making this call:

curl --request POST 'https://api.boldcommerce.com/checkout/storefront/{shop_identifier}/{public_order_id}/addresses/billing' \
     --header 'Authorization: Bearer {JWT}' \
     --header 'Bold-API-Version-Date: 2022-05-01' \
     --header 'Content-Type: application/json' \
     --data '{
         "id": "12",
         "first_name": "John",
         "last_name": "Doe",
         "address_line_1": "50 Fultz Blvd",
         "address_line_2": "",
         "province": "Manitoba",
         "city": "Winnipeg",
         "country_code": "CA",
         "country": "Canada",
         "province_code": "MB",
         "postal_code": "R3Y0L6",
         "business_name": "",
         "phone_number": "800-555-0102"
     }'

Add a discount code​

The Checkout Frontend API enables you to validate, apply, or delete a discount code that was configured in the Bold Checkout admin. Skip this step if your store does not have any discount codes or does not support them.

(Optional) Check validity​

While you are not required to check the validity of a discount code before you apply it, this step is useful if you want to implement custom error handling in a complicated discount code scenario. The Validate Discount Code endpoint performs this validation.

note

This endpoint does not apply the discount code, only checks that it is valid.

If the code is valid, the API returns an empty data array. If the discount code is not valid, the API returns the following error:

{
  "errors": [
    {
      "code": "02",
      "type": "discount_code.discount_validation",
      "message": "Could not find Discount: BFCM30"
    }
  ]
}

Apply the discount code​

Apply the code to the order using the Add Discount Code endpoint. The following cURL command demonstrates an example of this call:

curl --request POST 'https://api.boldcommerce.com/checkout/storefront/{shop_identifier}/{public_order_id}/discounts' \
     --header 'Authorization: Bearer {JWT}' \
     --header 'Bold-API-Version-Date: 2022-05-01' \
     --header 'Content-Type: application/json' \
     --data '{
         "code": "BFCM20"
     }'

Generate taxes​

After you collect the customer's address and apply any price changes, calculate the applicable taxes.

Configure your tax settings in the Bold Checkout app by clicking Payment Options, then Tax Settings. For more information, refer to Set up Tax Settings in Bold Checkout.

When you are ready to calculate an order's taxes, call the Generate Taxes endpoint. The following cURL snippet shows an example of that call:

curl --request POST 'https://api.boldcommerce.com/checkout/storefront/{shop_identifier}/{public_order_id}/taxes' \
     --header 'Authorization: Bearer {JWT}' \
     --header 'Bold-API-Version-Date: 2022-05-01'
note

Taxes are not recalculated automatically. If you make any changes to the shipping address (through Update Shipping Address or Delete Shipping Address) after you initially generate taxes, you must call the Generate Taxes endpoint again to recalculate the taxes. Failing to do so could result in charging customers for taxes inaccurately.

Initialize PIGI and add payment​

Bold uses a Payment Isolation Gateway Interface (PIGI) to isolate customer payment information from the rest of the site. This information is displayed in an <iframe> on a customer-facing page.

You must generate a new instance of PIGI for each order using a shop_identifier, public_order_id, and jwt. For detailed instructions on using PIGI, refer to the Payment Isolation Gateway Interface page.

After the customer enters their payment information and confirms it, you must capture the payment information using the PIGI_ADD_PAYMENT action.

For example, the following JavaScript snippet shows how you might take the information captured in the <iframe> and add a payment to the order:

const iframeElement = document.querySelector("iframe#PIGI");
const iframeWindow = iframeElement.contentWindow;
const action = { actionType: "PIGI_ADD_PAYMENT" };
iframeWindow.postMessage(action, "*");

A full list of PIGI actions and responses can be found in the PIGI API reference.

Process order​

When the customer indicates that they are ready to complete the order, call the Process Order endpoint. This call triggers the backend processing of the order.

When this command is called, Bold Checkout checks to ensure all components of the order are valid, including the following:

  • Taxes are calculated.
  • Inventory is still available for the chosen products.
  • Payment(s) are authorized.
  • Discounts are finalized and officially applied.

If each of these checks passes, Bold Checkout sends the order to the platform to be processed there. If one of these checks does not pass, the endpoint returns an error with a message indicating which step failed.

The following cURL command demonstrates an example of a call to process an order:

curl --request POST 'https://api.boldcommerce.com/checkout/storefront/{shop_identifier}/{public_order_id}/process_order' \
     --header 'Authorization: Bearer {JWT}' \
     --header 'Bold-API-Version-Date: 2022-05-01'

This command adds a payments object to the application_state object. Note that value of the status key is paid, but that the transactions list is empty.

The following snippet shows an example of the payments object:

"payments": [
    {
        "value": 5400,
        "amount": 54,
        "lineText": "1111",
        "tag": "Credit",
        "driver": "stripe",
        "merchant_account": "Stripe",
        "gateway_id": 35212,
        "step": "preAuthed",
        "token": "cus_Kn0z9EBAiVxo2f",
        "currency": "CAD",
        "id": "ch_3K7QycC6rJ6JeBJ015WC5hb8",
        "transaction_token": "ch_3K7QycC6rJ6JeBJ015WC5hb8",
        "brand": "Visa",
        "is_customer": false,
        "public_payment_method_id": null,
        "key": "PaymentByCreditCard:PaymentService;Final:91000",
        "status": "paid",
        "transactions": [],
        "is_eligible_for_app_fee": true,
        "has_app_fee_been_collected": false,
        "application_fee_charged": 54,
        "application_fee_tier_id": 25,
        "order_to_bold_exchange_rate": 1.27864,
        "order_to_bold_currency_id": 1,
        "tier_id": 0,
        "order_payment_type_id": 1,
        "additional_information": "",
        "initial_recurring_charge": false,
        "recurring_charge": false,
        "bold_customer_id": 23317222,
        "sequence_number": 1,
        "successful_preauth": true,
        "message": "",
        "error_details": [],
        "created_at": "2021-12-16 20:54:03.305734",
        "single_use_token": "tok_1K7QxhC6rJ6JeBJ0EgFwRoBI",
        "is_3ds_enabled": false,
        "client_secret": "",
        "idempotent_key": "",
        "first_four_digits": "",
        "bin": "",
        "expiry": "",
        "gateway_transaction_no": "",
        "avs_result": "",
        "cvd_result": "",
        "transaction_time": "205459",
        "transaction_date": "20211216",
        "reference_num": "",
        "txn_time": "",
        "authorization_code": "ch_3K7QycC6rJ6JeBJ015WC5hb8",
        "extra_payment_data": {
            "cof": "none"
        }
    }
]

Call the Get Application State endpoint to see the transactions list populate with data, as you can see in the following example:

"transactions": [
    {
        "transaction_id": "2_0",
        "payment_transactions": [
            "2_0_0"
        ]
    }
]

Next steps​

Once the you populate and process the order, you can proceed to fulfill it — for more information, refer to Fulfill an Order.