Skip to content

JSON:API Conventions

The shape of Store API documents, and the include, fields, filter, sort and page parameters that every endpoint reads the same way.

The Store API answers with JSON:API documents, built on Laravel's JSON:API resources. This page covers what every endpoint shares: the shape of a document, the query parameters that change a response, how amounts and languages come back, and the allowlists of the resource classes that decide which filters, sorts and includes a client may request. Each guide lists the values its own endpoints accept.

JSON:API applies to responses only. Request bodies are flat JSON objects, such as {"quantity": 2}, sent with Content-Type: application/json: the API never reads a data.attributes envelope.

Document Structure

A successful response is a JSON object served as application/vnd.api+json. Its top-level members are:

MemberContent
dataOne resource object, or an array of them on a listing
includedThe related resources requested with include, each one listed once
linksThe pagination links of a listing
metaThe pagination details of a listing, and values specific to an endpoint, such as meta.currency on the product listing

Each resource object carries an id, a type and its attributes, plus relationships when the request includes related resources. The id is always a string. For most resources, such as products, carts, orders, customers and zones, it is the public ID of the record, a ULID such as 01JD3ZA2B4C6D8E0F2G4H6J8K0. A few resources differ: a legal page carries its database key, such as "1", and is read by its slug; the store settings carry "store"; a shipping option or a payment session carries the ID its shipping or payment driver gives it, such as manual:01JD9C4E6G8J0K2M4N6P8R0S2T. The type is a plural, lowercase name with hyphens, such as products, cart-lines or order-items. A member with nothing to show is left out: a resource read without include has no relationships, and a document without related resources has no included. The API does not add a jsonapi member.

Dates are ISO 8601 strings with their offset, such as 2026-11-02T09:15:00+00:00, in the timezone of the application.

This request reads the zone EU and includes its currency:

Request
curl "http://localhost:8000/store/zones/EU?include=currency" \
  -H "Accept: application/vnd.api+json"

The API answers 200 OK. The zone points to its currency in relationships, and the currency itself comes in included:

Response
{
    "data": {
        "id": "01JD3ZA2B4C6D8E0F2G4H6J8K0",
        "type": "zones",
        "attributes": {
            "name": "Europe",
            "slug": "europe",
            "code": "EU",
            "currency_code": "EUR",
            "metadata": null,
            "created_at": "2026-11-02T09:15:00+00:00",
            "updated_at": "2026-11-02T09:15:00+00:00"
        },
        "relationships": {
            "currency": {
                "data": {
                    "id": "01JD3Z8M4K7Q2W9E5R6T1Y0H3B",
                    "type": "currencies"
                }
            }
        }
    },
    "included": [
        {
            "id": "01JD3Z8M4K7Q2W9E5R6T1Y0H3B",
            "type": "currencies",
            "attributes": {
                "name": "Euro",
                "code": "EUR",
                "symbol": "€",
                "format": "1.0,00 €",
                "exchange_rate": 0
            }
        }
    ]
}

To read a relationship, find the object in included whose type and id match the identifier in relationships. A to-one relationship holds one identifier, a to-many relationship an array of them.

Includes

Related resources are left out by default, so that a listing stays small. The include parameter names the relationships to add, separated by commas. Each one adds a relationships entry to the resources of data, and the related resources to included, once each even when several resources share them:

Request
curl "http://localhost:8000/store/products?include=brand,categories" \
  -H "Accept: application/vnd.api+json"

A dot path includes a relationship of an included resource, such as lines.purchasable.product on a cart: the lines, the variant or product of each line, and the parent product of each variant. A path works only when it is listed for the resource, as the cart lists it. The names are case-sensitive and keep the case of the allowlist, such as relatedProducts or paymentMethod.

Included catalog resources only hold what a visitor may see: a disabled brand, a hidden category or an unpublished collection stays out of included, and so do unpublished products.

A few includes add values instead of related resources:

ResourceIncludeAdds
ProductsratingThe rating attribute, the average of the approved reviews rounded to one decimal (null without reviews), and reviews_count
ProductsoptionsThe options attribute: the enabled attributes of the product, such as a color or a size, each with the values the product uses
Productsprice_rangeOn the listing, meta.price_range: the lowest and highest price of all the products that match the filters other than price_min and price_max, so that a price slider keeps its bounds
Categoriesproducts_countThe products_count attribute: the products of the category and of its subcategories

An include that is not in the allowlist of the resource answers 400 Bad Request with the bad_request code. The detail names the includes the endpoint accepts:

Response
{
    "errors": [
        {
            "status": "400",
            "code": "bad_request",
            "title": "Bad Request",
            "detail": "Requested include(s) `shippingOptions` are not allowed. Allowed include(s) are `currency, countries`."
        }
    ]
}

Sparse Fieldsets

A product carries its description, images, SEO fields and prices. A product grid needs a few of them. The fields[<type>] parameter keeps only the listed attributes for the resources of that type, in data and in included alike. The key is the resource type, such as products or brands:

Request
curl -g "http://localhost:8000/store/products?include=brand&fields[products]=name,slug,price_range&fields[brands]=name&page[size]=1" \
  -H "Accept: application/vnd.api+json"

The API answers 200 OK. This response leaves out links and meta:

Response
{
    "data": [
        {
            "id": "01JD8YQ1A2B3C4D5E6F7G8H9JK",
            "type": "products",
            "attributes": {
                "name": "Classic Leather Sneakers",
                "slug": "classic-leather-sneakers",
                "price_range": {
                    "currency_code": "EUR",
                    "min": 9000,
                    "max": 9500
                }
            },
            "relationships": {
                "brand": {
                    "data": {
                        "id": "01JD8XV1C3E5G7J9K1M3P5R7T9",
                        "type": "brands"
                    }
                }
            }
        }
    ],
    "included": [
        {
            "id": "01JD8XV1C3E5G7J9K1M3P5R7T9",
            "type": "brands",
            "attributes": {
                "name": "Maison Cuir"
            }
        }
    ]
}

id, type and relationships stay. An attribute name that the resource does not have is ignored, without an error. A fieldset trims the response but does not add anything: an attribute that comes with an include, such as rating, still needs that include.

On two listings, four includes do not accept a fieldset for their own type: variants and tags on /products, currency and countries on /zones. A listing request that pairs one of them with fields[variants], fields[tags], fields[currencies] or fields[countries] answers 400 Bad Request with the bad_request code. Every other include of a listing accepts a fieldset, and so does every include of a single resource, such as /products/{slug}?include=variants&fields[variants]=name or /zones/{code}?include=countries&fields[countries]=name,cca2.

Filters

A listing narrows its results with filter[<name>]=<value>. The names a listing accepts come from its allowlist, and each one matches in one of three ways:

KindMatchesExample
PartialRecords whose column contains the value, ignoring casefilter[name]=sneak
ExactRecords whose column equals the valuefilter[code]=EUR
ScopeRecords selected by logic of its own, described in the guide of the endpointfilter[in_stock]=true

A comma inside one filter means OR, and separate filters combine with AND. This request lists the countries of the zone EU whose name contains "fra" or "bel":

Request
curl -g "http://localhost:8000/store/countries?filter[zone]=EU&filter[name]=fra,bel" \
  -H "Accept: application/vnd.api+json"

The values true and false are read as booleans, as in filter[featured]=true. Some endpoints accept filters of their own on top of their allowlist, such as the price and currency filters of the product listing, described in the Catalog guide.

A filter accepts at most 50 values. Past that, the API answers 422 with the filter_too_wide code, and source.pointer names the filter, such as /data/attributes/filter/category. A filter name outside the allowlist answers 400 Bad Request with the bad_request code, and a detail such as "Requested filter(s) `color` are not allowed. Allowed filter(s) are `name, code`.". Both are described in Errors.

Sorting

The sort parameter orders a listing by one of the sort names of its allowlist, in ascending order. A - prefix reverses it, and a comma separates several keys, applied in order:

Request
curl "http://localhost:8000/store/products?sort=-published_at,name" \
  -H "Accept: application/vnd.api+json"

The API always adds the record's creation order as the last sort key, so records with the same value come in a stable order and never move between two pages. Without sort, product reviews and the customer's orders come newest first, and the other listings come in the order the records were created. A sort name outside the allowlist answers 400 Bad Request with the bad_request code.

Pagination

Every listing is paginated, except the few that return all their records at once: the category tree, the latest reviews, the shipping options and payment methods of a cart, and the customer's addresses. A listing returns 15 records per page by default, set by SHOPPER_API_PER_PAGE. It offers two kinds of pagination: by page number, the default, and by cursor.

ParameterDefaultEffect
page[size]15The number of records per page, from 1 to 100 (pagination.max_per_page). A larger value returns 100 records, without an error
page[number]1The page to return, from 1 to 100 (pagination.max_page). A larger value returns page 100, without an error
page[cursor]NoneSwitches to cursor pagination. An empty value returns the first page

Page Numbers

Page numbers suit a classic paged catalog, with the total count and a link per page. This request reads the first page of brands, two per page:

Request
curl -g "http://localhost:8000/store/brands?sort=name&page[size]=2&page[number]=1" \
  -H "Accept: application/vnd.api+json"

The API answers 200 OK. After data, the document carries these links and meta:

Response
{
    "links": {
        "first": "http://localhost:8000/store/brands?sort=name&page%5Bsize%5D=2&page%5Bnumber%5D=1&page%5Bnumber%5D=1",
        "last": "http://localhost:8000/store/brands?sort=name&page%5Bsize%5D=2&page%5Bnumber%5D=1&page%5Bnumber%5D=3",
        "prev": null,
        "next": "http://localhost:8000/store/brands?sort=name&page%5Bsize%5D=2&page%5Bnumber%5D=1&page%5Bnumber%5D=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 3,
        "links": [
            {
                "url": null,
                "label": "&laquo; Previous",
                "page": null,
                "active": false
            },
            {
                "url": "http://localhost:8000/store/brands?sort=name&page%5Bsize%5D=2&page%5Bnumber%5D=1&page%5Bnumber%5D=1",
                "label": "1",
                "page": 1,
                "active": true
            },
            {
                "url": "http://localhost:8000/store/brands?sort=name&page%5Bsize%5D=2&page%5Bnumber%5D=1&page%5Bnumber%5D=2",
                "label": "2",
                "page": 2,
                "active": false
            },
            {
                "url": "http://localhost:8000/store/brands?sort=name&page%5Bsize%5D=2&page%5Bnumber%5D=1&page%5Bnumber%5D=3",
                "label": "3",
                "page": 3,
                "active": false
            },
            {
                "url": "http://localhost:8000/store/brands?sort=name&page%5Bsize%5D=2&page%5Bnumber%5D=1&page%5Bnumber%5D=2",
                "label": "Next &raquo;",
                "page": 2,
                "active": false
            }
        ],
        "path": "http://localhost:8000/store/brands",
        "per_page": 2,
        "to": 2,
        "total": 5
    }
}

meta.links lists one entry per page, ready for a pager. On a long listing, it replaces the pages in the middle with one entry labeled ..., whose url is null and that has no page. The link URLs keep the filters, sorts and includes of the request. When the request carries page[number], they also repeat it before the new one, as in page%5Bnumber%5D=1&page%5Bnumber%5D=2. The API reads the last value, so requesting a link URL as it is returns the right page. Do not read the page number from a link URL with URLSearchParams.get(), which returns the first value: use the page of each meta.links entry and meta.current_page instead.

The page number stops at 100 so that a request can never scan the whole table. To walk further, such as to export a large catalog, use a cursor.

Cursors

A cursor marks a position in the sorted results, so reading the next page costs the same at any depth. Send page[cursor] with an empty value to start, then follow links.next until it is null:

Request
curl -g "http://localhost:8000/store/brands?sort=name&page[size]=2&page[cursor]=" \
  -H "Accept: application/vnd.api+json"

The API answers 200 OK. A cursor page has no total and no page numbers:

Response
{
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": "http://localhost:8000/store/brands?sort=name&page%5Bsize%5D=2&page%5Bcursor%5D=eyJuYW1lIjoiTWFpc29uIEN1aXIiLCJzaF9icmFuZHMuaWQiOjMsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"
    },
    "meta": {
        "path": "http://localhost:8000/store/brands",
        "per_page": 2,
        "next_cursor": "eyJuYW1lIjoiTWFpc29uIEN1aXIiLCJzaF9icmFuZHMuaWQiOjMsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
        "prev_cursor": null
    }
}

Treat the cursor as an opaque string. From the second page on, links.next and links.prev repeat the cursor of the request before the new one, like the page links, and the API reads the last value. When you build the next URL yourself, send meta.next_cursor as page[cursor] with the same filters and sort as the first request: a cursor only applies to the sort that produced it.

Prices and Money

Every amount is an integer in cents, or in whole units for a zero-decimal currency, next to the code of its currency. A product priced at €19.90 carries 1990. Divide by 100, or use the currency's own number of decimals, before you display an amount. The Money page lists the amount attributes of each resource and shows how to format them in JavaScript.

The prices of a product or a variant list one entry per enabled currency, with the amount, the compare_amount (the crossed-out price, or null) and the currency_code. calculated_price and price_range use one currency, picked in this order: the filter[currency] parameter, then the currency of the zone sent in X-Shopper-Zone, then the default currency of the shop. meta.currency on the product endpoints gives the code that was picked. A filter[currency] that names an unknown or disabled currency answers 422 with the currency_unknown code. An enabled currency that the products have no price in still resolves: calculated_price and price_range are then null. The Pricing page explains how calculated_price is resolved.

A calculated price can depend on the customer, so product responses that carry one add Authorization to their Vary header. A cache in front of the API then keeps one copy per token.

Locale

The Accept-Language header selects the language of the response among the locales of the shop, as described in Request headers. It changes the translated_name of countries and the detail of error messages. Product names, descriptions and other catalog content are stored in one language and come back the same whatever the header.

Allowlists

A client may only filter, sort and include what the shop allows. Each resource class of Shopper\Api\Http\Resources declares its allowlists in three static methods: filters(), sorts() and includes(). Filters and sorts apply to the listing of a resource, includes to its listing and to its show endpoint:

ResourceEndpointsFiltersSortsIncludes
ProductResource/products, /products/{slug}name, sku, q, featured, in_stock, category, category_tree, collection, brand, tag, optionname, created_at, published_at, pricebrand, variants, categories, collections, options, tags, relatedProducts, rating, price_range
CategoryResource/categories, /categories/{slug}namename, positionparent, children, ancestors, products, products_count
CollectionResource/collections, /collections/{slug}namenameproducts
BrandResource/brands, /brands/{slug}namename, positionproducts
AttributeResource/attributesnamenameNone
TagResource/tagsnamenameproducts
CountryResource/countries, /countries/{code}name, cca2, cca3, region, zonenamezones
ZoneResource/zones, /zones/{code}name, codenamecurrency, countries
CurrencyResource/currencies, /currencies/{code}name, codename, codeNone
CartResourceThe cart endpoints that answer with the cartNoneNonelines, lines.purchasable, lines.purchasable.product, addresses, paymentMethod
OrderResource/customers/me/orders, /customers/me/orders/{orderId}statuscreated_atitems, shippingAddress, billingAddress, paymentMethod, shippings, shippings.events, refund
ReviewResource/products/{slug}/reviewsratingcreated_at, ratingNone
LegalResource/legals, /legals/{slug}titletitle, updated_atNone

GET /store/reviews returns the 20 latest reviews, and reviews.latest_limit in config/shopper/api.php changes that number. The guides describe what each filter and include does.

Extending the Allowlists

A storefront sometimes needs a filter, a sort or an include the shop does not allow yet, such as looking a product up by its barcode. To add one, extend the resource class, override the static method of the list and register your class with the ApiResource facade. The endpoints of that resource then read the lists from your class: the filters and sorts on the listing, the includes on the listing and on the show endpoint.

This class adds an exact barcode filter to the products. It spreads parent::filters() first, so the default filters stay, including those a later Shopper release adds:

app/Http/Resources/StoreProductResource.php
namespace App\Http\Resources;

use Shopper\Api\Http\Resources\ProductResource;
use Spatie\QueryBuilder\AllowedFilter;

class StoreProductResource extends ProductResource
{
    public static function filters(): array
    {
        return [
            ...parent::filters(),
            AllowedFilter::exact('barcode'),
        ];
    }
}

This boot method of a service provider makes the Store API use your class in place of ProductResource:

app/Providers/AppServiceProvider.php
use App\Http\Resources\StoreProductResource;
use Shopper\Api\Facades\ApiResource;
use Shopper\Api\Http\Resources\ProductResource;

public function boot(): void
{
    ApiResource::replace(ProductResource::class, StoreProductResource::class);
}

This request looks the product up by its barcode:

Request
curl -g "http://localhost:8000/store/products?filter[barcode]=3700123456789" \
  -H "Accept: application/vnd.api+json"

The lists hold the objects of Laravel Query Builder, which the Store API runs its queries with. The default lists use these forms:

EntryEffect
AllowedFilter::partial('name') in filters()Filter: the column contains the value, ignoring case
AllowedFilter::exact('sku') in filters()Filter: the column equals the value
AllowedFilter::exact('zone', 'zones.code') in filters()Filter: a column of a relation equals the value
AllowedFilter::scope('category') in filters()Filter: calls the category query scope of the model
AllowedFilter::scope('in_stock', 'availability') in filters()Filter: calls a scope with another name, here availability
'name' in sorts()Sort: by the column of that name
AllowedSort::field('price', 'min_price') in sorts()Sort: by another column or select alias, here the lowest price
'tags' in includes()Include: loads the relation with all its rows
AllowedInclude::custom('brand', new EnabledRelation) in includes()Include: runs an include class, which keeps only the public rows
'categories' => ['categories.parent'] in includeLoads()Loads these relations too when the include is requested, so that the response does not query each record

A plain include loads every related row, enabled or not. For a relation that holds drafts or disabled records, pass one of the include classes of Shopper\Api\Http\Includes to AllowedInclude::custom(): EnabledRelation and PublishedRelation apply the enabled and published scopes of the related model. An include class implements Spatie\QueryBuilder\Includes\IncludeInterface, so you can write your own.

To remove a default entry, return a list without it instead of spreading the parent list. An include you add also needs its relationship in toRelationships(), as Replacing a Resource explains.

Replacing a Resource

The allowlists decide what a client may request, not what a document contains. To add an attribute or a relationship to a resource, extend its resource class and register the replacement with the ApiResource facade. This class adds a care_instructions column that your application added to the products table:

app/Http/Resources/StoreProductResource.php
namespace App\Http\Resources;

use Illuminate\Http\Request;
use Shopper\Api\Http\Resources\ProductResource;

class StoreProductResource extends ProductResource
{
    public function toAttributes(Request $request): array
    {
        return [
            ...parent::toAttributes($request),
            'care_instructions' => $this->care_instructions,
        ];
    }
}

Register it in the boot method of a service provider:

app/Providers/AppServiceProvider.php
use App\Http\Resources\StoreProductResource;
use Shopper\Api\Facades\ApiResource;
use Shopper\Api\Http\Resources\ProductResource;

public function boot(): void
{
    ApiResource::replace(ProductResource::class, StoreProductResource::class);
}

Every endpoint then serializes products with your class, in data, in listings and in included, and reads the allowlists and the relations to load from it. replace() also takes an array that maps several stock classes to their replacements. A replacement must extend the class it replaces, or replace() throws an InvalidArgumentException. The type of a resource cannot change. One class can both change the allowlists and add attributes: a resource takes one replacement only, and the last replace() call wins.

A new include also needs its relationship declared in toRelationships() of the resource. Laravel's JSON:API resource leaves out the relationships a resource does not declare, so an include that is in includes() but missing from toRelationships() answers 200 without the relation. Override toRelationships() in the replacement and add your relation to the array the parent method returns.

Loading Relations

An attribute that reads a relation, such as the names of the tags of a product, runs one query per product: 24 queries on a listing of 24 products. The static eagerLoads() method lists the relations the Store API loads together with the records of a resource, on every query that serializes it. ProductResource loads prices.currency and media this way.

This replacement sends the names of the tags of each product, and adds tags to the relations it loads, so a listing reads the tags of all its products in one query:

app/Http/Resources/StoreProductResource.php
namespace App\Http\Resources;

use Illuminate\Http\Request;
use Shopper\Api\Http\Resources\ProductResource;

class StoreProductResource extends ProductResource
{
    public static function eagerLoads(): array
    {
        return [...parent::eagerLoads(), 'tags'];
    }

    public function toAttributes(Request $request): array
    {
        return [
            ...parent::toAttributes($request),
            'tag_names' => $this->tags->pluck('name'),
        ];
    }
}

An add-on does not replace the resource, since the store keeps that replacement for itself. It registers its relations with ApiResource::eagerLoad() on the stock class, and the Store API loads them for the replacement too, as Extending the Store API shows.

Next Steps

These conventions apply to every guide that follows, starting with the errors the parameters can cause.

Last updated on

Edit on GitHub