Skip to main content
Version: Thelia 3

API Endpoints Reference

Reference documentation for Thelia's core API endpoints.

Order returns are behind a setting

The order return resources answer 404, rather than 403, while order_return_enabled is off. See Order Returns.

Endpoint overview​

Admin endpoints (/api/admin/)​

Full CRUD operations requiring authentication.

ResourceEndpointOperations
Products/api/admin/productsGET, POST, PUT, PATCH, DELETE
Categories/api/admin/categoriesGET, POST, PUT, PATCH, DELETE
Customers/api/admin/customersGET, POST, PUT, PATCH, DELETE
Orders/api/admin/ordersGET, POST, PUT, PATCH, DELETE
Brands/api/admin/brandsGET, POST, PUT, PATCH, DELETE
Tax Rules/api/admin/tax_rulesGET, POST, PUT, PATCH, DELETE
Features/api/admin/featuresGET, POST, PUT, PATCH, DELETE
Attributes/api/admin/attributesGET, POST, PUT, PATCH, DELETE
Contents/api/admin/contentsGET, POST, PUT, PATCH, DELETE
Folders/api/admin/foldersGET, POST, PUT, PATCH, DELETE
Currencies/api/admin/currenciesGET, POST, PUT, PATCH, DELETE
Countries/api/admin/countriesGET, POST, PUT, PATCH, DELETE
Modules/api/admin/modulesGET, POST, PUT, DELETE
Sales/api/admin/salesGET (collection, item)
Order returns/api/admin/order_returnsGET, POST, PUT, PATCH, DELETE
Order return lines/api/admin/order_return_linesGET, POST, PATCH
Order return reasons/api/admin/order_return_reasonsGET, POST, PUT, PATCH, DELETE
Order return statuses/api/admin/order_return_statutesGET (collection, item)
Product relation types/api/admin/product_association_typesGET, POST, PUT, PATCH, DELETE
Product relations/api/admin/product_associationsGET, POST, DELETE
Subscriptions/api/admin/subscriptionsGET (collection, item)
Subscription plans/api/admin/subscription_plansGET, POST, PUT, PATCH, DELETE
Customer tags/api/admin/tagsGET, POST, PUT, PATCH, DELETE
Customer tag attachments/api/admin/tag-elementsGET, POST, DELETE
Newsletter subscribers/api/admin/news_lettersGET, POST, PUT, PATCH, DELETE
Payment journal of an order/api/admin/orders/{orderId}/payment_transactionsGET (collection)
Payment summary of an order/api/admin/orders/{orderId}/paymentGET
Capture of an order/api/admin/orders/{orderId}/capturePOST

Front endpoints (/api/front/)​

Mostly read-only public access. A few operations write data (cart management, account creation, account updates) and several require a customer JWT.

ResourceEndpointOperations
Products/api/front/productsGET (collection, item)
Categories/api/front/categoriesGET (collection, item)
Brands/api/front/brandsGET (collection, item)
Contents/api/front/contentsGET (collection, item)
Feature products/api/front/feature_productsGET (collection, item)
Cart/api/front/cartsPOST, GET (item), PUT, DELETE
Current cart/api/front/cartGET
Customers/api/front/customersPOST
Customer account/api/front/account/customers/{id}GET, PUT
Orders/api/front/account/ordersGET (collection)
Order detail/api/front/account/orders/{id}GET
Countries/api/front/countriesGET (collection, item)
Sales/api/front/salesGET (collection, item)
Product relation types/api/front/product_association_typesGET (collection, item)
Product relations/api/front/product_associationsGET (collection, item)
Account order returns/api/front/account/order_returnsGET (collection, item), POST
Account subscriptions/api/front/account/subscriptionsGET (collection, item), POST (cancel, pause, resume, payment_method)
Subscription plans/api/front/subscription_plansGET (collection, item)
Guest account conversion/api/front/guest-customers/{id}/convertPOST
Checkout/api/front/account/checkout/{cartId}POST (delivery_address, invoice_address, delivery_module, payment_module, place), GET (validation)
note

The current-cart shortcut /api/front/cart returns the cart bound to the current session through a dedicated controller, so you do not need to know its id. The collection-style /api/front/carts/{id} operations require customer authentication.

caution

Customer and order personal-data routes (/api/front/account/customers/{id}, /api/front/account/orders, /api/front/account/orders/{id}) require a customer JWT and only expose the authenticated customer's own data. The POST /api/front/customers operation is the public account-creation endpoint.

The checkout operations are documented on their own page: Checkout over the front API.

Promotions are not served by the front API​

Since 3.4 the front API no longer serves promotions. GET /api/front/coupons, GET /api/front/coupons/{id} and GET /api/front/coupons/{code}/by-code answer 404, and the serialization groups front:coupon:read and front:coupon:read:single are gone with them. Thelia\Api\Resource\Coupon is no longer an API resource. A customer enters a code through the cart. A module that used those groups, extended the resource through an addon or built its IRI has to drop that use.

Registering an account​

POST /api/front/customers takes this body:

{
"firstname": "Ada",
"lastname": "Lovelace",
"email": "ada@example.com",
"password": "a long passphrase",
"langId": 1,
"registrationToken": "optional-token-of-a-registration-link"
}

firstname, lastname, email and password are required. langId is optional and must be an existing language. registrationToken is optional: left out, the account joins the default customer group, and a token that opens no group is refused with nothing created. The fields customerTitle and lang (an IRI) are not read. The e-mail address must not belong to an account yet, and the password must reach the length set by password.length.

An account read from /api/front/account/customers/{id} no longer carries confirmationToken. A client that read it must use the link sent by e-mail.

Subscriptions​

Added in Thelia 3.4. The feature is described in Subscriptions. Null fields are left out of the JSON.

Front: the account of the customer​

These routes need a customer JWT and only reach the subscriptions of that customer.

RequestEffect
GET /api/front/account/subscriptionsThe subscriptions of the customer.
GET /api/front/account/subscriptions/{id}One subscription, with its installments.
POST /api/front/account/subscriptions/{id}/cancelCancels it. No body.
POST /api/front/account/subscriptions/{id}/pausePauses an active subscription, when its plan allows. No body.
POST /api/front/account/subscriptions/{id}/resumeResumes a paused subscription, and nothing else. No body.
POST /api/front/account/subscriptions/{id}/payment_methodChanges the payment method, of any subscription still billed but a cancelled one.
POST /api/front/account/subscriptions/3/payment_method
Content-Type: application/json

{"paymentMethod": "/api/front/account/payment_methods/12"}
StatusWhen
401No token.
403An administrator token.
404The subscription is another customer's.
409The state of the subscription refuses the action.
422The payment method is not the customer's.

A subscription:

{
"id": 3,
"ref": "SUB1A2B3C4D5E6F",
"status": "active",
"quantity": 1,
"periodUnit": "month",
"periodCount": 1,
"commitmentCount": 3,
"pausable": true,
"unitPrice": 9.9,
"installmentsBilled": 1,
"currentPeriodStart": "2028-01-31T10:00:00+01:00",
"currentPeriodEnd": "2028-02-29T10:00:00+01:00",
"nextBillingAt": "2028-02-29T10:00:00+01:00",
"createdAt": "2028-01-31T10:00:00+01:00",
"currencyCode": "EUR",
"productId": 12,
"productRef": "BOX",
"productTitle": "Monthly box",
"paymentMethodLabel": "Visa ending 4242",
"paymentMethodId": 5,
"initialOrderId": 40,
"initialOrderRef": "ORD000000000040",
"installments": [
{"number": 1, "state": "paid", "orderId": 40, "orderRef": "ORD000000000040", "date": "2028-01-31", "attemptCount": 1}
]
}

The payment method is shown by its label only, never by its token.

Front: the plans of a product​

GET /api/front/subscription_plans?product.id=12 lists the visible plans of an online product, and GET /api/front/subscription_plans/{id} reads one. price is the price of one installment in the currency being browsed.

A plan follows its product. The plan of a product the visitor may not see (a private drop they are not part of, a category closed to their customer group, a rule of a module) is left out of the list and answers 404 by id, as the product does. When the product shows no price to the visitor (prices for signed-in customers only, prices on request), the plan comes without price.

{
"id": 7,
"periodUnit": "month",
"periodCount": 1,
"trialDays": 14,
"commitmentCount": 3,
"pausable": false,
"position": 1,
"i18ns": {"en_US": {"title": "Monthly box"}},
"productId": 12,
"price": 9.9,
"currencyCode": "EUR"
}

A plan goes into the cart with subscriptionPlanId on the line. The cart refuses a plan beside any other line, a second plan, a plan that is not visible or not the product's, and a visitor who is not a signed-in customer, with a 422.

Admin​

GET /api/admin/subscriptions and /{id} need the admin.subscription right. They accept the filters status, ref and customer.id, and the order nextBillingAt. They add customer, failureCount and nextRetryAt to the subscription, and lastError to each installment.

/api/admin/subscription_plans supports POST, GET, PUT, PATCH and DELETE. prices replaces every price when it is sent, and a price in the default currency is required:

{
"product": "/api/admin/products/12",
"periodUnit": "month",
"periodCount": 1,
"trialDays": 7,
"pausable": true,
"visible": true,
"installmentCount": null,
"commitmentCount": 3,
"i18ns": {"en_US": {"title": "Monthly box"}},
"prices": [{"currencyId": 1, "price": 12.5, "fromDefaultCurrency": false}]
}

Newsletter subscribers​

/api/admin/news_letters lists and edits the subscribers. It needs the rights on customers. It filters on id, email and unsubscribed. It keeps working when the shop has turned its newsletter off. See Newsletter.

Payment journal and capture​

Added in Thelia 3.4. Every order keeps a journal of its money movements. These operations read it and let an administrator take money held by an authorization. Nothing of it is exposed on the front API.

RequestRightEffect
GET /api/admin/orders/{orderId}/payment_transactionsadmin.orderThe journal, latest movement first, twenty a page.
GET /api/admin/orders/{orderId}/paymentadmin.orderThe sums of the journal, and whether the payment module can capture.
POST /api/admin/orders/{orderId}/captureadmin.order.payment-capture (create)Captures through the payment module.

A line of the journal has the fields id, type, state, amount, currencyId, pspReference, parentId, paymentModuleId, actorType, actorLabel, adminId, errorCode, errorMessage and createdAt. amount is a decimal string.

The summary holds transactionRef, paymentModuleId, paymentModuleCode, authorized, captured, voided, refunded, pendingCapture and remainingToCapture, all amounts as decimal strings, and supportsCapture. remainingToCapture is what the authorization still holds once the captures waiting for their answer are set aside. It is zero when the module took the price at once, or when its provider takes a single capture and one was asked.

Capturing​

POST /api/admin/orders/42/capture
Authorization: Bearer <administrator JWT>
Content-Type: application/json

{"amount": 50.0}

amount is in the currency of the order. Send {} or {"amount": null} to capture everything still held. The answer is 201 with the line of the journal the capture wrote. The line is succeeded, failed with the code and the message of the provider, or pending when the provider answers later.

StatusWhen
403The administrator lacks the admin.order.payment-capture right.
404No such order.
409The same amount was captured on the order within the last minute, or another worker is writing its journal. A repeated call is not taken twice.
422The module takes the price at once, nothing is left to capture (a capture waiting for its answer counts as taken), the amount is not positive, has more decimals than the currency or exceeds the authorization, or the provider refused.
429The administrator account asked more captures than THELIA_API_RATE_LIMIT_ORDER_CAPTURE allows in a minute, 10 by default. The answer carries Retry-After and the module is not called. See Rate limiting.
502The module could not reach its provider. The capture stays pending in the journal.
500Any other failure. It is a fault of the shop, not the silence of the provider.

The back office and the API share these guards, so neither a double click nor a retried call takes the money twice. An administrator who signs in with a JWT is the author of the journal and history lines the call writes.

Updating an order​

PUT or PATCH /api/admin/orders/{id} follows two rules:

  • It answers 422 when it changes the transactionRef or the paymentModule of an order whose journal holds a line. A refund or a release would otherwise go to the transaction of another order. An order without a journal takes them as before. The orders paid before 3.4.0 get a journal line on update, so an integration that rewrites their transactionRef is refused too. No reference and an empty one count as the same.
  • With a new status, it checks the transition graph first, and the capture right when the status cancels an order whose authorization still holds an amount (403). A refused transition answers 422. Nothing of the request is written before these checks. The other fields are then written in the transaction that writes the status, under the lock of the order. The listeners of the status change run after it is committed, since they call payment modules and write the journal.

Common patterns​

Collection request​

GET /api/front/products?visible=true&itemsPerPage=20&page=1
Accept: application/ld+json

Sorting a collection​

Sorting is asked for with the order parameter, keyed by the property to sort on, with asc or desc as its value:

GET /api/front/products?order[createdAt]=desc&itemsPerPage=20

The product collection, both on /api/admin/products and on /api/front/products, sorts on:

PropertySorts by
refThe product reference
positionThe manual position
productCategories.positionThe manual position inside a category
productCategories.createdAtThe date the product was added to the category
createdAtThe date the product was created
updatedAtThe date the product was last written
titleThe product title in the requested language

The two productCategories sorts need the productCategories.category.id filter in the same request (see OrderFilter). The newest arrivals of a category come with:

GET /api/front/products?productCategories.category.id=10&order[productCategories.createdAt]=desc

order[title] is a filter of its own rather than the generic one, because a title lives in the translation rows of the product: sorting through the plain relation path would multiply the rows of the collection. It takes the same asc and desc values as the others.

Several keys can be combined, and they apply in the order they are written:

GET /api/front/products?order[position]=asc&order[title]=asc

Collection response​

{
"@context": "/api/contexts/Product",
"@id": "/api/front/products",
"@type": "hydra:Collection",
"hydra:totalItems": 150,
"hydra:member": [
{
"@id": "/api/front/products/1",
"@type": "Product",
"id": 1,
"ref": "PROD-001",
"visible": true,
"i18ns": {
"title": "Product Title",
"description": "..."
}
}
],
"hydra:view": {
"@id": "/api/front/products?page=1",
"hydra:first": "/api/front/products?page=1",
"hydra:last": "/api/front/products?page=8",
"hydra:next": "/api/front/products?page=2"
}
}

Single item request​

GET /api/front/products/1
Accept: application/ld+json

Single item response​

{
"@context": "/api/contexts/Product",
"@id": "/api/front/products/1",
"@type": "Product",
"id": 1,
"ref": "PROD-001",
"visible": true,
"position": 1,
"createdAt": "2024-01-15T10:30:00+00:00",
"i18ns": {
"title": "Product Title",
"description": "Full product description...",
"chapo": "Short description",
"postscriptum": "Additional notes"
},
"productCategories": [...],
"productSaleElements": [...],
"featureProducts": [...]
}

Create request (admin)​

POST /api/admin/products
Content-Type: application/json
Authorization: Bearer {token}

{
"ref": "NEW-PROD-001",
"visible": true,
"taxRule": "/api/admin/tax_rules/1",
"productCategories": [
{
"category": "/api/admin/categories/5",
"defaultCategory": true
}
],
"i18ns": {
"en_US": {
"title": "New Product",
"description": "Product description"
}
}
}

Update request (admin)​

Use PATCH to change part of a resource. Properties the payload leaves out keep their value.

PATCH /api/admin/products/1
Content-Type: application/merge-patch+json
Authorization: Bearer {token}

{
"visible": false
}

The Content-Type matters: a PATCH sent as application/json answers 415.

PUT replaces the whole resource​

PUT writes the resource the payload describes, so every writable property the payload omits is emptied. Sending only the property you want to change deletes the rest:

PUT /api/admin/products/1
Content-Type: application/json
Authorization: Bearer {token}

{
"visible": false
}

That request answers 422 naming taxRule, ref and i18ns, the writable properties it left out. Use PUT when you send the complete resource, and PATCH otherwise.

Nested collections are replaced, not merged​

A collection sent inside its parent replaces the collection that was there, for PATCH as well as for PUT. This follows the JSON merge patch rules, where an array is replaced as a whole.

The practical consequences on a product and its sale elements:

  • A sale element absent from productSaleElements is deleted, along with its attribute combinations and its customer family prices.
  • A sale element present but carrying no productPrices ends up with no price.
  • A sale element with no id is matched on its ref under the same product, so a client holding its own references keeps addressing the same row. Two rows sharing a reference are ambiguous, and a new one is created instead.

To update a sale element on its own, address it directly and leave productSaleElements out of the product payload:

PATCH /api/admin/product_sale_elements/42
Content-Type: application/merge-patch+json
Authorization: Bearer {token}

{
"quantity": 12
}

Delete request (admin)​

DELETE /api/admin/products/1
Authorization: Bearer {token}

Error responses​

note

Error responses use the Hydra format regardless of the Accept header you send.

400 Bad Request​

{
"@context": "/api/contexts/ConstraintViolationList",
"@type": "ConstraintViolationList",
"hydra:title": "An error occurred",
"hydra:description": "ref: This value should not be blank.",
"violations": [
{
"propertyPath": "ref",
"message": "This value should not be blank."
}
]
}

422 Unprocessable Entity​

A write that breaks a validation rule answers 422 and writes no row. Each violation names the property at fault in propertyPath:

{
"@context": "/api/contexts/ConstraintViolation",
"@type": "ConstraintViolation",
"status": 422,
"violations": [
{
"propertyPath": "firstname",
"message": "This value should not be blank.",
"code": "c1051bb4-d103-4f74-8988-acbcafc7fdc3"
},
{
"propertyPath": "lastname",
"message": "This value should not be blank.",
"code": "c1051bb4-d103-4f74-8988-acbcafc7fdc3"
}
],
"detail": "firstname: This value should not be blank.\nlastname: This value should not be blank.",
"hydra:title": "An error occurred",
"hydra:description": "firstname: This value should not be blank.\nlastname: This value should not be blank."
}

The checks that clients synchronising data, such as an ERP, run into most often:

RequestRefused whenViolations
POST /api/admin/customers, POST /api/front/customersfirstname or lastname is left out or emptyfirstname, lastname
PUT /api/admin/customers/{id}, PUT /api/front/account/customers/{id}firstname or lastname is left out or emptyfirstname, lastname
PUT /api/admin/customers/{id}email or password is left out or empty, as a PUT replaces the whole resourceemail, password
PATCH /api/admin/customers/{id}firstname or lastname is sent emptyfirstname, lastname
POST /api/admin/customersemail is left out, empty or not an email address, or password is left out or emptyemail, password
POST /api/admin/product_sale_elements, PUT /api/admin/product_sale_elements/{id}product or ref is left out or empty, or quantity is left outproduct, ref, quantity
PUT on another admin resourcea required property is left out (see PUT replaces the whole resource)the properties left out

Two customer checks answer in their own way: a password shorter than the password.length setting gives a violation with an empty propertyPath, and an email address another customer already uses is refused.

Property names are the ones the resource declares: a payload sending firstName where the customer resource reads firstname is refused as a customer without a first name. A quantity of 0 is accepted.

A violation found in a nested resource carries the path to that resource. When the second address posted with a customer has an empty label, the response names addresses[1].label, the index being the position of the address in the payload:

{
"violations": [
{
"propertyPath": "addresses[1].label",
"message": "This value should not be blank."
}
],
"detail": "addresses[1].label: This value should not be blank."
}

404 Not Found​

{
"@context": "/api/contexts/Error",
"@type": "hydra:Error",
"hydra:title": "An error occurred",
"hydra:description": "Not Found"
}

401 Unauthorized​

{
"@context": "/api/contexts/Error",
"@type": "hydra:Error",
"hydra:title": "An error occurred",
"hydra:description": "Full authentication is required to access this resource."
}

Available formats​

FormatAccept HeaderDescription
JSON-LDapplication/ld+jsonCanonical format, with Hydra metadata (pagination info)
JSONapplication/jsonPlain JSON, enabled by default
HTMLtext/htmlServes the interactive OpenAPI documentation
note

JSON-LD (application/ld+json) is the canonical format Thelia configures for its API and the one used throughout the examples below.

OpenAPI documentation​

Thelia's API is documented with OpenAPI. The interactive documentation is available at:

/api/docs

It offers:

  • "Try it out" functionality
  • Complete schema definitions
  • Authentication testing
  • Example requests and responses