Μενού τεκμηρίωσης: Merchants

Merchants

The businesses that issue documents under your account.

Η αναφορά API είναι διαθέσιμη μόνο στα αγγλικά, όπως και το API.

Σε αυτή τη σελίδα

Create a merchant
Retrieve a merchant

Create a merchant #

POST /api/v1/merchants

Creates a merchant: a business that issues documents under your account, seen by your test and live keys alike. Its external_id is unique ignoring case; creating a taken one is 409 already_exists, so look it up instead (a Shopify reinstall).

Bearer API key
Idempotency-Key required

Header parameters

idempotency-keystringrequired: A key you choose (1-255 printable ASCII characters, e.g. a UUID) that makes a create request safe to retry: the same key with the same body returns the first result instead of creating a second document.
1 to 255 characters
Show patternHide pattern
^[\x21-\x7E]+$

Request body

external_idstringrequired

Your own id for the merchant, e.g. a shop domain: 1 to 200 characters, trimmed, unique in your account ignoring case (Shop-A and shop-a are the same merchant). Find a merchant by it.

Up to 200 characters

Show pattern

\S

namestringrequired

The merchant's name, as you show it: 1 to 200 characters, trimmed.

Up to 200 characters

Show pattern

\S

tax_idstring

The merchant's own Greek tax number (ΑΦΜ), 9 digits. Spaces, hyphens and dots are removed before it is checked. Needed before the merchant can be onboarded to a provider.

Up to 60 characters

branchinteger

Branch number in the AADE registry; 0 (the default) for the head office.

From 0 to 9999

metadataobject

Up to 50 key-value pairs of your own (keys up to 40 characters, values up to 500). Do not put personal data in it.

Show nested fields (1)

{key}string: A value, up to 500 characters.
1 to 40 characters

Request

JSON

{
  "external_id": "olive-oil.myshopify.com",
  "name": "Olive Oil Co"
}

curl

curl -X POST 'https://tallio.dev/api/v1/merchants' \
  -H "Authorization: Bearer $TALLIO_API_KEY" \
  -H 'Idempotency-Key: order-1042' \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "olive-oil.myshopify.com",
  "name": "Olive Oil Co"
}'

TypeScript SDK

import { createTallioClient, unwrap } from "@tallio/sdk";

const tallio = createTallioClient({
  apiKey: process.env.TALLIO_API_KEY!,
  baseUrl: "https://tallio.dev",
});

const result = await unwrap(tallio.http.POST("/api/v1/merchants", {
  body: {
    external_id: "olive-oil.myshopify.com",
    name: "Olive Oil Co",
  },
}));

Responses
Status	Description
`201`	The merchant. A replay returns the first answer.
4XX, 5XX	An error: see Errors below.

Response body · 201

dataobjectrequired

A business that issues documents under your account.

Show nested fields (9)

idstringrequired

Id of the merchant (mer_…).

Show pattern

^mer_[0-9A-Za-z]{22}$

objectstringrequired

Always "merchant".

Always merchant

external_idstringrequired

Your own id for the merchant, e.g. a shop domain: 1 to 200 characters, trimmed, unique in your account ignoring case (Shop-A and shop-a are the same merchant). Find a merchant by it.

Up to 200 characters

Show pattern

\S

namestringrequired

The merchant's name, as you show it: 1 to 200 characters, trimmed.

Up to 200 characters

Show pattern

\S

tax_idstring | nullrequired

The merchant's ΑΦΜ, normalised, or null when not given.

branchintegerrequired

Branch number in the AADE registry; 0 for the head office.

From 0 to 9007199254740991

metadataobjectrequired

Up to 50 key-value pairs of your own (keys up to 40 characters, values up to 500). Do not put personal data in it.

Show nested fields (1)

{key}string: A value, up to 500 characters.
1 to 40 characters

archivedbooleanrequired

True once the merchant is archived; it then issues nothing new.

createdstringrequired

When the merchant was created.

Format: date-time

Example response · 201

{
  "data": {
    "id": "mer_02y9O8rh7F50tGi0QcWRrx",
    "object": "merchant",
    "external_id": "olive-oil.myshopify.com",
    "name": "Olive Oil Co",
    "tax_id": "string",
    "branch": 0,
    "metadata": {
      "shop_domain": "olive-oil.myshopify.com"
    },
    "archived": false,
    "created": "2026-10-11T09:30:00.000Z"
  }
}

Response headers

x-request-idstring: The request's correlation id; quote it when reporting a problem. One of: req_ plus a uuid (Tallio made it), client: plus the x-request-id you sent (8-128 of A-Z a-z 0-9 . _ : -), or the hosting platform's id.
With every response
Show patternHide pattern
^(?:req_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|client:[A-Za-z0-9._:-]{8,128}|[A-Za-z0-9._-]{1,16}::[A-Za-z0-9._:-]{6,110})$
ratelimit-limitinteger: Requests allowed in the current window for the bucket this request counted against.
With 201, 400, 409, 413, 415, 429 · At least 1
ratelimit-remaininginteger: Requests left in the current window; 0 means the next one is refused until the window resets.
With 201, 400, 409, 413, 415, 429 · At least 0
ratelimit-resetinteger: Seconds until the current window resets.
With 201, 400, 409, 413, 415, 429 · At least 0
idempotent-replayedstring: true when this answer replays an earlier request with the same Idempotency-Key (nothing new was created); absent on the request that created it.
With 201 · Always true
www-authenticatestring: The bearer challenge: send a vendor secret key as Authorization: Bearer <key>.
With 401 · Always Bearer realm="tallio"
retry-afterinteger: Seconds to wait before retrying a request refused with 429 rate_limited.
With 429 · At least 1

Errors
Code	Status	Retryable	Meaning
`validation_failed`	400	No	Request validation failed.
`unauthorized`	401	No	Authentication is required.
`idempotency_conflict`	409	No	This idempotency key was already used with a different request.
`idempotency_in_progress`	409	Yes	A request with this idempotency key is still in progress; retry it after Retry-After to get its answer.
`already_exists`	409	No	An object with this identifier already exists; look it up instead of creating it again.
`payload_too_large`	413	No	The request body is too large.
`unsupported_media_type`	415	No	The request body must be JSON (Content-Type: application/json).
`rate_limited`	429	Yes	A rate limit was reached. Retry later.
`internal_error`	500	No	An unexpected server error occurred.

Retrieve a merchant #

GET /api/v1/merchants/{id}

Returns one of your merchants.

Bearer API key

Path parameters

idstringrequired: The merchant's id (mer_…).

Request

curl

curl -X GET 'https://tallio.dev/api/v1/merchants/mer_02y9O8rh7F50tGi0QcWRrx' \
  -H "Authorization: Bearer $TALLIO_API_KEY"

TypeScript SDK

import { createTallioClient, unwrap } from "@tallio/sdk";

const tallio = createTallioClient({
  apiKey: process.env.TALLIO_API_KEY!,
  baseUrl: "https://tallio.dev",
});

const result = await unwrap(tallio.http.GET("/api/v1/merchants/{id}", {
  params: {
    path: {
      id: "mer_02y9O8rh7F50tGi0QcWRrx",
    },
  },
}));

Responses
Status	Description
`200`	The merchant.
4XX, 5XX	An error: see Errors below.

Response body · 200

dataobjectrequired

A business that issues documents under your account.

Show nested fields (9)

idstringrequired

Id of the merchant (mer_…).

Show pattern

^mer_[0-9A-Za-z]{22}$

objectstringrequired

Always "merchant".

Always merchant

external_idstringrequired

Your own id for the merchant, e.g. a shop domain: 1 to 200 characters, trimmed, unique in your account ignoring case (Shop-A and shop-a are the same merchant). Find a merchant by it.

Up to 200 characters

Show pattern

\S

namestringrequired

The merchant's name, as you show it: 1 to 200 characters, trimmed.

Up to 200 characters

Show pattern

\S

tax_idstring | nullrequired

The merchant's ΑΦΜ, normalised, or null when not given.

branchintegerrequired

Branch number in the AADE registry; 0 for the head office.

From 0 to 9007199254740991

metadataobjectrequired

Up to 50 key-value pairs of your own (keys up to 40 characters, values up to 500). Do not put personal data in it.

Show nested fields (1)

{key}string: A value, up to 500 characters.
1 to 40 characters

archivedbooleanrequired

True once the merchant is archived; it then issues nothing new.

createdstringrequired

When the merchant was created.

Format: date-time

Example response · 200

{
  "data": {
    "id": "mer_02y9O8rh7F50tGi0QcWRrx",
    "object": "merchant",
    "external_id": "olive-oil.myshopify.com",
    "name": "Olive Oil Co",
    "tax_id": "string",
    "branch": 0,
    "metadata": {
      "shop_domain": "olive-oil.myshopify.com"
    },
    "archived": false,
    "created": "2026-10-11T09:30:00.000Z"
  }
}

Response headers

x-request-idstring: The request's correlation id; quote it when reporting a problem. One of: req_ plus a uuid (Tallio made it), client: plus the x-request-id you sent (8-128 of A-Z a-z 0-9 . _ : -), or the hosting platform's id.
With every response
Show patternHide pattern
^(?:req_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|client:[A-Za-z0-9._:-]{8,128}|[A-Za-z0-9._-]{1,16}::[A-Za-z0-9._:-]{6,110})$
ratelimit-limitinteger: Requests allowed in the current window for the bucket this request counted against.
With 200, 404, 429 · At least 1
ratelimit-remaininginteger: Requests left in the current window; 0 means the next one is refused until the window resets.
With 200, 404, 429 · At least 0
ratelimit-resetinteger: Seconds until the current window resets.
With 200, 404, 429 · At least 0
www-authenticatestring: The bearer challenge: send a vendor secret key as Authorization: Bearer <key>.
With 401 · Always Bearer realm="tallio"
retry-afterinteger: Seconds to wait before retrying a request refused with 429 rate_limited.
With 429 · At least 1

Errors
Code	Status	Retryable	Meaning
`unauthorized`	401	No	Authentication is required.
`not_found`	404	No	The requested resource was not found.
`rate_limited`	429	Yes	A rate limit was reached. Retry later.
`internal_error`	500	No	An unexpected server error occurred.