Auth
Customer-facing OTP login. Requesting an OTP delivers a 4–6 digit code over SMS or email; verifying it issues a session cookie that subsequent calls (cart, checkout, orders) recognise as the same customer.
GET /api/v1/auth/status
Returns the current session, useful for hydrating storefronts that don’t want to keep client-side identity state.
Request
curl https://api.cimplify.io/api/v1/auth/status \
-H "X-Public-Key: pk_test_your_publishable_key"Response
{
"success": true,
"data": {
"is_authenticated": true,
"customer": {
"id": "cus_01H…",
"name": "Ama Mensah",
"email": "ama@example.com",
"phone": "+233241234567"
}
}
}Anonymous sessions return is_authenticated: false and customer: null.
POST /api/v1/auth/request-otp
Send a one-time passcode to a phone number or email. The server picks the channel from contact_type; if omitted, it’s inferred from the format of contact.
Body
| Field | Type | Description |
|---|---|---|
contact | string | E.164 phone (+2332…) or email. Required. |
contact_type | string | Optional. phone or email. |
Request
curl -X POST https://api.cimplify.io/api/v1/auth/request-otp \
-H "X-Public-Key: pk_test_your_publishable_key" \
-H "Content-Type: application/json" \
-d '{"contact": "+233241234567", "contact_type": "phone"}'Response
{
"success": true,
"data": {
"delivery_channel": "sms",
"expires_in_seconds": 300,
"next_resend_in_seconds": 30
}
}POST /api/v1/auth/verify-otp
Exchange the OTP for an authenticated session. The field is otp_code, not code. On success the response sets a session cookie and returns the resolved customer.
Body
| Field | Type | Description |
|---|---|---|
contact | string | Same value as the request-OTP call. Required. |
otp_code | string | 4–6 digit code. Required. |
contact_type | string | Optional phone / email. |
Request
curl -X POST https://api.cimplify.io/api/v1/auth/verify-otp \
-H "X-Public-Key: pk_test_your_publishable_key" \
-H "Content-Type: application/json" \
-d '{
"contact": "+233241234567",
"otp_code": "847362"
}'Response
{
"success": true,
"data": {
"customer": {
"id": "cus_01H…",
"name": "Ama Mensah",
"email": "ama@example.com",
"phone": "+233241234567"
},
"session": {
"expires_at": "2026-05-08T10:30:00Z"
}
}
}Errors
400 VALIDATION_ERROR:otp_codeempty, fewer than 4 or more than 6 chars.401 UNAUTHORIZED: code expired, mismatched, or already redeemed.
POST /api/v1/auth/logout
Invalidate the active session. Returns { success: true, data: null }.
curl -X POST https://api.cimplify.io/api/v1/auth/logout \
-H "X-Public-Key: pk_test_your_publishable_key"POST /api/v1/auth/profile
Update one or more fields on the active customer record. At least one of name, email, phone must be supplied.
Request
curl -X POST https://api.cimplify.io/api/v1/auth/profile \
-H "X-Public-Key: pk_test_your_publishable_key" \
-H "Content-Type: application/json" \
-d '{"name": "Ama N. Mensah"}'Response
{
"success": true,
"data": {
"id": "cus_01H…",
"name": "Ama N. Mensah",
"email": "ama@example.com",
"phone": "+233241234567"
}
}-
Orders List orders for the authenticated customer.
-
Subscriptions Manage recurring billing for the logged-in customer.
Checkout
Convert the active cart into an order, run payment, and return everything the caller needs to confirm or redirect. The body is **flat**: fields like `cart_id`, `customer`, and `payment_method` sit at the top level. There is no `checkout_data` wrapper.
Orders
Read and manage orders created by checkout. Authenticated customers get their own orders; guests can access individual orders by passing the order’s `bill_token` as a query parameter.