Getting Started

Integrate a retailer with the Polymatiks API by authenticating, selecting a store, creating a product and a customer, and importing a historical order.

Prerequisites

Use a provisioned retailer account with an active membership in its retailer workspace, write access and an existing store. Use your assigned API base URL. The production API base URL is https://api-v2.polymatiks.ai. Use test credentials and a test store to try the examples. Use JSON with camelCase keys and Authorization: Bearer <access> after login.

1. Sign in and select a store

POST /auth/ with {"username":"integration@example.com","password":"<password>"} returns HTTP 200 with access, refresh, retailers and cpgs. Pass {"refresh":"<refresh>"} to POST /auth/refresh/ to renew access.

Select a retailer where your account has an active membership. Find its UUID in the response or call GET /retailer/. Call GET /retailer/{retailerUuid}/stores/ and use the store's results[].uuid. The store endpoint returns count and up to 10 results, with search, scopeShop and scopeNode available to narrow the list. Use the same store in each payload below.

2. Create a product

POST /retailer/{retailerUuid}/product/ → HTTP 201. Use distinct external IDs for the parent and its variant. variants must contain at least one item. Pass an empty properties array if there are no custom fields. Save the sellable variant's UUID from variants[0].uuid.

{"shop":"<storeUuid>","id":"sku-parent-001","name":"Ground Coffee","stock":"20","price":"10.00","properties":[],"variants":[{"id":"sku-001","name":"Ground Coffee 250g","stock":"20","price":"10.00"}]}

3. Create a customer

POST /retailer/{retailerUuid}/customer/ → HTTP 201. Save the response uuid. The request id is your external reference. A loyalty customer needs both email and phone. A non-loyalty customer needs either one.

{"shop":"<storeUuid>","id":"customer-001","firstName":"Jamie","lastName":"Example","email":"jamie@example.com","isLoyaltyMember":false,"marketingOptIn":false,"properties":[]}

4. Import a historical order

POST /retailer/{retailerUuid}/order/import/ → HTTP 200 with the order uuid and the line UUIDs in items. Use the returned customer and variant UUIDs. Use the source purchase timestamp and distinct, stable sourceLineId values even when multiple lines share a product.

{"shopUuid":"<storeUuid>","id":"order-001","customer":"<customerUuid>","platformCreatedAt":"2026-11-01T15:00:00Z","subtotal":"10.00","discounts":"0.00","total":"10.00","values":[],"properties":[],"items":[{"sourceLineId":"line-1","product":"<variantUuid>","unitPrice":"10.00","quantity":"1","discount":"0.00"}]}

Use nonnegative amounts. Set the order total to subtotal minus discounts, and keep the line subtotals and line discounts within their corresponding order totals.

An identical retry returns the same order and line UUIDs. A changed order with the same source ID needs a strictly newer platformUpdatedAt. A missing or duplicate source line ID or a customer/product from a different store returns HTTP 400. Read-only CPG access cannot import orders and receives HTTP 403.