DEVDOCS-6246 - Quotes refresh #913
Conversation
Reformatted file. Added new copy. Added missing fields.
| description: BigCommerce B2B Edition Quote | ||
| title: Quotes | ||
| description: |- | ||
| B2B Edition sales quotes allow you to build tailored orders on behalf of your B2B buyers, B2C customers, and guest shoppers while also incorporating your business’s terms and conditions. |
There was a problem hiding this comment.
I'm still struggling with the general structure of DevDocs between the "Documentation" section and the "API Reference" section. Explanatory content like what's here in this intro seems to be more like what users would expect in the Documentation section. Maybe I'm not looking at this the right way.
There was a problem hiding this comment.
One of the reasons we've outlined so much "documentation" in these areas is that doing so allows us to write it once and reference it throughout.
In the diataxis docs and the style guide, we have a rule that generally we should link to existing content rather than rewriting it.
|
|
||
| Non-purchasable products are added to sales quotes as *custom items*. | ||
|
|
||
| A custom item is a one-time line item which uses the SKU and pricing of the selected product, but not the product’s ID. Note that the missing product ID can cause downstream issues if you have an external integration which uses the ID to sync information and events. |
There was a problem hiding this comment.
Just a sanity check on the wording "SKU and pricing of the selected product." A custom item has to correspond with a specific existing product in the catalog? You can't add a custom item with an arbitrary SKU?
There was a problem hiding this comment.
@CNanninga There is a distinction between "custom items" and "custom products". Custom items necessarily correspond to an existing product because they are generated to stand in for said product in the quote if it is otherwise unpurchasable on the storefront.
Custom products are completely new products created within the quote, and can have abritrary names, pricing, SKUs, etc.
Custom products are explained later on in the description of Create a Quote, and a comprehensive comparison of custom products and custom items is provided in the user doc link that appears a couple paragraphs below this line. However, if you think it would be beneficial, we can introduce the distinction here as well, and direct to the appropriate user doc for more information.
| description: |- | ||
| Creates a new sales quote and automatically submits it to the assigned buyer. | ||
|
|
||
| Unlike creating a quote in the B2B Edition control panel, you cannot start the quote in the API and save it as a draft without submitting it to the buyer’s Buyer Portal. However, you can give the `allowCheckout` a value of `false` to prevent the buyer from purchasing it immediately upon submission. |
There was a problem hiding this comment.
I'm unclear on exactly what this note means. My points of confusion:
- A "draft" quote in the Buyer Portal is just data saved in the user's browser and doesn't involve any record in the B2B Edition system at all, so I'm struggling to connect what we're talking about.
- "the buyer's Buyer Portal" is an awkward phrase, and I don't know what's meant by "submitting it to …" the Buyer Portal.
Some of my confusion might have to do with what, exactly, we're contrasting with "unlike creating a quote in the control panel."
There was a problem hiding this comment.
@CNanninga Here, we are referring to a quote in the Draft status, which is defined in the Quote Statuses section of the intro. Quotes in this status are actually saved in the B2B Edition quote list, but they are not visible until submitted to the buyer.
"Submitted" in this case refers to the UI "Submit" action, which relays new quotes, or updates to existing quotes, to the Buyer Portal of the assigned buyer.
With the API, sending the POST or PUT request is akin to clicking "Submit" in the UI, but it does not allow the user to save the new quote/quote updates. This is what we are trying to call out. What do you think about the following revision:
"While the B2B Edition control panel allows you to save a new quote as a draft without sending it to the buyer, quotes created with this endpoint are automatically visible in a Company user's Buyer Portal. However, you can give the allowCheckout a value of false to prevent the buyer from purchasing it immediately upon submission."
|
|
||
| Create a custom product while [creating or editing](https://support.bigcommerce.com/s/article/B2B-Edition-Quotes) a quote in the B2B Edition control panel, or by using the [Create a Product](/docs/rest-catalog/products#create-a-product) endpoint in the Catalog API. Obtain your newly-created product’s ID and add it to the `productId` field of the Create a Quote request body to include it in the quote. | ||
|
|
||
| ### Minimum-Required Fields |
There was a problem hiding this comment.
No hyphen between "Minimum" and "Required"
|
|
||
| ### Minimum-Required Fields | ||
|
|
||
| In order to create a sales quote, the request body must include the following fields. Fields marked with an asterisk are only required under specific conditions. |
There was a problem hiding this comment.
Do we not have a way to mark fields as required in the actual API reference schema below, rather than relying on a separate static list here?
There was a problem hiding this comment.
This one is a weird case because some of the fields labelled "required" are only required in a very loose sense. In most cases, we'd just label them as required without extra work on it [an array of required field names in the object]. This list constitutes a minimum working example with caveats, and part of the reason we call it out here is that it's somewhat counter-intuitive.
@bc-Vince can provide further context.
There was a problem hiding this comment.
As Terra mentioned, there are several common situations where certain fields are required, but are otherwise not needed to create a new quote; for example, one must include the extraFields array if any of their quote extra fields are marked as required in the control panel.
Instead of adding the information exclusively to the affected fields, we figured it would make sense to have a list of these callouts for ease of troubleshooting.
Reformatted file.
Added new copy.
Added missing fields.
DEVDOCS-6246
What changed?
Release notes draft
Anything else?
ping { @CNanninga @bc-Vince }