This page lists the REST calls Bolt’s backend issues against your Magento 2 store, in the order a typical checkout flows through them. All paths are relative to your store’s REST root (e.g. https://example.com/rest/V1/...).
Endpoints prefixed with /V1/bolt/boltpay/... are exposed by the Bolt for Adobe Commerce plugin — see Custom Endpoints for the full catalog. Every other path is a standard Magento REST endpoint.
Authentication is the same for every call: an OAuth Bearer token established during plugin setup. See Authentication.
1. Open Checkout — Load Cart
When the shopper opens Bolt Checkout, Bolt fetches a current snapshot of the cart, totals, items, and the products in the cart.
| Method | Endpoint | Purpose |
|---|---|---|
GET |
/V1/carts/{cartId} |
Fetch cart record (customer, addresses, currency). |
GET |
/V1/carts/{cartId}/totals |
Fetch totals (subtotal, tax, discount, grand total). |
GET |
/V1/carts/{cartId}/items |
List line items with selected options. |
GET |
/V1/bolt/boltpay/carts/{cartId}/maskedid |
Resolve the masked quote ID used for guest references. |
POST |
/V1/products |
Search products by SKU for catalog metadata. |
GET |
/V1/products-render-info |
Fetch render info for tier prices, MSRP, and complex products. |
GET |
/V1/directory/countries |
Allowed-country list for shipping/billing. |
GET |
/V1/carts/licence |
Store agreements / terms shown at checkout. |
2. Enter Shipping Address — Estimate Shipping & Tax
When the shopper enters or changes their shipping address, Bolt requests shipping options and a tax estimate.
| Method | Endpoint | Purpose |
|---|---|---|
POST |
/V1/bolt/boltpay/carts/{cartId}/estimate-shipping-and-tax |
Preferred — combined call returning shipping methods + tax in one round trip. |
POST |
/V1/carts/{cartId}/estimate-shipping-methods |
Fallback (used when the combined endpoint is unavailable). |
POST |
/V1/carts/{cartId}/totals-information |
Used in some flows (e.g. Apple Pay) to retrieve totals for an address-only state. |
3. Select Shipping Method — Commit Choice
Selecting a shipping method commits it to the quote and recomputes totals.
| Method | Endpoint | Purpose |
|---|---|---|
POST |
/V1/carts/{cartId}/shipping-information |
Set shipping method + addresses; returns updated totals and tax. |
4. Apply / Remove Discount
Discount validation goes through Magento’s native rules engine; Bolt does not mirror cart rules.
| Method | Endpoint | Purpose |
|---|---|---|
POST |
/V1/carts/{cartId}/coupons/{couponCode} |
Apply a coupon. |
DELETE |
/V1/carts/{cartId}/coupons |
Remove the active coupon. |
POST |
/V1/coupons/search |
Look up a coupon’s metadata when needed for validation. |
POST |
/V1/salesRules/search, GET /V1/salesRules/{ruleId} |
Inspect the underlying sales rule (discount type, conditions). |
If your store uses a third-party multi-coupon or gift card module, additional endpoints may be involved; see Custom Endpoints.
5. Add / Update / Remove Cart Items
Bolt-modal item actions are written back to Magento.
| Method | Endpoint | Purpose |
|---|---|---|
POST |
/V1/carts/{cartId}/items |
Add an item (resolves bundle / configurable / custom options). |
PUT |
/V1/carts/{cartId}/items/{itemId} |
Update quantity. |
DELETE |
/V1/carts/{cartId}/items/{itemId} |
Remove an item. |
6. Submit Order
Order placement diverges based on whether the shopper is logged in. Both paths return the created order ID.
| Shopper | Method | Endpoint |
|---|---|---|
| Guest | POST |
/V1/guest-carts/{maskedQuoteId}/payment-information (standard Magento) |
| Logged-in | POST |
/V1/bolt/boltpay/carts/mine/payment-information (Bolt plugin) |
The logged-in path is a custom Bolt plugin endpoint; it wraps carts/mine/payment-information to apply the Bolt payment method and persist transaction metadata in a single round trip.
After the order is created Bolt may issue follow-up calls to enrich the record:
| Method | Endpoint | Purpose |
|---|---|---|
GET |
/V1/orders/{orderId} |
Read back the created order to verify state. |
PUT |
/V1/orders/{orderId} |
Patch the order (e.g. shopper IP). |
POST |
/V1/orders/{orderId}/comments |
Add comments (return reference, fraud notes). |
Roll back on failure. If post-creation steps fail (payment declined, fraud rejection, enrichment error), Bolt rolls the Magento order back via DELETE /V1/bolt/boltpay/orders/{orderId} (plugin-created, non-finalized orders only) or POST /V1/orders/{orderId}/cancel for webhook-driven post-authorization cancellation.
7. Post-Order Lifecycle (Transaction Webhooks)
After the order is placed, the lifecycle is driven by transaction events Bolt receives from its payment processor (Worldline, Stripe, Adyen, etc.) and from actions taken in the Bolt Merchant Dashboard. For each event, Bolt’s merchantproxy fires a sequence of REST calls to your Magento store to keep state in sync.
The table below maps each transaction event to the exact Magento REST calls Bolt issues.
| Event | Magento REST calls (in order) | Purpose |
|---|---|---|
pending (pre-auth completed) |
PUT /V1/bolt/boltpay/carts/{cartId} (deactivate cart) → PUT /V1/orders/{orderId} → POST /V1/orders/{orderId}/comments → POST /V1/bolt/boltpay/order/{orderId}/triggerOrderEvents |
Lock the cart, mark order pending. |
auth |
PUT /V1/orders/{orderId} → POST /V1/orders/{orderId}/comments → POST /V1/orders/{orderId}/emails (if email config) |
Move order to authorized; send confirmation email. |
capture (full) |
POST /V1/order/{orderId}/invoice → POST /V1/orders/{orderId}/comments |
Create full invoice in Magento (standard Magento endpoint, note singular /order/). |
capture (partial) |
POST /V1/bolt/boltpay/order/{orderId}/invoice → POST /V1/orders/{orderId}/comments |
Create a partial invoice via the plugin (passes the captured amount). |
payment (auth + capture combined) |
Combination of auth + capture flows above. | Same as both above. |
credit (refund) |
POST /V1/order/{orderId}/refund → POST /V1/orders/{orderId}/comments |
Issue a Magento credit memo against the order. |
void (pre-capture cancel) |
POST /V1/orders/{orderId}/cancel → POST /V1/orders/{orderId}/comments |
Cancel an authorized-but-uncaptured order. |
failed_payment |
DELETE /V1/bolt/boltpay/orders/{orderId} |
Remove the order created during checkout when payment ultimately fails. |
rejected_reversible / rejected_irreversible |
PUT /V1/orders/{orderId} → POST /V1/orders/{orderId}/comments |
Update order state for a fraud-rejected transaction. |
After every event Bolt also persists the Bolt transaction reference on the Magento order via POST /V1/bolt/boltpay/transactions (Bolt transaction ID, processor metadata, amount). Plugin-internal helpers POST /V1/bolt/boltpay/order/{orderId}/triggerOrderEvents (replay) and GET /V1/bolt/boltpay/defaultOrderStatuses (status mapping) are used as needed.
Total mismatch. Before processing any post-order event Bolt verifies the order total against the amount in the webhook. If the difference is within the merchant’s configured allowed mismatch, processing continues; otherwise the webhook is rejected and surfaced as an alert in the dashboard.
See Webhooks for setup, signature verification, and failure handling, and Custom Endpoints — Cart & Order for the full /V1/bolt/boltpay/... catalog.
8. Magento Admin → Bolt API Calls
The Bolt for Adobe Commerce plugin also makes outbound calls from Magento to Bolt when an operations user performs an action directly in Magento Admin (rather than in the Bolt Merchant Dashboard). The plugin uses Bolt’s public Transactions API; host is https://api.bolt.com (production) or the corresponding sandbox / staging host.
| Magento Admin action | Bolt API call | Effect |
|---|---|---|
| Capture an invoice | POST /v1/merchant/transactions/capture |
Captures funds at the payment processor; the resulting capture event flows back as a transaction webhook. |
| Cancel an authorized order | POST /v1/merchant/transactions/void |
Voids the authorization; resulting void event flows back as a webhook. |
| Create a credit memo (refund) | POST /v1/merchant/transactions/credit |
Issues a refund through the payment processor; resulting credit event flows back as a webhook. |
| Look up a Bolt transaction | GET /v1/merchant/transactions/{reference} |
Fetches transaction state; used to render Bolt-side details in the order screen. |
These calls are signed with the merchant’s Bolt API Key (configured in the plugin admin during setup — see Bolt API Credentials). This is a different credential from the Magento OAuth token Bolt uses for the inbound direction documented in Authentication — Bolt → Magento and Magento → Bolt are two independent credentials, configured at the same time during plugin install.