The Ajax API provides a suite of lightweight REST API endpoints for development of Shopify themes. It is an unauthenticated API used to add products to the cart, display product recommendations, and suggest products during search within Shopify-hosted storefronts.
openapi: 3.1.0
info:
title: Shopify Ajax API
description: >-
The Shopify Ajax API provides lightweight REST endpoints for Shopify theme
development. It is an unauthenticated API used to manage the shopping cart,
retrieve product data, get product recommendations, and provide predictive
search within Shopify-hosted storefronts. All responses return JSON.
version: '2025-01'
contact:
name: Shopify
url: https://shopify.dev/docs/api/ajax
email: [email protected]
license:
name: Shopify API Terms
url: https://www.shopify.com/legal/api-terms
x-date: '2026-03-04'
servers:
- url: https://{store}.myshopify.com
description: Shopify storefront
variables:
store:
default: my-store
description: The Shopify store subdomain
tags:
- name: Cart
description: Manage the shopping cart
- name: Predictive Search
description: Search suggestions for products, collections, pages, and articles
- name: Product Recommendations
description: Get product recommendations
- name: Products
description: Retrieve product information
paths:
/cart.js:
get:
operationId: getCart
summary: Shopify Retrieve the current cart
description: >-
Retrieves the current cart contents as JSON, including all line items,
totals, attributes, notes, and currency information.
tags:
- Cart
responses:
'200':
description: The current cart
content:
application/json:
schema:
$ref: '#/components/schemas/Cart'
/cart/add.js:
post:
operationId: addToCart
summary: Shopify Add items to the cart
description: >-
Adds one or more product variants to the cart. Each item requires a
variant ID and quantity. Optional properties and selling plans can
be attached to line items.
tags:
- Cart
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- items
properties:
items:
type: array
description: Items to add to the cart
items:
type: object
required:
- id
- quantity
properties:
id:
type: integer
description: The variant ID
quantity:
type: integer
description: The quantity to add
properties:
type: object
description: Custom line item properties
additionalProperties:
type: string
selling_plan:
type: integer
description: The selling plan ID for subscriptions
sections:
type: string
description: Comma-separated section IDs to render in the response
responses:
'200':
description: The items added to the cart
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/CartItem'
'422':
description: Invalid variant or quantity
/cart/update.js:
post:
operationId: updateCart
summary: Shopify Update the cart
description: >-
Updates cart line item quantities, cart note, cart attributes, or
applies a discount code. Quantities can be updated using a map of
variant ID to quantity or line number to quantity.
tags:
- Cart
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
updates:
type: object
description: Map of variant ID or line key to new quantity
additionalProperties:
type: integer
note:
type: string
description: A note for the cart
attributes:
type: object
description: Custom cart attributes
additionalProperties:
type: string
discount:
type: string
description: A discount code to apply
responses:
'200':
description: The updated cart
content:
application/json:
schema:
$ref: '#/components/schemas/Cart'
/cart/change.js:
post:
operationId: changeCartItem
summary: Shopify Change a cart line item
description: >-
Changes the quantity, properties, or selling plan of a single cart
line item. Identify the item by line number (1-indexed) or by its key.
tags:
- Cart
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
line:
type: integer
description: The 1-indexed line number
id:
type: string
description: The line item key (variant_id:hash)
quantity:
type: integer
description: The new quantity
properties:
type: object
description: Updated line item properties
additionalProperties:
type: string
selling_plan:
type: integer
description: A selling plan ID
responses:
'200':
description: The updated cart
content:
application/json:
schema:
$ref: '#/components/schemas/Cart'
/cart/clear.js:
post:
operationId: clearCart
summary: Shopify Clear all items from the cart
description: >-
Removes all line items from the cart, returning an empty cart object.
tags:
- Cart
responses:
'200':
description: The empty cart
content:
application/json:
schema:
$ref: '#/components/schemas/Cart'
/cart/shipping_rates.json:
get:
operationId: getCartShippingRates
summary: Shopify Get estimated shipping rates
description: >-
Retrieves estimated shipping rates for the current cart based on the
provided shipping address. May be throttled for repeated requests.
tags:
- Cart
parameters:
- name: shipping_address[zip]
in: query
required: true
description: Postal or zip code
schema:
type: string
- name: shipping_address[country]
in: query
required: true
description: Country name or ISO code
schema:
type: string
- name: shipping_address[province]
in: query
description: Province, state, or region
schema:
type: string
responses:
'200':
description: Estimated shipping rates
content:
application/json:
schema:
type: object
properties:
shipping_rates:
type: array
items:
$ref: '#/components/schemas/ShippingRate'
/products/{handle}.js:
get:
operationId: getProductByHandle
summary: Shopify Retrieve a product by its handle
description: >-
Retrieves product information in JSON format using the product handle.
Returns product metadata, pricing, variants (up to 250), images,
options, and availability. Monetary values reflect the customer
presentment currency.
tags:
- Products
parameters:
- name: handle
in: path
required: true
description: The URL-friendly product handle
schema:
type: string
responses:
'200':
description: The product data
content:
application/json:
schema:
$ref: '#/components/schemas/StorefrontProduct'
'404':
description: Product not found
/recommendations/products.json:
get:
operationId: getProductRecommendations
summary: Shopify Get product recommendations
description: >-
Retrieves product recommendations for a given product. Returns related
or complementary products based on purchase history, product
descriptions, and related collections.
tags:
- Product Recommendations
parameters:
- name: product_id
in: query
required: true
description: The product ID to get recommendations for
schema:
type: integer
- name: limit
in: query
description: Number of recommendations (1-10, default 10)
schema:
type: integer
minimum: 1
maximum: 10
default: 10
- name: intent
in: query
description: The recommendation intent
schema:
type: string
enum:
- related
- complementary
default: related
responses:
'200':
description: Product recommendations
content:
application/json:
schema:
type: object
properties:
intent:
type: string
products:
type: array
items:
$ref: '#/components/schemas/StorefrontProduct'
'404':
description: Product not found
'422':
description: Invalid parameter
/search/suggest.json:
get:
operationId: getPredictiveSearchResults
summary: Shopify Get predictive search results
description: >-
Retrieves predictive search results for a query string. Returns
matching products, collections, pages, articles, and query
suggestions. Used for search-as-you-type experiences.
tags:
- Predictive Search
parameters:
- name: q
in: query
required: true
description: The search query
schema:
type: string
- name: resources[type]
in: query
description: >-
Comma-separated resource types to search
(product, page, article, collection, query)
schema:
type: string
default: query,product,collection,page
- name: resources[limit]
in: query
description: Number of results per type (1-10, default 10)
schema:
type: integer
minimum: 1
maximum: 10
default: 10
- name: resources[limit_scope]
in: query
description: >-
How the limit is distributed: all (shared across types)
or each (per type)
schema:
type: string
enum:
- all
- each
default: all
- name: resources[options][unavailable_products]
in: query
description: How to handle unavailable products
schema:
type: string
enum:
- show
- hide
- last
default: last
- name: resources[options][fields]
in: query
description: >-
Comma-separated fields to search within
(title, product_type, vendor, tag, variants.title,
variants.sku, body)
schema:
type: string
responses:
'200':
description: Predictive search results
content:
application/json:
schema:
type: object
properties:
resources:
type: object
properties:
results:
type: object
properties:
queries:
type: array
items:
type: object
properties:
text:
type: string
styled_text:
type: string
products:
type: array
items:
$ref: '#/components/schemas/StorefrontProduct'
collections:
type: array
items:
type: object
properties:
id:
type: integer
title:
type: string
handle:
type: string
url:
type: string
published_at:
type: string
format: date-time
body:
type: string
image:
type: object
properties:
url:
type: string
format: uri
alt:
type: string
width:
type: integer
height:
type: integer
pages:
type: array
items:
type: object
properties:
id:
type: integer
title:
type: string
handle:
type: string
url:
type: string
body:
type: string
articles:
type: array
items:
type: object
properties:
id:
type: integer
title:
type: string
handle:
type: string
url:
type: string
body:
type: string
published_at:
type: string
format: date-time
image:
type: object
properties:
url:
type: string
format: uri
alt:
type: string
width:
type: integer
height:
type: integer
'422':
description: Invalid parameter
'429':
description: Rate limited
components:
schemas:
Cart:
type: object
description: The shopping cart
properties:
token:
type: string
description: Unique cart token
note:
type:
- string
- 'null'
description: Cart note
attributes:
type: object
description: Custom cart attributes
additionalProperties:
type: string
total_price:
type: integer
description: Total price in cents
total_weight:
type: number
description: Total weight in grams
item_count:
type: integer
description: Total number of items
items:
type: array
description: Cart line items
items:
$ref: '#/components/schemas/CartItem'
requires_shipping:
type: boolean
currency:
type: string
description: Three-letter ISO 4217 currency code
total_discount:
type: integer
description: Total discount in cents
cart_level_discount_applications:
type: array
items:
type: object
properties:
type:
type: string
title:
type: string
total_allocated_amount:
type: integer
value:
type: string
value_type:
type: string
CartItem:
type: object
description: A line item in the cart
properties:
id:
type: integer
description: The variant ID
quantity:
type: integer
title:
type: string
description: Product title
price:
type: integer
description: Price in cents
original_price:
type: integer
description: Original price before discounts in cents
discounted_price:
type: integer
description: Discounted price in cents
line_price:
type: integer
description: Total line price in cents
original_line_price:
type: integer
description: Original total before discounts in cents
total_discount:
type: integer
description: Total line discount in cents
sku:
type:
- string
- 'null'
grams:
type: integer
vendor:
type: string
taxable:
type: boolean
product_id:
type: integer
product_has_only_default_variant:
type: boolean
gift_card:
type: boolean
url:
type: string
description: URL to the product page
featured_image:
type: object
properties:
url:
type: string
format: uri
alt:
type: string
aspect_ratio:
type: number
image:
type: string
format: uri
handle:
type: string
requires_shipping:
type: boolean
product_type:
type: string
product_title:
type: string
variant_title:
type:
- string
- 'null'
variant_options:
type: array
items:
type: string
properties:
type: object
additionalProperties:
type: string
key:
type: string
description: Unique line item key
line_level_discount_allocations:
type: array
items:
type: object
properties:
amount:
type: integer
discount_application:
type: object
properties:
type:
type: string
title:
type: string
value:
type: string
value_type:
type: string
line_level_total_discount:
type: integer
StorefrontProduct:
type: object
description: A product as returned by the storefront Ajax API
properties:
id:
type: integer
title:
type: string
handle:
type: string
description:
type: string
published_at:
type: string
format: date-time
created_at:
type: string
format: date-time
vendor:
type: string
type:
type: string
tags:
type: array
items:
type: string
price:
type: integer
description: Price in cents
price_min:
type: integer
price_max:
type: integer
available:
type: boolean
price_varies:
type: boolean
compare_at_price:
type:
- integer
- 'null'
compare_at_price_min:
type: integer
compare_at_price_max:
type: integer
compare_at_price_varies:
type: boolean
variants:
type: array
items:
type: object
properties:
id:
type: integer
title:
type: string
option1:
type:
- string
- 'null'
option2:
type:
- string
- 'null'
option3:
type:
- string
- 'null'
sku:
type:
- string
- 'null'
requires_shipping:
type: boolean
taxable:
type: boolean
featured_image:
type:
- object
- 'null'
available:
type: boolean
name:
type: string
public_title:
type:
- string
- 'null'
price:
type: integer
weight:
type: integer
compare_at_price:
type:
- integer
- 'null'
barcode:
type:
- string
- 'null'
images:
type: array
items:
type: string
format: uri
featured_image:
type: string
format: uri
options:
type: array
items:
type: object
properties:
name:
type: string
position:
type: integer
values:
type: array
items:
type: string
url:
type: string
media:
type: array
items:
type: object
properties:
alt:
type:
- string
- 'null'
id:
type: integer
position:
type: integer
media_type:
type: string
src:
type: string
format: uri
width:
type: integer
height:
type: integer
ShippingRate:
type: object
description: An estimated shipping rate
properties:
name:
type: string
description: Rate name
price:
type: string
description: Rate price
delivery_days:
type: array
items:
type: integer
source:
type: string
description: The rate provider