Skip to main content

​
Buyers

In Polinate, a “buyer” is a bundle of multiple underlying resources that work together. There are two bundle types, but only one is creatable via API.
You can only create phantom buyers via the API. Platform buyers are created by accounts that use the Polinate app directly.

​
Buyer bundle types

Platform buyer

A business running on Polinate. Created and managed inside the Polinate platform.

Phantom buyer

A business not on Polinate. Creatable via API and used to transact with your supplier account.

​
What happens when you create a buyer

Creating a buyer via the API orchestrates several resources in a specific order:
1

Partnership is created

We establish the relationship between your supplier business and the new buyer bundle.
2

Phantom (buyer organization) is created

This represents the buyer’s organization container where contact data is stored.
3

Phantom buyer is created

The buyer entity shares the same unique ID as the parent phantom.

​
Ownership model

  • Phantom (buyer organization): owns locations, phones, and emails.
  • Partnership: owns the relationship to your supplier and is where orders and invoices are associated.
  • Phantom buyer: shares the same ID as the phantom.

​
Relationship map

Supplier (you)
└─ Partnership (prt_...)
   ├─ Buyer Phantom (pha_...)  ← same ID as Phantom Buyer
   │  ├─ Locations
   │  ├─ Emails
   │  └─ Phones
   ├─ Orders
   └─ Invoices

​
Fetching buyers vs. partnerships

When you “fetch buyers” for a supplier, you’re actually retrieving partnerships. Use each partnership’s linked phantom to access the buyer’s contact details (locations, phones, emails).

​
Authentication

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

​
Create a Buyer

Creates a phantom buyer bundle by creating a partnership, phantom, and phantom buyer. You can start minimal and add contact/location data later. Endpoint: POST /api/v1/buyers 
curl -X POST "https://integrations.polinate.ai/api/v1/buyers" \
  -H "X-Business-ID: {{businessId}}" \
  -H "X-API-Key: {{apiKey}}" \
  -H "Content-Type: application/json" \
  -d '{
    "buyer": {
      "name": "Acme Pty Ltd",
      "legalName": "Acme Pty Ltd"
    }
  }'
This operation is idempotent when you provide an Idempotency-Key. Repeating the same key returns the original result.

​
Notes

  • Optional arrays emails, phones, and locations can be provided when creating a buyer.
  • Use Idempotency-Key header for safe retries on POST requests.