CartCheckoutSession creation by custom logic versus the Checkout API
Key Takeaway
Only the Checkout API should create a CartCheckoutSession. If custom logic also creates one in the same flow, remove the custom creation.
A CartCheckoutSession is the checkout session for a cart in a B2B Commerce store. The standard Checkout API creates and manages this session itself. If custom code also creates these records, the two paths conflict, so the fix is to use one creation method: the Checkout API.
What the Start Checkout call does
In the Checkout API, the Start Checkout call (/commerce/webstores/{webstoreId}/checkouts) handles session creation for you. The call checks whether an active CartCheckoutSession already exists for the cart and returns it if found. If none exists, the call creates a new session and returns its checkoutId.
cartId is the only required request parameter. deliveryAddressInput and customFields are optional.
Before the call returns or creates a session, the system validates these items:
- Access to the webstore
- Access to the cart
- The cart status
- The delivery address, if one is provided
Starting checkout also starts background work, which runs the pricing, promotions, and inventory calculators. The shipping and tax calculators run too if an address is available.
The response shows whether processing has finished.
If the call returns 200 OK...
The CartCheckoutSession is ready and all calculations are complete.
If the call returns 202 Accepted...
Processing is still running, so the caller should poll GET /checkouts until it returns 200.