Buy API

Use the Buy API to turn purchase intent into sourced offers, Purchase Orders, checkout handoff, Bills, and accounting readiness checks.

Last updated: June 20, 2026

Summary

The Buy API is a beta AI API for procurement workflows. Use it when you want Sanka to turn a purchase request into structured sourcing, approval, purchasing, and Bill handoff data.Buy API endpoints use the /v2/buy namespace.The first beta focuses on:

creating Buy Requests from manual or AI-assisted intent
sourcing product offers from Shopify Global Catalog
selecting offers by request line
creating Sanka Purchase Orders
preparing a checkout URL for manual confirmation
recording the external order ID after checkout
creating Sanka Bills with evidence files
previewing whether the Bill is ready for accounting export

The API does not submit payment automatically. Prepare-checkout returns a handoff URL or checkout metadata that a user should confirm manually.

Authentication

Send your Developer API key as Authorization: Bearer <api_key>.
Use a key with write access because the workflow can create Buy Requests, Companies, Purchase Orders, and Bills.
Send Idempotency-Key on write operations such as request creation, offer selection, Purchase Order creation, checkout preparation, order confirmation, and Bill creation.
Keep one stable idempotency key per user action, not one key for an entire workflow.

Workflow

The standard flow is:

Create a Buy Request.
Source offers for the request.
Select an offer for each request line.
Submit the request for approval or confirm it is ready.
Create Purchase Orders and merchant purchases.
Prepare checkout and let the user complete the merchant checkout manually.
Confirm the external order ID.
Create a Bill with evidence files.
Preview accounting readiness before exporting or posting accounting records.

For multi-line requests, keep offer selection at the line level. Sanka groups selected lines into merchant purchases so each merchant can be handed off separately.

Create a request

Create a Buy Request with one or more lines:

cURL

curl -X POST "https://api.sanka.com/v2/buy/requests" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: buy-request-001" \
  -d '{
    "title": "Restock shipping labels",
    "source": "manual",
    "currency": "USD",
    "business_purpose": "Warehouse replenishment",
    "lines": [
      {
        "description": "Thermal shipping labels, 4 x 6 inch",
        "quantity": 10,
        "unit": "roll"
      }
    ]
  }'

Use POST /v2/buy/intents when an AI agent or app starts from natural language and needs Sanka to structure the draft request before creation.

Source and approve

Start sourcing for a request:

cURL

curl -X POST "https://api.sanka.com/v2/buy/requests/<request_id>/source" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: buy-source-001" \
  -d '{
    "provider": "shopify_global_catalog"
  }'

Read sourcing results with:

GET /v2/buy/requests/<request_id>
GET /v2/buy/requests/<request_id>/sourcing-runs
GET /v2/buy/sourcing-runs/<sourcing_run_id>

Select an offer for a request line:

cURL

curl -X POST "https://api.sanka.com/v2/buy/requests/<request_id>/select-offer" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: buy-select-001" \
  -d '{
    "line_id": "<request_line_id>",
    "offer_snapshot_id": "<offer_snapshot_id>"
  }'

Use POST /v2/buy/requests/<request_id>/submit when the selected lines are ready for approval or purchasing.

Create purchasing records

Create Purchase Orders from the approved or ready Buy Request:

cURL

curl -X POST "https://api.sanka.com/v2/buy/requests/<request_id>/create-purchase-order" \
  -H "Authorization: Bearer <api_key>" \
  -H "Idempotency-Key: buy-po-001"

Sanka creates or reuses full Company records for merchants so downstream Purchase Orders, Bills, and accounting handoffs have a proper counterparty.Prepare checkout for one merchant purchase:

cURL

curl -X POST "https://api.sanka.com/v2/buy/merchant-purchases/<merchant_purchase_id>/prepare-checkout" \
  -H "Authorization: Bearer <api_key>" \
  -H "Idempotency-Key: buy-checkout-001"

After the user completes checkout with the merchant, record the external order ID:

cURL

curl -X POST "https://api.sanka.com/v2/buy/merchant-purchases/<merchant_purchase_id>/confirm-order" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: buy-order-001" \
  -d '{
    "external_order_id": "SHOP-10042"
  }'

Bill and accounting readiness

Create a Bill after the order is confirmed:

cURL

curl -X POST "https://api.sanka.com/v2/buy/merchant-purchases/<merchant_purchase_id>/create-bill" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: buy-bill-001" \
  -d '{
    "evidence_files": [
      {
        "file_id": "<uploaded_file_id>",
        "evidence_type": "receipt"
      }
    ]
  }'

Preview accounting readiness:

cURL

curl -X POST "https://api.sanka.com/v2/buy/merchant-purchases/<merchant_purchase_id>/accounting-preview" \
  -H "Authorization: Bearer <api_key>"

The readiness preview reports blockers, warnings, linked records, and evidence count. It does not create Journal Entries or export accounting data by itself.

Next steps

Review Object API for the Purchase Order and Bill records created by the workflow.
Use File API before Bill creation when you need to attach receipt or invoice evidence.
Use Workflow API for later accounting export workflows.
Review Rate Limits before running bulk purchase intake.

PreviousAI API NextData Enrichment