Implement Platform Interface APIs

Server implementation

The server implementation must follow the Simpler APIs, which comply with the OpenAPI Specification. The Platform Interface exposes several endpoint groups — three are required to enable checkout, one is recommended, and the remaining groups are optional and unlock specific capabilities.

Required

These three endpoints are the minimum needed to enable Simpler checkout on your storefront.

• Product Details — called when Simpler needs to retrieve information on your store's product catalog in order to display 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.

Recommended

• Webhooks — 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.

Optional

Implement these as the capability applies to your store.

• Reporting — paginated orders feed that unlocks several analytics benefits on the Simpler platform.
• Refunds — lets Simpler confirm a refund was recorded on your side when one is issued.
• Customer — customer identification and lookup for logged-in or returning-shopper flows.
• Pickup Stores — required only if your store offers in-store pickup as a fulfillment option.
• Product Feed — bulk catalog sync endpoint for onboarding or periodic reconciliation.

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 tables show how a platform interface hosted at https://www.my-interface.com should be organized. The required endpoints are the minimum for a working integration; recommended and optional endpoints are listed separately so the required bar stays scannable.

Required

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
Order Submission	/simpler/v1/submit	https://www.my-interface.com/simpler/v1/submit

Recommended

API	Resource Endpoint	Example Route
Webhooks	/simpler/v1/webhooks	https://www.my-interface.com/simpler/v1/webhooks

Optional

API	Resource Endpoint	When to implement
Reporting	/simpler/v1/reporting	Unlock Simpler analytics on historical orders.
Refunds	/simpler/v1/refunds	Required if Simpler should confirm refund receipts to your system.
Customer	/simpler/v1/customer	Required for logged-in customer flows or loyalty.
Pickup Stores	/simpler/v1/stores	Required only if offering in-store pickup as a fulfillment option.
Product Feed	/simpler/v1/products/feed	Bulk catalog sync for onboarding or periodic reconciliation.

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 network timeout) — Simpler retries on an exponential backoff before marking the order failed for manual review.
• Handled errors (4xx status code) — treated as terminal; an alert for manual handling is raised immediately.

See the Retries & Timeouts reference for concrete retry counts, backoff, and the 30-second per-attempt response timeout that applies to every /submit call.

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

When a Platform Interface call cannot succeed, return a JSON body of shape { code, message } with HTTP 400. The code values that influence the shopper-facing message are a closed set — see the Error Codes reference for the catalog and endpoint scoping.

If your server responds with a 5xx error code, or the response body contains malformed JSON, the checkout raises an unrecoverable error. Handle domain errors (Invalid Coupons, Unshippable addresses, Out-of-stock products) by returning the appropriate 4xx error code instead.

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.

Evaluating the integration or have a specific question? The Custom Integrations FAQ answers the most common questions about retries, lifecycle, payment states, and webhooks.