Integration API v2
Integration API v2
The integration API v2 is the API a connected system calls to read and write a workspace’s catalogue, orders, customers and stock. Every path starts with /api/integrations/v2/{connection_id}, where connection_id is the id of your custom integration. This reference covers contract version 2026-10.
Every request is signed with the integration’s API secret in X-Yedran-Timestamp and X-Yedran-Signature. Every write carries an Idempotency-Key. Every answer carries Yedran-Version. Errors are RFC 9457 problem documents (application/problem+json) with a stable code.
The OpenAPI 3.1 document of this reference is served at /openapi/integrations-v2.json on this site.
Endpoints
| Method | Path | Page |
|---|---|---|
| GET | /api/integrations/v2/{connection_id}/products |
Products |
| GET | /api/integrations/v2/{connection_id}/products/{product_id} |
Products |
| PUT | /api/integrations/v2/{connection_id}/products/by-external-id/{external_id} |
Products |
| GET | /api/integrations/v2/{connection_id}/orders |
Orders |
| GET | /api/integrations/v2/{connection_id}/orders/{order_id} |
Orders |
| GET | /api/integrations/v2/{connection_id}/customers |
Customers |
| GET | /api/integrations/v2/{connection_id}/customers/{customer_id} |
Customers |
| GET | /api/integrations/v2/{connection_id}/product-templates |
Product templates |
| GET | /api/integrations/v2/{connection_id}/product-templates/{template_id} |
Product templates |
| GET | /api/integrations/v2/{connection_id}/stock-locations |
Stock locations |
| GET | /api/integrations/v2/{connection_id}/inventory-levels |
Inventory levels |
| PUT | /api/integrations/v2/{connection_id}/inventory-levels/by-sku/{sku} |
Inventory levels |
| PUT | /api/integrations/v2/{connection_id}/inventory-levels/by-external-id/{external_id} |
Inventory levels |
Webhooks
| Event | Page |
|---|---|
order.created |
Webhooks |
order.confirmed |
Webhooks |
order.paid |
Webhooks |
order.cancelled |
Webhooks |
order.refunded |
Webhooks |
product.updated |
Webhooks |
price.updated |
Webhooks |
customer.upserted |
Webhooks |
inventory.updated |
Webhooks |
Errors
Every refusal is a problem document in one of these schemas.
ProblemDetails
RFC 9457 problem details, with our stable machine code beside them.
type is a URN naming the code (urn:yedran:problem:<code>), title the HTTP status phrase, detail a sentence for whoever reads a log. code is the contract a caller switches on — the same strings v1 answers in error (not_found, no_catalogue_authority, duplicate_sku, …) plus the v2 ones (idempotency_key_required, idempotency_key_reused, idempotency_key_in_flight, invalid_cursor, not_enabled, external_id_conflict, stale_write, validation_error, unsupported_version).
| Field | Type | Required | Description |
|---|---|---|---|
type |
string | yes | |
title |
string | yes | |
status |
integer | yes | |
detail |
string, nullable | no | |
code |
string | yes | |
errors |
array of ProblemFieldError, nullable | no |
ProblemFieldError
One field a request got wrong — the errors extension of a 422 problem.
| Field | Type | Required | Description |
|---|---|---|---|
loc |
array of string or integer | yes | |
msg |
string | yes | |
type |
string | yes |