Partners · Tenvelo API

POST/v1/partner-relationship-offers/search

Read the offer a link carries

No. searchPartnerRelationshipOffersAuth members:read
The offer of a relationship that the code in a partner's link names, for an owner deciding whether to let the partner in (docs/decisions/0104 §2). A search rather than a read by id, because the code is a secret: it travels in the body and never in an address a log keeps.
Only an owner may read one. A code nobody issued, or one already answered, revoked or lapsed, is 404.
Request body application/json · PartnerRelationshipOfferCode

codestring

Required
1–128 chars
Responses

200
The offer.

PartnerRelationshipOfferToAnswer · application/json

idstring · uuid

Required

lapses_atstring · date-time

Required

notestring

Required

offered_by_namestring

Required
Who on the partner's team made the offer.

partner_kindstring · enum

Required
What the partner does for the businesses it looks after.
operatorreselleraccountant

partner_namestring

Required

rolestring · enum

Required
What the partner asks to be. The owner may grant staff in place of manager, never more.
managerstaff

400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

404
No such resource, or none visible to this caller.
Also returned instead of 403 where acknowledging existence would itself leak information — so a 404 does not prove the id is unused globally, only that it is not yours.

410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

415
The request Content-Type is not supported. This API accepts application/json on all mutations.

429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.
Request
curl -X POST 'https://api.tenvelo.com/v1/partner-relationship-offers/search' \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' \ -d '{ "code": "string" }'
Response
{ "id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "lapses_at": "2026-09-11T09:30:00Z", "note": "string", "offered_by_name": "string", "partner_kind": "operator", "partner_name": "string", "role": "manager" }
POST/v1/partner-relationship-offers/{id}/accept

Let a partner in

No. acceptPartnerRelationshipOfferAuth members:write
An owner accepts the offer the code names, for this business: the partner reaches it as the role granted, at the locations chosen or every one, until the end date or for good (docs/decisions/0104 §2). Only an owner may. The offer is spent, once; accepting it again for this business answers what the first acceptance recorded.
A role above what was asked is 422. A partner that already reaches the business is 409. A code nobody issued, or an offer revoked, lapsed or answered by another business, is 404.
Parameters

idpath · string · uuid
Required
UUIDv7 of the resource.
For resources a device can originate — orders, and their line items — this id is minted by the client before the record is ever synced, which is what makes an offline create idempotent.

Idempotency-Keyheader · string
Required
A client-generated key making this request safe to retry.
Required on every mutation that creates a resource or moves money. A till on bad wifi cannot tell a lost response from a lost request; without a key its only options are to risk a duplicate sale or to drop a real one. With a key it retries freely: the first request to arrive is processed, and every replay returns that same stored response.
Rules:
Mint the key once, when the operation is first queued, and reuse it for every retry. A fresh key per attempt defeats the mechanism entirely.
Keys are scoped per merchant and per operation, and are retained for 30 days — long enough that a till switched off mid-sync can retry with the same key however long it stayed on the shelf.
Replaying a key with a different request body is a client bug and is rejected with 422, rather than silently returning the first result — quietly serving the old response would hide a real inconsistency in the caller.
A UUIDv7 or ULID is a good choice.
Request body application/json · PartnerRelationshipOfferAcceptance

codestring

Required
1–128 chars

ends_atstring · date-time

RequiredNullable
When the partner stops reaching the business; null for no end date.

location_idsarray of string · uuid

Required
The locations the partner reaches. Empty is every location.
≤ 1000 items

rolestring · enum

Required
What was asked, or staff in place of manager.
managerstaff
Responses

201
The partner reaches the business.

PartnerRelationship · application/json

approved_atstring · date-time

Required

approved_by_namestring

Required

ends_atstring · date-time

RequiredNullable

location_idsarray of string · uuid

Required
The locations the partner reaches. Empty is every location.

partner_idstring · uuid

Required

partner_kindstring · enum

Required
operatorreselleraccountant

partner_namestring

Required

rolestring · enum

Required
managerstaff

support_emailstring
The support address the partner says its clients write to first, shown under Help. Empty when it has not said.

support_hoursstring
When the partner answers, in its own words. Empty when it has not said.

support_phonestring
The support phone the partner says its clients ring first, shown under Help. Empty when it has not said.

versioninteger · int64

Required
The relationship's version, which ending it names in If-Match.

400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

404
No such resource, or none visible to this caller.
Also returned instead of 403 where acknowledging existence would itself leak information — so a 404 does not prove the id is unused globally, only that it is not yours.

409
The request conflicts with current state — a uniqueness constraint, or an attempt to mutate an order that is already completed or voided.
Unlike 412, re-reading and retrying unchanged will not resolve it; the request itself has to change.

410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

415
The request Content-Type is not supported. This API accepts application/json on all mutations.

422
The request parsed but failed validation.
invalid_params lists every failing field with a JSON Pointer, not just the first, so a client can mark up a whole form in one pass rather than making the user fix errors one round trip at a time.
Also returned when an Idempotency-Key is replayed with a different body, and when device-computed order totals disagree with the server's recomputation.

429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.
Request
curl -X POST 'https://api.tenvelo.com/v1/partner-relationship-offers/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/accept' \ -H "Authorization: Bearer $TOKEN" \ -H 'Idempotency-Key: 01J8ZK3QF7X2N5V9C4B1A6D8E0' \ -H 'Content-Type: application/json' \ -d '{ "code": "string", "ends_at": "2026-09-11T09:30:00Z", "location_ids": [ "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" ], "role": "manager" }'
Response
{ "approved_at": "2026-09-11T09:30:00Z", "approved_by_name": "string", "ends_at": "2026-09-11T09:30:00Z", "location_ids": [ "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" ], "partner_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "partner_kind": "operator", "partner_name": "string", "role": "manager", "support_email": "string", "support_hours": "string", "support_phone": "string", "version": 0 }
POST/v1/partner-relationship-offers/{id}/decline

Turn a partner down

No. declinePartnerRelationshipOfferAuth members:write
An owner declines the offer the code names, for this business, which spends it: the partner hears no from the business that said it (docs/decisions/0104 §2). Only an owner may. A code nobody issued, or an offer revoked, lapsed or answered by another business, is 404.
Parameters

idpath · string · uuid
Required
UUIDv7 of the resource.
For resources a device can originate — orders, and their line items — this id is minted by the client before the record is ever synced, which is what makes an offline create idempotent.

Idempotency-Keyheader · string
Required
A client-generated key making this request safe to retry.
Required on every mutation that creates a resource or moves money. A till on bad wifi cannot tell a lost response from a lost request; without a key its only options are to risk a duplicate sale or to drop a real one. With a key it retries freely: the first request to arrive is processed, and every replay returns that same stored response.
Rules:
Mint the key once, when the operation is first queued, and reuse it for every retry. A fresh key per attempt defeats the mechanism entirely.
Keys are scoped per merchant and per operation, and are retained for 30 days — long enough that a till switched off mid-sync can retry with the same key however long it stayed on the shelf.
Replaying a key with a different request body is a client bug and is rejected with 422, rather than silently returning the first result — quietly serving the old response would hide a real inconsistency in the caller.
A UUIDv7 or ULID is a good choice.
Request body application/json · PartnerRelationshipOfferCode

codestring

Required
1–128 chars
Responses

204
The offer is declined.

400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

404
No such resource, or none visible to this caller.
Also returned instead of 403 where acknowledging existence would itself leak information — so a 404 does not prove the id is unused globally, only that it is not yours.

410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

415
The request Content-Type is not supported. This API accepts application/json on all mutations.

429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.
Request
curl -X POST 'https://api.tenvelo.com/v1/partner-relationship-offers/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b/decline' \ -H "Authorization: Bearer $TOKEN" \ -H 'Idempotency-Key: 01J8ZK3QF7X2N5V9C4B1A6D8E0' \ -H 'Content-Type: application/json' \ -d '{ "code": "string" }'
GET/v1/partner-relationships

List the partners the business let in

No. listPartnerRelationshipsAuth members:read
Every partner that reaches the business through a relationship an owner approved: as what, where, since when and until when, and which owner let them in (0036 §3, 0104 §2). Owners and managers may read it. Paged with the cursor of the previous page.
Parameters

cursorquery · string
Opaque cursor from a previous page's next_cursor. Omit to start from the beginning.
Pass it back exactly as received. It is base64 and its structure is not part of this contract — decoding it, or constructing one by hand, will break without notice.

limitquery · integer · int32
Maximum items to return. The server may return fewer, so always drive the loop from has_more rather than from the size of the page you got back.
Responses

200
A page of partners.

PartnerRelationshipPage · application/json

has_moreboolean

Required

itemsarray of PartnerRelationship

Required

approved_atstring · date-time

Required

approved_by_namestring

Required

ends_atstring · date-time

RequiredNullable

location_idsarray of string · uuid

Required
The locations the partner reaches. Empty is every location.

partner_idstring · uuid

Required

partner_kindstring · enum

Required
operatorreselleraccountant

partner_namestring

Required

rolestring · enum

Required
managerstaff

support_emailstring
The support address the partner says its clients write to first, shown under Help. Empty when it has not said.

support_hoursstring
When the partner answers, in its own words. Empty when it has not said.

support_phonestring
The support phone the partner says its clients ring first, shown under Help. Empty when it has not said.

versioninteger · int64

Required
The relationship's version, which ending it names in If-Match.

next_cursorstring

Nullable

400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.
Request
curl -X GET 'https://api.tenvelo.com/v1/partner-relationships' \ -H "Authorization: Bearer $TOKEN"
Response
{ "has_more": false, "items": [ { "approved_at": "2026-09-11T09:30:00Z", "approved_by_name": "string", "ends_at": "2026-09-11T09:30:00Z", "location_ids": [ "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b" ], "partner_id": "0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b", "partner_kind": "operator", "partner_name": "string", "role": "manager", "support_email": "string", "support_hours": "string", "support_phone": "string", "version": 0 } ], "next_cursor": "string" }
DELETE/v1/partner-relationships/{id}

End a partner's access

No. deletePartnerRelationshipAuth members:write
An owner ends the business's relationship with a partner, guarded by If-Match with its version. Every one of the partner's people loses the business on their next request (docs/decisions/0104 §3). The relationship is kept as the record of what it was. Only an owner may. One already ended, or past its end date, is 404.
Parameters

idpath · string · uuid
Required
The partner's id.

If-Matchheader · string
Required
The ETag from the read that produced the value you are updating.
Required on updates, not optional, because "last write wins" is the wrong default for a catalogue two managers might edit at once. If anything has been written since your read, the request is rejected with 412 and you re-read and re-apply.
Use * to mean "write regardless of current version" — an explicit, greppable override rather than the silent default.
Responses

204
The partner no longer reaches the business.

400
The request could not be parsed. Malformed JSON, a bad query parameter, or a header that failed to decode, among them an API-Version later than the server speaks or not a date (api-version-unknown, with the server's own in api_version).
Distinct from 422: a 400 never reached validation, so invalid_params is absent. Retrying without changing the request will fail again, except that a request refused for its API-Version goes once the server is updated.

401
No credentials, or credentials that could not be verified — missing bearer token, malformed JWT, expired token, or a signature that failed against the issuer's JWKS.
Refresh the token and retry once. Repeated 401 after a refresh means the device needs to re-enrol.

403
Authenticated, but not permitted. The token is valid and its merchant was resolved, but the caller's role does not allow this operation, or the target belongs to a different merchant.
Cross-tenant access is reported as 403 on a resource the caller may not see, and as 404 where even confirming existence would leak information. Retrying will not help.

404
No such resource, or none visible to this caller.
Also returned instead of 403 where acknowledging existence would itself leak information — so a 404 does not prove the id is unused globally, only that it is not yours.

410
The request names an API-Version this server no longer serves (docs/decisions/0011). Nothing in it was read. api_version names the version the server speaks: the client is behind, and sends the request again once it is updated.

412
The If-Match version did not match the resource's current version: someone else wrote since you read.
This is the expected, healthy outcome of two clients editing the same record — not an error condition to suppress. Re-read the resource, re-apply your change on top of the new state, and retry with the fresh ETag.

429
Rate limit exceeded. Honour Retry-After rather than applying your own backoff.
A fleet of tills coming back online together after an outage is the realistic cause, which is exactly when uncoordinated client-side retry turns a brief outage into a sustained one. The limit is per process, and per site for what records trade there — a request spends its site's budget, and a till's own smaller one inside it — and per (client, merchant) for everything else; no RateLimit field is sent, so this response and its Retry-After are the whole of the contract.

500
Something failed on our side. trace_id identifies the request in our tracing — quote it in a support ticket.
The body never carries internal detail: no SQL, no stack traces, no upstream error strings. Safe to retry with the same Idempotency-Key.
Request
curl -X DELETE 'https://api.tenvelo.com/v1/partner-relationships/0192f1e4-7c3a-7b2e-9f10-5d6c7e8f9a0b' \ -H "Authorization: Bearer $TOKEN" \ -H 'If-Match: "3"'

Request body application/json · PartnerRelationshipOfferCode

Responses

Parameters

Request body application/json · PartnerRelationshipOfferAcceptance

Responses

Parameters

Request body application/json · PartnerRelationshipOfferCode

Responses

Parameters

Responses

Parameters

Responses