VenixPin API v1

Integrate your business with VenixPin

Use our REST API to register orders, check delivery status and create secure customer confirmation links from an ecommerce storefront or internal system.

Get started

1. Create an approved VenixPin business account.
2. Open the API tab and generate a private API key.
3. Store the key on your server. Never expose it in the shopper's browser.
4. Call API v1 using an Authorization Bearer header.

Authentication and security

Pass Authorization: Bearer vp_live_… over HTTPS. Keys can be revoked in the portal. Each key is scoped to one merchant. Initial quota: 600 requests per hour per key; your integration should back off on HTTP 429.

API endpoints

• POST /api/v1/orders creates an order.
• GET /api/v1/orders lists your newest 1–100 orders.
• GET /api/v1/orders/:id reads one order and its customer confirmation state.
• POST /api/v1/orders/:id creates a one-time customer location-confirmation link.
• PATCH /api/v1/orders/:id updates an order status, assigns a registered rider or records delivery fees and costs.

Create an order

curl https://www.venixpin.app/api/v1/orders \
  -H "Authorization: Bearer YOUR_PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: webshop-order-1042" \
  -d '{"reference":"ORDER-1042","customer_name":"Customer","instructions":"Fragile parcel"}'

Generate a customer confirmation link

curl -X POST https://www.venixpin.app/api/v1/orders/ORDER_UUID \
  -H "Authorization: Bearer YOUR_PRIVATE_KEY"

The returned URL is a bearer link. Share it privately with the customer through an existing channel. It expires after seven days and cannot be reused after confirmation.

Errors and idempotency

API requests return JSON. Common responses are 400 for invalid data, 401 for missing or invalid keys, 403 for insufficient scope, 404 for missing orders, 409 for conflicts, 429 for quota limits and 503 for temporary service issues. An Idempotency-Key helps avoid duplicate order creation when retrying requests.

Integration limitations

Customer postcode confirmation does not prove residence. Only successful live NIPOST checks are marked verified. Automatic outbound merchant webhooks, bulk synchronisation and platform plugins remain future enhancements. Use polling for delivery status until outgoing events are supported.

OpenAPI specification

Download the OpenAPI 3.0 specification for technical integration.