Items

List the organisation’s saved items

GET /i/v1/items

item.read. Non-archived by default (archived=true archived only, all both); q is a case-insensitive substring over name, description, sku, hsnCode and serviceCode; sorted most used first (-useCount), by name, or -lastUsedAt. The token’s mode picks the database.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`q`	query	string	No	Case-insensitive substring over name, description, sku, hsnCode, serviceCode. At most 100 characters.
`itemType`	query	string	No	One of `goods` \| `service`.
`archived`	query	string	No	`false` non-archived (default), `true` archived only, `all` both. One of `false` \| `true` \| `all`. Default: `false`.
`sort`	query	string	No	One of `-useCount` \| `name` \| `-lastUsedAt`. Default: `-useCount`.
`page`	query	number	No	Default: `1`. At least 1.
`limit`	query	number	No	Default: `20`. Between 1 and 100.

Example request

bash

curl https://gp.useyona.com/i/v1/items \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

One page of items, meta.pagination set.

Errors: 400, 401, 403, 429

Save an item

POST /i/v1/items

item.create; free. A goods item needs an hsnCode, a service item a serviceCode; productCategory is required; taxCategory is a code-list id of the organisation’s jurisdiction (a line alias is stored resolved); sku, when sent, is unique among the organisation’s non-archived items.

Who can call it: API key or signed-in user.

Request body

Field	Type	Required	Description
`name`	string	Yes	1 to 255 characters.
`description`	string or null	No	At most 1000 characters.
`itemType`	string	Yes	One of `goods` \| `service`.
`hsnCode`	string or null	No	Required for goods.
`serviceCode`	string or null	No	Required for services.
`productCategory`	string	Yes	1 to 500 characters.
`unitCode`	string	Yes
`unitPriceMinor`	string	Yes	Minor units as a decimal string (₦1,500.50 → “150050”); at most 10^14 — the line’s own maximum unit price.
`currency`	string	Yes
`taxCategory`	string	Yes	A tax-category id the jurisdiction serves, or a line alias (standard \| zero \| exempt).
`sku`	string or null	No	Unique among the organisation’s non-archived items. At most 64 characters.

Example request

bash

curl -X POST https://gp.useyona.com/i/v1/items \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Consulting hour",
    "itemType": "service",
    "hsnCode": "8471.30",
    "serviceCode": "6201",
    "productCategory": "Machinery",
    "unitCode": "EA",
    "unitPriceMinor": "150050",
    "currency": "NGN",
    "taxCategory": "STANDARD_VAT",
    "sku": "CONS-HR"
  }'

Responses

The saved item.

Errors: 400, 401, 403, 409, 422, 429, 503

One saved item

GET /i/v1/items/{id}

item.read. An archived item is readable by id (archivedAt set).

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes

Example request

bash

curl https://gp.useyona.com/i/v1/items/9f8e7d6c-5b4a-3210-fedc-ba9876543210 \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

The item.

Errors: 400, 401, 403, 404, 429

Edit a saved item

PATCH /i/v1/items/{id}

item.update. The same fields as when saving an item, all optional; itemType is immutable; a sku change obeys the unique rule; an archived item is editable but not usable on a line. Lines already built from the item never change.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes

Request body

Field	Type	Required	Description
`name`	string	No	1 to 255 characters.
`description`	string or null	No	At most 1000 characters.
`itemType`	string	No	Immutable: only the stored value is accepted. One of `goods` \| `service`.
`hsnCode`	string or null	No
`serviceCode`	string or null	No
`productCategory`	string	No	1 to 500 characters.
`unitCode`	string	No
`unitPriceMinor`	string	No
`currency`	string	No
`taxCategory`	string	No
`sku`	string or null	No	At most 64 characters.

Example request

bash

curl -X PATCH https://gp.useyona.com/i/v1/items/9f8e7d6c-5b4a-3210-fedc-ba9876543210 \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "description": "string"
  }'

Responses

The item after the edit.

Errors: 400, 401, 403, 404, 409, 422, 429

Delete a saved item

DELETE /i/v1/items/{id}

item.archive. Hard delete only while no invoice line of this mode’s database references the item; otherwise 409 BIZ004 — archive it instead. Answers 200 {id, deleted:true} in the platform envelope.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes

Example request

bash

curl -X DELETE https://gp.useyona.com/i/v1/items/9f8e7d6c-5b4a-3210-fedc-ba9876543210 \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

{id, deleted: true}.

Errors: 400, 401, 403, 404, 409, 429

Archive a saved item

POST /i/v1/items/{id}/archive

item.archive. Idempotent (an archived item answers 200 with the same view). An archived item is left out of the item list by default and refused on a new line (409 BIZ004); lines that already carry it are untouched.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes

Example request

bash

curl -X POST https://gp.useyona.com/i/v1/items/9f8e7d6c-5b4a-3210-fedc-ba9876543210/archive \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

The archived item.

Errors: 400, 401, 403, 404, 429

Unarchive a saved item

POST /i/v1/items/{id}/unarchive

item.archive. Idempotent. Refused 409 RES002 when another non-archived item took the sku meanwhile.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes

Example request

bash

curl -X POST https://gp.useyona.com/i/v1/items/9f8e7d6c-5b4a-3210-fedc-ba9876543210/unarchive \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

The item, live again.

Errors: 400, 401, 403, 404, 409, 429