Partner API — sell on Povito from your own system#

The Partner API keeps a Povito seller's catalog, stock, prices and orders in sync with the system they already run. It does not take payments; that is the separate Checkout API. Not sure which you need? See which API do I need.

Environments#

A well-formed key sent to the other environment is refused with 401 api_key_wrong_environment. How keys and environments work across Povito's APIs, and where the Checkout API differs: Keys and environments.

To build in the Sandbox you need a Sandbox seller account. Povito creates these on request, so ask your Povito contact. A Sandbox seller account stays in pending_approval, so nothing your integration syncs there is shown to shoppers.

All money on this API is a whole number of Iraqi dinars, with no decimals and no minor units: 25000 means 25,000 IQD. Every timestamp is ISO 8601 in UTC.

Quickstart#

These commands call the Sandbox. For Live, use the Live base URL and a live key; nothing else changes.

export POVITO_PARTNER_API=https://api-staging.povito.com/partner/v1   # Live: https://api.povito.com/partner/v1

Confirm you can reach Povito before you create anything. This endpoint needs no key:

curl $POVITO_PARTNER_API/health

Create an API key in the Seller dashboard under Settings → Integrations, signed in to the seller account you are integrating. A Sandbox seller account issues povito_sk_test_ keys; a Live seller account issues povito_sk_live_ keys. Then read your catalog back:

curl "$POVITO_PARTNER_API/products?limit=5" \
  -H "Authorization: Bearer povito_sk_test_..."

Then push stock and prices for the SKUs your system owns:

curl -X PATCH $POVITO_PARTNER_API/inventory/bulk \
  -H "Authorization: Bearer povito_sk_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "external_sku": "ERP-1042", "on_hand": 12, "price_iqd": 419000 }
    ]
  }'

Authentication#

Every request except /health carries your key as a bearer token:

Authorization: Bearer povito_sk_test_a1b2c3d4e5f6_<secret>

• The scheme word must be exactly Bearer followed by one space; any other form counts as no key. No other header is read.
• Treat the key as opaque. Its id and secret can themselves contain _ and -, so do not split a key on _.
• A key belongs to exactly one seller account and only ever reads or writes that seller's data. There is no cross-seller or platform-wide key.
• Keys are created, re-scoped and revoked in the Seller dashboard, never through this API. Creating one needs team-administration access. The dashboard calls POST /seller/v1/integration/keys, which answers 201 with the key's summary (id, label, scopes, last_used_at, created_at, revoked_at) plus the full key.
• That 201 is the only time the full key is shown. Povito stores only an HMAC of its secret, so nobody, including Povito support, can read it back. If you lose it, revoke it and create a new one.
• Seller dashboard login tokens and shopper tokens are refused here with 401 invalid_api_key. They are separate credentials on purpose.
• Revoking a key takes effect on the next request.

Scopes#

Choose a key's scopes when you create it; you can change them later in the dashboard. Grant only what the integration needs: a nightly stock sync does not need to create products.

Calling an endpoint your key lacks the scope for returns 403 insufficient_scope, naming the scope it needed.

Endpoints#

Before you build, know these rules:

• New products are drafts. POST /products/bulk creates products as draft and never publishes anything. A draft goes live only after someone submits it for approval in the Seller dashboard and Povito approves it. See from draft to live.
• Bulk results are per row. The bulk endpoints answer 200 even when rows fail; always read results[].
• Idempotency-Key is required on every write, and a retry with it is safe. Povito stores the first outcome for 24 hours and replays it for the same key and body, so a retry never re-runs a sync or moves stock twice.
• Rate limit: 60 requests per 600 seconds per API key, with a separate counter for each bulk endpoint.

Pagination, idempotency, rate limits and every error: Limits and errors. Every path and schema, generated from the contract: the interactive reference, the static reference and partner-v1.yaml.

GET /health#

Connectivity check; the only endpoint that needs no API key. It answers 200 whatever Authorization header you send, so use it to confirm the host, not the key.

{ "status": "ok", "api": "partner", "version": "v1", "currency": "IQD" }

Testing safely#

Build against the Sandbox first, with a povito_sk_test_… key from a Sandbox seller account. That account is never approved, so nothing a test sync does reaches a shopper. When the integration works there, move to Live with a povito_sk_live_… key and roll out in steps:

1. Create your first key with catalog:read and orders:read only. Nothing you do with it can change anything.
2. Verify you can read your real catalog and orders, and that your SKUs map to the products you expect.
3. Add inventory:write and send one row through PATCH /inventory/bulk for a single low-risk SKU. Read it back with GET /products/{sku}.
4. Add catalog:write last. New products are created as drafts and stay drafts until they are submitted in the Seller dashboard and approved by Povito, so a malformed first import cannot publish anything. An update row for a published product sends it back to review, so send only products that changed.
5. Once the integration is proven, revoke the read-only key you started with.

Not available yet#

• Webhooks. There is no order push. Poll GET /orders with since on a schedule.
• Submitting products for review. Drafts are submitted in the Seller dashboard.
• Multi-variant products and per-variant prices. This API creates single-variant products only, and a price update for a multi-variant SKU is rejected rather than partially applied.
• Incremental catalog pull. GET /products has no updated_since; GET /orders does support since.
• Order actions. Accepting, shipping and cancelling happen in the Seller dashboard.
• Returns and RMA sync. Not exposed.
• Published terms. Partner API terms are not published yet.