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