Carts and checkout

Make and fill a cart, estimate shipping and hand it to the shop's checkout page with a single-use link.

A cart is named by its token. Make one with createCart, keep its cartToken, and reach it again with cart. The CartSession that cart returns sends the token as the X-Cart-Token header for you. Every change answers with the whole cart, with its lines, totals and coupon.

Each write takes $idempotencyKey last: your own Idempotency-Key, or false for none. One is made for you when null (see retries).

Create a cart

$storefront->createCart(string|false|null $idempotencyKey = null): array

A new empty cart, named by the returned cartToken. Keep the token, in the shopper's session or a cookie, to come back to the cart. Made on a client with a shopper's access token, the cart is theirs and priced for them. Limited like cart writes (30 a minute, 300 an hour per visitor).

Parameters

Returns

The new Cart array:

Errors

Example

$cart = $storefront->createCart();
$request->session()->put('cartToken', $cart['cartToken']);

Open a cart

$storefront->cart(string $cartToken): CartSession

A CartSession for the cart a token names. Its methods below act on that cart, and its token property holds the token.

Parameters

Returns

A CartSession. No request is made.

Example

$session = $storefront->cart($cart['cartToken']);

Get the cart

$session->get(): array

The cart as it is now, priced as the shop's own cart page prices it.

Returns

A Cart array:

Errors

Example

$cart = $session->get();

Add a product

$session->addItem(int $productId, int $quantity = 1, string|false|null $idempotencyKey = null): array

Adds a product, or more of one already in the cart. No stock is held until the cart is claimed at checkout. Limited like cart writes.

Parameters

Returns

The changed Cart array:

Errors

Example

$cart = $session->addItem(12, 2);

Change a line's quantity

$session->updateItem(int $itemId, int $quantity, string|false|null $idempotencyKey = null): array

Sets a line's quantity. A quantity of 0 removes the line. Limited like cart writes.

Parameters

Returns

The changed Cart array:

Errors

Example

$cart = $session->updateItem($cart['items'][0]['id'], 3);

Remove a line

$session->removeItem(int $itemId, string|false|null $idempotencyKey = null): array

Removes a line from the cart.

Parameters

Returns

The changed Cart array:

Errors

Example

$cart = $session->removeItem($cart['items'][0]['id']);

Apply a coupon

$session->applyCoupon(string $code, string|false|null $idempotencyKey = null): array

Checked as the shop's own cart page checks it. A coupon only a known customer can use (first order, per customer) stays on the cart for checkout to decide. Limited to 10 attempts a minute and 60 an hour per visitor.

Parameters

Returns

The changed Cart array:

Errors

Example

$cart = $session->applyCoupon('WELCOME10');

Remove the coupon

$session->removeCoupon(string|false|null $idempotencyKey = null): array

Removes the cart's coupon. Removing an auto-applied coupon stops coupons auto-applying to this cart.

Parameters

Returns

The changed Cart array:

Errors

Estimate shipping

$session->estimateShipping(array $destination, string|false|null $idempotencyKey = null): array

The shipping rules the shopper could choose at checkout, priced for a destination as checkout prices them. Only when the shop turned its shipping calculator on (shippingEstimates from shop()). A shop without zones ships anywhere, free. Limited to 30 a minute and 300 an hour per visitor.

Parameters

Request fields

Returns

A ShippingEstimate array:

Errors

Example

$estimate = $session->estimateShipping([
    'shippingCountryCode' => 'SAU',
    'shippingCity' => 'Riyadh',
]);

if ($estimate['shipsTo']) {
    foreach ($estimate['quotes'] as $quote) {
        echo $quote['name'], ': ', $quote['cost'], PHP_EOL;
    }
}

Get a checkout link

$session->checkout(array $options = [], string|false|null $idempotencyKey = null): array

A single-use link to the shop's checkout page with this cart, valid for 30 minutes, for the shopper's browser to open now. Once opened, the cart belongs to that browser and the token no longer reaches it. When requiresSignIn is true, the cart belongs to a shopper, who must be signed in on the shop. A wholesale member's cart (mode enquiry) leads to the shop's cart page, where it is sent as a quotation request. Limited like cart writes.

Parameters

Request fields

Returns

A CheckoutLink array:

Errors

Example

$link = $session->checkout([
    'returnPath' => '/thanks',
    'cartPath' => '/cart',
    'attribution' => ['utmSource' => 'newsletter', 'utmCampaign' => 'november'],
]);

return redirect()->away($link['checkoutUrl']);