Sellers & Buyers

Every invoice requires a seller (the business issuing the invoice) and a buyer (the recipient). Both must be registered before you can create an invoice.

Sellers

A seller is the business entity issuing the invoice. You need at least one registered seller before you can create invoices.

Creating a seller

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": "Acme Nigeria Ltd",
    "email": "billing@acme.ng",
    "phoneNumber": "+2348012345678",
    "taxNumber": "12345678-0001",
    "postalAddress": {
      "line1": "123 Commerce Street",
      "city": "Lagos",
      "state": "Lagos",
      "country": "NG"
    }
  }'

Required fields

Field	Description
`partyName`	Business name (max 255 chars)
`taxNumber`	Tax identification number (max 50 chars)
`email`	Contact email
`phoneNumber`	Contact phone
`postalAddress`	Must include `line1`, `city`, and `country` (ISO 2-letter)

TIN verification

After creating a seller, initiate tax number verification:

bash

curl -X POST https://gateway.useyona.com/i/v1/sellers/{id}/verify-tax-number \
  -H "Authorization: Bearer sk_test_your_key_here"

Check verification progress:

bash

curl https://gateway.useyona.com/i/v1/sellers/{id}/verification-status \
  -H "Authorization: Bearer sk_test_your_key_here"

ℹ Field mapping

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

Buyers

Buyers work identically to sellers with two key differences:

taxNumber is optional (supporting B2C scenarios)
Default partyType is 'individual' (not 'company')

Creating a buyer

bash

curl -X POST https://gateway.useyona.com/i/v1/buyers \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "partyName": "John Doe Enterprises",
    "email": "john@example.com",
    "phoneNumber": "+2349087654321",
    "postalAddress": {
      "line1": "456 Market Road",
      "city": "Abuja",
      "country": "NG"
    }
  }'

Available operations

Both sellers and buyers support the same set of operations:

Operation	Sellers	Buyers
Create	`POST /i/v1/sellers`	`POST /i/v1/buyers`
List	`GET /i/v1/sellers`	`GET /i/v1/buyers`
Get	`GET /i/v1/sellers/:id`	`GET /i/v1/buyers/:id`
Update	`PATCH /i/v1/sellers/:id`	`PATCH /i/v1/buyers/:id`
Delete	`DELETE /i/v1/sellers/:id`	`DELETE /i/v1/buyers/:id`
Bulk delete	`DELETE /i/v1/sellers/bulk`	`DELETE /i/v1/buyers/bulk`
Search	`GET /i/v1/sellers/search?q=`	`GET /i/v1/buyers/search?q=`
Verify TIN	`POST /i/v1/sellers/:id/verify-tax-number`	`POST /i/v1/buyers/:id/verify-tax-number`

💡 SDK available

See SDK — Usage Examples for the programmatic interface.