Replacing Checkout (Server-Side)

Use this approach when you want your server to redirect users to Simpler Checkout at the point where they would normally enter your CMS's native checkout.

If you don't need server-side control and just want a simple frontend redirect, see Replacing Checkout (Client-Side) instead.

No Authentication Required

This endpoint does not require any authentication headers. You only need your merchant_id (App ID).

Overview

The flow has three steps:

1. Build a Cart Request object describing the user's cart.
2. POST it to the Simpler endpoint.
3. Forward the redirect response to the user's browser.

After the redirect, the user lands on the Simpler Checkout page where they complete their purchase. Simpler will then call your Platform Interface APIs to price the cart, resolve shipping, and submit the order.

Cart Request Schema

The Cart Request is a JSON-serializable object with the following fields:

Field	Type	Required	Description
merchant_id	string	Yes	Your Simpler Store App ID.
currency	string	Yes	ISO 4217 currency code (EUR, USD, GBP).
locale	string	Yes	IETF language tag per RFC 5646 (e.g. en, el, fr).
items	array	Yes	One or more line items. See below.
coupon	string	No	A coupon code to pre-apply in the Simpler checkout form.
metadata	object	No	Arbitrary key-value pairs passed through to your backend on every subsequent Platform Interface call for this session. Useful for tracking attribution, A/B test buckets, or internal references.

items[]

Field	Type	Required	Description
id	string	Yes	Product identifier as used in your Platform Interface product catalog.
quantity	integer	Yes	Number of units.
attributes	object	No	Key-value pairs that identify a specific product variant (e.g. {"color": "blue", "size": "L"}).

Sending the Request

POST the cart data as application/x-www-form-urlencoded to:

https://checkout.simpler.so/v1/carts

On success, the server responds with a 303 See Other status and a Location header pointing to the Simpler Checkout page. Your server should forward this redirect to the user's browser.

PHP + cURL Example

$url = 'https://checkout.simpler.so/v1/carts';
$data = [
  'merchant_id' => 'YOUR_APP_ID',
  'currency' => 'EUR',
  'locale' => 'en',
  'items' => [
    [
      'id' => 'PRODUCT_ID',
      'quantity' => 1,
      'attributes' => [
        'foo' => 'bar'
      ]
    ]
  ],
  'coupon' => 'WELCOME10',
  'metadata' => [
    'source' => 'cart_page'
  ]
];

$ch = curl_init($url);

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HEADER         => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => http_build_query($data),
    CURLOPT_FOLLOWLOCATION => false,
]);

$response = curl_exec($ch);
$info = curl_getinfo($ch);

if ($info['http_code'] == 303 || $info['http_code'] == 302) {
    preg_match('/^Location:\s+(.*)$/mi', $response, $matches);
    $location = trim($matches[1]);

    curl_close($ch);
    header("Location: $location", true, $info['http_code']);
    exit;
}

// The request did not result in a redirect — something went wrong.
$headerSize = $info['header_size'];
$body = substr($response, $headerSize);
curl_close($ch);

error_log("Cart request failed with status {$info['http_code']}: $body");

Error Responses

All error responses return a JSON body with a message field describing the issue.

Status Code	Meaning
400	Invalid request body.
404	Invalid App ID / Store not found.
500	Internal server error.