Shopisim

Shopisim API

v1.0.0

REST APIJSONJWT Auth

Overview

The Shopisim REST API lets you build custom storefronts, integrate e-commerce into existing websites, or create mobile apps powered by Shopisim shops.

Base URL

https://www.shopisim.com/api

Content Type

application/json

Authentication

Bearer <JWT>

Quick Start

All responses are JSON. Public endpoints require no authentication. Seller/Admin endpoints require a valid JWT token in the Authorization header.

# Fetch a shop's products (no auth required)
curl https://www.shopisim.com/api/public/shops/my-shop/products

# Authenticate and manage your shop
TOKEN=$(curl -s -X POST https://www.shopisim.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"you@example.com","password":"secret"}' | jq -r .token)

curl https://www.shopisim.com/api/seller/shops/me \
  -H "Authorization: Bearer $TOKEN"

Localization

Shopisim supports fr, en, and de locales. Send the Accept-Language header or use the ?locale=en query parameter to get translated content. Error messages are also returned in the requested language.

Pagination

List endpoints return paginated results. Use ?page=1&limit=20 to control pagination. The response includes items, total, page, and limit fields.

{
  "items": [...],
  "total": 142,
  "page": 1,
  "limit": 20
}

Authentication

Register, login, and manage user sessions with JWT tokens.

POST/auth/login

Authenticate a user and receive a JWT token.

Request Body

{
  "username": "user@example.com",
  "password": "SecurePass123!"
}

Response

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."
}
POST/auth/register

Create a new user account. Returns a JWT token immediately.

Request Body

{
  "email": "user@example.com",
  "password": "SecurePass123!",
  "firstName": "Jean",
  "lastName": "Dupont",
  "locale": "fr"
}

Response

{
  "message": "...",
  "user": { "id": 1, "email": "user@example.com", "firstName": "Jean", "lastName": "Dupont" },
  "token": "eyJ0eXAi..."
}
GET/auth/meAuth

Get the authenticated user's profile.

Response

{
  "id": 1, "email": "user@example.com", "firstName": "Jean", "lastName": "Dupont",
  "phone": "+33612345678", "preferredLocale": "fr",
  "roles": ["ROLE_USER", "ROLE_SELLER"], "status": "active",
  "createdAt": "2026-01-15T10:30:00+00:00"
}
PATCH/auth/meAuth

Update the authenticated user's profile.

Request Body

{
  "firstName": "Jean", "lastName": "Martin",
  "phone": "+33612345678", "preferredLocale": "en"
}
POST/auth/me/passwordAuth

Change the authenticated user's password.

Request Body

{
  "currentPassword": "OldPass123!",
  "newPassword": "NewSecurePass456!"
}
POST/auth/verify-email

Verify email address using the token sent by email.

Request Body

{ "token": "abc123..." }
POST/auth/resend-verificationAuth

Resend the verification email.

POST/auth/forgot-password

Request a password reset email. Always returns 200 for security.

Request Body

{ "email": "user@example.com" }
POST/auth/reset-password

Reset password using the token received by email.

Request Body

{ "token": "reset-token", "newPassword": "NewPass456!" }

Shops

Browse and retrieve shop information. All endpoints are public.

GET/public/shops

List all active shops.

Parameters

limitint- Items per page (default 20)
offsetint- Offset for pagination

Response

{
  "items": [
    {
      "id": 1, "name": "Ma Boutique", "slug": "ma-boutique",
      "description": "...", "logoUrl": "https://...",
      "primaryColor": "#174374", "themeCode": "classic", "currency": "EUR"
    }
  ],
  "total": 42
}
GET/public/shops/{slug}

Get full details of a specific shop.

Parameters

slugstringrequired- Shop URL slug
localestring- Locale for translated content (fr, en, de)

Response

{
  "id": 1, "name": "Ma Boutique", "slug": "ma-boutique",
  "description": "...", "logoUrl": "https://...", "bannerUrl": "https://...",
  "faviconUrl": "https://...", "primaryColor": "#174374", "accentColor": "#3375ad",
  "phone": "+33 1 23 45 67 89", "email": "contact@maboutique.fr",
  "address": "123 Rue du Commerce", "city": "Paris", "zipCode": "75001", "country": "France",
  "currency": "EUR", "themeCode": "classic",
  "supportedLocales": ["fr", "en", "de"], "defaultLocale": "fr",
  "shippingCostCents": 499, "customPages": [...], "contentBlocks": [...]
}
GET/public/shops/{slug}/payment-methods

Get enabled payment methods for a shop.

Response

{
  "testMode": false,
  "methods": [
    { "provider": "stripe", "label": "Credit Card", "enabled": true },
    { "provider": "paypal", "label": "PayPal", "enabled": true }
  ]
}

Products

Browse and search products within a shop.

GET/public/shops/{slug}/products

List products for a shop with pagination and search.

Parameters

slugstringrequired- Shop URL slug
pageint- Page number
limitint- Items per page
qstring- Search query
localestring- Locale (fr, en, de)

Response

{
  "items": [
    {
      "id": 1, "title": "T-Shirt Premium", "slug": "t-shirt-premium",
      "priceCents": 2999, "currency": "EUR", "stockQty": 50, "status": "active",
      "category": { "id": 1, "name": "Clothing", "slug": "clothing" },
      "images": [{ "id": 1, "url": "https://...", "alt": "..." }],
      "variants": [{ "id": 1, "name": "Default", "sku": "TSP-001", "priceCents": 2999, "stockQty": 50 }],
      "taxGroup": { "id": 1, "name": "TVA 20%", "rate": 20.00 }
    }
  ],
  "total": 85, "page": 1, "limit": 20
}
GET/public/shops/{slug}/products/{productSlug}

Get detailed information about a specific product.

Parameters

slugstringrequired- Shop URL slug
productSlugstringrequired- Product slug
localestring- Locale (fr, en, de)

Categories

Retrieve shop category tree with subcategories.

GET/public/shops/{slug}/categories

Get the full category tree for a shop (supports nested subcategories).

Parameters

slugstringrequired- Shop URL slug
localestring- Locale (fr, en, de)

Response

{
  "items": [
    {
      "id": 1, "name": "Clothing", "slug": "clothing", "imageUrl": "https://...",
      "productCount": 12,
      "children": [
        { "id": 2, "name": "T-Shirts", "slug": "t-shirts", "productCount": 5, "children": [] }
      ]
    }
  ]
}

Cart

Create and manage shopping carts. Carts are identified by UUID.

POST/public/carts

Create a new cart for a shop.

Request Body

{ "shopSlug": "ma-boutique" }

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "items": [], "totalCents": 0, "taxCents": 0, "totalWithTaxCents": 0
}
GET/public/carts/{id}

Retrieve cart contents with tax breakdown.

Parameters

iduuidrequired- Cart UUID

Response

{
  "id": "550e8400-...",
  "items": [
    {
      "id": 1, "productVariantId": 5, "productTitle": "T-Shirt Premium",
      "variantName": "L / Blue", "qty": 2, "unitPriceCents": 2999,
      "totalCents": 5998, "imageUrl": "https://..."
    }
  ],
  "totalCents": 5998, "taxCents": 1000, "totalWithTaxCents": 6998, "currency": "EUR"
}
POST/public/carts/{id}/items

Add an item to the cart.

Request Body

{ "productVariantId": 5, "qty": 2 }
PATCH/public/carts/{id}/items/{itemId}

Update item quantity.

Request Body

{ "qty": 3 }
DELETE/public/carts/{id}/items/{itemId}

Remove an item from the cart.

Checkout & Payment

Process orders with multiple payment providers. Supports Stripe, PayPal, Flutterwave, CinetPay, bank transfer, cash on delivery, and test mode.

POST/public/checkout

Create an order from a cart. Returns payment instructions based on the selected provider.

Request Body

{
  "cartId": "550e8400-...",
  "paymentProvider": "stripe",
  "cgvAccepted": true,
  "firstName": "Jean", "lastName": "Dupont",
  "email": "jean@example.com", "phone": "+33612345678",
  "shippingAddress": "123 Rue du Commerce",
  "shippingCity": "Paris", "shippingZipCode": "75001", "shippingCountry": "FR"
}

Response

{
  "order": {
    "id": 42, "orderNumber": "ORD-20260313-A1B2C3",
    "status": "pending", "totalCents": 6998, "currency": "EUR"
  },
  "paymentAction": {
    "type": "client_confirmation",
    "clientSecret": "pi_xxx_secret_xxx",
    "publishableKey": "pk_live_xxx"
  }
}

Payment Flow Types

client_confirmation - Confirm payment client-side (Stripe). Contains clientSecret and publishableKey.

redirect - Redirect user to payment page (PayPal, Flutterwave, CinetPay). Contains redirectUrl.

pending - Awaiting manual confirmation (bank transfer). Contains bankDetails.

none - No payment needed (cash on delivery, test mode). Order is confirmed immediately.

POST/public/checkout/verify-return

Verify a payment return after redirect (PayPal, Flutterwave, CinetPay).

Request Body

{
  "provider": "paypal",
  "orderNumber": "ORD-20260313-A1B2C3",
  "transactionId": "PAYID-xxx"
}

Response

{ "status": "paid", "orderNumber": "ORD-20260313-A1B2C3" }

Orders

Retrieve customer order history.

GET/auth/me/ordersAuth

Get the authenticated customer's order history.

Response

{
  "items": [
    {
      "id": 42, "orderNumber": "ORD-20260313-A1B2C3", "status": "shipped",
      "totalCents": 6998, "currency": "EUR", "itemCount": 2,
      "shopName": "Ma Boutique", "shopSlug": "ma-boutique",
      "createdAt": "2026-03-13T14:30:00+00:00"
    }
  ]
}

Invoices

Download order invoices as PDF.

GET/public/orders/{orderNumber}/invoice

Download the invoice PDF for an order.

Parameters

orderNumberstringrequired- Order number (e.g. ORD-20260313-A1B2C3)

Response

Binary PDF (Content-Type: application/pdf)

Contact

Send contact messages to shop owners.

POST/public/contact/{shopSlug}

Send a contact message to a shop.

Request Body

{
  "name": "Marie",
  "email": "marie@example.com",
  "subject": "Question",
  "message": "Hello..."
}

Response

{ "success": true }

Newsletter

Subscribe and unsubscribe from shop newsletters.

POST/public/newsletter/subscribe

Subscribe an email to a shop's newsletter.

Request Body

{ "email": "sub@example.com", "shopSlug": "ma-boutique", "locale": "fr" }

Response

{ "status": "subscribed" }
GET/public/newsletter/unsubscribe/{token}

Unsubscribe using the token from the email.

Blog

Read blog posts.

GET/public/blog

List published blog posts.

Parameters

pageint- Page number
limitint- Items per page
localestring- Locale (fr, en, de)
tagstring- Filter by tag
GET/public/blog/{slug}

Get a specific blog post.

Parameters

localestring- Locale (fr, en, de)

Customer Account

Manage addresses, export data, and delete accounts (GDPR).

GET/auth/me/addressesAuth

List saved addresses.

POST/auth/me/addressesAuth

Create a new address.

Request Body

{
  "label": "Home", "fullName": "Jean Dupont",
  "address1": "123 Rue du Commerce", "address2": "Apt 4B",
  "city": "Paris", "zipCode": "75001", "country": "FR",
  "phone": "+33612345678", "isDefault": true
}
PATCH/auth/me/addresses/{id}Auth

Update an address.

DELETE/auth/me/addresses/{id}Auth

Delete an address.

GET/auth/me/exportAuth

Export all user data (GDPR compliance).

DELETE/auth/meAuth

Delete account and anonymize all data (GDPR compliance). Notifies affected shops.

Seller - Shop Management

Create and manage your shop. Requires ROLE_SELLER.

POST/seller/shopsAuth

Create a new shop.

Request Body

{
  "name": "Ma Boutique", "slug": "ma-boutique",
  "description": "...", "themeCode": "classic",
  "primaryColor": "#174374", "currency": "EUR"
}
GET/seller/shops/meAuth

Get your shop details.

PATCH/seller/shops/meAuth

Update your shop. All fields optional.

Request Body

{
  "name": "...", "slug": "...", "description": "...",
  "primaryColor": "#...", "accentColor": "#...",
  "phone": "+33...", "email": "contact@...",
  "address": "...", "city": "...", "zipCode": "...", "country": "...",
  "seoTitle": "...", "seoDescription": "...", "keywords": "...",
  "themeCode": "classic", "currency": "EUR",
  "customPages": [...], "contentBlocks": [...]
}
POST/seller/shops/me/activateAuth

Activate your shop (make it publicly visible).

GET/seller/shops/me/localesAuth

Get supported locales configuration.

PUT/seller/shops/me/localesAuth

Update supported locales.

Request Body

{ "supportedLocales": ["fr", "en", "de"], "defaultLocale": "fr" }
GET/seller/shops/me/domainAuth

Get custom domain configuration.

POST/seller/shops/me/domainAuth

Set a custom domain.

Request Body

{ "domain": "www.myboutique.com" }
POST/seller/shops/me/domain/verifyAuth

Verify DNS configuration for your custom domain.

DELETE/seller/shops/me/domainAuth

Remove custom domain.

Seller - Products

CRUD operations on products, variants, and translations.

GET/seller/productsAuth

List your products.

Parameters

pageint- Page number
limitint- Items per page
searchstring- Search query
POST/seller/productsAuth

Create a product.

Request Body

{
  "title": "T-Shirt Premium", "slug": "t-shirt-premium",
  "description": "...", "priceCents": 2999, "currency": "EUR",
  "stockQty": 50, "sku": "TSP-001", "categoryId": 1, "taxGroupId": 1
}
GET/seller/products/{id}Auth

Get product details.

PATCH/seller/products/{id}Auth

Update a product (all fields optional).

DELETE/seller/products/{id}Auth

Delete a product.

POST/seller/products/{id}/activateAuth

Activate/publish a product.

Variants

GET/seller/products/{id}/variantsAuth

List product variants.

POST/seller/products/{id}/variantsAuth

Create a variant.

Request Body

{
  "name": "L / Blue", "sku": "TSP-001-L-BL",
  "priceCents": 2999, "stockQty": 20,
  "attributes": { "size": "L", "color": "Blue" }, "active": true
}
PATCH/seller/products/{productId}/variants/{variantId}Auth

Update a variant.

DELETE/seller/products/{productId}/variants/{variantId}Auth

Delete a variant.

Translations

GET/seller/products/{id}/translationsAuth

Get all translations for a product.

PATCH/seller/products/{id}/translations/{locale}Auth

Update translation for a locale.

Request Body

{ "title": "Premium T-Shirt", "description": "English description..." }
POST/seller/products/{id}/auto-translateAuth

Auto-translate product to all supported locales using AI.

Seller - Categories

Manage product categories with subcategory support.

GET/seller/categoriesAuth

List all categories.

POST/seller/categoriesAuth

Create a category.

Request Body

{
  "name": "Clothing", "slug": "clothing",
  "description": "...", "sortOrder": 0, "active": true, "parentId": null
}
PATCH/seller/categories/{id}Auth

Update a category.

DELETE/seller/categories/{id}Auth

Delete a category.

POST/seller/categories/{id}/auto-translateAuth

Auto-translate category using AI.

Seller - Orders

View and manage orders, process workflow transitions.

GET/seller/ordersAuth

List orders for your shop.

Parameters

pageint- Page number
limitint- Items per page
searchstring- Search query
GET/seller/orders/{id}Auth

Get order details including items, shipment info, and available workflow transitions.

GET/seller/orders/{id}/workflowAuth

Get available workflow transitions for an order.

Response

{
  "currentStatus": "paid",
  "availableTransitions": [
    { "name": "process", "label": "Process order" },
    { "name": "ship", "label": "Mark as shipped" }
  ]
}
POST/seller/orders/{id}/workflow/transitionAuth

Apply a workflow transition (e.g., process, ship, deliver, cancel, refund).

Request Body

{ "transition": "ship" }
POST/seller/orders/{id}/shipmentAuth

Add shipment tracking information.

Request Body

{
  "carrier": "DHL",
  "trackingNumber": "1234567890",
  "trackingUrl": "https://tracking.dhl.com/..."
}
POST/seller/orders/{id}/confirm-paymentAuth

Manually confirm a bank transfer payment.

GET/seller/orders/{id}/invoiceAuth

Download order invoice as PDF.

Seller - Media

Upload and manage images for shop, products, and categories. Use multipart/form-data for file uploads.

POST/seller/shops/me/logoAuth

Upload shop logo (multipart/form-data).

DELETE/seller/shops/me/logoAuth

Delete shop logo.

POST/seller/shops/me/bannerAuth

Upload shop banner (multipart/form-data).

DELETE/seller/shops/me/bannerAuth

Delete shop banner.

POST/seller/shops/me/banner/from-urlAuth

Set banner from an external URL.

Request Body

{ "url": "https://images.unsplash.com/..." }
POST/seller/shops/me/favicon/generateAuth

Auto-generate favicon from shop initials or logo.

Request Body

{ "source": "initials" }
POST/seller/shops/me/faviconAuth

Upload custom favicon (multipart/form-data).

DELETE/seller/shops/me/faviconAuth

Delete favicon.

POST/seller/products/{id}/imagesAuth

Upload product image (multipart/form-data).

DELETE/seller/products/{productId}/images/{imageId}Auth

Delete a product image.

PUT/seller/products/{productId}/images/reorderAuth

Reorder product images.

Request Body

{ "imageIds": [3, 1, 2] }
POST/seller/categories/{id}/imageAuth

Upload category image (multipart/form-data).

Seller - Payment Settings

Configure payment providers (Stripe, PayPal, Flutterwave, CinetPay, bank transfer, cash on delivery).

GET/seller/shops/me/payment-settingsAuth

Get payment configuration.

PATCH/seller/shops/me/payment-settingsAuth

Update payment provider settings and credentials.

POST/seller/shops/me/payment-settings/validate-credentialsAuth

Validate payment provider credentials.

POST/seller/shops/me/payment-settings/toggle-test-modeAuth

Toggle test/live mode.

Seller - Email Settings

Customize order notification emails with custom SMTP, templates, and translations.

GET/seller/shops/me/email-settingsAuth

Get email configuration.

PATCH/seller/shops/me/email-settingsAuth

Update email settings (SMTP, template, texts).

POST/seller/shops/me/email-settings/previewAuth

Preview rendered email template.

Request Body

{ "type": "order_confirmation", "locale": "fr" }
POST/seller/shops/me/email-settings/send-testAuth

Send a test email.

Request Body

{ "type": "order_confirmation", "locale": "fr" }

Seller - Newsletter

Manage subscribers and send newsletter campaigns.

GET/seller/shops/me/newsletter/subscribersAuth

List newsletter subscribers.

Parameters

pageint- Page number
searchstring- Search query
POST/seller/shops/me/newsletter/sendAuth

Send a newsletter campaign to all subscribers.

Request Body

{
  "subject": "Spring Collection!",
  "htmlContent": "<h1>New arrivals...</h1>",
  "locale": "fr"
}
GET/seller/shops/me/newsletter/campaignsAuth

List sent campaigns.

POST/seller/shops/me/newsletter/generateAuth

AI-generate newsletter content.

Request Body

{ "topic": "Spring sale", "locale": "fr", "tone": "friendly" }

Seller - Notifications

Real-time notifications via Server-Sent Events (SSE) with polling fallback.

GET/seller/notificationsAuth

List notifications.

Parameters

pageint- Page number
unread_onlybool- Filter unread only
GET/seller/notifications/unread-countAuth

Get unread notification count.

Response

{ "count": 5 }
PATCH/seller/notifications/{id}/readAuth

Mark a notification as read.

POST/seller/notifications/mark-all-readAuth

Mark all notifications as read.

GET/seller/notifications/streamAuth

Server-Sent Events stream for real-time notifications. Keep the connection open.

Seller - AI Tools

AI-powered tools for content generation using Claude and OpenAI.

POST/seller/shops/me/generate-descriptionAuth

AI-generate shop description with SEO optimization and translations.

Request Body

{ "keywords": "artisanal jewelry, handmade, Paris" }
POST/seller/shops/me/generate-legalAuth

AI-generate legal documents (CGV, privacy policy, etc.).

Request Body

{ "type": "cgv", "locale": "fr" }
POST/seller/shops/me/ai-bannerAuth

Search AI-curated banner images.

Request Body

{ "keywords": "fashion boutique modern" }
POST/seller/shops/me/ai-logoAuth

AI-generate a shop logo.

POST/seller/products/ai-generateAuth

AI-generate a complete product listing.

Request Body

{ "name": "Organic Cotton T-Shirt" }
POST/seller/products/{id}/social-captionAuth

AI-generate social media caption for a product.

Request Body

{ "platform": "instagram", "locale": "fr" }
POST/seller/shops/me/auto-translateAuth

Auto-translate all shop content to supported locales.

POST/seller/transcribeAuth

Transcribe an audio file to text (multipart/form-data).

Webhooks

Payment provider webhook endpoints. These are called by payment providers to confirm transactions.

The following webhook URLs are configured per payment provider:

POST /webhooks/stripe

POST /webhooks/paypal

POST /webhooks/flutterwave

POST /webhooks/cinetpay

POST /webhooks/orange_money

POST /webhooks/mtn_momo

These endpoints are for internal use by payment providers. You don't need to call them directly.

Error Handling

All errors follow a consistent JSON format with localized messages.

{
  "code": 401,
  "message": "Invalid credentials"
}

// validation:
{
  "error": "This email is already in use"
}

HTTP Status Codes

200 Success
201 Created
204 Deleted (no content)
400 Validation error
401 Not authenticated
403 Forbidden
404 Not found
500 Server error

Rate Limits

API usage guidelines.

Please be respectful of API usage. General guidelines:

  • Public endpoints: no hard limit, but avoid excessive polling
  • Authenticated endpoints: designed for single-shop usage patterns
  • AI endpoints: subject to upstream provider limits, use sparingly
  • SSE stream: maintain a single connection per session
  • File uploads: max 10 MB per file

For high-volume integrations, please contact us.

© 2026 Shopisim. All rights reserved.

Interactive Swagger UI also available at /api/doc