From 22c766ef92e19737b5a4888230acb7b98e343ad7 Mon Sep 17 00:00:00 2001 From: Traci Porter Date: Mon, 6 Nov 2023 15:55:17 -0600 Subject: [PATCH 1/9] Update tutorial.mdx --- docs/api-docs/headless/tutorial.mdx | 197 ++++++++++++++-------------- 1 file changed, 99 insertions(+), 98 deletions(-) diff --git a/docs/api-docs/headless/tutorial.mdx b/docs/api-docs/headless/tutorial.mdx index ea0187a9f..f3c4a5c13 100644 --- a/docs/api-docs/headless/tutorial.mdx +++ b/docs/api-docs/headless/tutorial.mdx @@ -13,11 +13,14 @@ This article assumes you are familiar with the following: ### Prerequisites -* A store-level API account with the following permissions. - - **Carts:** `Modify` - - **Checkout:** `Modify` - - **Orders:** `Modify` - - **Products:** `Read Only` +* A store-level or app-level API account with the following permissions. + +| UI Name | Permission | Parameter | +|----------|------------|-------------------------------| +| Carts | modify | `store_cart` | +| Checkouts| modify | `store_checkouts` | +| Orders | modify | `store_v2_orders_read_only` | +| Products | read-only | `store_v2_products_read_only` | For more information, see [OAuth Scopes](/docs/start/authentication/api-accounts#oauth-scopes). @@ -29,12 +32,12 @@ To generate the cart ID, send a request to the [create a cart](/docs/rest-manage - ```http filename="Example request: Create a cart" showLineNumbers copy - POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/carts - Accept: application/json - Content-Type: application/json - X-Auth-Token: {{ACCESS_TOKEN}} - { +```json filename="Example request: Create a cart" showLineNumbers copy +POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/carts +Accept: application/json +Content-Type: application/json +X-Auth-Token: {{ACCESS_TOKEN}} +{ "customer_id": 0, "line_items": [ { @@ -49,57 +52,57 @@ To generate the cart ID, send a request to the [create a cart](/docs/rest-manage "code": "USD" }, "locale": "en-US" - } - ``` +} +``` - ```json filename="Example response: Create a cart" showLineNumbers copy - { - "data": { - "id": "3cae6525-d0e8-4252-afec-0890fbb710c5", - "customer_id": 0, - "channel_id": 1, - "email": "", - "currency": { - "code": "USD" +```http filename="Example response: Create a cart" showLineNumbers copy +{ + "data": { + "id": "3cae6525-d0e8-4252-afec-0890fbb710c5", + "customer_id": 0, + "channel_id": 1, + "email": "", + "currency": { + "code": "USD" }, - "tax_included": false, - "base_amount": 30, - "discount_amount": 4.5, - "cart_amount": 25.5, - "coupons": [], - "line_items": { - "physical_items": [ - { - "id": "ca9ef0d1-1da9-48e5-a505-7051eb575432", - "parent_id": null, - "variant_id": 118, - "product_id": 120, - "sku": "SM-13", - "name": "mug", - "url": "https://arabic-store.mybigcommerce.com/bigcommerce-coffee-mug/", - "quantity": 2, - "taxable": true, - "image_url": "https://cdn11.bigcommerce.com/r-4b20dad619e29ebf3490f7f35369a8220637ce48/themes/ClassicNext/images/ProductDefault.gif", - "coupons": [], - "discount_amount": 0, - "coupon_amount": 0, - "original_price": 15, - "list_price": 15, - "sale_price": 13.86, - "extended_list_price": 30, - "extended_sale_price": 27.72, - "is_require_shipping": true, - "is_mutable": true - } - ], - "digital_items": [], - "gift_certificates": [], - "custom_items": [] + "tax_included": false, + "base_amount": 30, + "discount_amount": 4.5, + "cart_amount": 25.5, + "coupons": [], + "line_items": { + "physical_items": [ + { + "id": "ca9ef0d1-1da9-48e5-a505-7051eb575432", + "parent_id": null, + "variant_id": 118, + "product_id": 120, + "sku": "SM-13", + "name": "mug", + "url": "https://arabic-store.mybigcommerce.com/bigcommerce-coffee-mug/", + "quantity": 2, + "taxable": true, + "image_url": "https://cdn11.bigcommerce.com/r-4b20dad619e29ebf3490f7f35369a8220637ce48/themes/ClassicNext/images/ProductDefault.gif", + "coupons": [], + "discount_amount": 0, + "coupon_amount": 0, + "original_price": 15, + "list_price": 15, + "sale_price": 13.86, + "extended_list_price": 30, + "extended_sale_price": 27.72, + "is_require_shipping": true, + "is_mutable": true + } + ], + "digital_items": [], + "gift_certificates": [], + "custom_items": [] }, - "created_time": "2023-09-28T20:30:33+00:00", - "updated_time": "2023-09-28T20:30:33+00:00", - "locale": "en-US" + "created_time": "2023-09-28T20:30:33+00:00", + "updated_time": "2023-09-28T20:30:33+00:00", + "locale": "en-US" }, "meta": {} } @@ -109,7 +112,7 @@ To generate the cart ID, send a request to the [create a cart](/docs/rest-manage ### Step 2: Generate the redirect URLs -To generate the redirect URLs, send a POST request to the [create cart redirect URL](https://developer.bigcommerce.com/docs/rest-management/carts/redirects#create-cart-redirect-url) endpoint. You must use the cart ID generated in [step 1](#creating-a-cart) above. The response will contain the `cart_url` and the `checkout_url`. Use these URLs to redirect customers to the BigCommerce-hosted cart or checkout pages. +To generate the redirect URLs, send a POST request to the [create cart redirect URL](/docs/rest-management/carts/redirects#create-cart-redirect-url) endpoint. You must use the cart ID generated in [step 1](#creating-a-cart) above. The response will contain the `cart_url` and the `checkout_url`. Use these URLs to redirect customers to the BigCommerce-hosted cart or checkout pages. @@ -122,13 +125,13 @@ X-Auth-Token: {{ACCESS_TOKEN}} ``` - ```json filename="Example response: Create cart redirect URLs" showLineNumbers copy - { +```http filename="Example response: Create cart redirect URLs" showLineNumbers copy +{ "data": { "cart_url": "https://test-store.mybigcommerce.com/cart.php?action=load&id=3cae6525-d0e8-4252-afec-0890fbb710c5&token=888dbf8bc89d5bc925ed40d39996387574f8deceaf759c64c101679d1f164f4f", "checkout_url": "https://test-store.mybigcommerce.com/cart.php?action=loadInCheckout&id=3cae6525-d0e8-4252-afec-0890fbb710c5&token=888dbf8bc89d5bc925ed40d39996387574f8deceaf759c64c101679d1f164f4f", "embedded_checkout_url": "https://test-store.mybigcommerce.com/cart.php?embedded=1&action=loadInCheckout&id=3cae6525-d0e8-4252-afec-0890fbb710c5&token=888dbf8bc89d5bc925ed40d39996387574f8deceaf759c64c101679d1f164f4f" - }, + }, "meta": {} } ``` @@ -137,11 +140,11 @@ X-Auth-Token: {{ACCESS_TOKEN}} ## Creating a checkout -In this section, we will add a billing address to your checkout. You must have a `checkoutID`. The `checkoutID` is the same as the `cart_id` you generated in [step 1](#creating-a-cart) of creating a cart. To add a billing address, send a POST request to the [Add Checkout Billing Address](https://developer.bigcommerce.com/docs/rest-management/checkouts/checkout-billing-address#add-checkout-billing-address) endpoint. +In this section, we will add a billing address to your checkout. You must have a `checkoutID`. The `checkoutID` is the same as the `cart_id` you generated in [step 1](#creating-a-cart) of creating a cart. To add a billing address, send a POST request to the [Add Checkout Billing Address](/docs/rest-management/checkouts/checkout-billing-address#add-checkout-billing-address) endpoint. -```json filename="Example request: Add Checkout Billing Address" showLineNumbers copy +```http filename="Example request: Add Checkout Billing Address" showLineNumbers copy POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/checkouts/{checkoutId}/billing-address Accept: application/json Content-Type: application/json @@ -161,9 +164,9 @@ X-Auth-Token: {{ACCESS_TOKEN}} "phone": "555-555-5555" } ``` - + -```json filename="Example response: Add Checkout Billing Address" showLineNumbers copy +```http filename="Example response: Add Checkout Billing Address" showLineNumbers copy { "data": { "id": "3cae6525-d0e8-4252-afec-0890fbb710c5", @@ -298,7 +301,7 @@ X-Auth-Token: {{ACCESS_TOKEN}} ``` -```json filename="Example response: Add Consignment to checkout" showLineNumbers copy +```http filename="Example response: Add Consignment to checkout" showLineNumbers copy { "data": { "id": "3cae6525-d0e8-4252-afec-0890fbb710c5", @@ -469,38 +472,36 @@ X-Auth-Token: {{ACCESS_TOKEN}} The response will contain an array of `available_shipping_options`. In the next step, you will use one of the available shipping options to update the consignment. -```json filename="available shipping options" showLineNumbers copy +```http filename="available shipping options" showLineNumbers copy "available_shipping_options": [ - { - "id": "6ded13392879983ee32a3563f5fa6a7b", - "type": "shipping_pickupinstore", - "description": "Pickup In Store", - "image_url": "", - "cost": 0, - "transit_time": "", - "additional_description": "" - }, - { - "id": "26fb2db4ad77b0f039328d22d2869617", - "type": "shipping_flatrate", - "description": "Flat Rate", - "image_url": "", - "cost": 5, - "transit_time": "", - "additional_description": "" - }, - { - "id": "508540c73074d5ffa2cc3dced0adc552", - "type": "shipping_byweight", - "description": "Ship by Weight", - "image_url": "", - "cost": 8, - "transit_time": "", - "additional_description": "" - } - ] - } - ], + { + "id": "6ded13392879983ee32a3563f5fa6a7b", + "type": "shipping_pickupinstore", + "description": "Pickup In Store", + "image_url": "", + "cost": 0, + "transit_time": "", + "additional_description": "" + }, + { + "id": "26fb2db4ad77b0f039328d22d2869617", + "type": "shipping_flatrate", + "description": "Flat Rate", + "image_url": "", + "cost": 5, + "transit_time": "", + "additional_description": "" + }, + { + "id": "508540c73074d5ffa2cc3dced0adc552", + "type": "shipping_byweight", + "description": "Ship by Weight", + "image_url": "", + "cost": 8, + "transit_time": "", + "additional_description": "" + } +] ``` ### Step 2: Update the consignment From 9ffadd0717f96c76fe22464ed56889cf2263ffaf Mon Sep 17 00:00:00 2001 From: Traci Porter Date: Tue, 7 Nov 2023 09:06:50 -0600 Subject: [PATCH 2/9] Update and rename tutorial.mdx to guide, cleanup.mdx --- .../headless/{tutorial.mdx => guide.mdx} | 46 +++++++++++-------- 1 file changed, 28 insertions(+), 18 deletions(-) rename docs/api-docs/headless/{tutorial.mdx => guide.mdx} (95%) diff --git a/docs/api-docs/headless/tutorial.mdx b/docs/api-docs/headless/guide.mdx similarity index 95% rename from docs/api-docs/headless/tutorial.mdx rename to docs/api-docs/headless/guide.mdx index f3c4a5c13..d3ff3bd39 100644 --- a/docs/api-docs/headless/tutorial.mdx +++ b/docs/api-docs/headless/guide.mdx @@ -1,4 +1,4 @@ -# Headless Tutorial +# Headless Guide This tutorial will walk you through [creating a cart](#creating-a-cart), [checkout](#creating-a-checkout), an [order](#creating-an-order), and processing a payment using the [Carts](/docs/rest-management/carts/carts-single#create-a-cart) and [Checkout](/docs/rest-management/checkouts) REST Management APIs to build a headless storefront. @@ -16,10 +16,10 @@ This article assumes you are familiar with the following: * A store-level or app-level API account with the following permissions. | UI Name | Permission | Parameter | -|----------|------------|-------------------------------| +|----------|------------|-------------------------------| | Carts | modify | `store_cart` | | Checkouts| modify | `store_checkouts` | -| Orders | modify | `store_v2_orders_read_only` | +| Orders | modify | `store_v2_orders` | | Products | read-only | `store_v2_products_read_only` | For more information, see [OAuth Scopes](/docs/start/authentication/api-accounts#oauth-scopes). @@ -123,8 +123,8 @@ Content-Type: application/json X-Auth-Token: {{ACCESS_TOKEN}} {} ``` - - + + ```http filename="Example response: Create cart redirect URLs" showLineNumbers copy { "data": { @@ -135,7 +135,7 @@ X-Auth-Token: {{ACCESS_TOKEN}} "meta": {} } ``` - + ## Creating a checkout @@ -165,7 +165,7 @@ X-Auth-Token: {{ACCESS_TOKEN}} } ``` - + ```http filename="Example response: Add Checkout Billing Address" showLineNumbers copy { "data": { @@ -259,7 +259,7 @@ X-Auth-Token: {{ACCESS_TOKEN}} "meta": {} } ``` - + Now that you have transformed your headless cart into a proper checkout with a billing address, you can add a consignment with a shipping address, line items, and a shipping option. You can do so by following this two-step process: @@ -267,6 +267,7 @@ Now that you have transformed your headless cart into a proper checkout with a b ### Step 1: Add a new consignment to the checkout Send a `POST` request to the [Add Consignment to Checkout](/docs/rest-management/checkouts/checkout-consignments#add-consignment-to-checkout) endpoint. Append the `include=consignments.available_shipping_options` query parameter to your `POST` request to return available shipping options. You will use one of the available shipping options to update the consignment in [step 2](#step-2-update-the-consignment). + ```http filename="Example request: Add Consignment to checkout" showLineNumbers copy @@ -299,8 +300,8 @@ X-Auth-Token: {{ACCESS_TOKEN}} } ] ``` - - + + ```http filename="Example response: Add Consignment to checkout" showLineNumbers copy { "data": { @@ -468,7 +469,7 @@ X-Auth-Token: {{ACCESS_TOKEN}} "meta": {} } ``` - + The response will contain an array of `available_shipping_options`. In the next step, you will use one of the available shipping options to update the consignment. @@ -521,8 +522,8 @@ X-Auth-Token: {{ACCESS_TOKEN}} } ``` - - + + ```http filename="Example response" Update checkout consignment" showLineNumbers copy { "data": { @@ -691,12 +692,12 @@ X-Auth-Token: {{ACCESS_TOKEN}} "meta": {} } ``` - + ## Creating an order -Now that you have added a billing address and a consignment to your checkout, you can create an order by sending a `POST` request to the [Create an Order](https://developer.bigcommerce.com/docs/rest-management/checkouts/checkout-orders#create-an-order) endpoint. The order status will be set to incomplete. +Now that you have added a billing address and a consignment to your checkout, you can create an order by sending a `POST` request to the [Create an Order](/docs/rest-management/checkouts/checkout-orders#create-an-order) endpoint. The order status will be set to incomplete. @@ -707,9 +708,8 @@ Now that you have added a billing address and a consignment to your checkout, yo Content-Type: application/json X-Auth-Token: {{ACCESS_TOKEN}} ``` - - - + + ```json filename="Example response: Create an order" showLineNumbers copy { @@ -722,3 +722,13 @@ Now that you have added a billing address and a consignment to your checkout, yo + +## References +* [OAuth Scopes](/docs/start/authentication/api-accounts#oauth-scopes) +* [Carts](/docs/rest-management/carts/carts-single#create-a-cart) +* [Checkout](/docs/rest-management/checkouts/checkout-orders#create-an-order) +* [Order](/docs/rest-management/checkouts/checkout-orders#create-an-order) +* [Working with the REST Storefront Cart and Checkout APIs](/docs/storefront/cart-checkout/guide/rest-storefront) +* [Create cart redirect URL](/docs/rest-management/carts/redirects#create-cart-redirect-url) +* [Add Checkout Billing Address](/docs/rest-management/checkouts/checkout-billing-address#add-checkout-billing-address) +* [Update Checkout Consignment](/docs/rest-management/checkouts/checkout-consignments#update-checkout-consignment) From 1cc06b1a812f0615f4e4d3a8dad87b454c4b706a Mon Sep 17 00:00:00 2001 From: Sarah Riehl Date: Wed, 8 Nov 2023 15:47:46 -0600 Subject: [PATCH 3/9] move and rename guide --- docs/api-docs/headless/{guide.mdx => end-to-end-guide/rest.mdx} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename docs/api-docs/headless/{guide.mdx => end-to-end-guide/rest.mdx} (99%) diff --git a/docs/api-docs/headless/guide.mdx b/docs/api-docs/headless/end-to-end-guide/rest.mdx similarity index 99% rename from docs/api-docs/headless/guide.mdx rename to docs/api-docs/headless/end-to-end-guide/rest.mdx index d3ff3bd39..5e70d98ac 100644 --- a/docs/api-docs/headless/guide.mdx +++ b/docs/api-docs/headless/end-to-end-guide/rest.mdx @@ -1,4 +1,4 @@ -# Headless Guide +# End-to-End Guide: Headless Checkout Flow with REST Management APIs This tutorial will walk you through [creating a cart](#creating-a-cart), [checkout](#creating-a-checkout), an [order](#creating-an-order), and processing a payment using the [Carts](/docs/rest-management/carts/carts-single#create-a-cart) and [Checkout](/docs/rest-management/checkouts) REST Management APIs to build a headless storefront. From 8ac460cd9c9be032cab8034afa5dc52375696dc8 Mon Sep 17 00:00:00 2001 From: Sarah Riehl Date: Wed, 8 Nov 2023 15:50:46 -0600 Subject: [PATCH 4/9] add new article link to resources --- docs/api-docs/headless/carts.mdx | 5 +++-- docs/api-docs/headless/checkout.mdx | 1 + 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/api-docs/headless/carts.mdx b/docs/api-docs/headless/carts.mdx index 8b8992cdd..8e26b843e 100644 --- a/docs/api-docs/headless/carts.mdx +++ b/docs/api-docs/headless/carts.mdx @@ -256,6 +256,7 @@ In practice, removing all cart items also essentially deletes the cart. ## Resources -- [Carts API](/docs/rest-management/carts) -- [Storefront Carts API](/docs/rest-storefront/carts) +- [End-to-End Guide: Headless Checkout Flow with REST Management APIs](/docs/storefront/headless/end-to-end-guide/rest) +- [REST Management API: Carts](/docs/rest-management/carts) +- [REST Storefront API: Carts](/docs/rest-storefront/carts) - [Persistent Cart](https://support.bigcommerce.com/s/article/Persistent-Cart) diff --git a/docs/api-docs/headless/checkout.mdx b/docs/api-docs/headless/checkout.mdx index efffa4323..20f1dab4a 100644 --- a/docs/api-docs/headless/checkout.mdx +++ b/docs/api-docs/headless/checkout.mdx @@ -59,6 +59,7 @@ The Checkouts API allows you to move the cart to checkout and turn it into an or ## Resources +- [End-to-End Guide: Headless Checkout Flow with REST Management APIs](/docs/storefront/headless/end-to-end-guide/rest) - [Restyle Optimized One-Page Checkout](/docs/storefront/cart-checkout/optimized-one-page-checkout) - [Checkout JS repo](https://github.com/bigcommerce/checkout-js) - [Checkout SDK Tutorial](/docs/storefront/cart-checkout/checkout-sdk/tutorial) From 0db500107e568bd4323c10a4ac0295d7ecab1366 Mon Sep 17 00:00:00 2001 From: Sarah Riehl Date: Wed, 8 Nov 2023 16:20:08 -0600 Subject: [PATCH 5/9] update orders article --- docs/api-docs/headless/orders.mdx | 138 +++--------------------------- 1 file changed, 11 insertions(+), 127 deletions(-) diff --git a/docs/api-docs/headless/orders.mdx b/docs/api-docs/headless/orders.mdx index 0009fc03b..f3ca7da75 100644 --- a/docs/api-docs/headless/orders.mdx +++ b/docs/api-docs/headless/orders.mdx @@ -9,135 +9,19 @@ This section explains how to create and manage orders for headless storefronts. ## Creating an order from a cart -To successfully complete this section, you must first create a cart with a **redirect URL**. For instructions on how to create a cart, see the [Carts](/docs/storefront/headless/cart-checkout/carts) section of this guide. +To successfully complete this section, you must first create a cart with a **redirect URL**. For instructions on how to create a cart, see the [Carts article in this guide](/docs/storefront/headless/cart-checkout/carts). ### Adding a billing address -You can change a cart to a checkout by adding a billing address. To add a checkout billing address, send a `POST` request to the [Add Checkout Billing Address](/docs/rest-management/checkouts/checkout-billing-address#add-checkout-billing-address) endpoint. Your `checkoutId` will correspond with the cart `id` returned in response to [Create a Cart](/docs/rest-management/carts/carts-single#create-a-cart). - -```http filename="Example request: Add checkout billing address" showLineNumbers copy -POST https://api.bigcommerce.com/stores/{store_hash}/v3/checkouts/{checkoutId}/billing-address -Accept: application/json -Content-Type: application/json -X-Auth-Token: {{ACCESS_TOKEN}} - -{ - "first_name": "Jane", - "last_name": "Doe", - "email": "jane@example.com", - "address1": "123 Main Street", - "address2": "", - "city": "Austin", - "state_or_province": "Texas", - "state_or_province_code": "TX", - "country_code": "US", - "postal_code": "78751", - "phone": "1234567890" -} -``` +You can change a cart to a checkout by adding a billing address. To add a checkout billing address, send a request to the [Add Checkout Billing Address](/docs/rest-management/checkouts/checkout-billing-address#add-checkout-billing-address) endpoint. Your `checkoutId` will correspond with the cart ID returned by the [Create a Cart](/docs/rest-management/carts/carts-single#create-a-cart) endpoint. For an example request, see the [End-to-End Guide: Headless Checkout Flow with REST Management APIs](/docs/storefront/headless/end-to-end-guide/rest). ### Adding a consignment -Now that you have transformed your headless cart into a checkout, you need to add a consignment with a shipping address, line items, and a shipping option. You can do so following this two-step process: - -**Step 1: Add a new consignment to the checkout** - -Send a `POST` request to the [Add Consignment to Checkout](/docs/rest-management/checkouts/checkout-consignments#add-consignment-to-checkout) endpoint. Append the `include=consignments.available_shipping_options` query parameter to your `POST` request to return `available_shipping_options` (required for step two). - -```http filename="Example request: Add Consignment to checkout" showLineNumbers copy -POST https://api.bigcommerce.com/stores/{store_hash}/v3/checkouts/{checkoutId}/consignments?include=consignments.available_shipping_options -Accept: application/json -Content-Type: application/json -X-Auth-Token: {{ACCESS_TOKEN}} - -[ - { - "shipping_address": { - "first_name": "Jane", - "last_name": "Doe", - "email": "jane@example.com", - "address1": "123 Main Street", - "address2": "", - "city": "Austin", - "state_or_province": "Texas", - "state_or_province_code": "TX", - "country_code": "US", - "postal_code": "78751", - "phone": "1234567890" - }, - "line_items": [ - { - "item_id": "7e2f9b22-a16e-4056-9e2d-8fc919bcf653", - "quantity": 1 - } - ] - } -] -``` - -The response will contain an array of `available_shipping_options`. You will use one of the available shipping options to update the consignment in the next step. - -```json filename="Example response: Add Consignment to checkout" showLineNumbers copy -"available_shipping_options": [ - { - "id": "80ad65f7946c23bd4ee9a531d85c5e21", - "type": "shipping_pickupinstore", - "description": "Pickup In Store", - "image_url": "", - "cost": 0, - "transit_time": "", - "additional_description": "" - }, - { - "id": "4dcbf24f457dd67d5f89bcf374e0bc9b", - "type": "freeshipping", - "description": "Free Shipping", - "image_url": "", - "cost": 0, - "transit_time": "", - "additional_description": "" - }, - { - "id": "85dfaf5f834d7e594f0bd7cf67d5b200", - "type": "shipping_flatrate", - "description": "Flat Rate", - "image_url": "", - "cost": 5, - "transit_time": "", - "additional_description": "" - }, - { - "id": "8809b0bbcc8bdc2d5cad2a4fcbd6cf09", - "type": "shipping_byweight", - "description": "Ship by Weight", - "image_url": "", - "cost": 10, - "transit_time": "", - "additional_description": "" - } -] -``` - -**Step 2: Update the consignment** - -Use one of the available shipping options to update the consignment you created in Step 1. -Send a `PUT` request to the [Update Checkout Consignment](/docs/rest-management/checkouts/checkout-consignments#update-checkout-consignment) endpoint. - -```http filename="Example request: Update checkout consignment" showLineNumbers copy -PUT https://api.bigcommerce.com/stores/{store_hash}/v3/checkouts/{checkoutId}/consignments/{consignmentId} -Accept: application/json -Content-Type: application/json -X-Auth-Token: {{ACCESS_TOKEN}} - -{ - "shipping_option_id": "4dcbf24f457dd67d5f89bcf374e0bc9b" -} -``` - +Now that you have transformed your headless cart into a checkout, you need to add a consignment with a shipping address, line items, and a shipping option. You can do so by adding and then updating a consignment. For an example request, see the [End-to-End Guide: Headless Checkout Flow with REST Management APIs](/docs/storefront/headless/end-to-end-guide/rest). ### Creating an order -Now that you have added a billing address and a consignment to your checkout, you can create an order by sending a `POST` request to the [Create an Order](/docs/rest-management/checkouts/checkout-orders#create-an-order) endpoint. The order status will be set to incomplete. +Now that you have added a billing address and a consignment to your checkout, you can create an order by sending a request to the [Create an Order](/docs/rest-management/checkouts/checkout-orders#create-an-order) endpoint. When a new order is created by API, the order status is set to incomplete. @@ -182,7 +66,7 @@ Content-Type: application/json X-Auth-Token: {{ACCESS_TOKEN}} ``` -2. To process a payment for an order, you will need to make a call to the Payments API which requires an access token. To generate an access token, send a `POST` request to the [Create Payment Access Token](/docs/rest-payments/tokens#create-payment-access-token) endpoint. +2. To process a payment for an order, you must make a call to the Payments API, which requires an payment access token. To generate a payment access token, or _PAT_, send a request to the [Create Payment Access Token](/docs/rest-payments/tokens#create-payment-access-token) endpoint. ```http filename="Example request: Create payment access token" showLineNumbers copy POST https://api.bigcommerce.com/stores/{store_hash}/v3/payments/access_tokens @@ -198,10 +82,9 @@ X-Auth-Token: {{ACCESS_TOKEN}} } ``` +Make a note of the access token `id`. This token is required in the subsequent order payment call to the [Process Payment](/docs/rest-payments/processing#process-payment) endpoint. -Make a note of the access token `id`. This token is required in subsequent payment requests to the [Process Payment](/docs/rest-payments/processing#process-payment) endpoint. - -3. Send a `POST` request to the [Process Payment](/docs/rest-payments/processing#process-payment) endpoint. The headers to process a payment are different than the headers you normally send with a BigCommerce API. The authorization token is the ID returned in Create Payment Access Token (step two). To learn more, see [Stored cards](/docs/store-operations/payments#stored-cards). +3. Send a request to the [Process Payment](/docs/rest-payments/processing#process-payment) endpoint. The headers to process a payment are different than the headers you normally send with a BigCommerce API. The `Authorization` bearer token is the PAT ID returned by the Create Payment Access Token endpoint (step two). To learn more, see [Payments API: Stored Cards](/docs/store-operations/payments#stored-cards). @@ -244,9 +127,9 @@ Make a note of the access token `id`. This token is required in subsequent payme If a shopper does not have a payment method saved on file, you can process a payment using a credit card. There are two steps to this method: -1. Send a `POST` request to the [Create Payment Access Token](/docs/rest-payments/tokens#create-payment-access-token) endpoint to get the authorization token that needs to be passed in the header when processing the payment. +1. Send a request to the [Create Payment Access Token](/docs/rest-payments/tokens#create-payment-access-token) endpoint to get the payment access token that must be passed using the `Authorization` header to process the payment. -2. Send a `POST` request to the [Process Payment](/docs/rest-payments/processing#process-payment) endpoint. The headers to process a payment are different than the headers you normally send with a BigCommerce API. The Authorization token is the ID returned in Create Payment Access Token (step one). To learn more, see [Credit cards](/docs/store-operations/payments#credit-cards). +2. Send a request to the [Process Payment](/docs/rest-payments/processing#process-payment) endpoint. The headers to process a payment are different than the headers you normally send with a BigCommerce API. The `Authorization` bearer token is the PAT ID returned by the Create Payment Access Token endpoint (step one). To learn more, see [Payments API: Credit Cards](/docs/store-operations/payments#credit-cards). ```json filename="Example response: Process payment" showLineNumbers copy { @@ -258,7 +141,7 @@ If a shopper does not have a payment method saved on file, you can process a pay } ``` -A successful transaction will return a status of success. The order is then automatically moved to an Awaiting Fulfillment status. If you get a different response, see [Error Codes](/docs/store-operations/payments#error-codes) for troubleshooting. +A successful transaction will return a `success` status. The order status is then automatically changed to `Awaiting Fulfillment`. If you get a different response, see [Error Codes](/docs/store-operations/payments#error-codes) for troubleshooting. ## Next steps @@ -266,4 +149,5 @@ A successful transaction will return a status of success. The order is then auto ## Resources +- [End-to-End Guide: Headless Checkout Flow with REST Management APIs](/docs/storefront/headless/end-to-end-guide/rest) - [Payments API Overview](/docs/store-operations/payments) From 3312f99b1f679a8003df9bf20e4ba53563ea7919 Mon Sep 17 00:00:00 2001 From: Sarah Riehl Date: Wed, 8 Nov 2023 17:05:20 -0600 Subject: [PATCH 6/9] code blocks and minor rewording --- .../headless/end-to-end-guide/rest.mdx | 1199 +++++++++-------- 1 file changed, 603 insertions(+), 596 deletions(-) diff --git a/docs/api-docs/headless/end-to-end-guide/rest.mdx b/docs/api-docs/headless/end-to-end-guide/rest.mdx index 5e70d98ac..9c6643888 100644 --- a/docs/api-docs/headless/end-to-end-guide/rest.mdx +++ b/docs/api-docs/headless/end-to-end-guide/rest.mdx @@ -2,10 +2,6 @@ This tutorial will walk you through [creating a cart](#creating-a-cart), [checkout](#creating-a-checkout), an [order](#creating-an-order), and processing a payment using the [Carts](/docs/rest-management/carts/carts-single#create-a-cart) and [Checkout](/docs/rest-management/checkouts) REST Management APIs to build a headless storefront. - -If you are using a Stencil theme, you can use REST Storefront APIs; see the [Working with the REST Storefront Cart and Checkout APIs](/docs/storefront/cart-checkout/guide/rest-storefront) tutorial for more information to build your headless site. - - This article assumes you are familiar with the following: * Creating a channel and a site. @@ -13,170 +9,174 @@ This article assumes you are familiar with the following: ### Prerequisites -* A store-level or app-level API account with the following permissions. +* A store-level or app-level API account with the following permissions: -| UI Name | Permission | Parameter | -|----------|------------|-------------------------------| -| Carts | modify | `store_cart` | -| Checkouts| modify | `store_checkouts` | -| Orders | modify | `store_v2_orders` | -| Products | read-only | `store_v2_products_read_only` | +| UI Name | Permission | Parameter | +|-----------|------------|-------------------------------| +| Carts | modify | `store_cart` | +| Checkouts | modify | `store_checkouts` | +| Orders | modify | `store_v2_orders` | +| Products | read-only | `store_v2_products_read_only` | For more information, see [OAuth Scopes](/docs/start/authentication/api-accounts#oauth-scopes). ## Creating a cart -### Step 1: Generate the cart ID + -To generate the cart ID, send a request to the [create a cart](/docs/rest-management/carts/carts-single#create-a-cart) endpoint. The response will contain the `id`, which we will use as the `cart_id`. + ### Step 1: Generate the cart ID - - -```json filename="Example request: Create a cart" showLineNumbers copy -POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/carts -Accept: application/json -Content-Type: application/json -X-Auth-Token: {{ACCESS_TOKEN}} -{ - "customer_id": 0, - "line_items": [ + To generate the cart ID, send a request to the [Create a cart](/docs/rest-management/carts/carts-single#create-a-cart) endpoint. The response contain the `id`, which is the `cart_id` or `cartId` in subsequent calls. + + + + ```http filename="Example request: Create a cart" showLineNumbers copy + POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/carts + Accept: application/json + Content-Type: application/json + X-Auth-Token: {{ACCESS_TOKEN}} { - "quantity": 2, - "product_id": 120, - "list_price": 15, - "name": "mug" + "customer_id": 0, + "line_items": [ + { + "quantity": 2, + "product_id": 120, + "list_price": 15, + "name": "mug" + } + ], + "channel_id": 1, + "currency": { + "code": "USD" + }, + "locale": "en-US" } - ], - "channel_id": 1, - "currency": { - "code": "USD" - }, - "locale": "en-US" -} -``` - - -```http filename="Example response: Create a cart" showLineNumbers copy -{ - "data": { - "id": "3cae6525-d0e8-4252-afec-0890fbb710c5", - "customer_id": 0, - "channel_id": 1, - "email": "", - "currency": { - "code": "USD" - }, - "tax_included": false, - "base_amount": 30, - "discount_amount": 4.5, - "cart_amount": 25.5, - "coupons": [], - "line_items": { - "physical_items": [ + ``` + + + ```json filename="Example response: Create a cart" showLineNumbers copy { - "id": "ca9ef0d1-1da9-48e5-a505-7051eb575432", - "parent_id": null, - "variant_id": 118, - "product_id": 120, - "sku": "SM-13", - "name": "mug", - "url": "https://arabic-store.mybigcommerce.com/bigcommerce-coffee-mug/", - "quantity": 2, - "taxable": true, - "image_url": "https://cdn11.bigcommerce.com/r-4b20dad619e29ebf3490f7f35369a8220637ce48/themes/ClassicNext/images/ProductDefault.gif", + "data": { + "id": "3cae6525-d0e8-4252-afec-0890fbb710c5", + "customer_id": 0, + "channel_id": 1, + "email": "", + "currency": { + "code": "USD" + }, + "tax_included": false, + "base_amount": 30, + "discount_amount": 4.5, + "cart_amount": 25.5, "coupons": [], - "discount_amount": 0, - "coupon_amount": 0, - "original_price": 15, - "list_price": 15, - "sale_price": 13.86, - "extended_list_price": 30, - "extended_sale_price": 27.72, - "is_require_shipping": true, - "is_mutable": true + "line_items": { + "physical_items": [ + { + "id": "ca9ef0d1-1da9-48e5-a505-7051eb575432", + "parent_id": null, + "variant_id": 118, + "product_id": 120, + "sku": "SM-13", + "name": "mug", + "url": "https://arabic-store.mybigcommerce.com/bigcommerce-coffee-mug/", + "quantity": 2, + "taxable": true, + "image_url": "https://cdn11.bigcommerce.com/r-4b20dad619e29ebf3490f7f35369a8220637ce48/themes/ClassicNext/images/ProductDefault.gif", + "coupons": [], + "discount_amount": 0, + "coupon_amount": 0, + "original_price": 15, + "list_price": 15, + "sale_price": 13.86, + "extended_list_price": 30, + "extended_sale_price": 27.72, + "is_require_shipping": true, + "is_mutable": true + } + ], + "digital_items": [], + "gift_certificates": [], + "custom_items": [] + }, + "created_time": "2023-09-28T20:30:33+00:00", + "updated_time": "2023-09-28T20:30:33+00:00", + "locale": "en-US" + }, + "meta": {} } - ], - "digital_items": [], - "gift_certificates": [], - "custom_items": [] - }, - "created_time": "2023-09-28T20:30:33+00:00", - "updated_time": "2023-09-28T20:30:33+00:00", - "locale": "en-US" - }, - "meta": {} -} -``` - - - -### Step 2: Generate the redirect URLs + ``` + + + + ### Step 2: Generate the redirect URLs + + To generate the redirect URLs, send a request to the [Create a cart redirect URL](/docs/rest-management/carts/redirects#create-cart-redirect-url) endpoint. You use the cart ID generated in [Step 1](#creating-a-cart). The response will contain the `cart_url` and the `checkout_url`. Use these URLs to redirect customers to the BigCommerce-hosted cart or checkout pages. + + + + ```http filename="Example request: Create cart redirect URLs" showLineNumbers copy + POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/carts/{cartId}/redirect_urls + Accept: application/json + Content-Type: application/json + X-Auth-Token: {{ACCESS_TOKEN}} + {} + ``` + + + ```json filename="Example response: Create cart redirect URLs" showLineNumbers copy + { + "data": { + "cart_url": "https://test-store.mybigcommerce.com/cart.php?action=load&id=3cae6525-d0e8-4252-afec-0890fbb710c5&token=888dbf8bc89d5bc925ed40d39996387574f8deceaf759c64c101679d1f164f4f", + "checkout_url": "https://test-store.mybigcommerce.com/cart.php?action=loadInCheckout&id=3cae6525-d0e8-4252-afec-0890fbb710c5&token=888dbf8bc89d5bc925ed40d39996387574f8deceaf759c64c101679d1f164f4f", + "embedded_checkout_url": "https://test-store.mybigcommerce.com/cart.php?embedded=1&action=loadInCheckout&id=3cae6525-d0e8-4252-afec-0890fbb710c5&token=888dbf8bc89d5bc925ed40d39996387574f8deceaf759c64c101679d1f164f4f" + }, + "meta": {} + } + ``` + + -To generate the redirect URLs, send a POST request to the [create cart redirect URL](/docs/rest-management/carts/redirects#create-cart-redirect-url) endpoint. You must use the cart ID generated in [step 1](#creating-a-cart) above. The response will contain the `cart_url` and the `checkout_url`. Use these URLs to redirect customers to the BigCommerce-hosted cart or checkout pages. - - - -```json filename="Example request: Create cart redirect URLs" showLineNumbers copy -POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/carts/{cartId}/redirect_urls -Accept: application/json -Content-Type: application/json -X-Auth-Token: {{ACCESS_TOKEN}} -{} -``` - - -```http filename="Example response: Create cart redirect URLs" showLineNumbers copy -{ - "data": { - "cart_url": "https://test-store.mybigcommerce.com/cart.php?action=load&id=3cae6525-d0e8-4252-afec-0890fbb710c5&token=888dbf8bc89d5bc925ed40d39996387574f8deceaf759c64c101679d1f164f4f", - "checkout_url": "https://test-store.mybigcommerce.com/cart.php?action=loadInCheckout&id=3cae6525-d0e8-4252-afec-0890fbb710c5&token=888dbf8bc89d5bc925ed40d39996387574f8deceaf759c64c101679d1f164f4f", - "embedded_checkout_url": "https://test-store.mybigcommerce.com/cart.php?embedded=1&action=loadInCheckout&id=3cae6525-d0e8-4252-afec-0890fbb710c5&token=888dbf8bc89d5bc925ed40d39996387574f8deceaf759c64c101679d1f164f4f" - }, - "meta": {} -} -``` - - + ## Creating a checkout -In this section, we will add a billing address to your checkout. You must have a `checkoutID`. The `checkoutID` is the same as the `cart_id` you generated in [step 1](#creating-a-cart) of creating a cart. To add a billing address, send a POST request to the [Add Checkout Billing Address](/docs/rest-management/checkouts/checkout-billing-address#add-checkout-billing-address) endpoint. +In this section, we will add a billing address to your checkout. You must have a `checkoutId`. The `checkoutId` is the same as the `cart_id` you generated in [step 1](#creating-a-cart) of creating a cart. To add a billing address, send a POST request to the [Add Checkout Billing Address](/docs/rest-management/checkouts/checkout-billing-address#add-checkout-billing-address) endpoint. -```http filename="Example request: Add Checkout Billing Address" showLineNumbers copy -POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/checkouts/{checkoutId}/billing-address -Accept: application/json -Content-Type: application/json -X-Auth-Token: {{ACCESS_TOKEN}} -{ - "first_name": "Test", - "last_name": "User", - "email": "Test.User@email.com", - "company": "BigCommerce", - "address1": "555 Main Street", - "address2": "", - "city": "Austin", - "state_or_province": "TX", - "state_or_province_code": "TX", - "country_code": "US", - "postal_code": "78701", - "phone": "555-555-5555" -} -``` + ```http filename="Example request: Add Checkout Billing Address" showLineNumbers copy + POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/checkouts/{checkoutId}/billing-address + Accept: application/json + Content-Type: application/json + X-Auth-Token: {{ACCESS_TOKEN}} + { + "first_name": "Test", + "last_name": "User", + "email": "Test.User@email.com", + "company": "BigCommerce", + "address1": "555 Main Street", + "address2": "", + "city": "Austin", + "state_or_province": "TX", + "state_or_province_code": "TX", + "country_code": "US", + "postal_code": "78701", + "phone": "555-555-5555" + } + ``` -```http filename="Example response: Add Checkout Billing Address" showLineNumbers copy -{ - "data": { - "id": "3cae6525-d0e8-4252-afec-0890fbb710c5", - "cart": { + ```json filename="Example response: Add Checkout Billing Address" showLineNumbers copy + { + "data": { + "id": "3cae6525-d0e8-4252-afec-0890fbb710c5", + "cart": { "id": "3cae6525-d0e8-4252-afec-0890fbb710c5", "customer_id": 0, "channel_id": 1, "email": "Test.user@email.com", "currency": { - "code": "USD" + "code": "USD" }, "tax_included": false, "base_amount": 30, @@ -185,39 +185,39 @@ X-Auth-Token: {{ACCESS_TOKEN}} "cart_amount_ex_tax": 23.56, "coupons": [], "line_items": { - "physical_items": [ - { - "id": "ca9ef0d1-1da9-48e5-a505-7051eb575432", - "parent_id": null, - "variant_id": 118, - "product_id": 120, - "sku": "SM-13", - "name": "mug", - "url": "https://arabic-store.mybigcommerce.com/bigcommerce-coffee-mug/", - "quantity": 2, - "is_taxable": true, - "image_url": "https://cdn11.bigcommerce.com/r-4b20dad619e29ebf3490f7f35369a8220637ce48/themes/ClassicNext/images/ProductDefault.gif", - "coupons": [], - "discount_amount": 0, - "coupon_amount": 0, - "original_price": 15, - "list_price": 15, - "sale_price": 13.858823529412, - "extended_list_price": 30, - "extended_sale_price": 27.717647058824, - "is_require_shipping": true, - "gift_wrapping": null, - "is_mutable": true - } - ], - "digital_items": [], - "gift_certificates": [], - "custom_items": [] + "physical_items": [ + { + "id": "ca9ef0d1-1da9-48e5-a505-7051eb575432", + "parent_id": null, + "variant_id": 118, + "product_id": 120, + "sku": "SM-13", + "name": "mug", + "url": "https://arabic-store.mybigcommerce.com/bigcommerce-coffee-mug/", + "quantity": 2, + "is_taxable": true, + "image_url": "https://cdn11.bigcommerce.com/r-4b20dad619e29ebf3490f7f35369a8220637ce48/themes/ClassicNext/images/ProductDefault.gif", + "coupons": [], + "discount_amount": 0, + "coupon_amount": 0, + "original_price": 15, + "list_price": 15, + "sale_price": 13.858823529412, + "extended_list_price": 30, + "extended_sale_price": 27.717647058824, + "is_require_shipping": true, + "gift_wrapping": null, + "is_mutable": true + } + ], + "digital_items": [], + "gift_certificates": [], + "custom_items": [] }, "created_time": "2023-09-28T20:30:33+00:00", "updated_time": "2023-09-29T15:46:12+00:00" - }, - "billing_address": { + }, + "billing_address": { "id": "6516f14419a81", "first_name": "Test", "last_name": "User", @@ -233,145 +233,147 @@ X-Auth-Token: {{ACCESS_TOKEN}} "postal_code": "78701", "phone": "555-555-5555", "custom_fields": [] - }, - "consignments": [], - "taxes": [ + }, + "consignments": [], + "taxes": [ { - "name": "Texas Tax", - "amount": 1.94 + "name": "Texas Tax", + "amount": 1.94 } - ], - "coupons": [], - "order_id": null, - "shipping_cost_total_inc_tax": 0, - "shipping_cost_total_ex_tax": 0, - "handling_cost_total_inc_tax": 0, - "handling_cost_total_ex_tax": 0, - "tax_total": 1.94, - "subtotal_inc_tax": 30, - "subtotal_ex_tax": 27.717647058823, - "grand_total": 25.5, - "created_time": "2023-09-28T20:30:33+00:00", - "updated_time": "2023-09-29T15:46:12+00:00", - "customer_message": "", - "fees": [] - }, - "meta": {} -} -``` + ], + "coupons": [], + "order_id": null, + "shipping_cost_total_inc_tax": 0, + "shipping_cost_total_ex_tax": 0, + "handling_cost_total_inc_tax": 0, + "handling_cost_total_ex_tax": 0, + "tax_total": 1.94, + "subtotal_inc_tax": 30, + "subtotal_ex_tax": 27.717647058823, + "grand_total": 25.5, + "created_time": "2023-09-28T20:30:33+00:00", + "updated_time": "2023-09-29T15:46:12+00:00", + "customer_message": "", + "fees": [] + }, + "meta": {} + } + ``` Now that you have transformed your headless cart into a proper checkout with a billing address, you can add a consignment with a shipping address, line items, and a shipping option. You can do so by following this two-step process: -### Step 1: Add a new consignment to the checkout + -Send a `POST` request to the [Add Consignment to Checkout](/docs/rest-management/checkouts/checkout-consignments#add-consignment-to-checkout) endpoint. Append the `include=consignments.available_shipping_options` query parameter to your `POST` request to return available shipping options. You will use one of the available shipping options to update the consignment in [step 2](#step-2-update-the-consignment). + ### Step 1: Add a new consignment to the checkout - - -```http filename="Example request: Add Consignment to checkout" showLineNumbers copy -POST https://api.bigcommerce.com/stores/{store_hash}/v3/checkouts/{checkoutId}/consignments?include=consignments.available_shipping_options -Accept: application/json -Content-Type: application/json -X-Auth-Token: {{ACCESS_TOKEN}} -[ - { - "shipping_address": { - "first_name": "Test", - "last_name": "User", - "email": "Test.User@example.com", - "company": "BigCommerce", - "address1": "555 Main Street", - "address2": "", - "city": "Austin", - "state_or_province": "Texas", - "state_or_province_code": "TX", - "country_code": "US", - "postal_code": "78701", - "phone": "555-555-5555" - }, - "line_items": [ - { - "item_id": "ca9ef0d1-1da9-48e5-a505-7051eb575432", - "quantity": 2 - } - ] - } -] -``` - - -```http filename="Example response: Add Consignment to checkout" showLineNumbers copy -{ - "data": { - "id": "3cae6525-d0e8-4252-afec-0890fbb710c5", - "cart": { - "id": "3cae6525-d0e8-4252-afec-0890fbb710c5", - "customer_id": 0, - "channel_id": 1, - "email": "Test.user@email.com", - "currency": { - "code": "USD" - }, - "tax_included": false, - "base_amount": 30, - "discount_amount": 4.5, - "cart_amount_inc_tax": 25.5, - "cart_amount_ex_tax": 23.56, - "coupons": [], - "line_items": { - "physical_items": [ - { - "id": "ca9ef0d1-1da9-48e5-a505-7051eb575432", - "parent_id": null, - "variant_id": 118, - "product_id": 120, - "sku": "SM-13", - "name": "mug", - "url": "https://arabic-store.mybigcommerce.com/bigcommerce-coffee-mug/", - "quantity": 2, - "is_taxable": true, - "image_url": "https://cdn11.bigcommerce.com/r-4b20dad619e29ebf3490f7f35369a8220637ce48/themes/ClassicNext/images/ProductDefault.gif", - "coupons": [], - "discount_amount": 0, - "coupon_amount": 0, - "original_price": 15, - "list_price": 15, - "sale_price": 13.858823529412, - "extended_list_price": 30, - "extended_sale_price": 27.717647058824, - "is_require_shipping": true, - "gift_wrapping": null, - "is_mutable": true - } - ], - "digital_items": [], - "gift_certificates": [], - "custom_items": [] - }, - "created_time": "2023-09-28T20:30:33+00:00", - "updated_time": "2023-09-29T16:34:35+00:00" - }, - "billing_address": { - "id": "6516f14419a81", + Send a request to the [Add Consignment to Checkout](/docs/rest-management/checkouts/checkout-consignments#add-consignment-to-checkout) endpoint. Append the `include=consignments.available_shipping_options` query parameter to your request to return available shipping options. You will use one of the available shipping options to update the consignment in [step 2](#step-2-update-the-consignment). + + + + ```http filename="Example request: Add Consignment to checkout" showLineNumbers copy + POST https://api.bigcommerce.com/stores/{store_hash}/v3/checkouts/{checkoutId}/consignments?include=consignments.available_shipping_options + Accept: application/json + Content-Type: application/json + X-Auth-Token: {{ACCESS_TOKEN}} + [ + { + "shipping_address": { "first_name": "Test", "last_name": "User", - "email": "Test.user@email.com", + "email": "Test.User@example.com", "company": "BigCommerce", "address1": "555 Main Street", "address2": "", "city": "Austin", "state_or_province": "Texas", "state_or_province_code": "TX", - "country": "United States", "country_code": "US", "postal_code": "78701", - "phone": "555-555-5555", - "custom_fields": [] - }, - "consignments": [ + "phone": "555-555-5555" + }, + "line_items": [ { + "item_id": "ca9ef0d1-1da9-48e5-a505-7051eb575432", + "quantity": 2 + } + ] + } + ] + ``` + + + ```json filename="Example response: Add Consignment to checkout" showLineNumbers copy + { + "data": { + "id": "3cae6525-d0e8-4252-afec-0890fbb710c5", + "cart": { + "id": "3cae6525-d0e8-4252-afec-0890fbb710c5", + "customer_id": 0, + "channel_id": 1, + "email": "Test.user@email.com", + "currency": { + "code": "USD" + }, + "tax_included": false, + "base_amount": 30, + "discount_amount": 4.5, + "cart_amount_inc_tax": 25.5, + "cart_amount_ex_tax": 23.56, + "coupons": [], + "line_items": { + "physical_items": [ + { + "id": "ca9ef0d1-1da9-48e5-a505-7051eb575432", + "parent_id": null, + "variant_id": 118, + "product_id": 120, + "sku": "SM-13", + "name": "mug", + "url": "https://arabic-store.mybigcommerce.com/bigcommerce-coffee-mug/", + "quantity": 2, + "is_taxable": true, + "image_url": "https://cdn11.bigcommerce.com/r-4b20dad619e29ebf3490f7f35369a8220637ce48/themes/ClassicNext/images/ProductDefault.gif", + "coupons": [], + "discount_amount": 0, + "coupon_amount": 0, + "original_price": 15, + "list_price": 15, + "sale_price": 13.858823529412, + "extended_list_price": 30, + "extended_sale_price": 27.717647058824, + "is_require_shipping": true, + "gift_wrapping": null, + "is_mutable": true + } + ], + "digital_items": [], + "gift_certificates": [], + "custom_items": [] + }, + "created_time": "2023-09-28T20:30:33+00:00", + "updated_time": "2023-09-29T16:34:35+00:00" + }, + "billing_address": { + "id": "6516f14419a81", + "first_name": "Test", + "last_name": "User", + "email": "Test.user@email.com", + "company": "BigCommerce", + "address1": "555 Main Street", + "address2": "", + "city": "Austin", + "state_or_province": "Texas", + "state_or_province_code": "TX", + "country": "United States", + "country_code": "US", + "postal_code": "78701", + "phone": "555-555-5555", + "custom_fields": [] + }, + "consignments": [ + { "id": "6516fc9bbf6ef", "shipping_cost_inc_tax": 0, "shipping_cost_ex_tax": 0, @@ -380,246 +382,246 @@ X-Auth-Token: {{ACCESS_TOKEN}} "coupon_discounts": [], "discounts": [], "line_item_ids": [ - "ca9ef0d1-1da9-48e5-a505-7051eb575432" + "ca9ef0d1-1da9-48e5-a505-7051eb575432" ], "shipping_address": { - "first_name": "", - "last_name": "", - "email": "", - "company": "", - "address1": "13409 GENT DR", - "address2": "", - "city": "AUSTIN", - "state_or_province": "Texas", - "state_or_province_code": "TX", - "country": "United States", - "country_code": "US", - "postal_code": "78729", - "phone": "5129247111", - "custom_fields": [] + "first_name": "", + "last_name": "", + "email": "", + "company": "", + "address1": "13409 GENT DR", + "address2": "", + "city": "AUSTIN", + "state_or_province": "Texas", + "state_or_province_code": "TX", + "country": "United States", + "country_code": "US", + "postal_code": "78729", + "phone": "5129247111", + "custom_fields": [] }, "address": { - "first_name": "", - "last_name": "", - "email": "", - "company": "", - "address1": "13409 GENT DR", - "address2": "", - "city": "AUSTIN", - "state_or_province": "Texas", - "state_or_province_code": "TX", - "country": "United States", - "country_code": "US", - "postal_code": "78729", - "phone": "5129247111", - "custom_fields": [] + "first_name": "", + "last_name": "", + "email": "", + "company": "", + "address1": "13409 GENT DR", + "address2": "", + "city": "AUSTIN", + "state_or_province": "Texas", + "state_or_province_code": "TX", + "country": "United States", + "country_code": "US", + "postal_code": "78729", + "phone": "5129247111", + "custom_fields": [] }, - "available_shipping_options": [ - { - "id": "6ded13392879983ee32a3563f5fa6a7b", - "type": "shipping_pickupinstore", - "description": "Pickup In Store", - "image_url": "", - "cost": 0, - "transit_time": "", - "additional_description": "" - }, - { - "id": "26fb2db4ad77b0f039328d22d2869617", - "type": "shipping_flatrate", - "description": "Flat Rate", - "image_url": "", - "cost": 5, - "transit_time": "", - "additional_description": "" - }, - { - "id": "508540c73074d5ffa2cc3dced0adc552", - "type": "shipping_byweight", - "description": "Ship by Weight", - "image_url": "", - "cost": 8, - "transit_time": "", - "additional_description": "" - } + "available_shipping_options": [ + { + "id": "6ded13392879983ee32a3563f5fa6a7b", + "type": "shipping_pickupinstore", + "description": "Pickup In Store", + "image_url": "", + "cost": 0, + "transit_time": "", + "additional_description": "" + }, + { + "id": "26fb2db4ad77b0f039328d22d2869617", + "type": "shipping_flatrate", + "description": "Flat Rate", + "image_url": "", + "cost": 5, + "transit_time": "", + "additional_description": "" + }, + { + "id": "508540c73074d5ffa2cc3dced0adc552", + "type": "shipping_byweight", + "description": "Ship by Weight", + "image_url": "", + "cost": 8, + "transit_time": "", + "additional_description": "" + } ] - } - ], - "taxes": [ - { + } + ], + "taxes": [ + { "name": "Texas Tax", "amount": 1.94 - } - ], - "coupons": [], - "order_id": null, - "shipping_cost_total_inc_tax": 0, - "shipping_cost_total_ex_tax": 0, - "handling_cost_total_inc_tax": 0, - "handling_cost_total_ex_tax": 0, - "tax_total": 1.94, - "subtotal_inc_tax": 30, - "subtotal_ex_tax": 27.717647058823, - "grand_total": 25.5, - "created_time": "2023-09-28T20:30:33+00:00", - "updated_time": "2023-09-29T16:34:35+00:00", - "customer_message": "", - "fees": [] - }, - "meta": {} -} -``` - - -The response will contain an array of `available_shipping_options`. In the next step, you will use one of the available shipping options to update the consignment. - -```http filename="available shipping options" showLineNumbers copy - "available_shipping_options": [ - { - "id": "6ded13392879983ee32a3563f5fa6a7b", - "type": "shipping_pickupinstore", - "description": "Pickup In Store", - "image_url": "", - "cost": 0, - "transit_time": "", - "additional_description": "" - }, + } + ], + "coupons": [], + "order_id": null, + "shipping_cost_total_inc_tax": 0, + "shipping_cost_total_ex_tax": 0, + "handling_cost_total_inc_tax": 0, + "handling_cost_total_ex_tax": 0, + "tax_total": 1.94, + "subtotal_inc_tax": 30, + "subtotal_ex_tax": 27.717647058823, + "grand_total": 25.5, + "created_time": "2023-09-28T20:30:33+00:00", + "updated_time": "2023-09-29T16:34:35+00:00", + "customer_message": "", + "fees": [] + }, + "meta": {} + } + ``` + + + + The response will contain an array of `available_shipping_options`. In the next step, you will use one of the available shipping options to update the consignment. + + ```json filename="available shipping options" showLineNumbers copy + "available_shipping_options": [ + { + "id": "6ded13392879983ee32a3563f5fa6a7b", + "type": "shipping_pickupinstore", + "description": "Pickup In Store", + "image_url": "", + "cost": 0, + "transit_time": "", + "additional_description": "" + }, + { + "id": "26fb2db4ad77b0f039328d22d2869617", + "type": "shipping_flatrate", + "description": "Flat Rate", + "image_url": "", + "cost": 5, + "transit_time": "", + "additional_description": "" + }, + { + "id": "508540c73074d5ffa2cc3dced0adc552", + "type": "shipping_byweight", + "description": "Ship by Weight", + "image_url": "", + "cost": 8, + "transit_time": "", + "additional_description": "" + } + ] + ``` + + ### Step 2: Update the consignment + + Use one of the available shipping options to update the consignment you created in the previous step. + Send a request to the [Update Checkout Consignment](/docs/rest-management/checkouts/checkout-consignments#update-checkout-consignment) endpoint. + + + + ```http filename="Example request: Update checkout consignment" showLineNumbers copy + PUT https://api.bigcommerce.com/stores/{store_hash}/v3/checkouts/{checkoutId}/consignments/{consignmentId} + Accept: application/json + Content-Type: application/json + X-Auth-Token: {{ACCESS_TOKEN}} { - "id": "26fb2db4ad77b0f039328d22d2869617", - "type": "shipping_flatrate", - "description": "Flat Rate", - "image_url": "", - "cost": 5, - "transit_time": "", - "additional_description": "" - }, + "shipping_option_id": "6ded13392879983ee32a3563f5fa6a7b" + } + ``` + + + ```json filename="Example response" Update checkout consignment" showLineNumbers copy { - "id": "508540c73074d5ffa2cc3dced0adc552", - "type": "shipping_byweight", - "description": "Ship by Weight", - "image_url": "", - "cost": 8, - "transit_time": "", - "additional_description": "" - } -] -``` - -### Step 2: Update the consignment - -Use one of the available shipping options to update the consignment you created in the previous step. -Send a `PUT` request to the [Update Checkout Consignment](/docs/rest-management/checkouts/checkout-consignments#update-checkout-consignment) endpoint. - - - -```http filename="Example request: Update checkout consignment" showLineNumbers copy -PUT https://api.bigcommerce.com/stores/{store_hash}/v3/checkouts/{checkoutId}/consignments/{consignmentId} -Accept: application/json -Content-Type: application/json -X-Auth-Token: {{ACCESS_TOKEN}} -{ - "shipping_option_id": "6ded13392879983ee32a3563f5fa6a7b" -} - -``` - - -```http filename="Example response" Update checkout consignment" showLineNumbers copy -{ - "data": { - "id": "c3bf9d8c-2cae-43e0-a618-60e72255c75b", - "cart": { + "data": { "id": "c3bf9d8c-2cae-43e0-a618-60e72255c75b", - "customer_id": 0, - "channel_id": 1, - "email": "Test.User@email.com", - "currency": { + "cart": { + "id": "c3bf9d8c-2cae-43e0-a618-60e72255c75b", + "customer_id": 0, + "channel_id": 1, + "email": "Test.User@email.com", + "currency": { "code": "USD" - }, - "tax_included": false, - "base_amount": 100, - "discount_amount": 13.5, - "cart_amount_inc_tax": 0, - "cart_amount_ex_tax": 0, - "coupons": [], - "discounts": [], - "line_items": { + }, + "tax_included": false, + "base_amount": 100, + "discount_amount": 13.5, + "cart_amount_inc_tax": 0, + "cart_amount_ex_tax": 0, + "coupons": [], + "discounts": [], + "line_items": { "physical_items": [ - { - "id": "b2f0d1b2-f505-479a-b79a-813b33ce2771", - "parent_id": null, - "variant_id": 118, - "product_id": 120, - "sku": "SM-13", - "name": "BigCommerce Coffee Mug", - "url": "https://arabic-store.mybigcommerce.com/bigcommerce-coffee-mug/", - "quantity": 1, - "is_taxable": true, - "image_url": "https://cdn11.bigcommerce.com/r-4b20dad619e29ebf3490f7f35369a8220637ce48/themes/ClassicNext/images/ProductDefault.gif", - "discounts": [], - "coupons": [], - "discount_amount": 10, - "coupon_amount": 0, - "original_price": 10, - "list_price": 10, - "sale_price": 0, - "extended_list_price": 10, - "extended_sale_price": 0, - "is_require_shipping": true, - "gift_wrapping": null, - "is_mutable": true - }, - { - "id": "275a516e-c59b-58fc-9e5d-10b5f277919b", - "parent_id": null, - "variant_id": 118, - "product_id": 120, - "sku": "SM-13", - "name": "BigCommerce Coffee Mug", - "url": "https://arabic-store.mybigcommerce.com/bigcommerce-coffee-mug/", - "quantity": 9, - "is_taxable": true, - "image_url": "https://cdn11.bigcommerce.com/r-4b20dad619e29ebf3490f7f35369a8220637ce48/themes/ClassicNext/images/ProductDefault.gif", - "discounts": [], - "coupons": [], - "discount_amount": 76.5, - "coupon_amount": 0, - "original_price": 10, - "list_price": 10, - "sale_price": 1.5, - "extended_list_price": 90, - "extended_sale_price": 13.5, - "is_require_shipping": true, - "gift_wrapping": null, - "is_mutable": false - } + { + "id": "b2f0d1b2-f505-479a-b79a-813b33ce2771", + "parent_id": null, + "variant_id": 118, + "product_id": 120, + "sku": "SM-13", + "name": "BigCommerce Coffee Mug", + "url": "https://arabic-store.mybigcommerce.com/bigcommerce-coffee-mug/", + "quantity": 1, + "is_taxable": true, + "image_url": "https://cdn11.bigcommerce.com/r-4b20dad619e29ebf3490f7f35369a8220637ce48/themes/ClassicNext/images/ProductDefault.gif", + "discounts": [], + "coupons": [], + "discount_amount": 10, + "coupon_amount": 0, + "original_price": 10, + "list_price": 10, + "sale_price": 0, + "extended_list_price": 10, + "extended_sale_price": 0, + "is_require_shipping": true, + "gift_wrapping": null, + "is_mutable": true + }, + { + "id": "275a516e-c59b-58fc-9e5d-10b5f277919b", + "parent_id": null, + "variant_id": 118, + "product_id": 120, + "sku": "SM-13", + "name": "BigCommerce Coffee Mug", + "url": "https://arabic-store.mybigcommerce.com/bigcommerce-coffee-mug/", + "quantity": 9, + "is_taxable": true, + "image_url": "https://cdn11.bigcommerce.com/r-4b20dad619e29ebf3490f7f35369a8220637ce48/themes/ClassicNext/images/ProductDefault.gif", + "discounts": [], + "coupons": [], + "discount_amount": 76.5, + "coupon_amount": 0, + "original_price": 10, + "list_price": 10, + "sale_price": 1.5, + "extended_list_price": 90, + "extended_sale_price": 13.5, + "is_require_shipping": true, + "gift_wrapping": null, + "is_mutable": false + } ], "digital_items": [], "gift_certificates": [], "custom_items": [] + }, + "created_time": "2023-10-04T18:32:27+00:00", + "updated_time": "2023-10-04T19:45:40+00:00" }, - "created_time": "2023-10-04T18:32:27+00:00", - "updated_time": "2023-10-04T19:45:40+00:00" - }, - "billing_address": { - "id": "651db12447abc", - "first_name": "Test", - "last_name": "User", - "email": "Test.User@email.com", - "company": "BigCommerce", - "address1": "555 Main Street", - "address2": "", - "city": "Austin", - "state_or_province": "Texas", - "state_or_province_code": "TX", - "country": "United States", - "country_code": "US", - "postal_code": "78701", - "phone": "555-555-5555", - "custom_fields": [] - }, - "consignments": [ - { + "billing_address": { + "id": "651db12447abc", + "first_name": "Test", + "last_name": "User", + "email": "Test.User@email.com", + "company": "BigCommerce", + "address1": "555 Main Street", + "address2": "", + "city": "Austin", + "state_or_province": "Texas", + "state_or_province_code": "TX", + "country": "United States", + "country_code": "US", + "postal_code": "78701", + "phone": "555-555-5555", + "custom_fields": [] + }, + "consignments": [ + { "id": "651dbc9311976", "shipping_cost_inc_tax": 0, "shipping_cost_ex_tax": 0, @@ -628,107 +630,112 @@ X-Auth-Token: {{ACCESS_TOKEN}} "coupon_discounts": [], "discounts": [], "line_item_ids": [ - "275a516e-c59b-58fc-9e5d-10b5f277919b" + "275a516e-c59b-58fc-9e5d-10b5f277919b" ], "selected_shipping_option": { - "id": "6ded13392879983ee32a3563f5fa6a7b", - "type": "shipping_pickupinstore", - "description": "Pickup In Store", - "image_url": "", - "cost": 0, - "transit_time": "", - "additional_description": "" + "id": "6ded13392879983ee32a3563f5fa6a7b", + "type": "shipping_pickupinstore", + "description": "Pickup In Store", + "image_url": "", + "cost": 0, + "transit_time": "", + "additional_description": "" }, "shipping_address": { - "first_name": "Test", - "last_name": "User", - "email": "Test.User@example.com", - "company": "BigCommerce", - "address1": "555 Main Street", - "address2": "", - "city": "Austin", - "state_or_province": "Texas", - "state_or_province_code": "TX", - "country": "United States", - "country_code": "US", - "postal_code": "78701", - "phone": "555-555-5555", - "custom_fields": [] + "first_name": "Test", + "last_name": "User", + "email": "Test.User@example.com", + "company": "BigCommerce", + "address1": "555 Main Street", + "address2": "", + "city": "Austin", + "state_or_province": "Texas", + "state_or_province_code": "TX", + "country": "United States", + "country_code": "US", + "postal_code": "78701", + "phone": "555-555-5555", + "custom_fields": [] }, "address": { - "first_name": "Test", - "last_name": "User", - "email": "Test.User@example.com", - "company": "BigCommerce", - "address1": "555 Main Street", - "address2": "", - "city": "Austin", - "state_or_province": "Texas", - "state_or_province_code": "TX", - "country": "United States", - "country_code": "US", - "postal_code": "78701", - "phone": "555-555-5555", - "custom_fields": [] + "first_name": "Test", + "last_name": "User", + "email": "Test.User@example.com", + "company": "BigCommerce", + "address1": "555 Main Street", + "address2": "", + "city": "Austin", + "state_or_province": "Texas", + "state_or_province_code": "TX", + "country": "United States", + "country_code": "US", + "postal_code": "78701", + "phone": "555-555-5555", + "custom_fields": [] } - } - ], - "taxes": [], - "coupons": [], - "order_id": null, - "shipping_cost_total_inc_tax": 0, - "shipping_cost_total_ex_tax": 0, - "handling_cost_total_inc_tax": 0, - "handling_cost_total_ex_tax": 0, - "tax_total": 0, - "subtotal_inc_tax": 13.5, - "subtotal_ex_tax": 13.5, - "grand_total": 0, - "created_time": "2023-10-04T18:32:27+00:00", - "updated_time": "2023-10-04T19:45:40+00:00", - "customer_message": "", - "fees": [] - }, - "meta": {} -} -``` - - + } + ], + "taxes": [], + "coupons": [], + "order_id": null, + "shipping_cost_total_inc_tax": 0, + "shipping_cost_total_ex_tax": 0, + "handling_cost_total_inc_tax": 0, + "handling_cost_total_ex_tax": 0, + "tax_total": 0, + "subtotal_inc_tax": 13.5, + "subtotal_ex_tax": 13.5, + "grand_total": 0, + "created_time": "2023-10-04T18:32:27+00:00", + "updated_time": "2023-10-04T19:45:40+00:00", + "customer_message": "", + "fees": [] + }, + "meta": {} + } + ``` + + + + ## Creating an order -Now that you have added a billing address and a consignment to your checkout, you can create an order by sending a `POST` request to the [Create an Order](/docs/rest-management/checkouts/checkout-orders#create-an-order) endpoint. The order status will be set to incomplete. +After you add a billing address and a consignment to your checkout, you can create an order by sending a request to the [Create an Order](/docs/rest-management/checkouts/checkout-orders#create-an-order) endpoint. The order status will be set to incomplete. - ```http filename="Example request: Create an order" showLineNumbers copy - POST https://api.bigcommerce.com/stores/{store_hash}/v3/checkouts/{checkoutId}/orders - Accept: application/json - Content-Type: application/json - X-Auth-Token: {{ACCESS_TOKEN}} - ``` - - - + POST https://api.bigcommerce.com/stores/{store_hash}/v3/checkouts/{checkoutId}/orders + Accept: application/json + Content-Type: application/json + X-Auth-Token: {{ACCESS_TOKEN}} + ``` + + ```json filename="Example response: Create an order" showLineNumbers copy - { - "data": { - "id": 125 - }, - "meta": {} - } + { + "data": { + "id": 125 + }, + "meta": {} + } ``` - -## References +## Resources + * [OAuth Scopes](/docs/start/authentication/api-accounts#oauth-scopes) -* [Carts](/docs/rest-management/carts/carts-single#create-a-cart) -* [Checkout](/docs/rest-management/checkouts/checkout-orders#create-an-order) -* [Order](/docs/rest-management/checkouts/checkout-orders#create-an-order) -* [Working with the REST Storefront Cart and Checkout APIs](/docs/storefront/cart-checkout/guide/rest-storefront) -* [Create cart redirect URL](/docs/rest-management/carts/redirects#create-cart-redirect-url) -* [Add Checkout Billing Address](/docs/rest-management/checkouts/checkout-billing-address#add-checkout-billing-address) -* [Update Checkout Consignment](/docs/rest-management/checkouts/checkout-consignments#update-checkout-consignment) + +### API Reference: REST Management +* [Carts: Create a cart](/docs/rest-management/carts/carts-single#create-a-cart) +* [Carts: Create cart redirect URL](/docs/rest-management/carts/redirects#create-cart-redirect-url) +* [Checkout: Add a checkout billing address](/docs/rest-management/checkouts/checkout-billing-address#add-checkout-billing-address) +* [Checkout: Update checkout consignment](/docs/rest-management/checkouts/checkout-consignments#update-checkout-consignment) +* [Checkout: Create an order](/docs/rest-management/checkouts/checkout-orders#create-an-order) +* [Orders: Create an order](/docs/rest-management/checkouts/checkout-orders#create-an-order) + + + + From 71b0e1d99517ab1934015b965887f3beed2af8dc Mon Sep 17 00:00:00 2001 From: Traci Porter Date: Thu, 9 Nov 2023 10:14:29 -0600 Subject: [PATCH 7/9] changes per Sarah's review --- docs/api-docs/headless/end-to-end-guide/rest.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/api-docs/headless/end-to-end-guide/rest.mdx b/docs/api-docs/headless/end-to-end-guide/rest.mdx index 9c6643888..a95d6011e 100644 --- a/docs/api-docs/headless/end-to-end-guide/rest.mdx +++ b/docs/api-docs/headless/end-to-end-guide/rest.mdx @@ -1,6 +1,6 @@ # End-to-End Guide: Headless Checkout Flow with REST Management APIs -This tutorial will walk you through [creating a cart](#creating-a-cart), [checkout](#creating-a-checkout), an [order](#creating-an-order), and processing a payment using the [Carts](/docs/rest-management/carts/carts-single#create-a-cart) and [Checkout](/docs/rest-management/checkouts) REST Management APIs to build a headless storefront. +This tutorial walks you through [creating a cart](#creating-a-cart), [checkout](#creating-a-checkout), an [order](#creating-an-order), and processing a payment using the [Carts](/docs/rest-management/carts/carts-single#create-a-cart) and [Checkout](/docs/rest-management/checkouts) REST Management APIs to build a headless storefront. This article assumes you are familiar with the following: @@ -110,7 +110,7 @@ For more information, see [OAuth Scopes](/docs/start/authentication/api-accounts ### Step 2: Generate the redirect URLs - To generate the redirect URLs, send a request to the [Create a cart redirect URL](/docs/rest-management/carts/redirects#create-cart-redirect-url) endpoint. You use the cart ID generated in [Step 1](#creating-a-cart). The response will contain the `cart_url` and the `checkout_url`. Use these URLs to redirect customers to the BigCommerce-hosted cart or checkout pages. + To generate the redirect URLs, send a request to the [Create a cart redirect URL](/docs/rest-management/carts/redirects#create-cart-redirect-url) endpoint. You use the cart ID generated in [Step 1](#creating-a-cart). The response contains the `cart_url` and the `checkout_url`. Use these URLs to redirect customers to the BigCommerce-hosted cart or checkout pages. @@ -140,7 +140,7 @@ For more information, see [OAuth Scopes](/docs/start/authentication/api-accounts ## Creating a checkout -In this section, we will add a billing address to your checkout. You must have a `checkoutId`. The `checkoutId` is the same as the `cart_id` you generated in [step 1](#creating-a-cart) of creating a cart. To add a billing address, send a POST request to the [Add Checkout Billing Address](/docs/rest-management/checkouts/checkout-billing-address#add-checkout-billing-address) endpoint. +In this section, add a billing address to your checkout. You must have a `checkoutId`. The `checkoutId` is the same as the `cart_id` you generated in [step 1](#creating-a-cart) of creating a cart. To add a billing address, send a POST request to the [Add Checkout Billing Address](/docs/rest-management/checkouts/checkout-billing-address#add-checkout-billing-address) endpoint. @@ -268,7 +268,7 @@ Now that you have transformed your headless cart into a proper checkout with a b ### Step 1: Add a new consignment to the checkout - Send a request to the [Add Consignment to Checkout](/docs/rest-management/checkouts/checkout-consignments#add-consignment-to-checkout) endpoint. Append the `include=consignments.available_shipping_options` query parameter to your request to return available shipping options. You will use one of the available shipping options to update the consignment in [step 2](#step-2-update-the-consignment). + Send a request to the [Add Consignment to Checkout](/docs/rest-management/checkouts/checkout-consignments#add-consignment-to-checkout) endpoint. Append the `include=consignments.available_shipping_options` query parameter to your request to return available shipping options. Use one of the available shipping options to update the consignment in [step 2](#step-2-update-the-consignment). @@ -474,7 +474,7 @@ Now that you have transformed your headless cart into a proper checkout with a b - The response will contain an array of `available_shipping_options`. In the next step, you will use one of the available shipping options to update the consignment. + The response contains an array of `available_shipping_options`. In the next step, use one of the available shipping options to update the consignment. ```json filename="available shipping options" showLineNumbers copy "available_shipping_options": [ @@ -701,7 +701,7 @@ Now that you have transformed your headless cart into a proper checkout with a b ## Creating an order -After you add a billing address and a consignment to your checkout, you can create an order by sending a request to the [Create an Order](/docs/rest-management/checkouts/checkout-orders#create-an-order) endpoint. The order status will be set to incomplete. +After you add a billing address and a consignment to your checkout, you can create an order by sending a request to the [Create an Order](/docs/rest-management/checkouts/checkout-orders#create-an-order) endpoint. The order status displays as incomplete. From b771343af9bd8a529ea32bba9f1dafc796c6d4df Mon Sep 17 00:00:00 2001 From: Sarah Riehl Date: Tue, 28 Nov 2023 14:03:39 -0600 Subject: [PATCH 8/9] brackets and lines --- docs/api-docs/headless/end-to-end-guide/rest.mdx | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/api-docs/headless/end-to-end-guide/rest.mdx b/docs/api-docs/headless/end-to-end-guide/rest.mdx index a95d6011e..283c53c45 100644 --- a/docs/api-docs/headless/end-to-end-guide/rest.mdx +++ b/docs/api-docs/headless/end-to-end-guide/rest.mdx @@ -111,11 +111,12 @@ For more information, see [OAuth Scopes](/docs/start/authentication/api-accounts ### Step 2: Generate the redirect URLs To generate the redirect URLs, send a request to the [Create a cart redirect URL](/docs/rest-management/carts/redirects#create-cart-redirect-url) endpoint. You use the cart ID generated in [Step 1](#creating-a-cart). The response contains the `cart_url` and the `checkout_url`. Use these URLs to redirect customers to the BigCommerce-hosted cart or checkout pages. + ```http filename="Example request: Create cart redirect URLs" showLineNumbers copy - POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/carts/{cartId}/redirect_urls + POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/carts/{{cartId}}/redirect_urls Accept: application/json Content-Type: application/json X-Auth-Token: {{ACCESS_TOKEN}} @@ -145,7 +146,7 @@ In this section, add a billing address to your checkout. You must have a `checko ```http filename="Example request: Add Checkout Billing Address" showLineNumbers copy - POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/checkouts/{checkoutId}/billing-address + POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/checkouts/{{checkoutId}}/billing-address Accept: application/json Content-Type: application/json X-Auth-Token: {{ACCESS_TOKEN}} @@ -273,7 +274,7 @@ Now that you have transformed your headless cart into a proper checkout with a b ```http filename="Example request: Add Consignment to checkout" showLineNumbers copy - POST https://api.bigcommerce.com/stores/{store_hash}/v3/checkouts/{checkoutId}/consignments?include=consignments.available_shipping_options + POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/checkouts/{{checkoutId}}/consignments?include=consignments.available_shipping_options Accept: application/json Content-Type: application/json X-Auth-Token: {{ACCESS_TOKEN}} @@ -516,7 +517,7 @@ Now that you have transformed your headless cart into a proper checkout with a b ```http filename="Example request: Update checkout consignment" showLineNumbers copy - PUT https://api.bigcommerce.com/stores/{store_hash}/v3/checkouts/{checkoutId}/consignments/{consignmentId} + PUT https://api.bigcommerce.com/stores/{{store_hash}}/v3/checkouts/{{checkoutId}}/consignments/{{consignmentId}} Accept: application/json Content-Type: application/json X-Auth-Token: {{ACCESS_TOKEN}} @@ -706,7 +707,7 @@ After you add a billing address and a consignment to your checkout, you can crea ```http filename="Example request: Create an order" showLineNumbers copy - POST https://api.bigcommerce.com/stores/{store_hash}/v3/checkouts/{checkoutId}/orders + POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/checkouts/{{checkoutId}}/orders Accept: application/json Content-Type: application/json X-Auth-Token: {{ACCESS_TOKEN}} @@ -729,6 +730,7 @@ After you add a billing address and a consignment to your checkout, you can crea * [OAuth Scopes](/docs/start/authentication/api-accounts#oauth-scopes) ### API Reference: REST Management + * [Carts: Create a cart](/docs/rest-management/carts/carts-single#create-a-cart) * [Carts: Create cart redirect URL](/docs/rest-management/carts/redirects#create-cart-redirect-url) * [Checkout: Add a checkout billing address](/docs/rest-management/checkouts/checkout-billing-address#add-checkout-billing-address) From a45b73e5b7c9e33eb6d6d0be20cf465cecc50d1a Mon Sep 17 00:00:00 2001 From: Sarah Riehl Date: Tue, 28 Nov 2023 14:03:57 -0600 Subject: [PATCH 9/9] revise --- docs/api-docs/headless/end-to-end-guide/rest.mdx | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/api-docs/headless/end-to-end-guide/rest.mdx b/docs/api-docs/headless/end-to-end-guide/rest.mdx index 283c53c45..3257b6a75 100644 --- a/docs/api-docs/headless/end-to-end-guide/rest.mdx +++ b/docs/api-docs/headless/end-to-end-guide/rest.mdx @@ -26,7 +26,7 @@ For more information, see [OAuth Scopes](/docs/start/authentication/api-accounts ### Step 1: Generate the cart ID - To generate the cart ID, send a request to the [Create a cart](/docs/rest-management/carts/carts-single#create-a-cart) endpoint. The response contain the `id`, which is the `cart_id` or `cartId` in subsequent calls. + To generate a cart ID, send a request to the [Create a cart](/docs/rest-management/carts/carts-single#create-a-cart) endpoint. The response contains an `id`, which is the `cart_id` or `cartId` in subsequent calls. @@ -110,8 +110,9 @@ For more information, see [OAuth Scopes](/docs/start/authentication/api-accounts ### Step 2: Generate the redirect URLs - To generate the redirect URLs, send a request to the [Create a cart redirect URL](/docs/rest-management/carts/redirects#create-cart-redirect-url) endpoint. You use the cart ID generated in [Step 1](#creating-a-cart). The response contains the `cart_url` and the `checkout_url`. Use these URLs to redirect customers to the BigCommerce-hosted cart or checkout pages. + After you generate the cart ID, generate URLs to redirect customers to the BigCommerce-hosted cart and checkout pages. + To generate the redirect URLs, send a request to the [Create a cart redirect URL](/docs/rest-management/carts/redirects#create-cart-redirect-url) endpoint. You use the cart ID generated in [Step 1](#creating-a-cart). The response contains the `cart_url` and the `checkout_url`. @@ -141,7 +142,7 @@ For more information, see [OAuth Scopes](/docs/start/authentication/api-accounts ## Creating a checkout -In this section, add a billing address to your checkout. You must have a `checkoutId`. The `checkoutId` is the same as the `cart_id` you generated in [step 1](#creating-a-cart) of creating a cart. To add a billing address, send a POST request to the [Add Checkout Billing Address](/docs/rest-management/checkouts/checkout-billing-address#add-checkout-billing-address) endpoint. +After you create a cart, transform it into a checkout by adding a billing address. You must have a `checkoutId`, which is the same as the `cart_id` you generated in [Step 1 of creating a cart](#creating-a-cart). To add a billing address, send a request to the [Add Checkout Billing Address](/docs/rest-management/checkouts/checkout-billing-address#add-checkout-billing-address) endpoint. @@ -263,7 +264,7 @@ In this section, add a billing address to your checkout. You must have a `checko -Now that you have transformed your headless cart into a proper checkout with a billing address, you can add a consignment with a shipping address, line items, and a shipping option. You can do so by following this two-step process: +After you transform your headless cart into a proper checkout with a billing address, you can add a consignment with a shipping address, line items, and a shipping option. You can do so using the following two-step process: @@ -509,9 +510,9 @@ Now that you have transformed your headless cart into a proper checkout with a b ] ``` - ### Step 2: Update the consignment + ### Step 2: Update the consignment with a shipping option - Use one of the available shipping options to update the consignment you created in the previous step. + After you create the consignment, update it with one of the available shipping options the previous request returned. Send a request to the [Update Checkout Consignment](/docs/rest-management/checkouts/checkout-consignments#update-checkout-consignment) endpoint. @@ -702,7 +703,7 @@ Now that you have transformed your headless cart into a proper checkout with a b ## Creating an order -After you add a billing address and a consignment to your checkout, you can create an order by sending a request to the [Create an Order](/docs/rest-management/checkouts/checkout-orders#create-an-order) endpoint. The order status displays as incomplete. +After you add a billing address and a consignment to your checkout, you can create an order by sending a request to the [Create an Order](/docs/rest-management/checkouts/checkout-orders#create-an-order) endpoint. The initial order status is `incomplete`.