Skip to main content

The REST Admin API is a legacy API as of October 1, 2024. Starting April 1, 2025, all new public apps must be built exclusively with the GraphQL Admin API. For details and migration steps, visit our migration guide.

ProductListing

Multiple access scopes needed — refer to each endpoint for access scope requirements.

A ProductListing resource represents a Product which is available to your sales channel. Merchants can make products available to your sales channel directly from their Shopify admin.

You can use this resource to retrieve products that a merchant has published and display them to customers in your marketplace for sale.

A ProductListing resource itself is unable to have its attributes modified directly. The attributes of a ProductListing are inherited from the Product resource to which it is associated. Therefore, all attributes of a ProductListing should be considered read-only.

A product can have one of the following statuses: active, draft, or archived. Draft and archived are considered non-active statuses. If you create a listing for a non-active product, then the product won't be published immediately. You must change the product status to active to make the product available on a sales channel.

If the product is sold exclusively on subscription, then you can create a listing for the product only on an online store.

Was this section helpful?
#

Endpoints

Anchor to

The ProductListing resource

Anchor to

Properties

product_id
read-only
->
id

The unique identifer of the product this listing is for. The primary key for this resource.

body_html
read-only
->
descriptionHtml

The description of the product, complete with HTML formatting.

created_at
read-only
->
createdAt

The date and time when the product was created. The API returns this in ISO 8601.

handle
read-only
->
handle

A human-friendly unique string for the Product automatically generated from its title.

images
read-only
->
media

A list of image objects, each one representing an image associated with the product.

options
read-only
->
options

Custom product property names like "Size", "Color", and "Material".

product_type
read-only
->
productType

A categorization that a product can be tagged with, commonly used for filtering.

published_at
read-only
->
publishedAt

The date and time when the product was published. The API returns this in ISO 8601.

tags
read-only
->
tags

A categorization that a product can be tagged with, commonly used for filtering.

title
read-only
->
title

The name of the product.

updated_at
read-only
->
updatedAt

The date and time when the product was last modified. The API returns this in ISO 8601.

variants
read-only
->
variants

A list of variant objects, each one representing a slightly different version of the product. For example, if a product comes in different sizes and colors, each size and color permutation (such as "small black", "medium black", "large blue"), would be a variant.

To reorder variants, update the product with the variants in the desired order. The position attribute on the variant will be ignored.

Show variants properties
  • barcode: The barcode, UPC or ISBN number for the product.
  • compare_at_price: The competitor's price for the same item.
  • created_at: The date and time when the product variant was created. The API returns this in ISO 8601.
  • fulfillment_service: Service which is handling fulfillment. Valid values are: manual, gift_card, or the handle of a FulfillmentService.
  • grams: The weight of the product variant in grams.
  • weight: The weight of the product variant in the unit system specified with weight_unit.
  • weight_unit: The unit system that the product variant's weight is measure in. The weight_unit can be either "g", "kg, "oz", or "lb".
  • id: The unique numeric identifier for the product variant.
  • inventory_management: Specifies whether or not Shopify tracks the number of items in stock for this product variant.
  • inventory_policy: Specifies whether or not customers are allowed to place an order for a product variant when it's out of stock.
  • inventory_quantity: The number of items available to the product listing for the product variant.
  • metafield: Attaches additional information to a shop's resources.
  • option: Custom properties that a shop owner can use to define product variants. Multiple options can exist. Options are represented as: option1, option2, option3, etc.
  • position: The order of the product variant in the list of product variants. 1 is the first position. To reorder variants, update the product with the variants in the desired order. The position attribute on the variant will be ignored.
  • price: The price of the product variant.
  • product_id: The unique numeric identifier for the product.
  • requires_shipping: Specifies whether or not a customer needs to provide a shipping address when placing an order for this product variant.
  • sku: A unique identifier for the product in the shop.
  • taxable: Specifies whether or not a tax is charged when the product variant is sold.
  • title: The title of the product variant.
  • updated_at: The date and time when the product variant was last modified. The API returns this in ISO 8601.
vendor
read-only
->
vendor

The name of the vendor of the product.

Was this section helpful?
{}

The ProductListing resource

{
"product_id": {
"product_id": 1053727709
},
"body_html": "It's the small iPod with a big idea: Video.",
"created_at": "2012-02-15T15:12:21-05:00",
"handle": "ipod-nano",
"images": [
{
"src": "http://example.com/burton.jpg"
}
],
"options": [
{
"name": "Title"
}
],
"product_type": "Cult Products",
"published_at": "2007-12-31T19:00:00-05:00",
"tags": "Emotive, Flash Memory, MP3, Music",
"title": "IPod Nano - 8GB",
"updated_at": "2012-08-24T14:01:47-04:00",
"variants": {
"barcode": "1234_pink",
"compare_at_price": null,
"created_at": "2012-08-24T14:01:47-04:00",
"fulfillment_service": "manual",
"grams": 567,
"weight": 0.2,
"weight_unit": "kg",
"id": 808950810,
"inventory_management": "shopify",
"inventory_policy": "continue",
"inventory_quantity": 10,
"option1": "Pink",
"position": 1,
"price": 199.99,
"product_id": 632910392,
"requires_shipping": true,
"sku": "IPOD2008PINK",
"taxable": true,
"title": "Pink",
"updated_at": "2012-08-24T14:01:47-04:00"
},
"vendor": "Apple"
}

Anchor to GET request, Retrieve product listings that are published to your app
get
Retrieve product listings that are published to your app

products
Requires product_listings access scope.

Retrieve product listings that are published to your app. Note: This endpoint implements pagination by using links that are provided in the response header. To learn more, refer to Make paginated requests to the REST Admin API.

Anchor to Parameters of Retrieve product listings that are published to your appParameters

api_version
string
required
collection_id

Filter by products belonging to a particular collection

handle

Filter by product handle

limit
≤ 1000
default 50

Amount of results

product_ids

A comma-separated list of product ids

updated_at_min

Filter by product listings last updated after a certain date and time (formatted in ISO 8601)

Was this section helpful?

Anchor to get-product-listings-examplesExamples

Retrieve product listings that are published to your app

Was this section helpful?
get

/admin/api/2025-07/product_listings.json

curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-07/product_listings.json" \
-H "X-Shopify-Access-Token: {access_token}"

{}

Response

JSON
HTTP/1.1 200 OK
{
"product_listings": [
{
"product_id": 632910392,
"created_at": "2025-04-01T15:44:57-04:00",
"updated_at": "2025-04-01T15:44:57-04:00",
"body_html": "<p>It's the small iPod with one very big idea: Video. Now the world's most popular music player, available in 4GB and 8GB models, lets you enjoy TV shows, movies, video podcasts, and more. The larger, brighter display means amazing picture quality. In six eye-catching colors, iPod nano is stunning all around. And with models starting at just $149, little speaks volumes.</p>",
"handle": "ipod-nano",
"product_type": "Cult Products",
"title": "IPod Nano - 8GB",
"vendor": "Apple",
"available": true,
"tags": "Emotive, Flash Memory, MP3, Music",
"published_at": "2017-08-31T20:00:00-04:00",
"variants": [
{
"id": 808950810,
"title": "Pink",
"option_values": [
{
"option_id": 594680422,
"name": "Color",
"value": "Pink"
}
],
"price": "199.00",
"formatted_price": "$199.00",
"compare_at_price": null,
"grams": 567,
"requires_shipping": true,
"sku": "IPOD2008PINK",
"barcode": "1234_pink",
"taxable": true,
"position": 1,
"available": true,

Anchor to GET request, Retrieve a specific product listing that is published to your app
get
Retrieve a specific product listing that is published to your app

product
Requires product_listings access scope.

Retrieve a specific product listing that is published to your app

Anchor to Parameters of Retrieve a specific product listing that is published to your appParameters

api_version
string
required
product_listing_id
string
required
Was this section helpful?

Anchor to get-product-listings-product-listing-id-examplesExamples

Retrieve a specific product listing that is published to your app

Path parameters
product_listing_id=921728736
string
required
Was this section helpful?
get

/admin/api/2025-07/product_listings/921728736.json

curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-07/product_listings/921728736.json" \
-H "X-Shopify-Access-Token: {access_token}"

{}

Response

JSON
HTTP/1.1 200 OK
{
"product_listing": {
"product_id": 921728736,
"created_at": "2025-04-01T15:44:57-04:00",
"updated_at": "2025-04-01T15:44:57-04:00",
"body_html": "<p>The iPod Touch has the iPhone's multi-touch interface, with a physical home button off the touch screen. The home screen has a list of buttons for the available applications.</p>",
"handle": "ipod-touch",
"product_type": "Cult Products",
"title": "IPod Touch 8GB",
"vendor": "Apple",
"available": true,
"tags": "",
"published_at": "2017-08-31T20:00:00-04:00",
"variants": [
{
"id": 447654529,
"title": "Black",
"option_values": [
{
"option_id": 891236591,
"name": "Title",
"value": "Black"
}
],
"price": "199.00",
"formatted_price": "$199.00",
"compare_at_price": null,
"grams": 567,
"requires_shipping": true,
"sku": "IPOD2009BLACK",
"barcode": "1234_black",
"taxable": true,
"position": 1,
"available": true,
"inventory_policy": "continue",
"inventory_quantity": 13,
"inventory_management": "shopify",
"fulfillment_service": "manual",
"weight": 1.25,
"weight_unit": "lb",
"image_id": null,
"created_at": "2025-04-01T15:44:57-04:00",
"updated_at": "2025-04-01T15:44:57-04:00"
}
],
"images": [],
"options": [
{
"id": 891236591,
"name": "Title",
"product_id": 921728736,
"position": 1,
"values": [
"Black"
]
}
]
}
}

Anchor to GET request, Retrieve a count of products that are published to your app
get
Retrieve a count of products that are published to your app

publishedProductsCount
Requires product_listings access scope.

Retrieve a count of products that are published to your app

Anchor to Parameters of Retrieve a count of products that are published to your appParameters

api_version
string
required
Was this section helpful?

Anchor to get-product-listings-count-examplesExamples

Retrieve a count of products that are published to your app

Was this section helpful?
get

/admin/api/2025-07/product_listings/count.json

curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-07/product_listings/count.json" \
-H "X-Shopify-Access-Token: {access_token}"

{}

Response

JSON
HTTP/1.1 200 OK
{
"count": 2
}

Anchor to GET request, Retrieve <code>product_ids</code> that are published to your app
get
Retrieve product_ids that are published to your app

products

Retrieve product_ids that are published to your app. Maximum 1,000 results per page.

Anchor to Parameters of Retrieve <code>product_ids</code> that are published to your appParameters

api_version
string
required
limit
≤ 1000
default 50

Amount of results

Was this section helpful?

Anchor to get-product-listings-product-ids-examplesExamples

Retrieve product_ids that are published to your app

Was this section helpful?
get

/admin/api/2025-07/product_listings/product_ids.json

curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-07/product_listings/product_ids.json" \
-H "X-Shopify-Access-Token: {access_token}"

{}

Response

JSON
HTTP/1.1 200 OK
{
"product_ids": [
921728736,
632910392
]
}

Anchor to PUT request, Create a product listing to publish a product to your app
put
Create a product listing to publish a product to your app

publishablePublish
Requires product_listings access scope.

Create a product listing to publish a product to your app

Anchor to Parameters of Create a product listing to publish a product to your appParameters

api_version
string
required
product_listing_id
string
required
Was this section helpful?

Anchor to put-product-listings-product-listing-id-examplesExamples

Create a product listing to publish a product to your app

Path parameters
product_listing_id=921728736
string
required
Request body
product_listing
Product_listing resource
Show product_listing properties
product_listing.product_id:921728736
read-only

The unique identifer of the product this listing is for. The primary key for this resource.

Was this section helpful?
put

/admin/api/2025-07/product_listings/921728736.json

curl -d '{"product_listing":{"product_id":921728736}}' \
-X PUT "https://your-development-store.myshopify.com/admin/api/2025-07/product_listings/921728736.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"

{}

Response

JSON
HTTP/1.1 200 OK
{
"product_listing": {
"product_id": 921728736,
"created_at": "2025-04-01T15:44:57-04:00",
"updated_at": "2025-04-01T15:44:57-04:00",
"body_html": "<p>The iPod Touch has the iPhone's multi-touch interface, with a physical home button off the touch screen. The home screen has a list of buttons for the available applications.</p>",
"handle": "ipod-touch",
"product_type": "Cult Products",
"title": "IPod Touch 8GB",
"vendor": "Apple",
"available": true,
"tags": "",
"published_at": "2017-08-31T20:00:00-04:00",
"variants": [
{
"id": 447654529,
"title": "Black",
"option_values": [
{
"option_id": 891236591,
"name": "Title",
"value": "Black"
}
],
"price": "199.00",
"formatted_price": "$199.00",
"compare_at_price": null,
"grams": 567,
"requires_shipping": true,
"sku": "IPOD2009BLACK",
"barcode": "1234_black",
"taxable": true,
"position": 1,
"available": true,
"inventory_policy": "continue",
"inventory_quantity": 13,
"inventory_management": "shopify",
"fulfillment_service": "manual",
"weight": 1.25,
"weight_unit": "lb",
"image_id": null,
"created_at": "2025-04-01T15:44:57-04:00",
"updated_at": "2025-04-01T15:44:57-04:00"
}
],
"images": [],
"options": [
{
"id": 891236591,
"name": "Title",
"product_id": 921728736,
"position": 1,
"values": [
"Black"
]
}
]
}
}

Anchor to DELETE request, Delete a product listing to unpublish a product from your app
del
Delete a product listing to unpublish a product from your app

publishableUnpublish
Requires product_listings access scope.

Delete a product listing to unpublish a product from your app

Anchor to Parameters of Delete a product listing to unpublish a product from your appParameters

api_version
string
required
product_listing_id
string
required
Was this section helpful?

Anchor to delete-product-listings-product-listing-id-examplesExamples

Delete a product listing to unpublish a product from your app

Path parameters
product_listing_id=921728736
string
required
Was this section helpful?
del

/admin/api/2025-07/product_listings/921728736.json

curl -X DELETE "https://your-development-store.myshopify.com/admin/api/2025-07/product_listings/921728736.json" \
-H "X-Shopify-Access-Token: {access_token}"

{}

Response

JSON
HTTP/1.1 200 OK