# GET /v1/shop/products: Shop products API

The products of one shop collection (collection_id from shop/storefront), a page at a time. Pass next_cursor back as cursor for the next page.

- Call: `GET https://storiesfly.com/api/v1/shop/products`
- Price **1 request**
- Answers up to **1 hour** old

## Parameters

All parameters go in the query string.

| Name | Type | Sent | Description |
| --- | --- | --- | --- |
| `collection_id` | string | required | Id of a shop collection, as shop/storefront lists them. |
| `cursor` | string | optional | The next_cursor of the page before. Leave it out for the first page. |

## Example request

Put your own key in the header.

### cURL

```bash
curl "https://storiesfly.com/api/v1/shop/products?collection_id=curated-9651971321535029-390927249" \
  -H "X-Api-Key: sf_live_your_key"
```

### JavaScript

```javascript
const res = await fetch(
  "https://storiesfly.com/api/v1/shop/products?collection_id=curated-9651971321535029-390927249",
  { headers: { "X-Api-Key": process.env.STORIESFLY_KEY } }
);
const data = await res.json();
```

### Python

```python
import os
import requests

r = requests.get(
    "https://storiesfly.com/api/v1/shop/products",
    params={"collection_id": "curated-9651971321535029-390927249"},
    headers={"X-Api-Key": os.environ["STORIESFLY_KEY"]},
)
data = r.json()
```

## Example response

200 OK · X-Units-Charged: 1

```json
{
  "collection": {
    "id": "curated-9651971321535029-390927249"
  },
  "products": [
    {
      "id": "27260212646988163",
      "name": "Gymshark Adapt Solid Leggings - Cherry Purple",
      "price": 60,
      "currency": "USD",
      "image_url": "https://scontent-iad6-1.cdninstagram.com/v/t45.5328-4/829171560_1700662492062654_6359498266337264432_n.jpg",
      "url": "https://gymsharkusa.myshopify.com/products/gymshark-adapt-x-whitney-leggings-leggings-purple-aw26"
    },
    {
      "id": "28443363868664037",
      "name": "Gymshark Power T-Shirt - Cherry Purple",
      "price": 36,
      "currency": "USD",
      "image_url": "https://scontent-iad6-1.cdninstagram.com/v/t45.5328-4/831067489_1076985248435512_4691220592327613214_n.jpg",
      "url": "https://gymsharkusa.myshopify.com/products/gymshark-power-t-shirt-ss-tops-purple-aw26"
    }
  ],
  "next_cursor": null,
  "has_more": false
}
```

A real answer, shortened: lists are cut to two items and long texts to 160 characters.

## Price and freshness

A call takes 1 request. Free requests are spent first, then your balance. The [pricing](https://storiesfly.com/developers/pricing) page has the rates.

Answers are kept for up to 1 hour. Asking again inside that time returns the same answer and takes 1 request again.

Page size follows Instagram and varies by endpoint.

## Errors

A failed call answers with an HTTP status and a body `{error, code}`. These are the codes this endpoint gives. [Errors and what is charged](https://storiesfly.com/developers/docs#errors) covers all of them.

| Status | Code | When |
| --- | --- | --- |
| `400` | `bad_request` | A parameter is missing or wrong. `fields` lists the names. Free. |
| `401` | `unauthorized` | The `X-Api-Key` header is missing or the key is wrong. Free. |
| `402` | `credits_exhausted` | The free requests and the balance are used up. Top up in the [dashboard](https://storiesfly.com/developers/dashboard). Free. |
| `403` | `telegram_required` | The account behind the key is not linked to Telegram. The answer has a `link_url` to do it. Free. |
| `404` | `not_found` | The collection does not exist. Charged like an answer. |
| `429` | `rate_limited` | More requests in a second than your level allows. Wait for the `Retry-After` header. Free. |
| `500` | `internal_error` | A fault on our side. Retry shortly. Refunded. |
| `503` | `upstream_unavailable` | Our side failed or timed out. Retry shortly. Refunded. |

## Questions about this endpoint

### Where do I get collection_id?

From `collections` in [shop/storefront](https://storiesfly.com/developers/docs/shop-storefront).

### How do I read all the products of a collection?

Send the `next_cursor` of the answer back as `cursor` for the next page, and stop when `has_more` is `false`. Each page takes 1 request. A cursor works only on the endpoint that returned it.

### What does a product hold?

Its `id`, `name`, `price`, `currency`, picture link and `url`, the seller's own link to the product.

## Related endpoints

- [GET /v1/shop/storefront](https://storiesfly.com/developers/docs/shop-storefront): An account's shop: collections and first products
- [GET /v1/user/profile](https://storiesfly.com/developers/docs/user-profile): Profile with verified badge, bio, link and counts
- [GET /v1/user/posts](https://storiesfly.com/developers/docs/user-posts): Posts with likes, comments, views, shares, saves and reposts

## Links

- [This page on the site](https://storiesfly.com/developers/docs/shop-products)
- [Instagram data API](https://storiesfly.com/developers): what the API is and what it returns
- [Pricing](https://storiesfly.com/developers/pricing): rates, examples and billing rules
- [Documentation](https://storiesfly.com/developers/docs): quick start, authentication, errors and every endpoint
- [OpenAPI file](https://storiesfly.com/openapi.json): the whole API in one file
- [API dashboard](https://storiesfly.com/developers/dashboard): get a key and top up
- [Changelog](https://storiesfly.com/developers/changelog): what changed and when