Skip to content
Gillia Developers v1

API reference

Every route of the Gillia API, generated from the OpenAPI contract, with a sample request and response.

Base URLhttps://gillia.app/pos-api/api/v1

Get started in five minutes · Authentication · Download the OpenAPI contract

System & identity

GET/healthno authentication

Check API liveness

Lightweight unauthenticated probe that confirms the API process is running and returns the current UTC check timestamp.

Responses

StatusDescriptionBody
200

API is running

HealthResponse
GET/meany valid key

Return current token identity

Returns the authenticated principal decoded from the bearer token, including subject, client id, tenant id, accessible site ids, scopes, and roles.

Responses

StatusDescriptionBody
200

Current authenticated principal

MeResponse
401

Missing or invalid bearer token

—
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
GET/me/callsany valid key

Read the call journal of your API key

Returns the journal of the API key that makes the call, never another key's. A sandbox key (gsk_test_) reads its latest calls one by one, kept 30 days: method, route template, status, duration and the X-Request-Id you received. A production key reads daily counters for the last 30 days. Neither request nor response bodies are ever kept, and routes are templates, not real URLs.

Parameters

NameInTypeDescription
limit query integer

Maximum number of rows (calls or daily counters), 1 to 200.

default 50 · min 1 · max 200

Responses

StatusDescriptionBody
200

Call journal of the calling key

object
401

Missing or invalid bearer token

—
403

Token does not grant the required scope or site access

—
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
GET/me/appsany valid key

List your OAuth applications

Returns the OAuth applications registered by the business of the calling key (your sandbox), with the number of merchants who currently grant each one. Secrets are never returned.

Responses

StatusDescriptionBody
200

Applications of your sandbox

object
401

Missing or invalid bearer token

—
403

Token does not grant the required scope or site access

—
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
POST/me/appsany valid key

Register an OAuth application

Registers an application that merchants can authorize through OAuth 2 (authorization code with PKCE, see the OAuth guide). Call it with your sandbox key (gsk_test_). The client secret is returned once, in this response only. A new application is in sandbox status: only sandbox businesses can authorize it until it is certified. Up to 10 applications per sandbox.

Request bodyrequired

object application/json

Responses

StatusDescriptionBody
201

Application registered; keep the client secret now

DeveloperAppCredentials
400

Invalid request

ProblemDetails
401

Missing or invalid bearer token

—
403

Token does not grant the required scope or site access

—
409

Your sandbox already holds 10 applications

ProblemDetails
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
POST/me/apps/{clientId}/secretany valid key

Issue a new client secret

Replaces the client secret of one of your applications. The previous secret stops working at once.

Parameters

NameInTypeDescription
clientIdrequired path string

Public identifier of the application (gci_…).

Responses

StatusDescriptionBody
200

New credentials; keep the client secret now

DeveloperAppCredentials
401

Missing or invalid bearer token

—
403

Token does not grant the required scope or site access

—
404

Resource not found or not accessible

—
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
DELETE/me/apps/{clientId}any valid key

Delete an OAuth application

Deletes one of your applications and revokes every access merchants granted to it.

Parameters

NameInTypeDescription
clientIdrequired path string

Public identifier of the application (gci_…).

Responses

StatusDescriptionBody
204

Application deleted, accesses revoked

—
401

Missing or invalid bearer token

—
403

Token does not grant the required scope or site access

—
404

Resource not found or not accessible

—
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
GET/me/apps/{clientId}/certificationany valid key

Read your application's certification

Evaluates the latest certification session of your application against the call journal of the tokens it received in sandboxes, and returns each check with what is left to do. When every check passes, the session is passed and the application moves to production status: real merchants can then authorize it.

Parameters

NameInTypeDescription
clientIdrequired path string

Public identifier of the application (gci_…).

Responses

StatusDescriptionBody
200

Certification state

Certification
401

Missing or invalid bearer token

—
403

Token does not grant the required scope or site access

—
404

Resource not found or not accessible

—
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
POST/me/apps/{clientId}/certificationany valid key

Start a certification

Starts a certification session for a profile (it replaces a session in progress). Then run your application in your sandbox: authorize it through OAuth, perform the steps of the profile, recover from a simulated 503 and wait after a simulated 429 (Gillia-Simulate header). Sessions last 7 days.

Parameters

NameInTypeDescription
clientIdrequired path string

Public identifier of the application (gci_…).

Request bodyrequired

object application/json

Responses

StatusDescriptionBody
201

Session started, with its checks

Certification
400

Invalid request

ProblemDetails
401

Missing or invalid bearer token

—
403

Token does not grant the required scope or site access

—
404

Resource not found or not accessible

—
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails

Tenants & sites

GET/tenantstenant.read

List tenants visible to the current token

Returns the merchant accounts the current token can see. Most integrations never need this: a partner key is issued for one merchant and one or more of their sites, so /sites answers directly. It matters when a single token spans several merchants — a group, or a reseller integration.

Responses

StatusDescriptionBody
200

Tenants

object
401

Missing or invalid bearer token

—
403

Token does not grant the required scope or site access

—
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
GET/tenants/{tenantId}/sitessite.read

List the sites of one tenant

Returns the sites of one merchant that the current token can access.

Parameters

NameInType
tenantIdrequired path string (uuid)

Responses

StatusDescriptionBody
200

Sites

object
401

Missing or invalid bearer token

—
403

Token does not grant the required scope or site access

—
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
GET/sitessite.read

List sites available to the current token

Returns all POS sites the current token can access, across the tenants visible to the principal.

Responses

StatusDescriptionBody
200

Accessible sites

object
401

Missing or invalid bearer token

—
403

Token does not grant the required scope or site access

—
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
GET/sites/{siteId}site.read

Get one site

Returns one POS site when the current token has access to it. Inaccessible sites are returned as not found.

Parameters

NameInType
siteIdrequired path string (uuid)

Responses

StatusDescriptionBody
200

Site

Site
401

Missing or invalid bearer token

—
403

Token does not grant the required scope or site access

—
404

Resource not found or not accessible

—
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails

Zones

GET/sites/{siteId}/pos/zonespos.catalog.read

List POS zones for a site

Returns POS zones configured for the site store, such as sales/service areas when available in the client POS database.

Parameters

NameInType
siteIdrequired path string (uuid)

Responses

StatusDescriptionBody
200

POS zones

object
401

Missing or invalid bearer token

—
403

Token does not grant the required scope or site access

—
404

Resource not found or not accessible

—
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails

Catalog

GET/sites/{siteId}/pos/catalog/categoriespos.catalog.read

List catalog categories

Returns the merchant's families and sub-families, flattened: a sub-family carries the id of its family in parentId, a family carries none. Use it to map your own categories onto theirs before pushing products — a product references a category by id, and no category is created on the fly.

Parameters

NameInType
siteIdrequired path string (uuid)

Responses

StatusDescriptionBody
200

Categories

object
401

Missing or invalid bearer token

—
403

Either the token does not grant the required scope or site access, or (07/10) the merchant's Gillia subscription has been CANCELLED and its account is read-only or archived. In the second case the body is a problem+json whose code is tenant_read_only (read-only period: consult, download and export only — no catalog download or change, no device enrolment or pairing, no register configuration, no stock reads or adjustments, no voucher issuance or extension) or tenant_archived (after the read-only period: the account is closed, data are kept until keptUntil and returned on request). Reads, orders coming from elsewhere (POST /pos/orders) and HubRise disconnection keep passing.

object
404

Resource not found or not accessible

—
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
GET/sites/{siteId}/pos/catalog/productspos.catalog.read

List POS catalog products

When the client POS database is configured, id is the local POS article id and can be reused as productId in stock adjustments. Without updatedSince, products are sorted by name. Incremental sync: pass the greatest updatedAt you have seen as updatedSince; only products changed strictly after it are returned, sorted by updatedAt then id (products that never recorded a change date are left out in that mode). Paginate with page / pageSize while page * pageSize is lower than total.

Parameters

NameInTypeDescription
siteIdrequired path string (uuid) —
page query integer —default 1 · min 1
pageSize query integer —default 50 · min 1 · max 200
search query string

Search by POS article id, SKU, local label, or Gillia catalog reference when available.

updatedSince query string (date-time)

Only products created or changed strictly after this instant (ISO 8601, UTC Z or with an offset). Pass back the greatest updatedAt received.

Responses

StatusDescriptionBody
200

Product page

ProductPage
400

updatedSince is not a valid ISO 8601 instant.

—
401

Missing or invalid bearer token

—
403

Either the token does not grant the required scope or site access, or (07/10) the merchant's Gillia subscription has been CANCELLED and its account is read-only or archived. In the second case the body is a problem+json whose code is tenant_read_only (read-only period: consult, download and export only — no catalog download or change, no device enrolment or pairing, no register configuration, no stock reads or adjustments, no voucher issuance or extension) or tenant_archived (after the read-only period: the account is closed, data are kept until keptUntil and returned on request). Reads, orders coming from elsewhere (POST /pos/orders) and HubRise disconnection keep passing.

object
404

Resource not found or not accessible

—
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
POST/sites/{siteId}/pos/catalog/productspos.catalog.write

Create a POS catalog product

Creates the local POS Article, ArticleVente, Reserve, optional barcode, optional ArticleAchat, and optional initial stock journal.

Parameters

NameInType
siteIdrequired path string (uuid)

Request bodyrequired

CreateProductRequest application/json

Responses

StatusDescriptionBody
201

Product created

Product
400

Invalid request

ProblemDetails
401

Missing or invalid bearer token

—
403

Either the token does not grant the required scope or site access, or (07/10) the merchant's Gillia subscription has been CANCELLED and its account is read-only or archived. In the second case the body is a problem+json whose code is tenant_read_only (read-only period: consult, download and export only — no catalog download or change, no device enrolment or pairing, no register configuration, no stock reads or adjustments, no voucher issuance or extension) or tenant_archived (after the read-only period: the account is closed, data are kept until keptUntil and returned on request). Reads, orders coming from elsewhere (POST /pos/orders) and HubRise disconnection keep passing.

object
404

Resource not found or not accessible

—
422

Request is valid JSON but cannot be applied to the POS data

ProblemDetails
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
GET/sites/{siteId}/pos/catalog/products/{productId}pos.catalog.read

Get one POS catalog product

Returns the full POS product sheet for one article, including identifiers, labels, barcode, family/subfamily, accounting code, declination, sale price, VAT, purchase cost, supplier, stock fields, unit, category, status, and dates when available.

Parameters

NameInTypeDescription
siteIdrequired path string (uuid) —
productIdrequired path string

POS article id, ArticleVente id, barcode, internal reference, or Gillia catalog reference.

Responses

StatusDescriptionBody
200

Product

Product
401

Missing or invalid bearer token

—
403

Either the token does not grant the required scope or site access, or (07/10) the merchant's Gillia subscription has been CANCELLED and its account is read-only or archived. In the second case the body is a problem+json whose code is tenant_read_only (read-only period: consult, download and export only — no catalog download or change, no device enrolment or pairing, no register configuration, no stock reads or adjustments, no voucher issuance or extension) or tenant_archived (after the read-only period: the account is closed, data are kept until keptUntil and returned on request). Reads, orders coming from elsewhere (POST /pos/orders) and HubRise disconnection keep passing.

object
404

Resource not found or not accessible

—
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
PATCH/sites/{siteId}/pos/catalog/products/{productId}pos.catalog.write

Update one POS catalog product

PARTIAL update: a field you omit is left untouched, a field you send is written — including an empty value, which clears it. That distinction is the whole point of PATCH here, so send only what you actually mean to change. The write goes through the merchant's business rules, the same ones the merchant's own screen applies. The body accepts the fields of CreateProductRequest; unknown fields are ignored. Returns the product as it now stands.

Parameters

NameInType
siteIdrequired path string (uuid)
productIdrequired path string

Request bodyrequired

object application/json

Responses

StatusDescriptionBody
200

Product after the update

Product
204

Update applied, but the product could not be read back.

—
400

Invalid request

ProblemDetails
401

Missing or invalid bearer token

—
403

Either the token does not grant the required scope or site access, or (07/10) the merchant's Gillia subscription has been CANCELLED and its account is read-only or archived. In the second case the body is a problem+json whose code is tenant_read_only (read-only period: consult, download and export only — no catalog download or change, no device enrolment or pairing, no register configuration, no stock reads or adjustments, no voucher issuance or extension) or tenant_archived (after the read-only period: the account is closed, data are kept until keptUntil and returned on request). Reads, orders coming from elsewhere (POST /pos/orders) and HubRise disconnection keep passing.

object
404

Resource not found or not accessible

—
422

Request is valid JSON but cannot be applied to the POS data

ProblemDetails
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
GET/sites/{siteId}/pos/catalog/products/{productId}/imagespos.catalog.read

List the images of a product

One entry per image, in display order. The first one (position 1) is the main image — the one shown on the product sheet, at the register and in the online shop. Each image has a stable id, to pass to the move and delete routes below.

Parameters

NameInType
siteIdrequired path string (uuid)
productIdrequired path string

Responses

StatusDescriptionBody
200

Images of the product

ProductImageList
401

Missing or invalid bearer token

—
403

Either the token does not grant the required scope or site access, or (07/10) the merchant's Gillia subscription has been CANCELLED and its account is read-only or archived. In the second case the body is a problem+json whose code is tenant_read_only (read-only period: consult, download and export only — no catalog download or change, no device enrolment or pairing, no register configuration, no stock reads or adjustments, no voucher issuance or extension) or tenant_archived (after the read-only period: the account is closed, data are kept until keptUntil and returned on request). Reads, orders coming from elsewhere (POST /pos/orders) and HubRise disconnection keep passing.

object
404

Resource not found or not accessible

—
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
POST/sites/{siteId}/pos/catalog/products/{productId}/imagespos.catalog.write

Add an image to a product from a public address

Gillia downloads the image from the given public https address (your website, Shopify, a Google Drive or Dropbox sharing link open to "anyone with the link"), checks that it really is an image (JPEG, PNG, GIF or WebP, 15 MB at most) and stores it in three sizes. Nothing is written if the address does not return an image (422, with the reason). The image is added at the end, or at the given position (1 makes it the main image; the others shift). A product can have several images. This is deliberately separate from the product PATCH: a slow or refused download never blocks an update of the name or the price, and can be retried on its own. Returns the new image id and the product's images as they now stand.

Parameters

NameInType
siteIdrequired path string (uuid)
productIdrequired path string

Request bodyrequired

AddProductImageRequest application/json

Responses

StatusDescriptionBody
201

Image added

object
400

Invalid request

ProblemDetails
401

Missing or invalid bearer token

—
403

Either the token does not grant the required scope or site access, or (07/10) the merchant's Gillia subscription has been CANCELLED and its account is read-only or archived. In the second case the body is a problem+json whose code is tenant_read_only (read-only period: consult, download and export only — no catalog download or change, no device enrolment or pairing, no register configuration, no stock reads or adjustments, no voucher issuance or extension) or tenant_archived (after the read-only period: the account is closed, data are kept until keptUntil and returned on request). Reads, orders coming from elsewhere (POST /pos/orders) and HubRise disconnection keep passing.

object
404

Resource not found or not accessible

—
422

Request is valid JSON but cannot be applied to the POS data

ProblemDetails
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
PATCH/sites/{siteId}/pos/catalog/products/{productId}/images/{imageId}pos.catalog.write

Move an image

Moves the image to the given position; the other images shift. Position 1 makes it the main image. A position beyond the last one puts it last. Returns the product's images as they now stand.

Parameters

NameInTypeDescription
siteIdrequired path string (uuid) —
productIdrequired path string —
imageIdrequired path string

Image id, as listed by GET …/images.

Request bodyrequired

MoveProductImageRequest application/json

Responses

StatusDescriptionBody
200

Images after the move

ProductImageList
400

Invalid request

ProblemDetails
401

Missing or invalid bearer token

—
403

Either the token does not grant the required scope or site access, or (07/10) the merchant's Gillia subscription has been CANCELLED and its account is read-only or archived. In the second case the body is a problem+json whose code is tenant_read_only (read-only period: consult, download and export only — no catalog download or change, no device enrolment or pairing, no register configuration, no stock reads or adjustments, no voucher issuance or extension) or tenant_archived (after the read-only period: the account is closed, data are kept until keptUntil and returned on request). Reads, orders coming from elsewhere (POST /pos/orders) and HubRise disconnection keep passing.

object
404

Resource not found or not accessible

—
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
DELETE/sites/{siteId}/pos/catalog/products/{productId}/images/{imageId}pos.catalog.write

Delete an image

Deletes the image (all three sizes). The following images move up one place; deleting the main image makes the next one the main image. Returns the product's images as they now stand.

Parameters

NameInType
siteIdrequired path string (uuid)
productIdrequired path string
imageIdrequired path string

Responses

StatusDescriptionBody
200

Images after the deletion

ProductImageList
401

Missing or invalid bearer token

—
403

Either the token does not grant the required scope or site access, or (07/10) the merchant's Gillia subscription has been CANCELLED and its account is read-only or archived. In the second case the body is a problem+json whose code is tenant_read_only (read-only period: consult, download and export only — no catalog download or change, no device enrolment or pairing, no register configuration, no stock reads or adjustments, no voucher issuance or extension) or tenant_archived (after the read-only period: the account is closed, data are kept until keptUntil and returned on request). Reads, orders coming from elsewhere (POST /pos/orders) and HubRise disconnection keep passing.

object
404

Resource not found or not accessible

—
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails

Customers

GET/sites/{siteId}/pos/customerspos.customers.read

List POS customers

Returns POS customers from the site store, with identity, contact details, customer group, loyalty/account balances, discount defaults, card number, marketing consent, state, and synchronization metadata.

Parameters

NameInTypeDescription
siteIdrequired path string (uuid) —
page query integer —default 1 · min 1
pageSize query integer —default 50 · min 1 · max 200
search query string

Search by customer id, last name, first name, phone, email, card number, or reference number.

state query integer

Optional POS customer state filter. Common values are 1 active, 2 inactive, and 0 archived.

Responses

StatusDescriptionBody
200

Customer page

CustomerPage
401

Missing or invalid bearer token

—
403

Token does not grant the required scope or site access

—
404

Resource not found or not accessible

—
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
POST/sites/{siteId}/pos/customerspos.customers.write

Create a POS customer

Creates a customer in the local POS Client table for the site store. The customer is marked unsent so the existing POS synchronization can propagate it. At least one of lastName, firstName, email, or phone is required.

Parameters

NameInType
siteIdrequired path string (uuid)

Request bodyrequired

CreateCustomerRequest application/json

Responses

StatusDescriptionBody
201

Customer created

Customer
400

Invalid request

ProblemDetails
401

Missing or invalid bearer token

—
403

Token does not grant the required scope or site access

—
404

Resource not found or not accessible

—
409

A non-archived customer already exists with the same email or phone.

ProblemDetails
422

Request is valid JSON but cannot be applied to the POS data

ProblemDetails
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
GET/sites/{siteId}/pos/customers/{customerId}pos.customers.read

Get one POS customer

Returns one POS customer from the site store by local customer id, including contact, group, loyalty/account, discount, consent, and synchronization fields.

Parameters

NameInTypeDescription
siteIdrequired path string (uuid) —
customerIdrequired path string

Local POS customer id.

Responses

StatusDescriptionBody
200

Customer

Customer
401

Missing or invalid bearer token

—
403

Token does not grant the required scope or site access

—
404

Resource not found or not accessible

—
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
PATCH/sites/{siteId}/pos/customers/{customerId}pos.customers.write

Update one POS customer

PARTIAL update: a field you omit is left untouched, a field you send is written — including an empty value, which clears it. Send only what you mean to change. The write goes through the merchant's own rules: a professional record (gender 3) requires its company registration number, and an email or phone that already belongs to another active customer is refused (409) rather than silently creating a duplicate. Returns the customer as it now stands.

Parameters

NameInType
siteIdrequired path string (uuid)
customerIdrequired path string

Request bodyrequired

UpdateCustomerRequest application/json

Responses

StatusDescriptionBody
200

Customer after the update

Customer
400

Invalid request

ProblemDetails
401

Missing or invalid bearer token

—
403

Token does not grant the required scope or site access

—
404

Resource not found or not accessible

—
409

Another non-archived customer already uses that email or phone.

ProblemDetails
422

Request is valid JSON but cannot be applied to the POS data

ProblemDetails
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails

Sales tickets

GET/sites/{siteId}/pos/sales/ticketspos.sales.read

List POS sales tickets

Returns POS tickets from bills over the requested period. Each item includes a bills array with payment rows and means of payment. Set includeLines=false to retrieve only tickets and bills without POS orders; set includeLines=true to also include detailed order lines.

Parameters

NameInTypeDescription
siteIdrequired path string (uuid) —
page query integer —default 1 · min 1
pageSize query integer —default 50 · min 1 · max 200
from query string (date-time)

Include tickets sold at or after this POS timestamp.

to query string (date-time)

Exclude tickets sold at or after this POS timestamp.

includeLines query boolean

Include ticket lines from the POS orders table. Use false for a lighter ticket and payment-method list.

default true

Responses

StatusDescriptionBody
200

Sales ticket page

SalesTicketPage
401

Missing or invalid bearer token

—
403

Token does not grant the required scope or site access

—
404

Resource not found or not accessible

—
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
GET/sites/{siteId}/pos/sales/tickets/{ticketId}pos.sales.read

Get one POS sales ticket

Returns the full detail of one POS ticket. The response includes all matching bills/payment rows and, by default, all order lines with VAT, sale type, tariff type, discounts, offers, purchase prices, accounting code, family/subfamily, seller, customer, stock-deduction, and cancellation metadata.

Parameters

NameInTypeDescription
siteIdrequired path string (uuid) —
ticketIdrequired path string

POS ticket id. The lookup also accepts the order id or local bill id when available.

includeLines query boolean

Include POS orders/detail lines. Use false to retrieve only bills/payment rows for the ticket.

default true

Responses

StatusDescriptionBody
200

Sales ticket detail

SalesTicket
401

Missing or invalid bearer token

—
403

Token does not grant the required scope or site access

—
404

Resource not found or not accessible

—
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails

Accounting

GET/sites/{siteId}/pos/accounting/entriespos.accounting.read

Read the accounting entries of a period

Returns the accounting entries of the whole business for the period, exactly as the merchant's accounting export computes them: sales journal (invoices not issued from a register ticket) and their payments, register journals for closed days (one entry per day and journal), with the accounts set by the merchant. Days still open are listed in openDays and left out. Accounts the merchant has not set use a default, listed in defaultAccounts. The siteId only identifies the business; a key limited to some stores is refused.

Parameters

NameInTypeDescription
siteIdrequired path string (uuid) —
fromrequired query string (date)

First day of the period (YYYY-MM-DD).

torequired query string (date)

Last day of the period, included (YYYY-MM-DD). At most 366 days after from.

Responses

StatusDescriptionBody
200

Accounting entries

AccountingEntries
400

Invalid request

ProblemDetails
401

Missing or invalid bearer token

—
403

Missing pos.accounting.read, or a key limited to some stores (accounting covers the whole business)

ProblemDetails
404

Resource not found or not accessible

—
503

The period is still being computed; retry after the Retry-After delay (seconds)

ProblemDetails
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
GET/sites/{siteId}/pos/accounting/fecpos.accounting.read

Download the FEC of a period

Returns the French standard audit file (fichier des écritures comptables, FEC) of the whole business for the period: the same entries as /accounting/entries, in the official tab-separated format, encoded in ISO 8859-15, with the official file name (SIREN + FEC + end date).

Parameters

NameInTypeDescription
siteIdrequired path string (uuid) —
fromrequired query string (date)

First day of the period (YYYY-MM-DD).

torequired query string (date)

Last day of the period, included (YYYY-MM-DD). At most 366 days after from.

Responses

StatusDescriptionBody
200

FEC file

—
400

Invalid request

ProblemDetails
401

Missing or invalid bearer token

—
403

Missing pos.accounting.read, or a key limited to some stores (accounting covers the whole business)

ProblemDetails
404

Resource not found or not accessible

—
503

The period is still being computed; retry after the Retry-After delay (seconds)

ProblemDetails
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails

Register closings (Z)

GET/sites/{siteId}/pos/closurespos.sales.read

Get the register closing (Z) for one day

Returns the day as the merchant closed it: total collected, sales broken down by VAT rate, detail per payment method, and the cash difference. The day must be over, and every register must be closed for it — otherwise the call is refused (409) and should be retried later. Note that totalCollected and totalInvoiced are deliberately distinct and both returned: they legitimately differ as soon as there are on-account sales, credit notes, debt settlements or deposits. Pick the one that answers your question rather than assuming they match.

Parameters

NameInTypeDescription
siteIdrequired path string (uuid) —
daterequired query string (date)

The day to close, as YYYY-MM-DD. Must be strictly in the past.

Responses

StatusDescriptionBody
200

Closing of the day

PosClosure
400

Missing date, or the day is not over yet.

—
401

Missing or invalid bearer token

—
403

Token does not grant the required scope or site access

—
404

Resource not found or not accessible

—
409

At least one register is still open for that day. Retry later.

—
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails

Inventory

GET/sites/{siteId}/pos/inventory/stockspos.catalog.read

List POS stock rows for the site store

Without productId, returns all articles stocked in the local store linked to the site. With productId, filters by POS article id, ArticleVente id, barcode, or Gillia catalog reference when available.

Parameters

NameInTypeDescription
siteIdrequired path string (uuid) —
productId query string

Optional POS article id, ArticleVente id, barcode, or Gillia catalog reference.

page query integer —default 1 · min 1
pageSize query integer —default 200 · min 1 · max 1000

Responses

StatusDescriptionBody
200

Stock page

StockItemPage
401

Missing or invalid bearer token

—
403

Either the token does not grant the required scope or site access, or (07/10) the merchant's Gillia subscription has been CANCELLED and its account is read-only or archived. In the second case the body is a problem+json whose code is tenant_read_only (read-only period: consult, download and export only — no catalog download or change, no device enrolment or pairing, no register configuration, no stock reads or adjustments, no voucher issuance or extension) or tenant_archived (after the read-only period: the account is closed, data are kept until keptUntil and returned on request). Reads, orders coming from elsewhere (POST /pos/orders) and HubRise disconnection keep passing.

object
404

Resource not found or not accessible

—
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
GET/sites/{siteId}/pos/inventory/stocks/{productId}pos.catalog.read

List POS stock rows for one product

Returns all stock rows of the requested product within the local store linked to the site.

Parameters

NameInTypeDescription
siteIdrequired path string (uuid) —
productIdrequired path string

POS article id, ArticleVente id, barcode, or Gillia catalog reference.

page query integer —default 1 · min 1
pageSize query integer —default 200 · min 1 · max 1000

Responses

StatusDescriptionBody
200

Stock page for the product

StockItemPage
401

Missing or invalid bearer token

—
403

Either the token does not grant the required scope or site access, or (07/10) the merchant's Gillia subscription has been CANCELLED and its account is read-only or archived. In the second case the body is a problem+json whose code is tenant_read_only (read-only period: consult, download and export only — no catalog download or change, no device enrolment or pairing, no register configuration, no stock reads or adjustments, no voucher issuance or extension) or tenant_archived (after the read-only period: the account is closed, data are kept until keptUntil and returned on request). Reads, orders coming from elsewhere (POST /pos/orders) and HubRise disconnection keep passing.

object
404

Resource not found or not accessible

—
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
GET/sites/{siteId}/pos/inventory/movementspos.catalog.read

Stock movements of a store (stock exits, transfers, productions)

Stock movements of one type at a time: stock exits (out — damage, expiry, theft, donation, delivery notes, supplier returns…), transfers between sites of the brand (transfer — listed for both the sending and the receiving site, with fromSite / toSite), and productions (production). Incoming goods (supplier receptions, customer returns) are not listed here: read GET /sites/{siteId}/pos/purchases/orders. NO PRICES are ever returned (no movement amount, no cost). Dates: instants are UTC ISO 8601 with a Z suffix. Incremental sync: pass the greatest updatedAt you have seen as updatedSince; results are sorted by updatedAt then id, paginate with page / pageSize (max 100) while hasMore is true. updatedAt moves every time the movement is saved (validation, cancellation). Requires the pos.catalog.read (or pos.cloud.read) scope.

Parameters

NameInTypeDescription
siteIdrequired path string (uuid) —
typerequired query out · transfer · production

The kind of movement to list.

updatedSince query string (date-time)

Only movements changed strictly after this instant (ISO 8601, UTC Z or with an offset). Pass back the greatest updatedAt received.

page query integer —default 1 · min 1
pageSize query integer —default 50 · min 1 · max 100

Responses

StatusDescriptionBody
200

One page of stock movements

StockMovementPage
400

Missing or unknown type (code type_invalid), or updatedSince is not a valid ISO 8601 instant.

—
401

Missing or invalid bearer token

—
403

Token does not grant the required scope or site access

—
404

Unknown site, or a site this key cannot reach.

—
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
GET/sites/{siteId}/pos/inventory/lotspos.catalog.read

Lots in stock in a store, with their best-before dates

Open lots of the store that still have quantity left: lot number, serial number, best-before date (dlc) and remaining quantity. Sorted by dlc (soonest first, lots without dlc last) then id; paginate with page / pageSize (max 100) while hasMore is true. Use expiringBefore to watch lots about to expire. NO COST is ever returned. Dates: dlc is a plain calendar date YYYY-MM-DD; receivedDate is an instant, UTC ISO 8601 with a Z suffix. Requires the pos.catalog.read (or pos.cloud.read) scope.

Parameters

NameInTypeDescription
siteIdrequired path string (uuid) —
expiringBefore query string (date)

Only lots whose dlc is strictly before this calendar date (YYYY-MM-DD). Lots without dlc are left out when it is given.

page query integer —default 1 · min 1
pageSize query integer —default 50 · min 1 · max 100

Responses

StatusDescriptionBody
200

One page of lots

StockLotPage
400

expiringBefore is not a YYYY-MM-DD date (code expiring_before_invalid).

—
401

Missing or invalid bearer token

—
403

Token does not grant the required scope or site access

—
404

Unknown site, or a site this key cannot reach.

—
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
POST/sites/{siteId}/pos/inventory/adjustmentspos.inventory.write

Apply POS stock adjustments

Writes purchase movements to JournalAchat and other stock movements to StockUpgrade. POS database triggers update Reserve for synchronization. The write goes through the merchant's own business rules, so the same refusals apply as on screen: a product that does not exist, or that the merchant has deleted, is refused (404); a regularisation dated inside a locked period is refused (422); and an inventory count records its valuation snapshot and never overwrites a more recent count. Quantities are resolved against the CURRENT reserve, not against a figure you send: quantityAfter is converted to a delta at write time, so two concurrent callers cannot both be right about the stock they started from.

Parameters

NameInType
siteIdrequired path string (uuid)

Request bodyrequired

CreateStockAdjustmentRequest application/json

Responses

StatusDescriptionBody
201

Stock adjustment applied

StockAdjustmentResponse
400

Invalid request

ProblemDetails
401

Missing or invalid bearer token

—
403

Either the token does not grant the required scope or site access, or (07/10) the merchant's Gillia subscription has been CANCELLED and its account is read-only or archived. In the second case the body is a problem+json whose code is tenant_read_only (read-only period: consult, download and export only — no catalog download or change, no device enrolment or pairing, no register configuration, no stock reads or adjustments, no voucher issuance or extension) or tenant_archived (after the read-only period: the account is closed, data are kept until keptUntil and returned on request). Reads, orders coming from elsewhere (POST /pos/orders) and HubRise disconnection keep passing.

object
404

Unknown site, a productId that does not exist (product_not_found), or a product the merchant has deleted (product_deleted) — a deleted reference can no longer be counted or moved.

ProblemDetails
422

The merchant's own rules refused the movement — typically date_locked: no stock regularisation is allowed on that date any more, because the period has been closed.

ProblemDetails
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails

Orders from elsewhere

POST/sites/{siteId}/pos/orderspos.orders.write

Record an order sold elsewhere

Records in Gillia an order your own storefront, marketplace or integration has already sold. It enters as an ORDER, never as a sealed receipt: it becomes an accounting document when it is paid. Stock is NOT decremented here — that happens when the order is prepared. The order arrives WITH ITS PRICES: Gillia records what you sold, it does not re-price. A wrong price on your side is recorded as such. The write goes through the merchant's own business rules, so the same refusals apply as on screen: a customer without a minimum identity (phone, or email, or first and last name) makes the whole order fail, a known buyer is reused rather than duplicated, and every product must already exist — no reference is created on the fly. IDEMPOTENT on externalReference: calling again with the same reference returns the SAME order with alreadyExisted true instead of creating a second one, so a network incident can be replayed safely. Requires the pos.orders.write scope, which is distinct from pos.sales.write and must be granted explicitly by the merchant.

Parameters

NameInType
siteIdrequired path string (uuid)

Request bodyrequired

CreateOrderRequest application/json

Responses

StatusDescriptionBody
200

The order already existed for this external reference — nothing was created. The body carries the existing orderId and alreadyExisted true.

CreateOrderResponse
201

Order recorded

CreateOrderResponse
400

Missing external reference, no lines, a quantity that is not strictly positive, a negative price, a VAT rate outside 0-100, or an announced total that the lines do not explain (tolerance one cent).

ProblemDetails
401

Missing or invalid bearer token

—
403

Token does not grant the required scope or site access

—
404

Unknown site, unknown customerId, or a productId that does not exist.

ProblemDetails
422

The merchant's own rules refused the customer — typically no minimum identity, or a professional customer without its company registration number. The message is the one the merchant would read on screen.

ProblemDetails
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails

Partner orders

POST/sites/{siteId}/pos/partner-orderspos.orders.write

Push an online order from a partner app — it rings on the Gillia POS register

For a partner who built the merchant's online ordering app (website, mobile app, click & collect). The order RINGS on the Gillia POS register exactly like an Uber Eats order: the staff accepts it, prepares it and finalizes it (the register then issues the fiscal ticket), or refuses it. Your app learns what happens through signed webhooks (PUT /pos/partner-webhook) and/or by polling GET /pos/partner-orders/{externalReference}.

Not to be confused with POST /pos/orders, which records a BACK-OFFICE order (migration, third-party shop) that never goes through the register. Use partner-orders for an order that must be prepared and handed over in the shop.

Rules: - Products: each line names a product of the merchant's catalog by its id or its internal reference (GET /pos/catalog/products). It must be sellable online. Nothing is created on the fly: by default an unknown product rejects the whole order (422 unknown_product) and nothing is written. With unknownItems: "accept" (optional, per order) the order is received instead: the unknown line reaches the register under its name, at your price, flagged "Product to check" for the staff (an unknown option is added to its line's comment and price). Accepted unknown lines are handled by the Gillia POS register (tablet, web and Windows app) only; older registers do not support them. - Options (extras, removals) are products taken from the option lists of the line's product; removed: true marks a removal ("no onions"), which is not charged. - Total is mandatory and checked to the cent: sum of lines (unitPrice × quantity) + non-removed options (unitPrice × option quantity × line quantity) + charges (fees positive, discounts negative). Amounts are tax-inclusive, in euros. - Payment: the order must already be paid on your side — payment.status must be "paid". Optional payment.splits (card + meal voucher…): one settlement line each on the ticket; their sum must equal total to the cent (422 payment_mismatch). - Deals (optional): declare them in deals (key + name) and point lines to them with deal: { key, label }; the register shows "Menu midi · Drink" on each line. - Customer (optional): customer.id is YOUR customer id. The customer is found by it first (even after an e-mail change), then by e-mail, then by phone; it is kept per API key, so two partners never share ids. An e-mail or a phone is still needed to create the customer. An existing customer record is never overwritten. - VAT (optional): lines[].vatRate overrides the product's rate (0 to 100). - New fields are optional: an order without them is processed exactly as before. - Idempotent on externalReference (1 to 50 characters): sending the same reference again returns the SAME order with alreadyExisted: true and HTTP 200, so a network incident can be replayed safely. - Isolation: an API key (or OAuth client) only sees its own orders and its own webhook.

Lifecycle (status): received (ringing on the register, to accept) → accepted (being prepared) → completed (handed over, ticketId set); or rejected (with rejectionReason). While accepted, the staff can mark it ready (readyAt set, webhook order.ready) or push back the promised time and/or write to the customer (confirmedTime updated, webhook order.updated); neither changes status.

Requires the pos.orders.write (or pos.cloud.write) scope — the "Orders" right the merchant ticks for the key it hands to the partner.

Parameters

NameInType
siteIdrequired path string (uuid)

Request bodyrequired

PartnerOrderRequest application/json

Responses

StatusDescriptionBody
200

The order already existed for this externalReference — nothing was created. The body is its current state with alreadyExisted true.

PartnerOrderStatus
201

Order created — it is now ringing on the register (status received). Location points to GET /pos/partner-orders/{externalReference}.

PartnerOrderStatus
400

Malformed order. title carries a stable code: external_reference_required, channel_required, invalid_service_type, lines_required, product_required, option_product_required, invalid_charge, total_required, invalid_unknown_items, invalid_deal (duplicate or missing key, or a line pointing to an undeclared deal), invalid_customer_id (more than 100 characters).

ProblemDetails
401

Missing or invalid bearer token

—
403

The token does not grant pos.orders.write or this site, or the caller cannot be identified (title partner_unidentified).

ProblemDetails
404

Resource not found or not accessible

—
422

The order cannot be accepted as sent. title carries a stable code: too_many_lines (more than 200), invalid_quantity, invalid_price, invalid_option, payment_required (payment.status is not "paid"), total_mismatch (announced total differs from the computed one by more than one cent), negative_total, unknown_product (a product or option is unknown, not sellable online, or not in the product's option lists — nothing is written; not raised with unknownItems "accept"), invalid_vat_rate, payment_mismatch (payment.splits do not add up to the total, or one is not positive), site_without_store.

ProblemDetails
503

Partner orders are not enabled yet for this site (title partner_orders_unavailable). Retry later or contact the merchant.

ProblemDetails
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
GET/sites/{siteId}/pos/partner-orders/{externalReference}pos.orders.write

Current state of a partner order

Returns where one of YOUR orders stands (received / accepted / completed / rejected), with the refusal reason or the fiscal ticket id when known, the promised time and the time it was marked ready. Works even after the order has left the register. This is the source of truth: when in doubt about a webhook (missed, out of order), read it here. Requires the pos.orders.write (or pos.cloud.write) scope; a key only sees its own orders.

Parameters

NameInTypeDescription
siteIdrequired path string (uuid) —
externalReferencerequired path string

Your reference, as sent to POST /pos/partner-orders (URL-encoded).

max length 50

Responses

StatusDescriptionBody
200

Order state

PartnerOrderStatus
401

Missing or invalid bearer token

—
403

Token does not grant the required scope or site access

—
404

Unknown site, or no order with this reference for this key.

—
503

Partner orders are not enabled yet for this site (title partner_orders_unavailable).

ProblemDetails
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
GET/sites/{siteId}/pos/partner-webhookpos.orders.write

Webhook declared by the calling partner

Returns the URL Gillia calls for YOUR orders and the events sent. The signing secret is never returned here. One webhook per API key (or OAuth client) and per merchant: it serves every site the key can reach. Requires the pos.orders.write (or pos.cloud.write) scope.

Parameters

NameInType
siteIdrequired path string (uuid)

Responses

StatusDescriptionBody
200

Declared webhook (without secret)

PartnerWebhook
401

Missing or invalid bearer token

—
403

Token does not grant the required scope or site access

—
404

Unknown site, or no webhook declared for this key.

—
503

Partner orders are not enabled yet for this site (title partner_orders_unavailable).

ProblemDetails
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
PUT/sites/{siteId}/pos/partner-webhookpos.orders.write

Declare or change the webhook URL (and get the signing secret)

Creates or replaces the URL Gillia calls when one of your partner orders changes state. The signing secret (whsec_…) is returned ONLY ONCE: at creation, or when rotateSecret is true (the old secret stops working immediately). Store it; later calls return no secret. Requires the pos.orders.write (or pos.cloud.write) scope.

The URL must be https and point to a public address (no localhost, private, link-local or reserved IP — checked when declared and again on the resolved IP at each call), 500 characters at most, without credentials or fragment. Otherwise 422 invalid_webhook_url.

Events (POST, application/json, see also x-webhooks in this document): by default order.accepted, order.rejected, order.completed. Two more are sent ONLY if you ask for them in events: order.ready (the staff marked the order ready, data.readyAt) and order.updated (the staff pushed back the promised time, data.confirmedTime, and/or wrote to the customer, data.sellerNotes); they leave data.status unchanged. events absent = unchanged (the three defaults at creation); it also lets you receive fewer events. Body:

{
  "id": "evt_3f1c…",
  "type": "order.completed",
  "createdAt": "2026-10-10T17:42:05.120Z",
  "siteId": "6f0c…",
  "data": {
    "externalReference": "APP-2026-000731",
    "orderId": "4821",
    "status": "completed",
    "ticketId": "T0001-000123",
    "updatedAt": "2026-10-10T17:42:04.870Z"
  }
}

data.rejectionReason is present on order.rejected, data.ticketId on order.completed (omitted when empty).

Headers: X-Gillia-Event (event type), X-Gillia-Delivery (unique id of the event, equal to id — kept across retries, use it to de-duplicate), X-Gillia-Signature: t={unix seconds},v1={hex} where hex = lowercase HMAC-SHA256(secret, "{t}.{raw body}"). User-Agent: Gillia-Webhooks/1.0.

Verify on the RAW body (before any JSON parsing), compare in constant time, and refuse a t older than 5 minutes (replay protection). Node.js example:

const crypto = require('crypto');
function verify(secret, rawBody, header) {
  const parts = Object.fromEntries(header.split(',').map(p => p.trim().split('=')));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
  const a = Buffer.from(expected), b = Buffer.from(parts.v1 || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Delivery: answer with any 2xx within 10 seconds, then do your work. Any other status, a timeout or a redirect (redirects are NOT followed) counts as a failure and is retried after 30 s, 1 min, 2 min, 4 min… doubling, capped at 1 hour, for 12 attempts at most; then the event is dropped. Events can therefore arrive late or out of order: rely on data.status / data.updatedAt, and when in doubt read GET /pos/partner-orders/{externalReference}, which is always up to date. Without a declared webhook, nothing is sent and nothing is kept for later: poll instead.

Parameters

NameInType
siteIdrequired path string (uuid)

Request bodyrequired

PartnerWebhookRequest application/json

Responses

StatusDescriptionBody
200

Webhook saved. secret is present only on creation or rotation.

PartnerWebhook
401

Missing or invalid bearer token

—
403

Token does not grant the required scope or site access

—
404

Resource not found or not accessible

—
422

URL refused (title invalid_webhook_url) — not https, not public, too long, with credentials or a fragment; or events empty or naming an unknown event (title invalid_webhook_events).

ProblemDetails
503

Partner orders are not enabled yet for this site (title partner_orders_unavailable), or choosing events is not enabled yet for it (title webhook_events_unavailable — only the three default events can be sent).

ProblemDetails
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
DELETE/sites/{siteId}/pos/partner-webhookpos.orders.write

Remove the webhook

Stops the calls to your URL. Events not delivered yet are dropped; order states remain readable with GET /pos/partner-orders/{externalReference}. Requires the pos.orders.write (or pos.cloud.write) scope.

Parameters

NameInType
siteIdrequired path string (uuid)

Responses

StatusDescriptionBody
204

Webhook removed

—
401

Missing or invalid bearer token

—
403

Token does not grant the required scope or site access

—
404

Unknown site, or no webhook declared for this key.

—
503

Partner orders are not enabled yet for this site (title partner_orders_unavailable).

ProblemDetails
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
POST/sites/{siteId}/pos/partner-webhook/testpos.orders.write

Send a test event to your webhook

Sends at once a signed webhook.test event to the webhook you declared, with the same envelope and headers as real events (X-Gillia-Signature, X-Gillia-Event, X-Gillia-Delivery), and tells you what your endpoint answered.

Parameters

NameInType
siteIdrequired path string (uuid)

Responses

StatusDescriptionBody
200

Your endpoint acknowledged the event (2xx)

WebhookTestResult
401

Missing or invalid bearer token

—
403

Token does not grant the required scope or site access

—
404

No webhook declared for your key on this business

ProblemDetails
502

Your endpoint did not acknowledge the event (non-2xx answer, timeout or unreachable)

WebhookTestResult
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails

Suppliers & receptions

GET/sites/{siteId}/pos/purchases/orderspos.purchases.read

Supplier orders of a store, with their reception progress

Supplier orders (and direct deliveries) RECEIVED by this store, to follow delivery compliance: what was ordered, what was received, open discrepancies. Customer returns, unsent drafts and orders where the store itself is the supplier are excluded. NO PRICES are ever returned (no purchase price, order amount, shipping cost or lot cost). Dates: instants are UTC ISO 8601 with a Z suffix; calendar dates (deliveryDate, bestBefore) are plain YYYY-MM-DD. Incremental sync: pass the greatest updatedAt you have seen as updatedSince; results are sorted by updatedAt then id, paginate with page / pageSize (max 100) while hasMore is true. updatedAt moves on every change of the order, a reception, a discrepancy or an attachment. Requires the pos.purchases.read (or pos.cloud.read) scope.

Parameters

NameInTypeDescription
siteIdrequired path string (uuid) —
updatedSince query string (date-time)

Only orders changed strictly after this instant (ISO 8601, UTC Z or with an offset). Pass back the greatest updatedAt received.

page query integer —default 1 · min 1
pageSize query integer —default 50 · min 1 · max 100

Responses

StatusDescriptionBody
200

One page of supplier orders

PurchaseOrderPage
401

Missing or invalid bearer token

—
403

Token does not grant the required scope or site access

—
404

Unknown site, or a site this key cannot reach.

—
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
GET/sites/{siteId}/pos/purchases/orders/{orderId}pos.purchases.read

Reception report of a supplier order

The reception report of one supplier order: per line ordered / received / outstanding / over-received quantities, every reception record (date, operator first name and initial, quantities), qualified discrepancies (reason, comment, resolved), received lots / best-before dates / serial numbers, and the list of attached documents (signed delivery note, photos — metadata only). No prices. A completed order recorded without detailed receptions (older data) counts as fully received. Requires the pos.purchases.read (or pos.cloud.read) scope.

Parameters

NameInTypeDescription
siteIdrequired path string (uuid) —
orderIdrequired path integer

The id returned by the list.

Responses

StatusDescriptionBody
200

Reception report

object
401

Missing or invalid bearer token

—
403

Token does not grant the required scope or site access

—
404

Unknown site, or no supplier order with this id received by this store.

—
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
GET/sites/{siteId}/pos/supplierspos.purchases.read

Suppliers of the brand

The merchant's suppliers (shared by every site of the brand): name and contact details. Deleted suppliers are left out, and so are the brand's own sites (they are returned by GET /sites). Suppliers carry no creation or change date: the list is sorted from the most recently created to the oldest (then by id). To detect new suppliers, read the first page and remember the ids you have already seen. Paginate with page / pageSize (max 100) while hasMore is true. Requires the pos.purchases.read (or pos.cloud.read) scope.

Parameters

NameInTypeDescription
siteIdrequired path string (uuid) —
page query integer —default 1 · min 1
pageSize query integer —default 50 · min 1 · max 100

Responses

StatusDescriptionBody
200

One page of suppliers

SupplierPage
401

Missing or invalid bearer token

—
403

Token does not grant the required scope or site access

—
404

Unknown site, or a site this key cannot reach.

—
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails

Gift vouchers

POST/sites/{siteId}/pos/voucherspos.vouchers.write

Issue a gift voucher

Issues a voucher for a given amount. You may propose a code; leave it out and the merchant's own numbering assigns one. The response carries the code the bearer will present. ⚠️ ISSUING CREATES VALUE, so this needs the pos.vouchers.write scope, which the merchant grants explicitly and separately. You cannot SPEND a voucher through this API: the consumed amount is writable by no route at all. Spending is an act of sale, recorded at the register when it happens — exposing it would let a replayed request create or destroy money.

Parameters

NameInType
siteIdrequired path string (uuid)

Request bodyrequired

CreateVoucherRequest application/json

Responses

StatusDescriptionBody
201

Voucher issued

object
400

Missing amount (value is required).

ProblemDetails
401

Missing or invalid bearer token

—
403

Either the token does not grant the required scope or site access, or (07/10) the merchant's Gillia subscription has been CANCELLED and its account is read-only or archived. In the second case the body is a problem+json whose code is tenant_read_only (read-only period: consult, download and export only — no catalog download or change, no device enrolment or pairing, no register configuration, no stock reads or adjustments, no voucher issuance or extension) or tenant_archived (after the read-only period: the account is closed, data are kept until keptUntil and returned on request). Reads, orders coming from elsewhere (POST /pos/orders) and HubRise disconnection keep passing.

object
404

Resource not found or not accessible

—
422

Request is valid JSON but cannot be applied to the POS data

ProblemDetails
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
GET/sites/{siteId}/pos/vouchers/{code}pos.sales.read

Read a voucher and its balance

Returns the voucher matching the CODE the bearer presents or, failing that, the internal id returned when it was issued. isUsable answers the only question a checkout really asks: can this be used right now — still in date, and not fully consumed.

Parameters

NameInTypeDescription
siteIdrequired path string (uuid) —
coderequired path string

The voucher code, or the id returned at issuance.

Responses

StatusDescriptionBody
200

Voucher

Voucher
401

Missing or invalid bearer token

—
403

Token does not grant the required scope or site access

—
404

Resource not found or not accessible

—
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails
PATCH/sites/{siteId}/pos/vouchers/{voucherId}pos.vouchers.write

Extend a voucher's expiry

The ONLY field this route accepts is validUntil, and only to push it further out. Neither the amount nor the consumed balance can be touched here — see POST /pos/vouchers for why. Anything else in the body is ignored rather than partially applied.

Parameters

NameInType
siteIdrequired path string (uuid)
voucherIdrequired path string

Request bodyrequired

object application/json

Responses

StatusDescriptionBody
200

Voucher updated

object
400

validUntil missing — it is the only field this route can change.

ProblemDetails
401

Missing or invalid bearer token

—
403

Either the token does not grant the required scope or site access, or (07/10) the merchant's Gillia subscription has been CANCELLED and its account is read-only or archived. In the second case the body is a problem+json whose code is tenant_read_only (read-only period: consult, download and export only — no catalog download or change, no device enrolment or pairing, no register configuration, no stock reads or adjustments, no voucher issuance or extension) or tenant_archived (after the read-only period: the account is closed, data are kept until keptUntil and returned on request). Reads, orders coming from elsewhere (POST /pos/orders) and HubRise disconnection keep passing.

object
404

Resource not found or not accessible

—
422

Request is valid JSON but cannot be applied to the POS data

ProblemDetails
429

Rate limit reached (600 requests per minute per key, bursts up to 120). Wait the number of seconds given by Retry-After, then retry. Applies to every public route.

ProblemDetails

Webhooks

POSTyour webhook URL

Partner order changed state (order.accepted / order.rejected / order.completed, and order.ready / order.updated on request)

Sent by Gillia to the URL declared with PUT /pos/partner-webhook when the register accepts, refuses or finalizes one of your partner orders (and, if listed in your webhook events, marks it ready or pushes its time back / writes to the customer). Verify X-Gillia-Signature (t={unix},v1=hex HMAC-SHA256 of "{t}.{raw body}" with your whsec_ secret), refuse a t older than 5 minutes, de-duplicate on X-Gillia-Delivery, answer 2xx within 10 seconds. Redirects are not followed; failures are retried after 30 s, 1 min, 2 min… capped at 1 hour, 12 attempts. When in doubt, read GET /pos/partner-orders/{externalReference}. See PUT /pos/partner-webhook for a verification example.

Parameters

NameInTypeDescription
X-Gillia-Eventrequired header order.accepted · order.rejected · order.completed · order.ready · order.updated —
X-Gillia-Deliveryrequired header string

Unique event id, equal to the body id — use it to de-duplicate.

X-Gillia-Signaturerequired header string

t={unix seconds},v1={lowercase hex HMAC-SHA256(secret, "{t}.{raw body}")}

Request bodyrequired

PartnerWebhookEvent application/json

Responses

StatusDescriptionBody
200

Any 2xx acknowledges the event. Anything else (or no answer within 10 s) is retried.

—

Objects

AccountingEntries

FieldTypeDescription
fromalways string (date)
toalways string (date)
tillIncludedalways boolean

False if register journals could not be built; entries then cover invoices only.

openDaysalways array of string

Days with a register still open, left out of the entries.

defaultAccountsalways array of object

Accounts used by default because the merchant has not set them.

unbalancedalways array of string

References of entries whose debit and credit differ (should stay empty).

entriesalways array of object

AddProductImageRequest

FieldTypeDescription
urlalways string

Public https address of the image (website, Shopify, Google Drive or Dropbox sharing link open to anyone with the link). JPEG, PNG, GIF or WebP, 15 MB at most.

position integer

Wanted position (1 = main image). Omitted, the image is added last.

min 1

Certification

FieldTypeDescription
clientIdalways string
profilealways catalog · customers · orders · sales · accounting · inventory
statusalways running · passed · replaced · expired
startedAtalways string (date-time)
passedAt string (date-time)
expiresAtalways string (date-time)
appStatusalways sandbox · production
checksalways array of object

CodedValue

A coded value of the POS software, returned with its label.

FieldTypeDescription
codealways integer
name string

CreateCustomerRequest

Creates the customer record AND its addresses in a single call. The record itself goes through the POS business rules (minimum identity, company registration number, email and phone uniqueness); addresses are written straight after, in one transaction.

FieldTypeDescription
firstName string
lastName string
gender integer

0 none, 1 Mr, 2 Mrs, 3 company.

email string
phone string
birthday string (date-time)
groupId string
cardNumber string
comment string
marketingConsent boolean
sendTicketByEmail boolean
referenceNumber string
overDraft number (double)
iban string
bic string
mainAddress object

The address held by the record itself, the one the POS displays. It does NOT replace addresses: to deliver, add an addresses entry of type DELIVERY.

addresses array of WriteCustomerAddress

Typed addresses, set at creation time.

CreateOrderCustomer

The buyer to create if unknown. Goes through the SAME rules as on-screen entry: without a minimum identity (phone, or email, or first and last name) the whole ORDER is refused. A buyer already known by email or phone is reused, never duplicated.

FieldTypeDescription
gender integer
lastName string
firstName string
phone string
email string
address string
postalCode string
city string
referenceNumber string

Company registration number, required for a professional customer as it is on screen.

CreateOrderLine

FieldTypeDescription
productIdalways string

The product must EXIST at the merchant's — no reference is created on the fly.

quantityalways number
unitPriceTtcalways number

Unit price including tax, as YOU sold it.

min 0
vatRatealways number

VAT rate as a percentage (20 for 20%).

min 0 · max 100
label string

The wording the buyer saw. Defaults to the merchant's own product name.

comment string

CreateOrderRequest

FieldTypeDescription
externalReferencealways string

YOUR order reference. Required, and it is what makes the call replayable: calling again with the same reference returns the same order instead of creating a second one.

max length 100
customerId string

A customer already known to the merchant. Otherwise fill customer.

customer CreateOrderCustomer

The buyer to create if unknown. Goes through the SAME rules as on-screen entry: without a minimum identity (phone, or email, or first and last name) the whole ORDER is refused. A buyer already known by email or phone is reused, never duplicated.

linesalways array of CreateOrderLine
total number

Announced total including tax. Optional, but when supplied it is a CONTROL: a gap of more than one cent with the sum of the lines plus shipping makes the order fail, rather than recording an amount that does not add up.

shippingFees number
preparationHour string (date-time)
preparationOption string
deliveryDate string (date-time)
tableNumber string

CreateOrderResponse

FieldTypeDescription
orderIdalways string

The order identifier at the merchant's.

alreadyExistedalways boolean

True when the order already existed for this external reference (replayed call).

CreateProductRequest

Creates a product together with everything that hangs off it — all its barcodes, one price per sales channel, one purchase price per supplier, its components, its stock per store, its sections and its dimensions — in a single transaction. Nothing is written unless everything is.

Images are deliberately absent from this body: a product image is not a URL but a FILE stored on the site and served in three sizes under /Documents/<tenant>/Articles/<id>/. Add them once the product exists with POST …/products/{productId}/images, which downloads the picture from its public address and stores it (several images per product). The Gillia catalog reference is absent for the same kind of reason: it is the primary key of the central catalogue, unique across the whole estate.

FieldTypeDescription
namealways string

Short name, the one printed on receipts and shown on POS keys.

longName string

Long name, for an online product page. Defaults to the short name.

description string
internalReference string
unit integer

Sales unit AND product nature (see unit on read). 0 PIECE, 1 KILO, 2 LITRE, 3 METRE, 5 ARTICLE_COMPOSE, 6 FORMULE, 18 SERVICE, 19 LOT… Posting components without setting a composed unit produces a product that contradicts itself.

default 0
categoryArticle integer default 0
weight number (double)
contenance string
dimensions object
familyId string

Existing family. Otherwise familyName finds it by name, or creates it.

familyName string
subFamilyId string
subFamilyName string
salesOnline boolean default true
stockTracking boolean default true
options array of ProductOption

The product options — and, at the same time, its DECLINATION. There is deliberately no declination field on write: in the software that label is never typed, it is DERIVED. A database trigger always resets it to OptionValue1 + ' ' + OptionValue2 + ' ' + OptionValue3, so posting {"key":"Couleur","value":"Rouge"} and {"key":"Taille","value":"XL"} yields the declination "Rouge XL". Accepting a field only to overwrite it would be a promise the API does not keep.

At most THREE: the POS stores three option slots. A fourth one is REFUSED rather than silently dropped.

barcodes array of string

All barcodes. Blanks and duplicates are ignored.

prices array of WriteProductPrice

One entry per sales channel. Without any price the product exists but cannot be sold until the merchant sets one.

purchases array of WriteProductPurchase

One entry per supplier.

components array of WriteProductComponent

What the product is made of. Posting components marks the product as composed.

stock array of WriteProductStock

Stock to open, per store. Left empty, a single line is created for the site's own store — a product with no stock line disappears from several screens of the software, so one is always created.

sectionIds array of string

Sections to display the product in. They must already exist.

CreateStockAdjustmentLine

FieldTypeDescription
productIdalways string

POS product id from /pos/catalog/products or POS ticket line productId.

quantityDelta number (decimal)

Signed quantity delta. For loss or withdrawal, a positive value is converted to a negative stock delta.

quantityAfter number (decimal)

Absolute counted stock after the movement. Useful for inventory counts.

purchaseDutyFree number (decimal)
purchaseVat number (decimal)
purchaseIncludingTaxes number (decimal)
purchaseEcoTax number (decimal)
purchaseShipping number (decimal)
expirationDate string (date)

DLC or expiration date.

comment string

CreateStockAdjustmentRequest

FieldTypeDescription
reference string

External reference supplied by the calling application.

reason string

Business reason such as waste, inventory_count, correction, or supplier_return.

movementType adjustment · inventory · loss · withdrawal · purchase · transfer · production · add

Determines the POS journal type. purchase writes JournalAchat; the other values write StockUpgrade.

withdrawalCause damage · expiry · other

Used for loss or withdrawal movements.

supplierId string
supplierName string

Used mainly with purchase movements. Created in Societe when supplierId is not supplied.

effectiveAt string (date-time)
linesalways array of CreateStockAdjustmentLine

CreateVoucherRequest

FieldTypeDescription
valuealways number

Amount to issue.

code string

Your own code. Omit it and the merchant's numbering assigns one.

validFrom string (date-time)
validUntil string (date-time)

Customer

A customer as the POS actually holds it. Addresses are a LIST, each with its type and its default flag; paired x/xName fields are grouped into objects.

FieldTypeDescription
idalways string

Local POS customer id.

referenceNumber string

Human-readable customer number, the one the merchant announces.

firstName string
lastName string
gender object

Title. Codes: 0 none, 1 Mr, 2 Mrs, 3 company.

email string
phone string
birthday string (date-time)
group object

Customer pricing group, when the customer belongs to one.

state object

Record state. Codes: 0 archived, 1 active, 2 inactive.

addressesalways array of CustomerAddress

ALL typed addresses. Do NOT take the first one: type says what an address is for, and isDefault marks the one the merchant normally uses. An invoice goes to the billing address, a parcel to the delivery one, and they are not always the same.

mainAddress object

The address held by the RECORD itself, when filled in. It is NOT part of addresses: the POS captures one address directly on the record, with no type and no default, while typed addresses live separately. Many customer files only have this one.

activity object
terms object
cardNumber string
comment string
marketingConsentalways boolean
sendTicketByEmailalways boolean
updatedAt string (date-time)

CustomerActivity

What the customer has bought, as counters.

FieldTypeDescription
visitCountalways integer
articleCountalways integer
turnoverIncludingTaxesalways number (double)
loyaltyPointsalways number (double)
balancealways number (double)

Customer account balance; negative when the customer owes money.

CustomerAddress

FieldTypeDescription
idalways string
typealways string

BILLING_DELIVERY, BILLING, DELIVERY, or UNSPECIFIED when no type was ever chosen. UNSPECIFIED is NOT a delivery address: treating it as one would ship parcels to an address nobody designated for that.

label string

Name given to the address by the customer ("Home", "Office").

isDefaultalways boolean
firstName string
lastName string
society string
line1 string
line2 string
zipCode string
city string
region string
countryCode integer

ISO 3166-1 NUMERIC country code (250 = France). Not a name, not a two-letter code.

phone string
mobilePhone string

CustomerMainAddress

FieldTypeDescription
line1 string
line2 string
zipCode string
city string

CustomerPage

FieldTypeDescription
pagealways integer
pageSizealways integer
totalalways integer
cursoralways integer (int64)

Freshness cursor. Send it back as the cursor query parameter to read ONLY what changed since. With a cursor the page is ordered by change order, the only order in which a record modified during pagination cannot be skipped.

itemsalways array of Customer

CustomerTerms

FieldTypeDescription
discountAmount number (double)
discountPercent number (double)
overDraft number (double)
iban string
bic string

DeveloperApp

FieldTypeDescription
clientIdalways string
namealways string
redirectUrisalways array of string
scopesalways array of string
statusalways sandbox · production

sandbox until the application is certified; only sandbox businesses can authorize it meanwhile.

createdAtalways string (date-time)
activeGrantsalways integer

Number of businesses currently granting the application.

DeveloperAppCredentials

FieldTypeDescription
clientIdalways string
clientSecretalways string

Shown once. Send it to the token endpoint (HTTP Basic or form body); never put it in a browser or a mobile app.

namealways string
redirectUrisalways array of string
scopesalways array of string
statusalways sandbox · production

EntityRef

An entity quoted by its id AND its name.

FieldTypeDescription
idalways string
name string

HealthResponse

FieldTypeDescription
statusalways string
checkedAtUtcalways string (date-time)

MeResponse

FieldTypeDescription
subject string
clientId string
tenantId string (uuid)
siteIds array of string
scopes array of string
roles array of string

MoveProductImageRequest

FieldTypeDescription
positionalways integer

New position (1 = main image). The other images shift.

min 1

PartnerOrderCharge

FieldTypeDescription
labelalways string

Label ("Frais de livraison", "Code BIENVENUE").

amountalways number (double)

Tax-inclusive amount, not zero — positive for a fee, negative for a discount.

vatRate number (double)

Optional VAT rate in percent (10 for 10 %). Without it the amount follows the VAT of the order's articles — their rate, or split pro rata of their tax-inclusive amount when they have several rates.

min 0 · max 100

PartnerOrderCustomer

Optional buyer details. An existing customer record of the merchant is never overwritten.

FieldTypeDescription
id string

Optional. YOUR customer id. The customer is found by it first (even after an e-mail change), then by e-mail, then by phone. Kept per API key: two partners never share ids. An e-mail or a phone is still needed to create the customer.

max length 100
firstName string
lastName string
email string
phone string
address string
postalCode string
city string

PartnerOrderDeal

FieldTypeDescription
keyalways string

Key of the deal WITHIN this order ("d1"), unique, used by lines[].deal.key.

max length 50
name string

Name shown on the register ("Menu midi").

PartnerOrderLine

FieldTypeDescription
productIdalways string

Product of the merchant's catalog — its id or internal reference (GET /pos/catalog/products). Must be sellable online.

quantity number (double) default 1 · min 0
unitPricealways number (double)

Unit price, tax-inclusive, as you sold it (options excluded).

min 0
comment string

Instruction for this product ("bien cuit").

options array of PartnerOrderOption
name string

Optional. Product name, shown on the register ONLY when the product is unknown and the order carries unknownItems "accept". Never used to look the product up.

max length 250
vatRate number (double)

Optional VAT rate in percent. Without it, the product's own rate.

min 0 · max 100
deal PartnerOrderLineDeal

PartnerOrderLineDeal

FieldTypeDescription
keyalways string

Key of a deal declared in deals.

label string

Place of the line in the deal ("Drink"). The register shows "Menu midi · Drink".

PartnerOrderOption

Extra or removal chosen by the customer, taken from the option lists of the line's product.

FieldTypeDescription
productIdalways string

Product of the option (id or internal reference), as listed in the product's options.

quantity number (double)

Quantity per parent product.

default 1 · min 0
unitPrice number (double)

Unit price, tax-inclusive (0 for an included option).

default 0 · min 0
removed boolean

true for a REMOVAL ("no onions") — nothing is charged.

default false
name string

Optional. Option name, shown ONLY when the option is unknown and the order carries unknownItems "accept".

PartnerOrderPayment

FieldTypeDescription
statusalways paid

Only "paid" is accepted — the order must already be paid on your side.

method string

Payment method shown on the register ("Carte en ligne"). Defaults to the channel name.

splits array of object

Optional. Payment in several parts (card + meal voucher). One settlement line each on the ticket; their sum must equal total to the cent (422 payment_mismatch).

PartnerOrderRequest

Gillia format (not HubRise), camelCase. Amounts are tax-inclusive, in euros, with a decimal point.

FieldTypeDescription
externalReferencealways string

YOUR order reference. Makes the call replayable (same reference = same order) and identifies the order in responses and webhooks.

max length 50
channelalways string

Name shown on the register and the receipt ("Appli Pizza Express").

max length 50
displayNumber string

Short number announced to the customer ("4821"), shown large on the register. When absent, Gillia picks a number.

serviceType collection · delivery · eat_in default collection
expectedTime string (date-time)

Requested time (ISO 8601 with offset). Absent = as soon as possible.

notes string

Preparation note for the whole order.

customer PartnerOrderCustomer

Optional buyer details. An existing customer record of the merchant is never overwritten.

linesalways array of PartnerOrderLine
charges array of PartnerOrderCharge

Fees (positive amount) and discounts (negative amount).

totalalways number (double)

Total paid by the customer. Must equal, to the cent, the sum of lines (unitPrice × quantity), non-removed options (unitPrice × option quantity × line quantity) and charges.

paymentalways PartnerOrderPayment
deals array of PartnerOrderDeal

Optional. Deals (menus) sold in the order, referenced by lines[].deal.key.

unknownItems reject · accept

Optional. reject (default): an unknown product or option rejects the whole order (422 unknown_product). accept: the order is received; an unknown product reaches the register under lines[].name at your price, flagged "Product to check"; an unknown option is added to its line's comment and price.

default reject

PartnerOrderStatus

State of a partner order (creation and read responses; same fields as the webhook data).

FieldTypeDescription
externalReferencealways string
orderIdalways string

Order id on the Gillia side (shown on the register).

statusalways received · accepted · completed · rejected

received (ringing on the register, to accept) → accepted (being prepared) → completed; or rejected.

rejectionReason string

Present once rejected (omitted otherwise).

ticketId string

Fiscal ticket issued by the register at completion (omitted until then).

updatedAtalways string (date-time)

Last state change (UTC).

confirmedTime string (date-time)

Time the store PROMISED when accepting (preparation time chosen on the register), UTC. Omitted for a scheduled order (your expectedTime stands) or before acceptance. Updated when the store pushes the time back (order.updated).

readyAt string (date-time)

Time the store marked the order ready (UTC). Omitted until then.

alreadyExisted boolean

Present (true) only on a replayed creation — the order already existed for this reference.

PartnerWebhook

FieldTypeDescription
urlalways string (uri)
secret string

Signing secret ("whsec_…"). Returned ONLY on creation or rotation — store it.

eventsalways array of string

Events sent to this webhook.

PartnerWebhookEvent

Body of a webhook sent to the partner (compact JSON, signed as is).

FieldTypeDescription
idalways string

Unique event id ("evt_…"), same as the X-Gillia-Delivery header, unchanged across retries.

typealways order.accepted · order.rejected · order.completed · order.ready · order.updated
createdAtalways string (date-time)
siteIdalways string (uuid)
dataalways object

PartnerWebhookRequest

FieldTypeDescription
urlalways string (uri)

Public HTTPS address that receives the events by POST.

max length 500
rotateSecret boolean

true to generate a new signing secret (the old one stops working immediately).

default false
events array of string

Optional. Events wanted. Absent = unchanged (the three defaults order.accepted, order.rejected, order.completed at creation). order.ready and order.updated are sent only if listed here.

PosClosure

FieldTypeDescription
datealways string (date)
statusalways closed

Only closed days are returned; an open day is refused with 409.

totalCollectedalways number

Total taken in on that day — the figure printed on the merchant's own Z ticket.

totalInvoicedalways number

Total sales invoiced, VAT included (sum of the tax breakdown). Deliberately distinct from totalCollected: on-account sales, credit notes, debt settlements and deposits make them differ.

taxAmountalways number
cashDifferencealways number

Cash discrepancy recorded at closing.

taxesalways array of PosClosureTax
paymentsalways array of PosClosurePayment

PosClosurePayment

FieldTypeDescription
methodalways string

Stable technical key (cash, card, check, transfer, direct_debit, meal_voucher, credit_note, credit_note_used, gift_card, on_account, debt_settlement, deposit_received, online_card, online_paypal, cash_movement, other...). Best-effort normalisation of the merchant's own payment-method name: anything unrecognised comes back as "other". When in doubt, label is authoritative.

labelalways string

The payment method name as the merchant defined it.

totalalways number

PosClosureTax

FieldTypeDescription
ratealways number

VAT rate as a percentage (20 means 20%).

baseHtalways number
vatAmountalways number
totalalways number

Rate bracket total, VAT included.

PosZone

FieldTypeDescription
idalways string
namealways string
type string

ProblemDetails

FieldTypeDescription
type string
title string
status integer
detail string
instance string

Product

A product as the POS actually holds it. Anything a merchant can have several of is a LIST: barcodes, prices (one per sales channel), purchase prices (one per supplier), components, images, stock (one per store), sections and declinations. Do not assume a single value.

FieldTypeDescription
idalways string

POS article id.

internalReference string

The merchant's own reference.

namealways string

Short name, the one printed on receipts and shown on POS keys.

longName string

Long name, suitable for an online product page.

description string
unit object

Sales unit AND product nature in a single value, as the POS stores it. Codes: 0 PIECE, 1 KILO, 2 LITRE, 3 METRE, 4 CARBURANT, 5 ARTICLE_COMPOSE, 6 FORMULE, 7 CARTE_CADEAU, 8 TICKET, 9 REGLEMENT_CREANCE, 10 BILLET, 11 FRAIS, 12 SUBVENTION, 13 JEU, 14 MENSUEL, 15 ANNUEL, 16 POINT, 17 OPTION, 18 SERVICE, 19 LOT.

weight number (double)
contenance string

Declared content ("33 cl", "1 kg").

dimensions object
family object
subFamily object
category object

Gillia catalog category. The name is not resolved; only the id is returned.

salesOnlinealways boolean

True when the merchant offers this product for online sale.

stockTrackingalways boolean
isActivealways boolean

False for a product the merchant has put to sleep. Deleted products are never returned.

barcodesalways array of ProductBarcode

ALL barcodes of the product. A product often has more than one.

pricesalways array of ProductPrice

ALL prices, one per sales channel. Do NOT take the first one: pick the channel that matches your context (INTERNET for an online shop, LIVRAISON for delivery, EMPORTER for take-away). A price may also be time-bounded by validFrom/validTo/hourFrom/hourTo.

purchasesalways array of ProductPurchase

Purchase price per supplier.

referencesalways array of string

Other known references for this product (Gillia catalog).

optionsalways array of ProductOption
componentsalways array of ProductComponent

What the product is made of, when it is a recipe, a set menu or a bundle. Empty otherwise.

imagesalways array of ProductImage

Images in display order, one entry per image; the main one (position 1) comes first and is flagged isMain. Managed with …/products/{productId}/images.

stockalways array of ProductStock

Stock PER STORE. A three-shop chain returns three entries.

sectionsalways array of EntityRef

Sections (online shop, kiosk) the product is displayed in.

declination string

This product's own declination label ("Red", "XL"), when it has one.

declinationsalways array of ProductDeclination

The OTHER declinations of the same product. Each one is a full product with its own barcodes, prices and stock: to sell "red in XL" you need ITS id, not the parent's.

createdAt string (date-time)
updatedAt string (date-time)

ProductBarcode

FieldTypeDescription
codealways string

ProductCategory

FieldTypeDescription
idalways string
namealways string
parentId string

The family this sub-family belongs to. Null on a family itself.

ProductComponent

FieldTypeDescription
productalways EntityRef

An entity quoted by its id AND its name.

quantityalways number (double)
yield number (double)

Yield, when the component is transformed (a recipe loses weight while cooking).

ProductDeclination

FieldTypeDescription
productalways EntityRef

An entity quoted by its id AND its name.

label string
positionalways integer

ProductDimensions

FieldTypeDescription
height number (double)
width number (double)
depth number (double)

ProductImage

One image of a product (stored in three sizes). Paths are relative to the merchant's site (/Documents/…).

FieldTypeDescription
idalways string

Stable image id (does not change when the image or another one is moved or deleted).

urlalways string

Large size (960 px at most).

urls object
positionalways integer

Display rank, from 1. Position 1 is the main image.

isMainalways boolean

True for the main image (the first one).

isDefaultalways boolean

Same as isMain, kept for existing integrations.

width integer
height integer
isPortrait boolean

ProductImageList

FieldTypeDescription
itemsalways array of ProductImage

ProductOption

FieldTypeDescription
keyalways string
value string

ProductPage

FieldTypeDescription
pagealways integer
pageSizealways integer
totalalways integer

Total number of products matching the query.

itemsalways array of Product

ProductPrice

FieldTypeDescription
channelalways string

Sales channel. NORMAL, EMPORTER (take-away), SUR_PLACE (eat-in), LIVRAISON (delivery), HEURE (time-based), GROUPE_CLIENTS (customer group), LIBRE, RECEPTION, PERTE, INVENTAIRE, SOLDES (sale period), INTERNET (online), MOQ, TRADASTRA_SUR_PLACE, TRADASTRA_LIVRAISON, TRADASTRA_EMPORTER, JEU_ACHAT, JEU_GAIN. An unknown code is returned as TYPE_<n> rather than silently mapped to NORMAL.

label string
dutyFree number (double)
vatRate number (double)
includingTaxes number (double)
ecoTax number (double)
minimumOrderQuantity number (double)
accountingCode string

Accounting code, set PER PRICE and not on the product.

validFrom string (date-time)
validTo string (date-time)
hourFrom string

Start of daily validity, "HH:mm".

hourTo string
isActivealways boolean

ProductPurchase

FieldTypeDescription
supplier object
supplierReference string
dutyFree number (double)
vatRate number (double)
includingTaxes number (double)
ecoTax number (double)
shipping number (double)
packLabel string

Purchase pack name ("case of 12").

packSize number (double)
pricePerPack number (double)
leadTimeDays integer
minimumOrderQuantity number (double)

ProductStock

FieldTypeDescription
storeIdalways integer
storeName string
stockName string

Name of the storage location in that store ("COMPTOIR"). This is a label, not a quantity.

quantityalways number (double)
minimum number (double)
maximum number (double)
outOfStockalways boolean
averageCost number (double)

PurchaseAttachment

FieldTypeDescription
fileName string
category signed_delivery_note · invoice · warranty · reception_photo · reservation_photo · other
uploadedAt string (date-time)

PurchaseDiscrepancy

FieldTypeDescription
productId string
productName string
quantityExpected number
quantityReceived number
reason transport_damage · supplier_shortage · quality_rejected · order_error · other
comment string
resolved boolean
resolvedAt string (date-time)
createdAt string (date-time)

PurchaseLot

FieldTypeDescription
productId string
lotNumber string
serialNumber string
bestBefore string (date)

Calendar date (YYYY-MM-DD).

quantity number
receivedAt string (date-time)
location string

Storage location (warehouse mode)

PurchaseOrderDetail

object

PurchaseOrderLine

FieldTypeDescription
lineId integer
productId string
productName string
packageId string

Ordered package

quantityOrdered number
quantityFree number

Part of the ordered quantity given free by the supplier.

quantityReceived number
quantityOutstanding number

Still to receive (0 once the order is completed or cancelled).

quantityOver number

Received beyond the ordered quantity.

announced object

Lot / best-before / serial numbers announced by the supplier (imported delivery note), before reception.

PurchaseOrderPage

FieldTypeDescription
page integer
pageSize integer
hasMore boolean

True when another page follows.

items array of PurchaseOrderSummary

PurchaseOrderSummary

FieldTypeDescription
id integer

Gillia id of the order (use it for the detail route).

reference string

Order number in Gillia (purchase order number).

supplierOrderReference string

Order number on the supplier side

trackingNumber string

Carrier tracking number.

supplier PurchaseSupplier
status ordered · partiallyReceived · received · cancelled
directDelivery boolean

Goods recorded on arrival without a prior order.

networkOrder boolean

Order placed with the network central platform.

orderedAt string (date-time)
deliveryDate string (date)

Calendar date (YYYY-MM-DD) - expected delivery while nothing is received

quantityOrdered number
quantityReceived number
openDiscrepancies integer

Qualified reception discrepancies not resolved yet.

updatedAt string (date-time)

Last change (order

PurchaseReception

FieldTypeDescription
receivedAt string (date-time)
receivedBy string

Operator first name and last-name initial.

lines array of object

PurchaseSupplier

FieldTypeDescription
id string
name string
kind supplier · store

External supplier

SalesTicket

FieldTypeDescription
idalways string
localIdalways integer
orderId string
soldAt string (date-time)
openedSessionDate string (date-time)
storeId integer
postId integer
userId string
userName string
saleType integer

Numeric POS TypeSales value.

saleTypeName string
paymentMode string
tableNumber string
guestCount integer
customerId string
customerGroupId string
sessionId string
totalInclTax number (decimal)
paidAmount number (decimal)
infoPayment string
amountInfoPayment number (decimal)
offer integer
infoTicket integer
printed integer
proof integer
voucherId string
cancelledTicketId string
cancelledOrderId string
linesTotalDutyFree number (decimal)
linesVatAmount number (decimal)
linesDiscountAmount number (decimal)
linesSalesAmount number (decimal)
linesVoucherAmount number (decimal)
linesPurchaseDutyFree number (decimal)
linesPurchaseIncludingTaxes number (decimal)
isCancelledalways boolean
billsalways array of SalesTicketBill

Payment rows for the ticket, including means of payment and paid amounts.

linesalways array of SalesTicketLine

SalesTicketBill

FieldTypeDescription
localIdalways integer
idalways string
orderId string
ticketId string
soldAt string (date-time)
openedSessionDate string (date-time)
storeId integer
postId integer
userId string
userName string
saleType integer

Numeric POS TypeSales value.

saleTypeName string
paymentMode string
amountInclTax number (decimal)
paidAmount number (decimal)
infoPayment string
amountInfoPayment number (decimal)
offer integer
tableNumber string
guestCount integer
customerId string
customerGroupId string
infoTicket integer
printed integer
sessionId string
proof integer
voucherId string
cancelledTicketId string
cancelledOrderId string
isCancelledalways boolean

SalesTicketLine

FieldTypeDescription
idalways string
localIdalways integer
ticketId string
orderId string
soldAt string (date-time)
openedSessionDate string (date-time)
ticketPosition integer
storeId integer
postId integer
userId string
userName string
orderUserId string
orderUserName string
saleType integer
saleTypeName string
tariffType integer

Numeric POS TypeTarif value.

tariffTypeName string
productId string

POS article id from the ticket line.

productName string
productGroupName string
familyId string
familyName string
subFamilyId string
subFamilyName string
declination string
declinationLink string
quantityalways number (decimal)
tare number (decimal)
originalUnitPriceInclTax number (decimal)
unitPriceInclTax number (decimal)
discountAmount number (decimal)
discountReason string
salesName string
salesAmount number (decimal)
voucherAmount number (decimal)
offerQuantity integer
offerAmount number (decimal)
totalInclTax number (decimal)
totalDutyFree number (decimal)
vatRate number (decimal)
vatAmount number (decimal)
ecoTax number (decimal)
purchaseDutyFree number (decimal)
purchaseVatRate number (decimal)
purchaseVatAmount number (decimal)
purchaseIncludingTaxes number (decimal)
purchaseEcoTax number (decimal)
purchaseShipping number (decimal)
cump number (decimal)
purchaseFifo number (decimal)
typeItem string
categoryArticle integer
accountingCode string
formuleId string
link string
customerId string
tableNumber string
sessionId string
cancelledTicketId string
cancelledOrderId string
isCancelledalways boolean
stockAlreadyDeducted boolean
state integer
customText string
articleExtraProductId string
articleCollectionId string
collectionId string
collectionName string
season string

SalesTicketPage

FieldTypeDescription
pagealways integer
pageSizealways integer
totalCountalways integer
itemsalways array of SalesTicket

Site

FieldTypeDescription
idalways string (uuid)
tenantIdalways string (uuid)
namealways string
code string
localStoreId integer
tradastraInstitutionId string (uuid)

Gillia establishment id of the site (historical field name).

apiEnabledalways boolean

StockAdjustmentLineResult

FieldTypeDescription
productIdalways string
posArticleIdalways string
quantityDeltaalways number (decimal)
quantityAfteralways number (decimal)
journalIdalways string

POS journal id.

journalTypealways stockUpgrade · journalAchat

StockAdjustmentResponse

FieldTypeDescription
idalways string
statusalways applied · accepted
acceptedAtalways string (date-time)
linesalways array of StockAdjustmentLineResult

StockItem

FieldTypeDescription
productIdalways string
productName string
stockIdalways string
stockName string
storeId integer
storeName string
quantityalways number (decimal)
stockMin number (decimal)
stockMax number (decimal)
outOfStockalways boolean
cumpalways number (decimal)
updatedAt string (date-time)

StockItemPage

FieldTypeDescription
pagealways integer
pageSizealways integer
totalCountalways integer
itemsalways array of StockItem

StockLot

FieldTypeDescription
id string
productId string
productName string
lotNumber string
serialNumber string
dlc string (date)

Best-before / use-by date

quantityRemaining number
receivedDate string (date-time)

When the lot was received (UTC instant).

StockLotPage

FieldTypeDescription
page integer
pageSize integer
hasMore boolean

True when another page follows.

items array of StockLot

StockMovement

FieldTypeDescription
id integer

Gillia id of the movement.

type out · transfer · production
reference string

Movement number in Gillia (otherwise the external reference typed by the store).

state pending · completed · cancelled

pending (saved, not validated yet), completed (validated, stock moved), cancelled.

cause damage · expiry · other · cancellation · exceptional_sale · theft · donation · sample · customer_gift · production_cascade · unsold · supplier_return · customer_return · customer_return_loss · lot_content · network_transfer

Reason of a stock exit (type out only; null otherwise or when none was given). New values may be added - treat unknown ones as other.

createdAt string (date-time)
updatedAt string (date-time)

Last time the movement was saved. Use it for updatedSince.

fromSite StockMovementSite

A site of the brand - only on a transfer (fromSite = sending site, toSite = receiving site).

toSite StockMovementSite

A site of the brand - only on a transfer (fromSite = sending site, toSite = receiving site).

lines array of StockMovementLine

StockMovementLine

FieldTypeDescription
productId string
productName string
quantity number

Quantity moved (in the product's base unit).

StockMovementPage

FieldTypeDescription
page integer
pageSize integer
hasMore boolean

True when another page follows.

items array of StockMovement

StockMovementSite

A site of the brand - only on a transfer (fromSite = sending site, toSite = receiving site).

FieldTypeDescription
id string (uuid)

The siteId of that site.

name string

Supplier

FieldTypeDescription
id string
name string
email string
phone string
address string
postalCode string
city string
siret string

French company registration number

SupplierPage

FieldTypeDescription
page integer
pageSize integer
hasMore boolean

True when another page follows.

items array of Supplier

Tenant

FieldTypeDescription
idalways string (uuid)
namealways string
isActivealways boolean

TenantLockedProblem

07/10 — 403 of a merchant whose Gillia subscription is cancelled (read-only or archived).

object

UpdateCustomerRequest

PARTIAL update. A field you omit is left untouched; a field you send is written, an empty value included — that is how a field is cleared.

FieldTypeDescription
gender integer

3 = professional (company registration number required); other values = individual.

lastName string
firstName string
phone string
email string
address string
address2 string
postalCode string
city string
birthday string (date)
customerGroupId string
referenceNumber string

Company registration number. Required (9 digits minimum) as soon as the record is professional.

comment string
bic string
iban string
sendTicketMail boolean
marketingConsentState boolean

Voucher

FieldTypeDescription
idalways string
codealways string

What the bearer presents.

valuealways number

Amount issued.

usedalways number

Amount already consumed at the register. Writable by no route.

remainingalways number
validFrom string (date-time)
validUntil string (date-time)
isUsablealways boolean

Usable today — within its validity period AND not fully consumed.

storeId integer

WebhookTestResult

FieldTypeDescription
deliveredalways boolean
status integer

HTTP status your endpoint answered, when it answered.

error string

Why the event was not acknowledged.

deliveryIdalways string

WriteCustomerAddress

FieldTypeDescription
type string

BILLING_DELIVERY, BILLING or DELIVERY. Defaults to DELIVERY.

label string
isDefault boolean

Setting this clears the default flag on the customer's other addresses.

firstName string
lastName string
society string
line1 string
line2 string
zipCode string
city string
region string
countryCode integer

ISO 3166-1 numeric code. Defaults to 250 (France).

phone string
mobilePhone string

WriteProductComponent

FieldTypeDescription
productIdalways string

Id of the component product. It must already exist.

quantityalways number (double)

Strictly positive.

yield number (double)

WriteProductPrice

FieldTypeDescription
channel string

NORMAL (default), EMPORTER, SUR_PLACE, LIVRAISON, INTERNET, SOLDES, HEURE… An unknown channel is REFUSED, never folded back to NORMAL: a price filed under the wrong channel would be sold in the wrong place.

label string
dutyFree number (double)

RECALCULATED, and what you send here is overwritten. A database trigger always resets it to includingTaxes / (1 + vatRate / 100). The source of truth for a price is the tax- inclusive amount together with the VAT rate.

vatRate number (double)

Between 0 and 100.

includingTaxes number (double)

The tax-inclusive price — this is the one that counts.

ecoTax number (double)
minimumOrderQuantity number (double)
accountingCode string

Defaults to 70700000, as the software does.

validFrom string (date-time)
validTo string (date-time)
hourFrom string

Start of daily validity, "HH:mm". Any other format is refused.

hourTo string
isActive boolean default true

WriteProductPurchase

FieldTypeDescription
supplierId string

Existing supplier. Otherwise supplierName finds it by name, or creates it.

supplierName string
supplierReference string
dutyFree number (double)
vatRate number (double)
includingTaxes number (double)
ecoTax number (double)
shipping number (double)
packLabel string
packSize number (double)
pricePerPack number (double)
leadTimeDays integer
minimumOrderQuantity number (double)

WriteProductStock

FieldTypeDescription
storeId integer

Store number. Defaults to the site's own store. It must exist.

stockName string

Storage location name. Defaults to COMPTOIR, as the software does.

initialQuantity number (double)

Opening quantity. It is applied through a stock MOVEMENT, not by writing the quantity directly: that is what records where the stock came from and feeds the weighted average cost.

minimum number (double)
maximum number (double)