Format karqa-shop-export, version 1

The shop data export

Every shop on karqa can download all of its data, free and as often as it likes, from Settings → Billing in its back office: the catalogue with its images, customers and their orders, invoices and credit notes, reviews, and the shop's pages, designs and settings.

This page is the register of the export's data structures and formats that the Data Act asks for (Regulation (EU) 2023/2854, article 26(b)), and section 19 of the Platform Terms of Use promises. It is generated from the code that writes the export, so it describes the export as it is today. The same register, machine-readable and with a JSON Schema for each JSON file, is published by the platform's API.

How every file is written

A ZIP archive. JSON files are UTF-8 (RFC 8259), with property names in camelCase; a property whose value is empty is left out. CSV files are UTF-8 with a byte order mark, comma-separated, quoted as RFC 4180 describes, with CRLF line ends and a header row; a cell that would start with =, +, -, @ or a tab and is not a number is prefixed with an apostrophe, so a spreadsheet does not run it. Amounts use a full stop for decimals. Dates are UTC: ISO 8601 in JSON, "yyyy-MM-dd HH:mm" in CSV. Stored files keep the bytes and format they were uploaded in.

The archive's root

`README.txt`

Plain text (UTF-8) What the archive holds, in brief.

`manifest.json`

JSON When the archive was made, the format and its version, and how many records each part holds.

Fields of each record (6)

Field	Value
`format`	text
`version`	text
`shop`	text
`shopName`	text, or empty
`exportedAt`	date and time (UTC)
`records`	record

`catalogue/`

`catalogue/products.json`

JSON Every product, with its variants, options, attributes, categories, prices and images.

Fields of each record (43)

Field	Value
`id`	text
`name`	text
`description`	text
`metaTitle`	text, or empty
`metaDescription`	text, or empty
`metaKeywords`	text, or empty
`minimumOrderQuantity`	text, or empty
`subtractStock`	yes or no, or empty
`requiresShipping`	yes or no, or empty
`primaryImageUrl`	text, or empty
`images`	list of records
`isActive`	yes or no
`slug`	text, or empty
`categories`	list of records
`createdAt`	date and time (UTC)
`updatedAt`	date and time (UTC), or empty
`taxClass`	one of: Standard, Books & publications, Food & drink, Medicines, Medical equipment, Children's clothing & footwear, Children's car seats, Plants & cut flowers
`weightClass`	one of: Milligram, Gram, Kilogram, Ounce, Pound
`lengthClass`	one of: Millimeter, Centimeter, Meter, Inch, Foot, Yard, or empty
`sortOrder`	text, or empty
`brand`	text, or empty
`sku`	text, or empty
`upc`	text, or empty
`ean`	text, or empty
`isbn`	text, or empty
`mpn`	text, or empty
`jan`	text, or empty
`price`	text
`salePrice`	text, or empty
`saleEndsAt`	date and time (UTC), or empty
`priorPrice`	text, or empty
`stockQuantity`	text
`outOfStockStatus`	one of: In Stock, Out of Stock, Pre-Order, Back Order, Discontinued Product, Low Stock, On The Way, Temporarily Unavailable, or empty
`isInStock`	yes or no, or empty
`weight`	text, or empty
`handlingTimeDays`	text, or empty
`length`	text, or empty
`width`	text, or empty
`height`	text, or empty
`attributeValues`	list of records
`hasVariants`	yes or no
`variants`	list of records, or empty
`productOptionGroups`	list of records

`catalogue/products.csv`

CSV One row per product and one per variant, for a spreadsheet or another shop system.

Columns (15)

`catalogue/categories.json`

JSON The categories.

Fields of each record (13)

Field	Value
`id`	text
`name`	text
`description`	text
`imageUrl`	text, or empty
`slug`	text
`metaTitle`	text
`metaDescription`	text
`metaKeywords`	text
`isActive`	yes or no
`parentCategoryId`	text, or empty
`createdAt`	date and time (UTC)
`updatedAt`	date and time (UTC), or empty
`sortOrder`	text

`catalogue/option-groups.json`

JSON The option groups (size, colour, …) and their options.

Fields of each record (8)

Field	Value
`id`	text
`name`	text
`type`	one of: Select, Radio, Checkbox, Text, Number, Date, Time, Date Time
`description`	text, or empty
`isFilterable`	yes or no
`required`	yes or no, or empty
`sortOrder`	text, or empty
`productOptions`	list of records, or empty

`catalogue/attribute-groups.json`

JSON The attribute groups (material, …) and their values.

Fields of each record (5)

Field	Value
`id`	text
`name`	text
`description`	text, or empty
`isFilterable`	yes or no
`values`	list of records

`customers/`

`customers/customers.json`

JSON Every customer who has ordered, with what they ordered in total and their labels.

Fields of each record (11)

Field	Value
`email`	text
`name`	text
`phone`	text
`ordersCount`	text
`paidOrders`	text
`totalSpent`	text
`currency`	text
`firstOrderAt`	date and time (UTC)
`lastOrderAt`	date and time (UTC)
`lastStatus`	text
`labels`	list of records

`customers/customers.csv`

CSV The customers, one per row.

Columns (11)

Email
Name
Phone
Orders
Paid orders
Total spent
Currency
First order
Last order
Last status
Labels

`customers/labels.json`

JSON The labels used on customers.

Fields of each record (4)

Field	Value
`id`	text
`tenantId`	text
`name`	text
`color`	text

`orders/`

`orders/orders.json`

JSON Every order, with its lines, addresses, payment, delivery, amounts and labels.

Fields of each record (78)

Field	Value
`id`	text
`orderNumber`	text
`status`	one of: Awaiting payment, Processing, Completed, Cancelled, Refunded, On Hold, Failed, Cash on delivery
`subTotal`	text
`shippingCost`	text
`codFee`	text
`platformCommissionPercent`	text, or empty
`taxAmount`	text, or empty
`taxNote`	text, or empty
`vatRatePercent`	text, or empty
`vatCountry`	text, or empty
`vatBasis`	one of: Origin, Destination, SellerExempt, DestinationUnverified, OutsideEu, OriginUnknown, OriginUnverified, IntraCommunity, or empty
`baseGrandTotalEur`	text, or empty
`eurFxRate`	text, or empty
`eurFxRateDate`	text, or empty
`discountAmount`	text, or empty
`discountCode`	text, or empty
`grandTotal`	text
`refundedAmount`	text, or empty
`baseRefundedAmount`	text, or empty
`currency`	one of: USD, EUR, RON, GBP, JPY, CNY, AUD, CAD, CHF, INR, BRL, RUB, MXN, SGD, NZD, HKD, SEK, NOK, DKK, PLN, ZAR, TRY, AED, SAR, KRW, HUF
`baseGrandTotal`	text
`baseCurrency`	one of: USD, EUR, RON, GBP, JPY, CNY, AUD, CAD, CHF, INR, BRL, RUB, MXN, SGD, NZD, HKD, SEK, NOK, DKK, PLN, ZAR, TRY, AED, SAR, KRW, HUF
`fxRate`	text
`fxRateDate`	text, or empty
`customerEmail`	text
`customerPhone`	text
`billingFirstName`	text
`billingLastName`	text
`billingAddress1`	text
`billingAddress2`	text, or empty
`billingCompanyName`	text, or empty
`billingCompanyTaxId`	text, or empty
`billingCompanyRegistrationNumber`	text, or empty
`billingCompanyVerifiedAt`	date and time (UTC), or empty
`billingCompanyVerificationSource`	text, or empty
`billingCompanyVerificationRef`	text, or empty
`billingCompanyInactive`	yes or no
`billingCompanyRegisteredOffice`	record, or empty
`billingCity`	text
`billingState`	text
`billingPostalCode`	text
`billingCountry`	text
`shippingFirstName`	text
`shippingLastName`	text
`shippingAddress1`	text
`shippingAddress2`	text, or empty
`shippingCity`	text
`shippingState`	text
`shippingPostalCode`	text
`shippingCountry`	text
`paymentMethod`	text, or empty
`paymentTransactionId`	text, or empty
`paymentStatus`	one of: Pending, Authorized, Paid, Refunded, Failed, Voided
`shippingMethod`	text, or empty
`trackingNumber`	text, or empty
`trackingUrl`	text, or empty
`shippingStatus`	one of: Pending, Processing, Shipped, Delivered, Failed
`awbCost`	text, or empty
`lockerId`	text, or empty
`lockerName`	text, or empty
`lockerAddress`	text, or empty
`returnAwbNumber`	text, or empty
`createdAt`	date and time (UTC)
`updatedAt`	date and time (UTC), or empty
`paidAt`	date and time (UTC), or empty
`handlingTimeDays`	text, or empty
`shippedAt`	date and time (UTC), or empty
`completedAt`	date and time (UTC), or empty
`piiAnonymisedAt`	date and time (UTC), or empty
`note`	text
`shopNote`	text
`liveMode`	yes or no
`stripePaymentIntentId`	text, or empty
`stripeCheckoutSessionId`	text, or empty
`isPaid`	yes or no
`items`	list of records, or empty
`labels`	list of records, or empty

`orders/orders.csv`

CSV The orders, one per row.

Columns (33)

Order number
Date
Status
Payment status
Shipping status
Payment method
Customer email
Customer phone
Billing name
Shipping name
Shipping address
Shipping city
Shipping postal code
Shipping country
Shipping method
Tracking number
Subtotal
Shipping cost
COD fee
Discount code
Discount amount
Tax
Total
Currency
Total in shop currency
Shop currency
Labels
Billing company
Company fiscal code
VAT treatment
Company checked with
Company checked at
VIES consultation number

`orders/history.json`

JSON What happened to each order after it was placed, naming it by orderId.

Fields of each record (10)

Field	Value
`id`	text
`orderId`	text
`tenantId`	text
`event`	one of: Order Created, Order Completed, Order Cancelled, Order Refunded, Order Failed, Order Updated, Status Changed, Tracking Number Set, Order Fulfilled, Note Updated, Dispute Opened, Partially Refunded, Dispute Closed, Withdrawal Received
`note`	text
`previousValue`	text, or empty
`newValue`	text, or empty
`isCustomerNotified`	yes or no
`createdAt`	date and time (UTC)
`createdBy`	text

`orders/messages.json`

JSON The messages exchanged about each order.

Fields of each record (7)

Field	Value
`id`	text
`tenantId`	text
`orderId`	text
`sender`	one of: Merchant, Customer
`body`	text
`createdAt`	date and time (UTC)
`readAt`	date and time (UTC), or empty

`orders/refunds.json`

JSON Each refund, with what it refunded.

Fields of each record (11)

Field	Value
`id`	text
`tenantId`	text
`orderId`	text
`amount`	text
`baseAmount`	text
`isFull`	yes or no
`reason`	text, or empty
`createdAt`	date and time (UTC)
`creditNoteIssueStartedAt`	date and time (UTC), or empty
`createdBy`	text
`lines`	list of records

`orders/return-requests.json`

JSON Each return request and what became of it.

Fields of each record (9)

Field	Value
`id`	text
`tenantId`	text
`orderId`	text
`kind`	one of: Refund, Replacement
`status`	one of: Requested, Approved, Rejected, Refunded
`reason`	text
`createdAt`	date and time (UTC)
`reviewedAt`	date and time (UTC), or empty
`merchantNote`	text, or empty

`orders/labels.json`

JSON The labels used on orders.

Fields of each record (4)

Field	Value
`id`	text
`tenantId`	text
`name`	text
`color`	text

`invoices/`

`invoices/invoices.csv`

CSV Every invoice and credit note, with where its PDF and XML are in the archive.

Columns (13)

Number
Type
Issued
Order number
Reverses
Total
Currency
Issued through
Status
PDF
XML
Provider's PDF link
Note

`invoices/{number}.pdf`

PDF Each invoice or credit note as it was sent to the customer.

`invoices/{number}.xml`

XML (UBL 2.1, CIUS-RO for e-Factura) Each invoice or credit note the platform issued itself, as an EN 16931 electronic invoice.

`reviews/`

`reviews/reviews.json`

JSON Every product review, with what the shop decided about it.

Fields of each record (12)

Field	Value
`id`	text
`productId`	text
`productName`	text, or empty
`orderId`	text, or empty
`customerName`	text, or empty
`customerEmail`	text, or empty
`rating`	text
`comment`	text, or empty
`status`	one of: Pending, Approved, Rejected
`rejectionGround`	one of: Unlawful, Offensive, OthersPersonalData, NotAboutTheProduct, or empty
`moderatedAt`	date and time (UTC), or empty
`createdAt`	date and time (UTC)

`reviews/reviews.csv`

CSV The reviews, one per row.

Columns (7)

Date
Product
Customer
Rating
Review
Status
Rejected because

`shop/`

`shop/settings.json`

JSON The shop's settings: its identity, address, branding, currencies, markets, tax, payment, delivery and invoicing choices. Stored credentials are not included.

Fields of each record (107)

Field	Value
`id`	text
`tenantId`	text
`customDomain`	text, or empty
`customDomainVerificationToken`	text, or empty
`customDomainVerifiedAt`	date and time (UTC), or empty
`customDomainCheckFailingSince`	date and time (UTC), or empty
`businessName`	text
`legalName`	text
`businessAddress`	text
`city`	text
`county`	text, or empty
`country`	text, or empty
`postalCode`	text
`businessEmail`	text
`businessPhone`	text
`showPhoneOnShop`	yes or no
`taxId`	text, or empty
`vatNumberVerifiedAt`	date and time (UTC), or empty
`vatNumberVerificationRef`	text, or empty
`vatRate`	text
`vatExempt`	yes or no
`vatExemptionNote`	text, or empty
`vatThreshold`	text, or empty
`chargesDestinationVat`	yes or no
`chargesDestinationVatSince`	date and time (UTC), or empty
`businessRegistrationNumber`	text, or empty
`invoicingProvider`	one of: None, XmlExport, Oblio, SmartBill
`invoicingEnabledAt`	date and time (UTC), or empty
`invoiceSeries`	text, or empty
`nextInvoiceNumber`	text
`invoicingApiEmail`	text, or empty
`courierProvider`	one of: None, Sameday
`samedayApiUsername`	text, or empty
`samedaySandbox`	yes or no
`samedayPickupPointId`	text, or empty
`samedayHomeServiceId`	text, or empty
`samedayLockerServiceId`	text, or empty
`samedayAccountCountry`	text
`samedayCrossBorderHomeServiceId`	text, or empty
`samedayCrossBorderLockerServiceId`	text, or empty
`shopLanguage`	text
`timeZone`	text, or empty
`effectiveTimeZone`	text, or empty
`currency`	one of: USD, EUR, RON, GBP, JPY, CNY, AUD, CAD, CHF, INR, BRL, RUB, MXN, SGD, NZD, HKD, SEK, NOK, DKK, PLN, ZAR, TRY, AED, SAR, KRW, HUF
`acceptedPaymentCurrencies`	list of text, or empty
`displayCurrencies`	list of text, or empty
`checkoutStrategy`	one of: NativeOnly, StripeConversion
`codEnabled`	yes or no
`codFee`	text
`codCountryCodes`	list of text, or empty
`weightClass`	one of: Milligram, Gram, Kilogram, Ounce, Pound
`lengthClass`	one of: Millimeter, Centimeter, Meter, Inch, Foot, Yard
`website`	text, or empty
`instagramUrl`	text, or empty
`facebookUrl`	text, or empty
`tiktokUrl`	text, or empty
`description`	text, or empty
`logoUrl`	text, or empty
`aboutPageContent`	text, or empty
`isActive`	yes or no
`suspendedAt`	date and time (UTC), or empty
`archivedAt`	date and time (UTC), or empty
`closureRequestedAt`	date and time (UTC), or empty
`closureEffectiveAt`	date and time (UTC), or empty
`closureReason`	text, or empty
`suspensionReason`	text, or empty
`isLive`	yes or no
`wentLiveAt`	date and time (UTC), or empty
`isVerified`	yes or no
`verificationDate`	date and time (UTC), or empty
`primaryColor`	text
`secondaryColor`	text
`paragraphFont`	one of: Arial, Verdana, Tahoma, Trebuchet MS, Georgia, Times New Roman, Courier New, Impact, Comic Sans MS, Lucida Console, Helvetica, Arial Black, Palatino Linotype, Garamond, Bookman Old Style, Inter, Roboto, Open Sans, Lato, Montserrat, Poppins, Raleway, Nunito, Work Sans, Rubik, DM Sans, Manrope, Mulish, Source Sans 3, Playfair Display, Merriweather, Lora, Roboto Slab, PT Serif, Oswald
`headingFont`	one of: Arial, Verdana, Tahoma, Trebuchet MS, Georgia, Times New Roman, Courier New, Impact, Comic Sans MS, Lucida Console, Helvetica, Arial Black, Palatino Linotype, Garamond, Bookman Old Style, Inter, Roboto, Open Sans, Lato, Montserrat, Poppins, Raleway, Nunito, Work Sans, Rubik, DM Sans, Manrope, Mulish, Source Sans 3, Playfair Display, Merriweather, Lora, Roboto Slab, PT Serif, Oswald
`createdAt`	date and time (UTC)
`updatedAt`	date and time (UTC), or empty
`neglectedOrderCount`	text
`neglectedOrdersFlaggedAt`	date and time (UTC), or empty
`lastNeglectDigestAt`	date and time (UTC), or empty
`onboardingCompleted`	yes or no
`platformTermsAcceptedAt`	date and time (UTC), or empty
`platformTermsVersion`	text, or empty
`platformTermsNotifiedVersion`	text, or empty
`dpaAcceptedAt`	date and time (UTC), or empty
`dpaVersion`	text, or empty
`stripeTestConnected`	yes or no
`stripeLiveConnected`	yes or no
`subscriptionChargeAmount`	text, or empty
`subscriptionChargeCurrency`	text, or empty
`subscriptionFxRate`	text, or empty
`subscriptionFxRateDate`	text, or empty
`subscriptionStatus`	text, or empty
`orderPiiRetentionMonths`	text, or empty
`freeTextRetentionMonths`	text, or empty
`defaultOrderNoteTemplate`	text, or empty
`returnWindowDays`	text
`handlingTimeDays`	text, or empty
`lowStockThreshold`	text, or empty
`lastLowStockDigestAt`	date and time (UTC), or empty
`merchantCenterSubmitted`	yes or no
`analyticsPropertyId`	text, or empty
`gaMeasurementId`	text, or empty
`gaPropertyResourceName`	text, or empty
`gaProvisioningStatus`	one of: None, Pending, Active, Failed, Deleting
`analyticsEnabled`	yes or no
`gaClaimedAt`	date and time (UTC), or empty
`analyticsPropertyDeletedAt`	date and time (UTC), or empty

`shop/pages.json`

JSON The shop's own pages.

Fields of each record (9)

Field	Value
`id`	text
`tenantId`	text
`title`	text
`slug`	text
`content`	text, or empty
`isPublished`	yes or no
`displayOrder`	text
`createdAt`	date and time (UTC)
`updatedAt`	date and time (UTC)

`shop/shop-front.json`

JSON Every shop front design, with its sections.

Fields of each record (10)

Field	Value
`id`	text
`name`	text
`description`	text, or empty
`isActive`	yes or no
`isPublished`	yes or no
`displayOrder`	text
`sourceName`	text, or empty
`createdAt`	date and time (UTC)
`updatedAt`	date and time (UTC)
`sections`	list of one of 14 kinds of record

`shop/email-templates.json`

JSON The shop's email templates.

Fields of each record (9)

Field	Value
`id`	text
`tenantId`	text
`emailType`	one of: OrderConfirmation, OrderRefunded, OrderFulfilled, AdminNewOrder, OrderShipped, ContactMessageFromCustomer, ContactMessageFromShop, PaymentConfirmation, AdminPaymentReceived, ReviewRequest, ReviewThankYou, AdminNewReview, PaymentRecovery, OrderAccessLink, OrderMessageToCustomer, AdminDisputeCreated, AdminProductRemoved, OrderDelivered, PlatformTermsUpdated, AdminProductRestored, MerchantSuspended, MerchantReopened
`name`	text
`subject`	text
`body`	text
`isActive`	yes or no
`createdAt`	date and time (UTC)
`updatedAt`	date and time (UTC)

`shop/discount-codes.json`

JSON The discount codes.

Fields of each record (17)

Field	Value
`id`	text
`tenantId`	text
`name`	text
`description`	text, or empty
`code`	text
`discountType`	one of: Percentage, FixedAmount
`value`	text
`startDate`	date and time (UTC)
`endDate`	date and time (UTC), or empty
`isActive`	yes or no
`minimumOrderAmount`	text
`maximumDiscountAmount`	text
`usageLimit`	text
`usedCount`	text
`isOneTimeUse`	yes or no
`createdAt`	date and time (UTC)
`updatedAt`	date and time (UTC), or empty

`shop/sales.json`

JSON The sales: price reductions on products and variants.

Fields of each record (9)

Field	Value
`id`	text
`name`	text
`type`	text
`value`	text
`startDate`	date and time (UTC)
`endDate`	date and time (UTC), or empty
`isActive`	yes or no
`products`	list of records
`variants`	list of records

`shop/shipping-options.json`

JSON The delivery options, with their prices and where they apply.

Fields of each record (20)

Field	Value
`id`	text
`tenantId`	text
`shippingProvider`	record, or empty
`nationalBasePrice`	text, or empty
`internationalBasePrice`	text, or empty
`pricePerKg`	text, or empty
`volumetricDivisor`	text, or empty
`estimatedDaysMin`	text, or empty
`estimatedDaysMax`	text, or empty
`maxWeight`	text, or empty
`maxLength`	text, or empty
`maxWidth`	text, or empty
`maxHeight`	text, or empty
`isActive`	yes or no, or empty
`markets`	list of records
`trackingUrlTemplate`	text, or empty
`isLockerDelivery`	yes or no
`restrictsProducts`	yes or no
`allowedProducts`	list of records
`allowedCategories`	list of records

`files/`

`files/index.csv`

CSV Every image and video the shop uses, where it is in the archive, and what it was used as.

Columns (4)

File
Original address
Used as
Status

`files/{path}`

As uploaded (images and videos) The stored files themselves.