Create a merchant

POST

merchants

Create a merchant

curl --request POST \
  --url https://api.alguna.io/merchants \
  --header 'Alguna-Version: <alguna-version>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "display_name": "Northwind Traders",
  "external_id": "acct_492",
  "avatar": {
    "content": "iVBORw0KGgoAAAANSUhEUg==",
    "content_type": "image/png"
  },
  "logo": {
    "content": "iVBORw0KGgoAAAANSUhEUg==",
    "content_type": "image/png"
  },
  "support_email": "support@northwind.example"
}
'

import requests

url = "https://api.alguna.io/merchants"

payload = {
    "display_name": "Northwind Traders",
    "external_id": "acct_492",
    "avatar": {
        "content": "iVBORw0KGgoAAAANSUhEUg==",
        "content_type": "image/png"
    },
    "logo": {
        "content": "iVBORw0KGgoAAAANSUhEUg==",
        "content_type": "image/png"
    },
    "support_email": "support@northwind.example"
}
headers = {
    "Alguna-Version": "<alguna-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Alguna-Version': '<alguna-version>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    display_name: 'Northwind Traders',
    external_id: 'acct_492',
    avatar: {content: 'iVBORw0KGgoAAAANSUhEUg==', content_type: 'image/png'},
    logo: {content: 'iVBORw0KGgoAAAANSUhEUg==', content_type: 'image/png'},
    support_email: 'support@northwind.example'
  })
};

fetch('https://api.alguna.io/merchants', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "created_at": "2026-08-01T10:00:00Z",
  "display_name": "Northwind Traders",
  "external_id": "acct_492",
  "id": "mrch_034DG8VMQwhPngo3S9mdKO",
  "updated_at": "2026-08-01T12:30:00Z",
  "archived_at": "2026-08-20T12:00:00Z",
  "avatar_url": "<string>",
  "logo_url": "<string>",
  "support_email": "support@northwind.example"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

Authorizations

Authorization

string

header

required

API key authentication. Pass your API key as a Bearer token.

Headers

Alguna-Version

enum<string>

required

Available options:

2026-04-01

Idempotency-Key

string

A unique string that makes a retried write safe. If you send the same request with the same key within 24 hours, the API returns the stored response and does not run the request again. A 5xx or 429 response is not stored, so a retry with that key runs the request again.

Maximum string length: 255

Example:

"ik_a1b2c3d4e5f6"

Body

application/json

display_name

string

required

Name shown on the documents and emails issued for this merchant

Required string length: 1 - 200

Example:

"Northwind Traders"

external_id

string

required

Your own identifier for the merchant, unique within your organization.

Minimum string length: 1

Example:

"acct_492"

avatar

object | null

Square mark for places too small for the full logo. We host it and return its URL as avatar_url.

Show child attributes

logo

object | null

Logo shown beside yours in the header of this merchant's documents and emails. We host it and return its URL as logo_url.

Show child attributes

support_email

string<email> | null

Support address shown to this merchant's buyers. Omit it to show yours instead.

Example:

"support@northwind.example"

Response

Success

created_at

string<date-time>

required

When the merchant was created

Example:

"2026-08-01T10:00:00Z"

display_name

string

required

Name shown on the documents and emails issued for this merchant

Example:

"Northwind Traders"

external_id

string

required

Your own identifier for the merchant, unique within your organization

Example:

"acct_492"

string

required

Unique identifier for the merchant

Example:

"mrch_034DG8VMQwhPngo3S9mdKO"

updated_at

string<date-time>

required

When the merchant was last updated

Example:

"2026-08-01T12:30:00Z"

archived_at

string<date-time> | null

When the merchant was archived. Absent while the merchant is active; archived merchants take no new document attribution but keep rendering on historical documents.

Example:

"2026-08-20T12:00:00Z"

avatar_url

string

Square mark for places too small for the full logo, such as list rows

logo_url

string

Logo shown beside yours in the header of documents and emails issued for this merchant

support_email

string

Support address shown to this merchant's buyers on its documents and emails

Example:

"support@northwind.example"

⌘I

Create a merchant

curl --request POST \
  --url https://api.alguna.io/merchants \
  --header 'Alguna-Version: <alguna-version>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "display_name": "Northwind Traders",
  "external_id": "acct_492",
  "avatar": {
    "content": "iVBORw0KGgoAAAANSUhEUg==",
    "content_type": "image/png"
  },
  "logo": {
    "content": "iVBORw0KGgoAAAANSUhEUg==",
    "content_type": "image/png"
  },
  "support_email": "support@northwind.example"
}
'

import requests

url = "https://api.alguna.io/merchants"

payload = {
    "display_name": "Northwind Traders",
    "external_id": "acct_492",
    "avatar": {
        "content": "iVBORw0KGgoAAAANSUhEUg==",
        "content_type": "image/png"
    },
    "logo": {
        "content": "iVBORw0KGgoAAAANSUhEUg==",
        "content_type": "image/png"
    },
    "support_email": "support@northwind.example"
}
headers = {
    "Alguna-Version": "<alguna-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Alguna-Version': '<alguna-version>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    display_name: 'Northwind Traders',
    external_id: 'acct_492',
    avatar: {content: 'iVBORw0KGgoAAAANSUhEUg==', content_type: 'image/png'},
    logo: {content: 'iVBORw0KGgoAAAANSUhEUg==', content_type: 'image/png'},
    support_email: 'support@northwind.example'
  })
};

fetch('https://api.alguna.io/merchants', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "created_at": "2026-08-01T10:00:00Z",
  "display_name": "Northwind Traders",
  "external_id": "acct_492",
  "id": "mrch_034DG8VMQwhPngo3S9mdKO",
  "updated_at": "2026-08-01T12:30:00Z",
  "archived_at": "2026-08-20T12:00:00Z",
  "avatar_url": "<string>",
  "logo_url": "<string>",
  "support_email": "support@northwind.example"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

API Reference

Examples

SDKs

API Reference

Webhooks

Authorizations

Headers

Body

Response