Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

DEVDOCS-5505: [Update] Clarified text re. correlating request and edi… #2071

Merged
merged 18 commits into from
Oct 24, 2023
Merged

DEVDOCS-5505: [Update] Clarified text re. correlating request and edi… #2071

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
2ee3049
DEVDOCS-5505: [Update] Clarified text re. correlating request and edi…
bc-traciporter Sep 28, 2023
8612a97
Update checkout resources
bc-traciporter Sep 28, 2023
e40625c
Create tutorial.mdx
bc-traciporter Sep 28, 2023
a0aa2b5
work in progress
bc-traciporter Sep 29, 2023
0b54580
Update tutorial.mdx
bc-traciporter Oct 2, 2023
1828ff8
more edits
bc-traciporter Oct 3, 2023
bc2e33d
More updates
bc-traciporter Oct 4, 2023
87d7204
tutorial update
bc-traciporter Oct 16, 2023
275bb6c
Update orders.mdx
bc-traciporter Oct 18, 2023
2d85396
add tutorial to the references
bc-traciporter Oct 18, 2023
079fdb9
added Tutorial reference link
bc-traciporter Oct 18, 2023
b8974b3
Updated tutorial link
bc-traciporter Oct 18, 2023
7df111e
Update tutorial.mdx
bc-traciporter Oct 18, 2023
213727f
added create a cart
bc-traciporter Oct 18, 2023
d0bd850
removed mention of GraphQL in the callout
bc-traciporter Oct 23, 2023
c8c69ff
Updated per Nathan's feedback
bc-traciporter Oct 24, 2023
9e6cd98
Update tutorial.mdx
bc-traciporter Oct 24, 2023
1515540
Merge branch 'main' into DEVDOCS-5505
bc-traciporter Oct 24, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/api-docs/headless/carts.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -259,3 +259,4 @@ In practice, removing all cart items also essentially deletes the cart.
- [Carts API](/docs/rest-management/carts)
- [Storefront Carts API](/docs/rest-storefront/carts)
- [Persistent Cart](https://support.bigcommerce.com/s/article/Persistent-Cart)
- [Headless Tutorial](/docs/api-docs/headless/tutorial)
3 changes: 2 additions & 1 deletion docs/api-docs/headless/checkout.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,4 +61,5 @@ The Checkouts API allows you to move the cart to checkout and turn it into an or

- [Restyle Optimized One-Page Checkout](/stencil-docs/customizing-checkout/optimized-one-page-checkout)
- [Checkout JS repo](https://github.com/bigcommerce/checkout-js)
- [Checkout SDK Quickstart](/stencil-docs/customizing-checkout/checkout-sdk-quickstart)
- [Checkout SDK Tutorial](/stencil-docs/customizing-checkout/checkout-sdk-quickstart)
- [Headless Tutorial](/docs/api-docs/headless/tutorial)
137 changes: 11 additions & 126 deletions docs/api-docs/headless/orders.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]() section of this tutorial.
To successfully complete this section, you must create a cart with a **redirect URL**. For instructions on creating a cart, see the [Carts](/api-docs/storefronts/guide/carts) section of this guide.

### 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": "[email protected]",
"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 `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). See the [headless tutorial](/api-docs/storefronts/guide/tutorial) for an example request.
bc-traciporter marked this conversation as resolved.
Show resolved Hide resolved

### 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": "[email protected]",
"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. See the [headless tutorial](/api-docs/storefronts/guide/tutorial) for an example request.

### 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 `POST` request to the [Create an Order](/docs/rest-management/checkouts/checkout-orders#create-an-order) endpoint. The order status will display as incomplete.

<Tabs items={['Request', 'Response']}>
<Tab>
Expand Down Expand Up @@ -182,7 +66,7 @@ Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}
```

1. 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 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.

```http filename="Example request: Create payment access token" showLineNumbers copy
POST https://api.bigcommerce.com/stores/{store_hash}/v3/payments/access_tokens
Expand All @@ -199,9 +83,9 @@ X-Auth-Token: {{ACCESS_TOKEN}}
```


Make a note of the access token `id`. This token is required in subsequent payment request to the [Process Payment](/docs/rest-payments/processing#process-payment) endpoint.
Make a note of the access token `id`. This token is a requirement for subsequent payment requests to the [Process Payment](/docs/rest-payments/processing#process-payment) endpoint.

1. 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](/api-docs/store-management/payments-api-overview#stored-cards).
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 when creating the Payment Access Token (step two). To learn more, see [Stored cards](/api-docs/store-management/payments-api-overview#stored-cards).

<Tabs items={['Request', 'Response']}>
<Tab>
Expand Down Expand Up @@ -246,7 +130,7 @@ If a shopper does not have a payment method saved on file, you can process a pay

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.

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](/api-docs/store-management/payments-api-overview#credit-cards).
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 when creating the Payment Access Token (step one). To learn more, see [Credit cards](/api-docs/store-management/payments-api-overview#credit-cards).

```json filename="Example response: Process payment" showLineNumbers copy
{
Expand All @@ -258,12 +142,13 @@ 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](/api-docs/store-management/payments-api-overview#error-codes) for troubleshooting.
A successful transaction will return a status of success. The order is then automatically moved to an Awaiting Fulfillment status. See [Error Codes](/api-docs/store-management/payments-api-overview#error-codes) for troubleshooting if you get a different response.

## Next steps

- [Learn more about PCI compliance](/api-docs/storefronts/guide/pci-compliance)

## Resources

- [Payments API Overview](/api-docs/store-management/payments-api-overview)
- [Payments API Overview](/api-docs/store-management/payments-api-overview
- [Headless Tutorial](/docs/api-docs/headless/tutorial)
6 changes: 3 additions & 3 deletions docs/api-docs/headless/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,9 @@ This is the first article in a comprehensive developer's guide to using BigComme

## Ways to implement headless commerce

If you are looking to build a headless storefront powered by a BigCommerce backend without starting from scratch, BigCommerce offers multiple starter apps and pre-built solutions to choose from. For headless storefront solutions and tools, see [Headless Integrations](/tools-resources#headless-integrations).
If you want to build a headless storefront powered by a BigCommerce backend without starting from scratch, BigCommerce offers multiple starter apps and pre-built solutions. For headless storefront solutions and tools, see [Headless Integrations](/tools-resources#headless-integrations).

If you need to build a custom solution, BigCommerce has APIs and [SDKs](/tools-resources#sdks) available to support your headless architecture. For specific use cases, see the following sections of the guide:
If you need to build a custom solution, BigCommerce has APIs and [SDKs](/tools-resources/tools#sdks) available to support your headless architecture. For specific use cases, see the following sections of the guide:

* [Create a channel and a channel site](/api-docs/storefronts/guide/channels)
* [Fetch and manage product data](/api-docs/storefronts/guide/products)
Expand All @@ -35,7 +35,7 @@ In the diagram below, the storefront is where the shopper interacts with product

## Correlating requests

Completing an operation on a headless storefront may require several API calls. For example, [processing a payment](/api-docs/store-management/payments-api-overview) and [refunding an order](/api-docs/store-management/order-refunds) each require reading and writing information using multiple endpoints. When you perform a multi-part operation on a headless storefront, group the constituent requests by generating one UUID to represent the whole operation, then use the `X-Correlation-Id` request header to send that UUID with every request in the group. This indicates to BigCommerce's infrastructure that an API call is part of a larger operation, and helps us track the handoff from request to request as the operation moves through our servers. To learn more about the header, see our [list of request headers](/api-docs/getting-started/about-our-api#bigcommerce-specific-request-headers).
Completing an operation on a headless storefront may require several API calls. For example, [processing a payment](/api-docs/store-management/payments-api-overview) and [refunding an order](/api-docs/store-management/order-refunds) each require reading and writing information using multiple endpoints. When you perform a multi-part operation on a headless storefront, group the constituent requests by generating one UUID to represent the whole operation, then use the `X-Correlation-Id` request header to send that UUID with every request in the group. The value you pass to the `X-Correlation-Id` header should be a UUID-type string you generate independently. This indicates to BigCommerce's infrastructure that an API call is part of a larger operation and helps us track the handoff from request to request as the operation moves through our servers. To learn more about the header, see our [list of request headers](/api-docs/getting-started/about-our-api#bigcommerce-specific-request-headers).

When you're using the BigCommerce for WordPress plugin, there is no need to send the `X-Correlation-Id` header.

Expand Down
Loading