Implement Platform Interface APIs

Server implementation

The server implementation must follow the Simpler APIs, which comply with the OpenAPI Specification. There are 3 required APIs (and 1 optional) that you must implement, grouped around the resources required by Simpler:

Product Details

Called when Simpler needs to retrieve information on your store's product catalog in order to display product titles, images and options.

Quotes

Called when Simpler needs to price the carts opened via Simpler and retrieve available shipping & payment options.

Order Submission

Called as the final step in the checkout process to submit the completed order to your system.

Reporting orders data (Optional)

Called on a paginated schedule to incrementally retrieve orders data and unlock several benefits by enhancing the Simpler analytics platform.

Webhooks (Highly Recommended)

An endpoint on your server that Simpler calls to notify you of events that happen outside the standard request/response flow, such as payment confirmations for asynchronous methods (MultiBanco, Sequra), order cancellations or refunds.

Once your webhook endpoint is live and publicly accessible, share the full URL with our Integrations Support team so we can register it against your account.

General server requirements

The server you implement must meet the following requirements:

• Must be publicly accessible via a stable domain.
• Must accept requests from Simpler public IP addresses.
• Must handle JSON requests and return JSON responses.

Endpoint configuration

The server you use as the platform interface should be hosted entirely on a single domain to support each API. The following table shows how a platform interface hosted at https://www.my-interface.com should be organized:

API	Resource Endpoint	Example Route
Products	/simpler/v1/products	https://www.my-interface.com/simpler/v1/products
Quotes	/simpler/v1/quote	https://www.my-interface.com/simpler/v1/quote
Orders	/simpler/v1/submit	https://www.my-interface.com/simpler/v1/submit
Webhooks	/simpler/v1/webhooks	https://www.my-interface.com/simpler/v1/webhooks

Create the API server

You must set up the API server code to handle requests and interact with your store. Create the code manually or use an OpenAPI generator.

Either method begins with retrieving the Platform Interface API Specifications.

An OpenAPI generator like Swagger Codegen or OpenAPI Generator can be used to create a server stub for the platform interface. This can speed up the process by automatically generating boilerplate code to handle incoming requests.

Ensure all paths are handled as outlined in the specification.

Authentication

Every request from Simpler includes an X-Simpler-CRC header. This is an HMAC-SHA1 signature of the raw request body, computed using your App Secret.

You should validate this header on every incoming request to confirm it originates from Simpler. In pseudo-code:

expected = hmac_sha1(request_body, your_app_secret)
valid    = (expected == request.header("X-Simpler-CRC"))

PHP example using Symfony's Request object:

public static function validateCRC(Request $request, string $secret): bool
{
  return hash_hmac("sha1", $request->getContent(), $secret) === $request->headers->get('X-Simpler-CRC');
}

Best Practices

When planning your implementation, it is preferable to start with a basic end-to-end flow that handles a simple product with minimal configuration and a single shipping option, in order to get the hang of how the three endpoints interoperate. You can find a complete example of the minimum viable implementation in our Tutorials section.

Stateless Quotations

The goal is to use the Platform Interface as a thin adapter to your existing store logic. The Quotation endpoint in particular should lean into your existing cart/pricing logic instead of duplicating rules for Simpler.

The Platform Interface is designed to be used in a stateless manner — avoid synchronizing cart state between requests. Instead:

• Create an ephemeral cart for every quotation request.
• Delegate pricing, discounts and shipping resolution to your core system.
• Destroy the cart after responding to Simpler.

Cart Metadata

In the rare case where stateless quotations are not applicable to your system, you can use the cart metadata field to store state that will be returned to you in all subsequent requests for the same session.

This approach is not recommended — you will need to implement eviction logic, and long-lived carts (e.g. a shopper keeping a tab open for hours or days) may fail to checkout.

Handling Shopper Data

Quotation & Order Submission requests include partial shopper data to enable cross-domain identification of customers. You can use the supplied email to check if they are already a registered customer (e.g. to offer special discounts or validate coupon ownership).

You MUST NOT store personal data for new shoppers, except when submitting orders.

Order Submission Failures

The checkout process takes place entirely within Simpler. Once the shopper completes their payment, their order is stored on Simpler alongside the payment authorization, and Simpler will attempt to submit the order to your systems.

If your systems cannot accept the submission (network issue, validation error, or malformed response), the order is still stored and the shopper sees a partial success screen. Their payment is authorized but not yet captured, and a manual support issue is raised.

• Retryable errors (5xx status code or malformed response) — Simpler will retry submission a few times before raising an alert for manual handling.
• Handled errors (4xx status code) — An alert for manual handling is raised immediately.

Idempotence

If Simpler submits an order, it is stored on your system, but something goes wrong in the response, Simpler may retry the submission. The request includes the simpler_id property — store this alongside your order and enforce uniqueness to avoid duplicates.

Error Handling

Pay special attention to the error response examples in the Full API Reference, as they will be used in order to display meaningful error messages to shoppers when their checkout cannot be processed.

If your server responds with a 5xx error code, or the response body contains malformed JSON the checkout will raise an unrecoverable error, so make sure your server handles domain errors (such as Invalid Coupons, Shipping addresses that are not serviced, Out of stock products etc.) meaningfully.

Testing & Troubleshooting

Contract Testing

When beginning your Platform Interface implementation, use the API Reference & Examples sections as a guide. Issue manual requests to your system to validate the desired behaviour before wiring everything up.

Test Stores

You can create a test store through the Simpler Merchant Dashboard and use these credentials to test full examples. If you have not yet implemented the Javascript SDK Integration, you can construct your own Simpler URLs and test that everything works as expected.

Constructing a Checkout URL is as simple as :

https://checkout.simpler.so/?app=<YOUR_APP_ID>&cur=<EUR|USD|GBP>&prd=[{"id":"<YOUR_PRODUCT_ID>","qty":1}]

Debug View

The Simpler Merchant Dashboard hosts a nifty debug view that you can use to debug your Platform interface implementation, containing the full HTTP Request & Response headers and bodies, as well as information on any errors encountered by the Simpler platform when processing these requests.

Next Steps

Ready to start building?

Follow the Basic Flow Tutorial for a complete, step-by-step walkthrough of implementing all three endpoints with working code examples.