Skip to main content

​
Pricing

Pricing revolves around the Item List, which is a price list owned by a supplier and expanded with richer pricing functionality.
An Item List is a price list plus extras (taxes, costs, branching, and global adjustments). Most partners treat it as a simple price list.

​
Item List structure

Partnership assignments

Array of partnerships (buyers) this Item List is applied to. Assigned partnerships get these prices, which override the buyer’s default item variant prices.

Entries (variant joins)

Array of entries that each link to an Item Variant. Each entry overrides pricing fields (e.g., price, currency) for that variant under this Item List.

Global overrides

The Item List can include global percentage adjustments (e.g., discount factors) that apply across entries.

​
Default Item List

Every supplier has a Default Item List. It is automatically applied to all newly created buyers (partnerships) when no specific Item List is assigned.
  • No global overrides are applied on the Default Item List.
  • Entries on the Default Item List do not override pricing; prices come from the underlying Item Variant.
  • When new Items are created, all variants are automatically included on the Default Item List.
  • If a partnership is later assigned a specific Item List, that assignment overrides the Default Item List for that partnership.

​
Relationship map

Supplier (you)
└─ Item List (owned by supplier)
   ├─ Partnerships [prt_...] (assignments; 1 list per partnership)
   └─ Entries [→ Item Variants] (override variant price under this list)

​
Fetching item lists

When fetching an Item List, we group entries by their parent Items for readability. Conceptually, it’s still a list of variants and a list of partnerships.

​
Constraints

  • Each partnership can have at most one assigned Item List.
  • All partnerships and item variants referenced must already exist.

​
Authentication

Include the following headers in every request:
  • X-Business-ID: Your business identifier
  • X-API-Key: Your API key

​
Create an Item List

Creates an Item List and one or more entries, and optionally assigns partnerships. Endpoint: POST /api/v1/pricing 
curl -X POST "https://integrations.polinate.ai/api/v1/pricing" \
  -H "X-Business-ID: {{businessId}}" \
  -H "X-API-Key: {{apiKey}}" \
  -H "Content-Type: application/json" \
  -d '{
    "itemListData": { "label": "Winter 2025" },
    "entries": [
      { "itemListId": "list_123", "itemVariantId": "var_123", "price": 10, "currency": "AUD" }
    ],
    "partnerships": ["prt_123"]
  }'
This operation is idempotent when you provide an Idempotency-Key. Repeating the same key returns the original result.

​
Notes

  • Include at least one entry in entries.
  • Use Idempotency-Key header for safe retries on POST requests.