Introducing our brand new Rules Engine —
Read the docs
LogoLogo
Core APIOther APIsChangelog
How-tos
How-tos
  • Introduction
  • Product discovery
    • Product listing page
    • Product page
  • Placing orders
    • Shopping cart
      • Creating a shopping cart
      • Adding products to cart
      • Updating cart quantities
      • Removing products from cart
      • Displaying the cart summary
    • Checkout
      • Adding the customer
      • Adding a billing address
      • Adding a shipping address
      • Selecting a shipping method
      • Selecting a payment method
      • Adding a payment source
      • Adding a gift card or coupon
      • Placing the order
    • Subscriptions
      • Configuring a subscription model
      • Selecting the source order
      • Generating the subscriptions
      • Updating the subscriptions
    • Payments
      • Adyen
        • Adding the payment source
        • Sending back the payment details
        • Configuring the notification webhooks
        • Reusing the payment source
      • Axerve
        • Adding the payment source
        • Updating the payment intent
      • Braintree
        • Adding the payment source
        • Sending back the payment method nonce
        • Accepting local payments
        • Reusing the payment source
      • Checkout.com
        • Adding the payment source
        • Getting the payment details
        • Refreshing pending transactions
        • Reusing the payment source
      • Klarna
        • Adding the payment source
        • Sending back the authorization token
        • Reusing the payment source
      • PayPal
        • Adding the payment source
        • Preparing the payment for execution
      • Stripe
        • Adding the payment source
        • Refreshing the payment source
        • Reusing the payment source
      • Manual payments
        • Adding a wire transfer payment source
      • External payments
        • Adding the payment source
        • Reusing the payment source
    • Auto-capture
      • Enabling the auto-capture
      • Limiting the auto-capture amount
  • inventory
    • Inventory strategies
      • No split
      • Split shipments
      • Split by line items
      • Ship from first available (or primary)
      • Ship from primary
  • FAQ
    • Environments and initial setup
    • Authentication and access tokens
On this page
  • Problem
  • Solution
  • Example
  • Mapping
  • Additional notes
  • More to read
  1. Product discovery

Product listing page

How to display prices for a list of products

PreviousIntroductionNextProduct page

Last updated 3 years ago

Problem

You've created a product listing page (i.e. category or collection page) with your favorite CMS and now you want to display the price for each of the products. You have the SKU codes of the products you want to list.

Solution

To retrieve the price for each of the SKUs on the page, send a GET request to the /api/skusendpoint, filter it by code, and include the associated prices.

Example

The following request retrieves the prices of the SKUs identified by a list of specific codes:

curl -g -X GET \
  'https://yourdomain.commercelayer.io/api/skus?filter[q][code_in]=TSHIRTG5B5B5BST,TSHIRTWF5F5F5MN,TSHIRTB0A0A0ACL,TSHIRTB212F3FSM&include=prices' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token'

On success, the API responds with a 200 OK status code, returning the four SKU objects with the prices included:

{
  "data": [
    {
      "id": "WLgbSXqyoZ",
      "type": "skus",
      "links": {
        "self": "https://yourdomain.commercelayer.io/api/skus/WLgbSXqyoZ"
      },
      "attributes": {
        "code": "TSHIRTG5B5B5BST",
        "name": "Gray T-Shirt Star",
        "description": "Gray cotton t-shirt. Short sleeves and a round neckline. Unique high quality design.",
        "image_url": "https://img.yourdomain.com/skus/TSHIRTG5B5B5BST.png",
        "tag_names": "",
        "pieces_per_pack": null,
        "weight": null,
        "unit_of_weight": null,
        "hs_tariff_number": null,
        "do_not_ship": false,
        "do_not_track": false,
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": "TSHIRTG5B5B5B",
        "metadata": {}
      },
      "relationships": {
        "shipping_category": {
          "links": {...}
        },
        "prices": {
          "links": {...},
          "data": [
            {
              "type": "prices",
              "id": "ajKQUMdKQp"
            }
            ]
          },
          "stock_items": {
            "links": {...}
          },
          "delivery_lead_times": {
            "links": {...}
          },
          "sku_options": {
            "links": {...}
          }
      },
      "meta": {
        "mode": "test"
      }
    },
    {
        "id": "ZjwqSNOQKW",
        "type": "skus",
        "links": {
            "self": "https://yourdomain.commercelayer.io/api/skus/ZjwqSNOQKW"
        },
        "attributes": {
            "code": "TSHIRTWF5F5F5MN",
            "name": "White T-Shirt Moon",
            "description": "White cotton t-shirt. Short sleeves and a round neckline. Unique high quality design.",
            "image_url": "https://img.yourdomain.com/skus/TSHIRTWF5F5F5MN.png",
            "tag_names": "",
            "pieces_per_pack": null,
            "weight": null,
            "unit_of_weight": null,
            "hs_tariff_number": null,
            "do_not_ship": false,
            "do_not_track": false,
            "created_at": "2018-01-01T12:00:00.000Z",
            "updated_at": "2018-01-01T12:00:00.000Z",
            "reference": "TSHIRTWF5F5F5",
            "metadata": {}
        },
        "relationships": {
            "shipping_category": {
                "links": {...}
            },
            "prices": {
                "links": {...},
                "data": [
                    {
                        "type": "prices",
                        "id": "pYwMUWJRzg"
                    }
                ]
            },
            "stock_items": {
                "links": {...}
            },
            "delivery_lead_times": {
                "links": {...}
            },
            "sku_options": {
                "links": {...}
            }
        },
        "meta": {
            "mode": "test"
        }
    },
    {
        "id": "WvAJSyDMqZ",
        "type": "skus",
        "links": {
            "self": "https://yourdomain.commercelayer.io/api/skus/WvAJSyDMqZ"
        },
        "attributes": {
            "code": "TSHIRTB0A0A0ACL",
            "name": "Black T-Shirt Cloud",
            "description": "Black cotton t-shirt. Short sleeves and a round neckline. Unique high quality design.",
            "image_url": "https://img.yourdomain.com/skus/TSHIRTB0A0A0ACL.png",
            "tag_names": "",
            "pieces_per_pack": null,
            "weight": null,
            "unit_of_weight": null,
            "hs_tariff_number": null,
            "do_not_ship": false,
            "do_not_track": false,
            "created_at": "2018-01-01T12:00:00.000Z",
            "updated_at": "2018-01-01T12:00:00.000Z",
            "reference": "TSHIRTB0A0A0A",
            "metadata": {}
        },
        "relationships": {
            "shipping_category": {
                "links": {...}
            },
            "prices": {
                "links": {...},
                "data": [
                    {
                        "type": "prices",
                        "id": "gQVmUKewQa"
                    }
                ]
            },
            "stock_items": {
                "links": {...}
            },
            "delivery_lead_times": {
                "links": {...}
            },
            "sku_options": {
                "links": {...}
            }
        },
        "meta": {
            "mode": "test"
        }
    },
    {
        "id": "BbpjSNePDZ",
        "type": "skus",
        "links": {
            "self": "https://yourdomain.commercelayer.io/api/skus/BbpjSNePDZ"
        },
        "attributes": {
            "code": "TSHIRTB212F3FSM",
            "name": "Blue T-Shirt Smile",
            "description": "Blue cotton t-shirt. Short sleeves and a round neckline. Unique high quality design.",
            "image_url": "https://img.yourdomain.com/skus/TSHIRTB212F3FSM.png",
            "tag_names": "",
            "pieces_per_pack": null,
            "weight": null,
            "unit_of_weight": null,
            "hs_tariff_number": null,
            "do_not_ship": false,
            "do_not_track": false,
            "created_at": "2018-01-01T12:00:00.000Z",
            "updated_at": "2018-01-01T12:00:00.000Z",
            "reference": "TSHIRTB212F3F",
            "metadata": {}
        },
        "relationships": {
            "shipping_category": {
                "links": {...}
            },
            "prices": {
                "links": {...},
                "data": [
                    {
                        "type": "prices",
                        "id": "aDPrUElXla"
                    }
                ]
            },
            "stock_items": {
                "links": {...}
            },
            "delivery_lead_times": {
                "links": {...}
            },
            "sku_options": {
                "links": {...}
            }
        },
        "meta": {
            "mode": "test"
        }
    }
  ],
  "included": [
    {
      "id": "ajKQUMdKQp",
      "type": "prices",
      "links": {
        "self": "https://yourdomain.commercelayer.io/api/prices/ajKQUMdKQp"
      },
      "attributes": {
        "currency_code": "EUR",
        "sku_code": "TSHIRTG5B5B5BST",
        "amount_cents": 12900,
        "amount_float": 129.0,
        "formatted_amount": "€129,00",
        "compare_at_amount_cents": 15000,
        "compare_at_amount_float": 150.0,
        "formatted_compare_at_amount": "€150,00",
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": null,
        "metadata": {}
      },
      "relationships": {
        "price_list": {
          "links": {...}
        },
        "sku": {
          "links": {...}
        }
      },
      "meta": {
        "mode": "test"
      }
    },
    {
      "id": "pYwMUWJRzg",
      "type": "prices",
      "links": {
        "self": "https://yourdomain.commercelayer.io/api/prices/pYwMUWJRzg"
      },
      "attributes": {
        "currency_code": "EUR",
        "sku_code": "TSHIRTWF5F5F5MN",
        "amount_cents": 11900,
        "amount_float": 119.0,
        "formatted_amount": "€119,00",
        "compare_at_amount_cents": 15000,
        "compare_at_amount_float": 150.0,
        "formatted_compare_at_amount": "€150,00",
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": null,
        "metadata": {}
      },
      "relationships": {
        "price_list": {
          "links": {...}
        },
        "sku": {
          "links": {...}
        }
      },
      "meta": {
        "mode": "test"
      }
    },
    {
      "id": "gQVmUKewQa",
      "type": "prices",
      "links": {
        "self": "https://yourdomain.commercelayer.io/api/prices/gQVmUKewQa"
      },
      "attributes": {
        "currency_code": "EUR",
        "sku_code": "TSHIRTB0A0A0ACL",
        "amount_cents": 15900,
        "amount_float": 159.0,
        "formatted_amount": "€159,00",
        "compare_at_amount_cents": 19000,
        "compare_at_amount_float": 190.0,
        "formatted_compare_at_amount": "€190,00",
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": null,
        "metadata": {}
      },
      "relationships": {
        "price_list": {
          "links": {...}
        },
        "sku": {
          "links": {...}
        }
      },
      "meta": {
        "mode": "test"
      }
    },
    {
      "id": "aDPrUElXla",
      "type": "prices",
      "links": {
        "self": "https://yourdomain.commercelayer.io/api/prices/aDPrUElXla"
      },
      "attributes": {
        "currency_code": "EUR",
        "sku_code": "TSHIRTB212F3FSM",
        "amount_cents": 14900,
        "amount_float": 149.0,
        "formatted_amount": "€149,00",
        "compare_at_amount_cents": 17000,
        "compare_at_amount_float": 170.0,
        "formatted_compare_at_amount": "€170,00",
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": null,
        "metadata": {}
      },
      "relationships": {
        "price_list": {
          "links": {...}
        },
        "sku": {
          "links": {...}
        }
      },
      "meta": {
        "mode": "test"
      }
    }
  ],
  "meta": {
      "record_count": 4,
      "page_count": 1
  },
  "links": {
      "first": "https://yourdomain.commercelayer.io/api/skus?filter[q][code_in]=TSHIRTG5B5B5BST,TSHIRTWF5F5F5MN,TSHIRTB0A0A0ACL,TSHIRTB212F3FSM&include=prices&page[number]=1&page[size]=10",
      "last": "https://yourdomain.commercelayer.io/api/skus?filter[q][code_in]=TSHIRTG5B5B5BST,TSHIRTWF5F5F5MN,TSHIRTB0A0A0ACL,TSHIRTB212F3FSM&include=prices&page[number]=1&page[size]=10"
  }
}

Mapping

The image below shows the two main dynamic elements of the page (selling price and full price) and how each of these is mapped to a specific field of the price object.

Additional notes

Available products and "Add to cart" button

Out-of-stock items are still considered sellable (i.e. they have a price and are associated with an existing stock item, only that the stock item quantity is equal to 0) but they are not available and would return an error when trying to add them to the cart.

If you want to display the available products only and show an "Add to cart" button instead of a "View details" one, we recommend you to refine the above request with an additional filter to make sure that the returned SKUs have an available quantity (i.e. they are associated with a stock item that has a quantity greater than 0).

The following request retrieves the prices of all the available SKUs:

curl -g -X GET \
  'https://yourdomain.commercelayer.io/api/skus?filter[q][code_in]=TSHIRTG5B5B5BST,TSHIRTWF5F5F5MN,TSHIRTB0A0A0ACL,TSHIRTB212F3FSM&filter[q][stock_items_quantity_gt]=0&include=prices' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token'

On success, the API responds with a 200 OK status code, returning the SKU objects with the prices included (please note that the available products are only 3 out of the previous 4):

{
  "data": [
    {
      "id": "WLgbSXqyoZ",
      "type": "skus",
      "links": {
        "self": "https://yourdomain.commercelayer.io/api/skus/WLgbSXqyoZ"
      },
      "attributes": {
        "code": "TSHIRTG5B5B5BST",
        "name": "Gray T-Shirt Star",
        "description": "Gray cotton t-shirt. Short sleeves and a round neckline. Unique high quality design.",
        "image_url": "https://img.yourdomain.com/skus/TSHIRTG5B5B5BST.png",
        "tag_names": "",
        "pieces_per_pack": null,
        "weight": null,
        "unit_of_weight": null,
        "hs_tariff_number": null,
        "do_not_ship": false,
        "do_not_track": false,
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": "TSHIRTG5B5B5B",
        "metadata": {}
      },
      "relationships": {
        "shipping_category": {
          "links": {...}
        },
        "prices": {
          "links": {...},
          "data": [
            {
              "type": "prices",
              "id": "ajKQUMdKQp"
            }
            ]
          },
          "stock_items": {
            "links": {...}
          },
          "delivery_lead_times": {
            "links": {...}
          },
          "sku_options": {
            "links": {...}
          }
      },
      "meta": {
        "mode": "test"
      }
    },
    {
        "id": "ZjwqSNOQKW",
        "type": "skus",
        "links": {
            "self": "https://yourdomain.commercelayer.io/api/skus/ZjwqSNOQKW"
        },
        "attributes": {
            "code": "TSHIRTWF5F5F5MN",
            "name": "White T-Shirt Moon",
            "description": "White cotton t-shirt. Short sleeves and a round neckline. Unique high quality design.",
            "image_url": "https://img.yourdomain.com/skus/TSHIRTWF5F5F5MN.png",
            "tag_names": "",
            "pieces_per_pack": null,
            "weight": null,
            "unit_of_weight": null,
            "hs_tariff_number": null,
            "do_not_ship": false,
            "do_not_track": false,
            "created_at": "2018-01-01T12:00:00.000Z",
            "updated_at": "2018-01-01T12:00:00.000Z",
            "reference": "TSHIRTWF5F5F5",
            "metadata": {}
        },
        "relationships": {
            "shipping_category": {
                "links": {...}
            },
            "prices": {
                "links": {...},
                "data": [
                    {
                        "type": "prices",
                        "id": "pYwMUWJRzg"
                    }
                ]
            },
            "stock_items": {
                "links": {...}
            },
            "delivery_lead_times": {
                "links": {...}
            },
            "sku_options": {
                "links": {...}
            }
        },
        "meta": {
            "mode": "test"
        }
    },
    {
        "id": "WvAJSyDMqZ",
        "type": "skus",
        "links": {
            "self": "https://yourdomain.commercelayer.io/api/skus/WvAJSyDMqZ"
        },
        "attributes": {
            "code": "TSHIRTB0A0A0ACL",
            "name": "Black T-Shirt Cloud",
            "description": "Black cotton t-shirt. Short sleeves and a round neckline. Unique high quality design.",
            "image_url": "https://img.yourdomain.com/skus/TSHIRTB0A0A0ACL.png",
            "tag_names": "",
            "pieces_per_pack": null,
            "weight": null,
            "unit_of_weight": null,
            "hs_tariff_number": null,
            "do_not_ship": false,
            "do_not_track": false,
            "created_at": "2018-01-01T12:00:00.000Z",
            "updated_at": "2018-01-01T12:00:00.000Z",
            "reference": "TSHIRTB0A0A0A",
            "metadata": {}
        },
        "relationships": {
            "shipping_category": {
                "links": {...}
            },
            "prices": {
                "links": {...},
                "data": [
                    {
                        "type": "prices",
                        "id": "gQVmUKewQa"
                    }
                ]
            },
            "stock_items": {
                "links": {...}
            },
            "delivery_lead_times": {
                "links": {...}
            },
            "sku_options": {
                "links": {...}
            }
        },
        "meta": {
            "mode": "test"
        }
    }
  ],
  "included": [
    {
      "id": "ajKQUMdKQp",
      "type": "prices",
      "links": {
        "self": "https://yourdomain.commercelayer.io/api/prices/ajKQUMdKQp"
      },
      "attributes": {
        "currency_code": "EUR",
        "sku_code": "TSHIRTG5B5B5BST",
        "amount_cents": 12900,
        "amount_float": 129.0,
        "formatted_amount": "€129,00",
        "compare_at_amount_cents": 15000,
        "compare_at_amount_float": 150.0,
        "formatted_compare_at_amount": "€150,00",
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": null,
        "metadata": {}
      },
      "relationships": {
        "price_list": {
          "links": {...}
        },
        "sku": {
          "links": {...}
        }
      },
      "meta": {
        "mode": "test"
      }
    },
    {
      "id": "pYwMUWJRzg",
      "type": "prices",
      "links": {
        "self": "https://yourdomain.commercelayer.io/api/prices/pYwMUWJRzg"
      },
      "attributes": {
        "currency_code": "EUR",
        "sku_code": "TSHIRTWF5F5F5MN",
        "amount_cents": 11900,
        "amount_float": 119.0,
        "formatted_amount": "€119,00",
        "compare_at_amount_cents": 15000,
        "compare_at_amount_float": 150.0,
        "formatted_compare_at_amount": "€150,00",
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": null,
        "metadata": {}
      },
      "relationships": {
        "price_list": {
          "links": {...}
        },
        "sku": {
          "links": {...}
        }
      },
      "meta": {
        "mode": "test"
      }
    },
    {
      "id": "gQVmUKewQa",
      "type": "prices",
      "links": {
        "self": "https://yourdomain.commercelayer.io/api/prices/gQVmUKewQa"
      },
      "attributes": {
        "currency_code": "EUR",
        "sku_code": "TSHIRTB0A0A0ACL",
        "amount_cents": 15900,
        "amount_float": 159.0,
        "formatted_amount": "€159,00",
        "compare_at_amount_cents": 19000,
        "compare_at_amount_float": 190.0,
        "formatted_compare_at_amount": "€190,00",
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": null,
        "metadata": {}
      },
      "relationships": {
        "price_list": {
          "links": {...}
        },
        "sku": {
          "links": {...}
        }
      },
      "meta": {
        "mode": "test"
      }
    }
  ],
  "meta": {
    "record_count": 3,
    "page_count": 1
  },
  "links": {
      "first": "https://spineless.commercelayer.io/api/skus?filter[q][code_in]=TSHIRTG5B5B5BST,TSHIRTWF5F5F5MN,TSHIRTB0A0A0ACL,TSHIRTB212F3FSM&include=prices&page[number]=1&page[size]=10",
      "last": "https://spineless.commercelayer.io/api/skus?filter[q][code_in]=TSHIRTG5B5B5BST,TSHIRTWF5F5F5MN,TSHIRTB0A0A0ACL,TSHIRTB212F3FSM&include=prices&page[number]=1&page[size]=10"
  }
}

More to read

To be sellable in a market an SKU must have a price in the market's price list and at least one stock item in one of the market's stock locations, regardless of its quantity. About that, please note that the above API call returns sellable products, but doesn't show any details about the availability of the SKUs because, for performance reasons, the inventory information is only returned when fetching a single SKU. for more info on how to display just the available products.

See our documentation if you need more information on how to and .

filter data
include associations
Read this
A sample product listing page
A sample product listing page mapping