Merchant Service (2026-08-09.2745644872)

Download OpenAPI specification:Download

Merchant-facing API. Endpoints for listing accessible merchants, reading/updating the merchant profile, and managing communication endpoints — the shared inboxes that receive merchant-level notifications.

List merchants accessible to the current user

Returns merchants the authenticated user can access based on their Keycloak token.

Authorizations:

idp

Responses

Response samples

200
400

Content type

application/json

{"merchants": [{"id": "string",
"name": "string",
"status": "active",
"vat_id": "string"
}
]
}

Get merchant profile

Returns the full profile of the active merchant identified by the x-logitrail-merchant-id header.

Authorizations:

idp

header Parameters

x-logitrail-merchant-id

required

string non-empty

Logitrail's Merchant ID.

Responses

Response samples

200
400

Content type

application/json

{"merchant_profile": {"id": "string",
"status": "active",
"official_name": "string",
"name": "string",
"address": {"street": "string",
"postal_code": "string",
"city": "string",
"country": "st"
},
"vat_id": "string",
"business_id": "string",
"eori": "string",
"voec": "string",
"hmrc": "string",
"ioss": "string",
"ioss_issuer_country": "st",
"gs1_company_id": "string",
"customer_service": {"email": "user@example.com",
"phone": "string"
},
"invoicing": {"mode": "email",
"email_recipient": "string",
"finvoice_address": "string",
"finvoice_operator_id": "string",
"payment_term_days": -9007199254740991
},
"logo_url": "http://example.com",
"tracking": {"requires_batch_number": true,
"requires_best_before_date": true
}
}
}

Update merchant profile

Updates editable fields of the active merchant profile. PATCH semantics — only supplied fields are updated. Read-only fields (id, status, invoicing.payment_term_days, logo_url) are not accepted.

Authorizations:

idp

header Parameters

x-logitrail-merchant-id

required

string non-empty

Logitrail's Merchant ID.

Responses

Response samples

200
400

Content type

application/json

{"merchant_profile": {"id": "string",
"status": "active",
"official_name": "string",
"name": "string",
"address": {"street": "string",
"postal_code": "string",
"city": "string",
"country": "st"
},
"vat_id": "string",
"business_id": "string",
"eori": "string",
"voec": "string",
"hmrc": "string",
"ioss": "string",
"ioss_issuer_country": "st",
"gs1_company_id": "string",
"customer_service": {"email": "user@example.com",
"phone": "string"
},
"invoicing": {"mode": "email",
"email_recipient": "string",
"finvoice_address": "string",
"finvoice_operator_id": "string",
"payment_term_days": -9007199254740991
},
"logo_url": "http://example.com",
"tracking": {"requires_batch_number": true,
"requires_best_before_date": true
}
}
}

List merchant communication endpoints

Returns the shared-inbox contact records (email/SMS) configured for the active merchant.

Authorizations:

idp

header Parameters

x-logitrail-merchant-id

required

string non-empty

Logitrail's Merchant ID.

Responses

Response samples

200
400

Content type

application/json

{"endpoints": [{"id": "stringstringstringstring",
"channel": "email",
"address": "string",
"label": "string",
"locale": "string"
}
]
}

Create a merchant communication endpoint

Adds a shared-inbox contact record to the active merchant. Admin attestation only — no address verification.

Authorizations:

idp

header Parameters

x-logitrail-merchant-id

required

string non-empty

Logitrail's Merchant ID.

Request Body schema: application/json

channel required	string Enum: "email" "sms"
address required	string non-empty Delivery address for this channel.
label	string non-empty Human-readable label.
locale	string Optional per-endpoint locale override.

Responses

Request samples

Payload

Content type

application/json

{"channel": "email",
"address": "string",
"label": "string",
"locale": "string"
}

Response samples

201
400

Content type

application/json

{"endpoint": {"id": "stringstringstringstring",
"channel": "email",
"address": "string",
"label": "string",
"locale": "string"
}
}

Update a merchant communication endpoint

Partially updates address, label, or locale override for one endpoint. Channel is immutable after creation.

Authorizations:

idp

header Parameters

x-logitrail-merchant-id

required

string non-empty

Logitrail's Merchant ID.

Request Body schema: application/json

address	string non-empty Updated delivery address.
label	string non-empty Updated label.
	string or null Updated locale override, or null to clear it.

Responses

Request samples

Payload

Content type

application/json

{"address": "string",
"label": "string",
"locale": "string"
}

Response samples

200
400
404

Content type

application/json

{"endpoint": {"id": "stringstringstringstring",
"channel": "email",
"address": "string",
"label": "string",
"locale": "string"
}
}

Delete a merchant communication endpoint

Removes the contact record. Existing per-type subscription rows for this endpoint are not cleaned up.

Authorizations:

idp

header Parameters

x-logitrail-merchant-id

required

string non-empty

Logitrail's Merchant ID.

Responses

Response samples

400
404

Content type

application/json

{"message": "string",
"error_code": "VALIDATION_ERROR",
"validation_errors": [null
]
}

Subscribe a merchant communication endpoint to a type

Sets enabled/channels/cadence for one communication type on one shared-inbox endpoint. Rejects channels or cadence outside the permitted set and opting out of a type where optOutAllowed is false.

Authorizations:

idp

header Parameters

x-logitrail-merchant-id

required

string non-empty

Logitrail's Merchant ID.

Request Body schema: application/json

enabled required	boolean
channels required	Array of strings Items Enum: "email" "sms"
cadence required	string Enum: "instant" "daily" "weekly"

Responses

Request samples

Payload

Content type

application/json

{"enabled": true,
"channels": ["email"
],
"cadence": "instant"
}

Response samples

200
400
404

Content type

application/json

{"typeKey": "string",
"enabled": true,
"channels": ["string"
],
"cadence": "string",
"updatedAt": "string"
}