Sellers API

Base path: https://gateway.useyona.com/i/v1/sellers

A seller is the business entity issuing invoices. You must register at least one seller before creating invoices.

Create seller

POST /i/v1/sellers

Request body

Field	Type	Required	Description
`partyName`	string	Yes	Business name, max 255 chars
`tradingName`	string	No	Trading/brand name, max 255 chars
`partyType`	string	No	`individual` \| `company` \| `partnership` \| `non_profit` \| `government`. Default: `company`
`taxNumber`	string	Yes	Tax identification number, max 50 chars. Unique per organization.
`vatNumber`	string	No	VAT number, max 50 chars
`registrationNumber`	string	No	Business registration number, max 100 chars
`email`	string	Yes	Valid email address, max 255 chars
`phoneNumber`	string	Yes	Valid phone number, max 50 chars
`website`	string	No	URL, max 255 chars
`postalAddress`	object	Yes	See address fields below
`notes`	string	No	Max 1000 chars

Address fields

Field	Type	Required
`line1`	string	Yes
`line2`	string	No
`city`	string	Yes
`state`	string	No
`postalCode`	string	No
`country`	string	Yes — ISO 3166-1 alpha-2 (e.g. `NG`)

ℹ Field mapping

The request uses partyType and phoneNumber, but the response returns sellerType and phone.

bash

curl -X POST https://gateway.useyona.com/i/v1/sellers \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "partyName": "Zenith Software Solutions Ltd",
    "email": "billing@zenithsoftware.ng",
    "phoneNumber": "+2348012345678",
    "taxNumber": "31245678-0001",
    "postalAddress": {
      "line1": "14 Admiralty Way",
      "city": "Lagos",
      "state": "Lagos",
      "country": "NG"
    }
  }'

Status	Code	Trigger
400	VAL001	Missing or invalid required fields
409	RES002	Seller with this tax number already exists

List sellers

GET /i/v1/sellers

List sellers with pagination.

bash

curl "https://gateway.useyona.com/i/v1/sellers?page=1&limit=20" \
  -H "Authorization: Bearer sk_test_your_key_here"

Get seller

GET /i/v1/sellers/:id

Retrieve a single seller by ID.

bash

curl https://gateway.useyona.com/i/v1/sellers/c7a1d3e5-8f2b-4a6c-9d0e-1f2a3b4c5d6e \
  -H "Authorization: Bearer sk_test_your_key_here"

Status	Code	Trigger
404	RES001	Seller not found

Update seller

PATCH /i/v1/sellers/:id

Update a seller. taxNumber is immutable after creation.

bash

curl -X PATCH https://gateway.useyona.com/i/v1/sellers/c7a1d3e5-8f2b-4a6c-9d0e-1f2a3b4c5d6e \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "finance@zenithsoftware.ng",
    "website": "https://zenithsoftware.ng"
  }'

Status	Code	Trigger
400	VAL001	Invalid field values
404	RES001	Seller not found

Delete seller

DELETE /i/v1/sellers/:id

Delete a single seller.

bash

curl -X DELETE https://gateway.useyona.com/i/v1/sellers/c7a1d3e5-8f2b-4a6c-9d0e-1f2a3b4c5d6e \
  -H "Authorization: Bearer sk_test_your_key_here"

Status	Code	Trigger
404	RES001	Seller not found

Bulk delete sellers

DELETE /i/v1/sellers/bulk

Delete multiple sellers at once.

Request body

Field	Type	Required	Description
`ids`	string[]	Yes	Array of seller UUIDs

bash

curl -X DELETE https://gateway.useyona.com/i/v1/sellers/bulk \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "c7a1d3e5-8f2b-4a6c-9d0e-1f2a3b4c5d6e",
      "d8b2e4f6-9a3c-5b7d-0e1f-2a3b4c5d6e7f"
    ]
  }'

Search sellers

GET /i/v1/sellers/search

Search sellers by name or tax identification number.

Query parameters

Parameter	Type	Required	Description
`q`	string	Yes	Search term

bash

curl "https://gateway.useyona.com/i/v1/sellers/search?q=Zenith" \
  -H "Authorization: Bearer sk_test_your_key_here"

Verify tax number

POST /i/v1/sellers/:id/verify-tax-number

Initiate TIN verification against the tax authority database. This is an asynchronous operation.

bash

curl -X POST https://gateway.useyona.com/i/v1/sellers/c7a1d3e5-8f2b-4a6c-9d0e-1f2a3b4c5d6e/verify-tax-number \
  -H "Authorization: Bearer sk_test_your_key_here"

Status	Code	Trigger
404	RES001	Seller not found

Get verification status

GET /i/v1/sellers/:id/verification-status

Check the progress of a TIN verification.

bash

curl https://gateway.useyona.com/i/v1/sellers/c7a1d3e5-8f2b-4a6c-9d0e-1f2a3b4c5d6e/verification-status \
  -H "Authorization: Bearer sk_test_your_key_here"