@spree/docs 0.1.93 → 0.1.95

package/dist/developer/core-concepts/markets.md

@@ -74,7 +74,7 @@ If no market matches the customer's country, the store's **default market** is u
 Fetch all markets for the current store, including their countries:
 
 
-```typescript SDK
+```typescript Store SDK
 const { data: markets } = await client.markets.list()
 // [
 //   {
@@ -94,6 +94,10 @@ const { data: markets } = await client.markets.list()
 // ]
 ```
 
+```typescript Admin SDK
+const { data: markets } = await adminClient.markets.list()
+```
+
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/markets' \
   -H 'X-Spree-API-Key: pk_xxx'
@@ -105,7 +109,7 @@ curl 'https://api.mystore.com/api/v3/store/markets' \
 When you know a customer's country (e.g., from geolocation or a country picker), resolve which market applies:
 
 
-```typescript SDK
+```typescript Store SDK
 const market = await client.markets.resolve('DE')
 // { id: "mkt_gbHJdmfr", name: "Europe", currency: "EUR", tax_inclusive: true, ... }
 ```
@@ -125,7 +129,7 @@ This is useful for building a country switcher — resolve the market to show th
 List countries belonging to a specific market. Useful for populating address form dropdowns during checkout:
 
 
-```typescript SDK
+```typescript Store SDK
 const { data: countries } = await client.markets.countries.list('mkt_k5nR8xLq')
 // [
 //   { iso: "CA", name: "Canada", states_required: true, zipcode_required: true },
@@ -134,7 +138,7 @@ const { data: countries } = await client.markets.countries.list('mkt_k5nR8xLq')
 
 // Get a country with its states (for address form dropdowns)
 const usa = await client.markets.countries.get('mkt_k5nR8xLq', 'US', {
-  include: 'states',
+  expand: ['states'],
 })
 ```
 
@@ -152,15 +156,21 @@ curl 'https://api.mystore.com/api/v3/store/markets/mkt_k5nR8xLq/countries/US?exp
 You can also fetch countries flat (across all markets) or include the market on a country:
 
 
-```typescript SDK
+```typescript Store SDK
 // All countries across all markets
 const { data: countries } = await client.countries.list()
 
 // Get a country with its market details
-const germany = await client.countries.get('DE', { include: 'market' })
+const germany = await client.countries.get('DE', { expand: ['market'] })
 // { iso: "DE", name: "Germany", market: { currency: "EUR", default_locale: "de", tax_inclusive: true } }
 ```
 
+```typescript Admin SDK
+const { data: countries } = await adminClient.countries.list()
+
+const germany = await adminClient.countries.get('DE')
+```
+
 ```bash cURL
 # All countries across all markets
 curl 'https://api.mystore.com/api/v3/store/countries' \
@@ -174,12 +184,12 @@ curl 'https://api.mystore.com/api/v3/store/countries/DE?expand=market' \
 
 ## Currency and Locale
 
-Each market defines a currency and set of supported locales. When a market is resolved, its currency and locale become the defaults for the session.
+Each market defines a [currency and set of supported locales](../../api-reference/store-api/monetary-amounts.md). When a market is resolved, its currency and locale become the defaults for the session.
 
 You can discover all available currencies and locales (aggregated from all markets) via dedicated endpoints:
 
 
-```typescript SDK
+```typescript Store SDK
 const { data: currencies } = await client.currencies.list()
 // [{ iso_code: "USD", name: "US Dollar", symbol: "$" }, { iso_code: "EUR", name: "Euro", symbol: "€" }]
 
@@ -221,31 +231,65 @@ See [Pricing — Price Rules](pricing.md#price-rules) for details on configuring
 
 Markets are managed in the admin dashboard under **Settings → Markets**. When you run `rails db:seed`, Spree automatically creates a default market for each store.
 
-To create markets programmatically:
+To create markets programmatically, use the [Admin API](../../api-reference/admin-api/introduction.md). See the [Admin API endpoints](../../api-reference/admin-api/endpoints.md) for the full list of `/markets` routes and required scopes:
+
 
-```ruby
-# North America market
-current_store.markets.create!(
+```typescript Admin SDK
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+  baseUrl: 'https://store.example.com',
+  secretKey: 'sk_xxx',
+})
+
+// North America market (countries by ISO code)
+const northAmerica = await client.markets.create({
   name: 'North America',
   currency: 'USD',
   default_locale: 'en',
-  countries: [usa, canada],
-  default: true
-)
+  country_isos: ['US', 'CA'],
+  default: true,
+})
 
-# Europe market with tax-inclusive pricing
-current_store.markets.create!(
+// Europe market with tax-inclusive pricing
+const europe = await client.markets.create({
   name: 'Europe',
   currency: 'EUR',
   default_locale: 'de',
-  supported_locales: 'de,en,fr',
+  supported_locales: ['de', 'en', 'fr'],
   tax_inclusive: true,
-  countries: [germany, france, austria, netherlands]
-)
+  country_isos: ['DE', 'FR', 'AT', 'NL'],
+})
 ```
 
+```bash CLI
+spree api post /markets -d '{
+  "name": "North America",
+  "currency": "USD",
+  "default_locale": "en",
+  "country_isos": ["US", "CA"],
+  "default": true
+}'
+```
+
+
+Update or remove a market the same way:
+
+
+```typescript Admin SDK
+await client.markets.update('market_xxx', { tax_inclusive: true })
+await client.markets.delete('market_xxx')
+```
+
+```bash CLI
+spree api patch /markets/market_xxx -d '{"tax_inclusive": true}'
+spree api delete /markets/market_xxx
+```
+
+
 ## Related Documentation
 
+- [Markets (Store SDK)](../sdk/store/markets.md) — Listing, resolving, and reading markets from the Store SDK
 - [Stores](stores.md) — Multi-store setup and configuration
 - [Pricing](pricing.md) — Price Lists, Price Rules, and the Pricing Context
 - [Addresses](addresses.md) — Countries, States, and Zones

package/dist/developer/core-concepts/media.md

@@ -54,6 +54,31 @@ curl -X POST 'https://api.mystore.com/api/v3/admin/products/prod_86Rf07xd4z/medi
 ```
 
 
+#### Creating media from a remote URL
+
+When the image already lives at a public URL, pass `url` instead of a `signed_id` — Spree fetches the remote file and stores it as product media, so you skip the direct-upload step entirely.
+
+
+```typescript Admin SDK
+await client.products.media.create('prod_86Rf07xd4z', {
+  url: 'https://cdn.example.com/images/tote-front.jpg',
+  position: 1,
+})
+```
+
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/products/prod_86Rf07xd4z/media' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "url": "https://cdn.example.com/images/tote-front.jpg",
+    "position": 1
+  }'
+```
+
+
+> **NOTE:** The fetch runs in the background, so this request returns `202 Accepted` with no body — the media appears in the gallery once the download and processing finish. Re-fetch the product's media to know when it's ready.
+
 #### Sharing a single image across variants
 
 Pass a `variant_ids` array on the same media endpoint to link/unlink variants. The server replaces the asset's link set on every call — empty array clears all links, omitting the field leaves them untouched.
@@ -99,10 +124,10 @@ All variants are cropped to fill the exact dimensions and converted to WebP form
 
 ### Thumbnails (Always Available)
 
-Every product response includes a `thumbnail_url` field — ready to use without any expands. Similarly, each variant includes a `thumbnail` URL and a `media_count` counter.
+Every product response includes a `thumbnail_url` field — ready to use without any expands. Similarly, each variant includes a `thumbnail_url` and a `media_count` counter.
 
 
-```typescript SDK
+```typescript Store SDK
 // List products — thumbnail_url is always included
 const { data: products } = await client.products.list({ limit: 12 })
 
@@ -111,6 +136,10 @@ products.forEach(product => {
 })
 ```
 
+```typescript Admin SDK
+const { data: products } = await adminClient.products.list({ limit: 12 })
+```
+
 ```bash cURL
 # thumbnail_url is always in the response — no ?expand needed
 curl 'https://api.mystore.com/api/v3/store/products?limit=12' \
@@ -122,10 +151,10 @@ curl 'https://api.mystore.com/api/v3/store/products?limit=12' \
 
 ### Full Media (On Demand)
 
-On the product detail page, expand `media` and `variants` to get the full set of media with all named variant URLs:
+On the product detail page, [expand media and variants](../../api-reference/store-api/relations.md) to get the full set of media with all named variant URLs:
 
 
-```typescript SDK
+```typescript Store SDK
 const product = await client.products.get('spree-tote', {
   expand: ['media', 'variants'],
 })
@@ -135,12 +164,18 @@ product.media // [{ id, media_type, product_id, variant_ids, original_url, mini_
 
 // Each variant has its own thumbnail and media_count
 product.variants?.forEach(variant => {
-  variant.thumbnail    // "https://cdn.../tote-red.webp" — always available
+  variant.thumbnail_url // "https://cdn.../tote-red.webp" — present in the response, null when the variant has no media
   variant.media_count  // 3 — quick check without loading media
   variant.media        // full media array (only with ?expand=media)
 })
 ```
 
+```typescript Admin SDK
+const product = await adminClient.products.get('prod_86Rf07xd4z', {
+  expand: ['media', 'variants'],
+})
+```
+
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=media,variants' \
   -H 'X-Spree-API-Key: pk_xxx'
@@ -174,7 +209,7 @@ curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=media,vari
 | Field | Available on | Always Returned | Description |
 |-------|-------------|:---:|-------------|
 | `thumbnail_url` | Product | Yes | URL to the product's first media |
-| `thumbnail` | Variant | Yes | URL to the variant's first media |
+| `thumbnail_url` | Variant | Yes | URL to the variant's first media |
 | `media_count` | Variant | Yes | Number of media items (counter cache) |
 | `media` | Product, Variant | No | Full media array (requires `?expand=media`) |
 
@@ -224,4 +259,6 @@ Spree supports two storage service types:
 ## Related Documentation
 
 - [Products](products.md) — Product catalog and media
+- [Products & Categories](../sdk/store/products.md) — Store SDK guide for fetching products, `thumbnail_url`, and expanded media
+- [Admin SDK](../sdk/admin/resources.md) — Admin SDK resource methods, including the nested `products.media` create/update calls
 - [Deployment — Assets](../deployment/assets.md) — Storage and CDN configuration

package/dist/developer/core-concepts/metafields.md

@@ -3,9 +3,12 @@ title: Metafields
 description: Add custom structured data to products, orders, and other resources with type-safe metafields
 ---
 
+import { Since } from '/snippets/since.mdx';
+
+
 ## Overview
 
-Metafields provide a flexible, type-safe system for adding custom structured data to Spree resources. Unlike [metadata](../customization/metadata.md) which is simple JSON storage, metafields are schema-defined with strong typing, validation, and visibility controls.
+Metafields provide a flexible, type-safe system for adding custom structured attributes to Spree models. Unlike [metadata](../customization/metadata.md) which is simple JSON storage, metafields are schema-defined with strong typing, validation, and visibility controls.
 
 Use metafields for:
 
@@ -14,8 +17,6 @@ Use metafields for:
 - Integration data from external systems
 - Order-specific custom attributes
 
-> **NOTE:** Metafields are available from Spree 5.2 onwards.
-
 ## Architecture
 
 ```mermaid
@@ -75,12 +76,11 @@ flowchart LR
 
 ## Visibility Control
 
-Metafields support three visibility levels via the `display_on` attribute:
+Metafields support two visibility levels via the `display_on` attribute:
 
 | Visibility | Store API | Admin API | Use Case |
 |------------|:---------:|:---------:|----------|
 | `both` | Yes | Yes | Public product specifications |
-| `front_end` | Yes | No | Customer-facing data |
 | `back_end` | No | Yes | Internal notes, integration IDs |
 
 ## Supported Resources
@@ -104,10 +104,12 @@ Namespaces organize metafields into logical groups and prevent key conflicts:
 
 ## Store API
 
-Metafields with `display_on` set to `both` or `front_end` are included in Store API responses when you request the `custom_fields` expand:
+Metafields with `display_on` set to `both` are included in Store API responses when you [request the `custom_fields` expand](../../api-reference/store-api/relations.md):
+
+> **INFO:** Metafields in API are called Custom Fields as we plan to rename Metafields to Custom Fields completely in Spree 6.0.
 
 
-```typescript SDK
+```typescript Store SDK
 const product = await client.products.get('spree-tote', {
   expand: ['custom_fields'],
 })
@@ -115,8 +117,14 @@ const product = await client.products.get('spree-tote', {
 product.custom_fields?.forEach(field => {
   console.log(field.key)   // "properties.manufacturer"
   console.log(field.label) // "Manufacturer"
-  console.log(field.value) // "Wilson"
-  console.log(field.type)  // "short_text"
+  console.log(field.value)      // "Wilson"
+  console.log(field.field_type) // "short_text"
+})
+```
+
+```typescript Admin SDK
+const product = await adminClient.products.get('prod_86Rf07xd4z', {
+  expand: ['custom_fields'],
 })
 ```
 
@@ -137,14 +145,14 @@ curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=custom_fie
       "id": "cf_k5nR8xLq",
       "label": "Manufacturer",
       "key": "properties.manufacturer",
-      "type": "short_text",
+      "field_type": "short_text",
       "value": "Wilson"
     },
     {
       "id": "cf_m3Rp9wXz",
       "label": "Material",
       "key": "properties.material",
-      "type": "short_text",
+      "field_type": "short_text",
       "value": "100% Cotton"
     }
   ]
@@ -153,16 +161,70 @@ curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=custom_fie
 
 > **NOTE:** The `display_on` attribute is intentionally excluded from Store API responses for security.
 
-## Admin Panel Management
+## Admin Management
 
 ### Managing Definitions
 
 Navigate to **Settings → Metafield Definitions** in the Admin Panel to create and manage metafield definitions. Select the resource type, enter namespace and key, choose the data type, and set visibility.
 
+Definitions are also [managed via the Admin API](../../api-reference/admin-api/endpoints.md). `storefront_visible: true` is equivalent to `display_on: both` — it exposes the field to the Store API:
+
+
+```typescript Admin SDK
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+  baseUrl: 'https://store.example.com',
+  secretKey: 'sk_xxx',
+})
+
+const definition = await client.customFieldDefinitions.create({
+  resource_type: 'Spree::Product',
+  namespace: 'properties',
+  key: 'manufacturer',
+  label: 'Manufacturer',
+  field_type: 'short_text',
+  storefront_visible: true,
+})
+
+await client.customFieldDefinitions.update(definition.id, { storefront_visible: false })
+await client.customFieldDefinitions.delete(definition.id)
+```
+
+```bash CLI
+spree api post /custom_field_definitions -d '{
+  "resource_type": "Spree::Product",
+  "namespace": "properties",
+  "key": "manufacturer",
+  "label": "Manufacturer",
+  "field_type": "short_text",
+  "storefront_visible": true
+}'
+```
+
+
 ### Managing Values
 
 When editing a resource (e.g., a product), metafields appear in a dedicated section. The admin panel automatically builds forms for all defined metafields.
 
+To set a value programmatically, use the resource's nested `customFields` accessor (parent ID first):
+
+
+```typescript Admin SDK
+await client.products.customFields.create('prod_xxx', {
+  custom_field_definition_id: 'cfdef_xxx',
+  value: 'Wilson',
+})
+```
+
+```bash CLI
+spree api post /products/prod_xxx/custom_fields -d '{
+  "custom_field_definition_id": "cfdef_xxx",
+  "value": "Wilson"
+}'
+```
+
+
 ## Metafields vs Metadata
 
 Spree has two permanent, complementary systems for custom data — **metadata for machines, metafields for humans**. They serve different purposes and are not interchangeable. Neither is going away.
@@ -182,10 +244,11 @@ Spree has two permanent, complementary systems for custom data — **metadata fo
 
 **Use [Metadata](../customization/metadata.md)** for external system IDs, tracking attribution, syncing with integrations, or simple write-and-forget data that only backend systems need to read.
 
-> **WARNING:** Product Properties are deprecated and will be removed in Spree 6.0. For new projects, always use Metafields. For existing projects, plan to migrate using the [migration guide](../upgrades/5.1-to-5.2.md#3-migrate-to-metafields-or-keep-using-properties).
+> **WARNING:** Product Properties are deprecated and will be removed in Spree 6.0. For new projects, always use Metafields. For existing projects, plan to migrate using the [migration guide](../upgrades/5.1-to-5.2.md#migrate-to-metafields-or-keep-using-product-properties).
 
 ## Related Documentation
 
 - [Metadata](../customization/metadata.md) — Simple key-value metadata
 - [Products](products.md) — Product catalog
 - [Events](events.md) — Subscribe to metafield events
+- [Admin SDK](../sdk/admin/resources.md) — Manage definitions and values from TypeScript

package/dist/developer/core-concepts/orders.md

@@ -62,28 +62,27 @@ The API returns these key fields on every order:
 | Attribute | Description |
 |-----------|-------------|
 | `number` | Unique order number (e.g., `R123456789`), shown to customers |
-| `state` | Current checkout state (`cart`, `address`, `delivery`, `payment`, `confirm`, `complete`) |
 | `email` | Customer's email address |
 | `currency` | Order currency (e.g., `USD`) |
-| `item_count` | Total number of items |
+| `total_quantity` | Total number of items |
 | `item_total` / `display_item_total` | Sum of line item prices |
 | `delivery_total` / `display_delivery_total` | Delivery cost |
 | `tax_total` / `display_tax_total` | Total tax |
-| `promo_total` / `display_promo_total` | Total discount from promotions |
+| `discount_total` / `display_discount_total` | Total discount from promotions |
 | `adjustment_total` / `display_adjustment_total` | Sum of all adjustments (tax + delivery + promos) |
 | `total` / `display_total` | Final order total |
-| `payment_state` | Payment status (`balance_due`, `paid`, `credit_owed`, `failed`, `void`) |
+| `payment_status` | Payment status (`balance_due`, `paid`, `credit_owed`, `failed`, `void`) |
 | `fulfillment_status` | Fulfillment status (`pending`, `ready`, `partial`, `shipped`, `backorder`) |
 | `completed_at` | Timestamp when the order was placed |
 
-The `display_*` fields return formatted strings with currency symbols (e.g., `"$15.99"`).
+The [`display_*` fields return formatted strings with currency symbols](../../api-reference/store-api/monetary-amounts.md) (e.g., `"$15.99"`).
 
 ## Cart
 
-A cart is simply an order in the `cart` state. Guest carts are identified by a cart token; authenticated users' carts are linked to their account.
+A cart is simply an order in the `cart` state. Guest carts are [identified by a cart token; authenticated users' carts are linked to their account](../../api-reference/store-api/authentication.md).
 
 
-```typescript SDK
+```typescript Store SDK
 // Create a cart
 const cart = await client.carts.create()
 // cart.token => "abc123" (save this for guest checkout)
@@ -171,21 +170,21 @@ Order is placed. `completed_at` is set and fulfillment begins.
 If the order doesn't meet the requirements for the next state (e.g., missing address), the API returns an error.
 
 
-```typescript SDK
+```typescript Store SDK
 // Set addresses
 await client.carts.update(cartId, {
   email: 'john@example.com',
-  ship_address: {
-    firstname: 'John', lastname: 'Doe',
+  shipping_address: {
+    first_name: 'John', last_name: 'Doe',
     address1: '123 Main St', city: 'Los Angeles',
-    country_iso: 'US', state_abbr: 'CA', zipcode: '90001',
+    country_iso: 'US', state_abbr: 'CA', postal_code: '90001',
     phone: '555-0100',
   },
 })
 
 // Get fulfillments and select a delivery rate
 // (the Store API/SDK exposes shipments as `fulfillments`)
-const cart = await client.carts.get(cartId, { expand: ['fulfillments'] })
+const cart = await client.carts.get(cartId)
 await client.carts.fulfillments.update(cartId, cart.fulfillments[0].id, {
   selected_delivery_rate_id: 'rate_xxx',
 })
@@ -211,10 +210,10 @@ curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \
   -H 'Content-Type: application/json' \
   -d '{
     "email": "john@example.com",
-    "ship_address": {
-      "firstname": "John", "lastname": "Doe",
+    "shipping_address": {
+      "first_name": "John", "last_name": "Doe",
       "address1": "123 Main St", "city": "Los Angeles",
-      "country_iso": "US", "state_abbr": "CA", "zipcode": "90001",
+      "country_iso": "US", "state_abbr": "CA", "postal_code": "90001",
       "phone": "555-0100"
     }
   }'
@@ -238,7 +237,7 @@ curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/complete' \
 Apply or remove promotional coupon codes during checkout:
 
 
-```typescript SDK
+```typescript Store SDK
 // Apply a discount code
 await client.carts.discountCodes.apply(cartId, 'SAVE20')
 
@@ -266,7 +265,7 @@ curl -X DELETE 'https://api.mystore.com/api/v3/store/carts/cart_xxx/discount_cod
 Authenticated customers can view their past orders:
 
 
-```typescript SDK
+```typescript Store SDK
 // List past orders
 const { data: orders } = await client.customer.orders.list()
 
@@ -276,6 +275,10 @@ const order = await client.orders.get('or_xxx', {
 })
 ```
 
+```typescript Admin SDK
+const order = await adminClient.orders.get('or_xxx')
+```
+
 ```bash cURL
 # List past orders
 curl 'https://api.mystore.com/api/v3/store/customer/orders' \
@@ -287,6 +290,80 @@ curl 'https://api.mystore.com/api/v3/store/orders/or_xxx?expand=items,fulfillmen
 ```
 
 
+## Managing Orders
+
+Everything above is the **Store API** — the customer's own cart and orders. Back-office order management (listing every order, creating phone/manual orders, capturing payments, cancelling) uses the [Admin API](../../api-reference/admin-api/introduction.md).
+
+### Listing and creating orders
+
+List orders with [Ransack filters and pagination](../../api-reference/admin-api/querying.md) (`state_eq`, `limit`, sorting). A draft order is created in one call; pass line items as `items` (each `{ variant_id, quantity }`):
+
+
+```typescript Admin SDK
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+  baseUrl: 'https://store.example.com',
+  secretKey: 'sk_xxx',
+})
+
+// List orders (Ransack filters)
+const { data: orders } = await client.orders.list({ state_eq: 'complete', limit: 25 })
+
+// Create a draft order on a customer's behalf
+const order = await client.orders.create({
+  email: 'buyer@example.com',
+  items: [{ variant_id: 'variant_xxx', quantity: 2 }],
+  currency: 'USD',
+})
+```
+
+```bash CLI
+spree api get /orders -q state_eq=complete --limit 25
+spree api post /orders -d '{
+  "email": "buyer@example.com",
+  "items": [{ "variant_id": "variant_xxx", "quantity": 2 }]
+}'
+```
+
+
+### Order state actions
+
+Orders move through their [state machine](#checkout-flow) via dedicated actions rather than raw `state` writes:
+
+
+```typescript Admin SDK
+await client.orders.complete('or_xxx')               // finalize a draft
+await client.orders.cancel('or_xxx', { reason: 'customer' })
+await client.orders.approve('or_xxx')
+await client.orders.resume('or_xxx')
+await client.orders.resendConfirmation('or_xxx')
+```
+
+```bash CLI
+spree api patch /orders/or_xxx/complete
+spree api patch /orders/or_xxx/cancel -d '{"reason": "customer"}'
+spree api patch /orders/or_xxx/approve
+```
+
+
+### Payments and refunds
+
+Capture or void an authorized payment, and issue refunds, through the nested order resources:
+
+
+```typescript Admin SDK
+await client.orders.payments.capture('or_xxx', 'pay_xxx')
+await client.orders.payments.void('or_xxx', 'pay_xxx')
+await client.orders.refunds.create('or_xxx', { payment_id: 'pay_xxx', amount: 19.99 })
+```
+
+```bash CLI
+spree api patch /orders/or_xxx/payments/pay_xxx/capture
+spree api post /orders/or_xxx/refunds -d '{"payment_id": "pay_xxx", "amount": 19.99}'
+```
+
+
 ## Line Items
 
 Line items represent individual products in an order. Each line item links to a [Variant](products.md#variants) and tracks the quantity and price at the time of purchase.
@@ -323,6 +400,7 @@ For more details, see [Shipments](shipments.md) and [Payments](payments.md).
 
 ## Related Documentation
 
+- [Cart, Checkout & Orders](../sdk/store/cart-checkout.md) — Store SDK guide for carts, checkout, coupon codes, and order history
 - [Payments](payments.md) — Payment processing and payment sessions
 - [Shipments](shipments.md) — Fulfillment and shipping rates
 - [Addresses](addresses.md) — Billing and shipping addresses