← Back to API quickstart and copyable commands

Fields & errors

Reference for /api/v1/sourcing-requests. Download the full OpenAPI contract.

Request fields

Unknown fields are rejected. Maximum 100 items per SR and 1 MB per request. The OpenAPI download contains exact types and limits.

SR field What to send
external_id Your source record ID. Required on create.
merchant Object with id and name. Required on create.
items Array of items. Optional on create; when included in an update, must contain at least one item.
destination Optional or null. Requires uppercase two-letter country and city; optional region, postal_code, address.
needed_by Optional date, YYYY-MM-DD, or null.
notes Optional text or null.
callback_url Optional HTTPS URL or null. Stored only; callbacks are not sent yet.
version Required only for PATCH. Use the latest value returned by the API.

Fields inside each item

name and description
Required for each new item.
quantity
Positive integer, omitted or null. Use null when unknown, never zero.
selected
Boolean, defaults to false. Set true for a merchant’s chosen item.
images and reference_url
Up to 20 HTTP(S) image URLs; optional HTTP(S) reference URL or null.
specs
Up to 100 objects with name, value and optional boolean required (defaults to false).
customization
Optional object or null. Supports logo_url (HTTP/S), packaging, colour and notes.
notes
Optional item-specific text or null.
id
For PATCH only: include the integer item ID to edit an existing item.

If a request fails

Status What to do
400 Check the JSON, field paths in issues, SR ID and item ownership.
401 / 403 Check the bearer token and environment. Cross-site writes may be rejected; use a trusted backend integration.
404 Check the full endpoint and the returned sr_id.
409 On create: merchant + external ID already exists. On update: a newer version was saved; coordinate with the other writer and use its returned version. Do not blindly retry.
413 / 415 Keep the body under 1 MB and send Content-Type: application/json.
500 Server error. Contact the team before retrying a create whose outcome is unknown.