Skip to main content

Web shop order intake contract

A shop connector (integriq's web shop connectors for WooCommerce, Shopify, Lightspeed, CCV Shop, Magento and others) hands shillinq one WebshopOrder object per order the shop takes. Shillinq turns that record into one sales invoice (ARInvoice) on the channel's administration. This page is the contract the connector's mapping follows. The source of truth is the WebshopOrder and WebshopChannel schemas in lib/Settings/register.d/sales-webshop-orders.json; when this page and the schema disagree, the schema wins.

Before the first order: the channel​

Every order names a WebshopChannel. A bookkeeper creates the channel in shillinq; the connector only reads its id.

FieldRequiredMeaning
nameyesThe shop's name, such as its domain.
platformyesOne of woocommerce, shopify, lightspeed, ccvshop, magento, other.
administrationIdyesThe administration the shop's orders are booked in.
consumerDebtorIdyesThe collective debtor (verzameldebiteur) consumer orders are booked on.
revenueAccountyesThe revenue account for the order lines.
shippingAccountnoThe revenue account for the shipping charge.
clearingAccountyesThe payment clearing account a paid order is settled on.
issueModeyesauto-issue issues the invoice at once; draft-for-review leaves it a draft.

The order record​

The connector writes these fields. Every field marked required must be present, or OpenRegister refuses the write.

FieldRequiredTypeMeaning
channelIdyesstringThe WebshopChannel id. An order for an unknown channel is refused.
shopOrderIdyesstringThe shop's own order number, as the shop shows it to the buyer.
orderedAtyesdate-timeWhen the buyer placed the order.
buyeryesobjectThe buyer, see below.
currencyyesstringISO 4217 code, such as EUR.
pricesIncludeVatnobooleanWhether unitPrice, shipping and totals include VAT.
linesyesarrayOne entry per order line, see below.
shippingnonumberThe shipping charge, with or without VAT as pricesIncludeVat says.
discountTotalnonumberThe order's discount total.
totalsyesobjectnet, vat and gross as the shop computed them. The lines must add up to them.
paymentyesobjectThe payment state, see below.

buyer​

FieldMeaning
typebusiness or consumer.
nameThe buyer's name, printed on the invoice.
emailThe buyer's email address.
companyNameA business buyer's company name.
vatIdA business buyer's VAT id. Matched first.
kvkNumberA business buyer's KvK number. Matched second.
addressThe invoice address, printed on the invoice.

A business buyer is matched to an existing customer of the channel's administration by VAT id, else KvK number, else invoice email; when none matches, shillinq creates the customer and marks it as created by the channel. A consumer order is booked on the channel's collective debtor, with the buyer's name and address on the invoice.

lines[]​

FieldMeaning
skuThe shop's article code.
descriptionThe line text, printed on the invoice.
quantityThe ordered quantity.
unitPricePrice per unit, with or without VAT as pricesIncludeVat says.
vatRateThe VAT rate in percent the shop applied to this line.

The shipping charge takes the rate of the goods it ships; on an order mixing rates it is split pro rata over those rates.

payment​

FieldMeaning
statusOne of the values below.
methodThe payment method, such as ideal.
providerPaymentIdThe payment provider's id, kept on the invoice so the payout can be matched.
statusWhat shillinq does
paidInvoices the order and settles it on the channel's clearing account.
pendingInvoices the order; it stays open until a later write reports paid.
refundedWrites a credit note for an invoiced order.
cancelledWrites a credit note for an invoiced order.

A change of payment status is sent as an update of the same order record.

Settling posts one receipt (debit the clearing account, credit receivables) for the invoice's gross amount and marks the invoice paid. It happens once per order, and only for an issued invoice: on a channel that leaves invoices as drafts, the bookkeeper settles them after issuing.

Idempotency​

The idempotency key is the pair channelId + shopOrderId, never the id of the intake record. A connector that sends the same order again, also under a new record id, gets no second invoice: the second record is marked duplicate. Retrying a write is therefore always safe.

Fields the connector never writes​

These are shillinq's own and are set by its lifecycle; the connector leaves them out.

FieldMeaning
intakeStatereceived, invoiced, refused, duplicate or credited. A new record starts as received.
administrationIdTaken from the channel.
arInvoiceIdThe invoice written for the order.
creditNoteIdThe credit note written on refund or cancellation.
refusalReasonWhy the order was refused.

Refusals​

An order shillinq cannot invoice is moved to refused with a refusalReason, and the administration's bookkeepers get a notification. Shillinq refuses, rather than guesses, when:

  • the channel is unknown;
  • the lines, shipping and discount do not add up to totals (the reason names both totals);
  • the VAT route cannot be determined: shillinq never falls back to the Dutch rate.