{"openapi":"3.1.0","info":{"title":"LivTech ePay API","version":"1.2.0","description":"LivTech's payment service: the payer portal, pay links and onboarding, behind a versioned public API.. Conventions: docs/api-conventions.md.","contact":{"name":"LivTech","url":"https://dev.livtech.com"}},"servers":[{"url":"https://staging.pay.livtech.com/rest/v1","description":"staging"},{"url":"https://us.pay.livtech.com/rest/v1","description":"us"}],"security":[{"centralAuthStaging":[]},{"centralAuthUs":[]}],"tags":[{"name":"legal-entities","description":"Businesses, each known by its EIN, that every LivTech product shares."},{"name":"merchants","description":"The money identities of a legal entity: later, one Connect account each."}],"components":{"headers":{"TraceId":{"description":"The W3C trace id of this request. It is on every response.","schema":{"type":"string","pattern":"^[0-9a-f]{32}$"}}},"responses":{"BadRequest":{"description":"bad_request: the request could not be read, or Prefer: handling=strict found unknown fields.","headers":{"Trace-Id":{"$ref":"#/components/headers/TraceId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unauthenticated":{"description":"unauthenticated: the bearer token is missing or not valid.","headers":{"Trace-Id":{"$ref":"#/components/headers/TraceId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Forbidden":{"description":"forbidden: the token does not have the scope this operation needs.","headers":{"Trace-Id":{"$ref":"#/components/headers/TraceId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotFound":{"description":"not_found: it does not exist, or it is not yours.","headers":{"Trace-Id":{"$ref":"#/components/headers/TraceId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotAcceptable":{"description":"not_acceptable: Accept allows neither application/json nor application/problem+json.","headers":{"Trace-Id":{"$ref":"#/components/headers/TraceId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Conflict":{"description":"edit_conflict: the version is stale; conflict: a duplicate or a state that does not allow this; idempotency_key_in_use.","headers":{"Trace-Id":{"$ref":"#/components/headers/TraceId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"PreconditionFailed":{"description":"edit_conflict: the If-Match version is stale. data holds submittedVersion and currentVersion.","headers":{"Trace-Id":{"$ref":"#/components/headers/TraceId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"PayloadTooLarge":{"description":"payload_too_large: the body is over the limit.","headers":{"Trace-Id":{"$ref":"#/components/headers/TraceId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"UnsupportedMediaType":{"description":"unsupported_media_type: the body is not application/json.","headers":{"Trace-Id":{"$ref":"#/components/headers/TraceId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"UnprocessableContent":{"description":"validation_failed: every failure is listed; idempotency_key_mismatch.","headers":{"Trace-Id":{"$ref":"#/components/headers/TraceId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"TooManyRequests":{"description":"rate_limited: wait for Retry-After seconds.","headers":{"Trace-Id":{"$ref":"#/components/headers/TraceId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"InternalError":{"description":"internal_error: our bug. Quote the traceId.","headers":{"Trace-Id":{"$ref":"#/components/headers/TraceId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"securitySchemes":{"centralAuthStaging":{"type":"oauth2","description":"A client-credentials token from LivTech central auth (staging), with this service's resource as its audience.","flows":{"clientCredentials":{"tokenUrl":"https://staging.id.livtech.com/oauth/v1/token","scopes":{"merchants:read":"Read the legal entities and merchants that your product links.","merchants:write":"Make and change legal entities and merchants, and link or unlink them."}}}},"centralAuthUs":{"type":"oauth2","description":"A client-credentials token from LivTech central auth (us), with this service's resource as its audience.","flows":{"clientCredentials":{"tokenUrl":"https://us.id.livtech.com/oauth/v1/token","scopes":{"merchants:read":"Read the legal entities and merchants that your product links.","merchants:write":"Make and change legal entities and merchants, and link or unlink them."}}}}},"schemas":{"Problem":{"type":"object","properties":{"type":{"type":"string","format":"uri","example":"https://dev.livtech.com/errors/validation-failed"},"title":{"type":"string","example":"Validation failed"},"status":{"type":"integer","example":422},"detail":{"type":"string"},"instance":{"type":"string","example":"/rest/v1/merchants"},"code":{"type":"string","example":"validation_failed","description":"Clients branch on code, never on title or detail."},"traceId":{"type":"string","example":"4bf92f3577b34da6a3ce929d0e0e4736","description":"The W3C trace id. Quote it in a support request."},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ProblemErrorItem"}},"data":{"type":"object","additionalProperties":{},"description":"A payload for the code, such as edit_conflict versions."}},"required":["type","title","status","code","traceId"],"description":"RFC 9457 problem details, with LivTech members. Clients ignore members they do not know."},"ProblemErrorItem":{"type":"object","properties":{"code":{"type":"string","example":"required"},"property":{"type":"string","example":"name"},"in":{"type":"string","enum":["body","query","path","header"]},"message":{"type":"string","example":"name: Invalid input: expected string, received undefined"},"userMessage":{"type":"string"}},"required":["code","message"],"description":"One failure. message is English and names the property, never its value."},"LegalEntityList":{"type":"object","properties":{"query":{"$ref":"#/components/schemas/LegalEntityListQuery"},"data":{"type":"array","items":{"$ref":"#/components/schemas/LegalEntity"}},"page":{"$ref":"#/components/schemas/PageInfo"}},"required":["query","data","page"]},"LegalEntityListQuery":{"type":"object","properties":{"page":{"type":"integer"},"size":{"type":"integer"},"sort":{"type":"string"},"externalId":{"type":"string"}},"required":["page","size","sort"],"description":"What the server understood: after defaults, normalization and clamping."},"LegalEntity":{"type":"object","properties":{"id":{"type":"string","example":"len-peg3c7w14pekpm7s46raslq4"},"externalId":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,99}$","description":"Your product's own id for this record: 1 to 100 letters, digits and . _ : -","example":"agency-1042"},"legalName":{"type":"string","example":"Sunrise Home Care LLC"},"einLast4":{"type":"string","description":"The last 4 digits of the EIN.","example":"4567"},"version":{"type":"integer","description":"Send it back on PUT (optimistic locking).","example":0},"createdAt":{"type":"string","format":"date-time","example":"2026-11-18T14:03:22.000Z"},"updatedAt":{"type":"string","format":"date-time","example":"2026-11-18T14:03:22.000Z"}},"required":["id","externalId","legalName","einLast4","version","createdAt","updatedAt"],"description":"One business, known by its EIN, that every LivTech product shares."},"PageInfo":{"type":"object","properties":{"num":{"type":"integer","description":"This page number. Offset mode only."},"size":{"type":"integer"},"matching":{"type":"integer","description":"Items that match the filters. Offset mode only."},"total":{"type":"integer","description":"All the items the caller can see. Offset mode only."},"pages":{"type":"integer"},"more":{"type":"boolean","description":"Whether another page follows. Always present."},"nextCursor":{"type":"string","description":"The cursor of the next page. Cursor mode only."}},"required":["size","more"]},"LegalEntityCreate":{"type":"object","properties":{"externalId":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,99}$","description":"Your product's own id for this record: 1 to 100 letters, digits and . _ : -","example":"agency-1042"},"legalName":{"type":"string","minLength":1,"maxLength":200},"ein":{"type":"string","maxLength":20,"description":"The business's EIN: 9 digits. Write-only: a response shows only einLast4.","example":"00-1234567"}},"required":["externalId","legalName","ein"]},"LegalEntityUpdate":{"type":"object","properties":{"version":{"type":"integer","minimum":0,"description":"The version you read. Or send it as If-Match."},"legalName":{"type":"string","minLength":1,"maxLength":200}}},"MerchantList":{"type":"object","properties":{"query":{"$ref":"#/components/schemas/MerchantListQuery"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Merchant"}},"page":{"$ref":"#/components/schemas/PageInfo"}},"required":["query","data","page"]},"MerchantListQuery":{"type":"object","properties":{"page":{"type":"integer"},"size":{"type":"integer"},"sort":{"type":"string"},"externalId":{"type":"string"}},"required":["page","size","sort"],"description":"What the server understood: after defaults, normalization and clamping."},"Merchant":{"type":"object","properties":{"id":{"type":"string","example":"mer-q2v8k7n4m1x9c3b5z6a0s8d7"},"legalEntityId":{"type":"string","example":"len-peg3c7w14pekpm7s46raslq4"},"externalId":{"type":["string","null"],"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,99}$","description":"Your product's own id for the merchant; null when your product does not link it.","example":"agency-1042"},"dba":{"type":["string","null"],"example":"Sunrise Care"},"statementDescriptor":{"type":"string","example":"SUNRISE CARE"},"onboarding":{"$ref":"#/components/schemas/MerchantOnboarding"},"version":{"type":"integer","description":"Send it back on PUT and DELETE (optimistic locking).","example":0},"createdAt":{"type":"string","format":"date-time","example":"2026-11-18T14:03:22.000Z"},"updatedAt":{"type":"string","format":"date-time","example":"2026-11-18T14:03:22.000Z"}},"required":["id","legalEntityId","externalId","dba","statementDescriptor","onboarding","version","createdAt","updatedAt"],"description":"One money identity of a legal entity: later, one Connect account."},"MerchantOnboarding":{"type":"object","properties":{"status":{"type":"string","enum":["not_started","in_progress","in_review","active","action_needed","restricted","rejected"],"description":"An open enum: accept values you do not know yet."},"requirementsDue":{"type":"array","items":{"type":"string"},"description":"The names of the requirements that are due. Names only."},"chargesEnabled":{"type":"boolean"},"payoutsEnabled":{"type":"boolean"}},"required":["status","requirementsDue","chargesEnabled","payoutsEnabled"]},"MerchantCreate":{"type":"object","properties":{"externalId":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,99}$","description":"Your product's own id for this record: 1 to 100 letters, digits and . _ : -","example":"agency-1042"},"legalEntityId":{"type":"string","pattern":"^len-[a-z][a-z0-9]{23}$","example":"len-peg3c7w14pekpm7s46raslq4","description":"Make a merchant under this legal entity, which your product links."},"merchantId":{"type":"string","pattern":"^mer-[a-z][a-z0-9]{23}$","example":"mer-q2v8k7n4m1x9c3b5z6a0s8d7","description":"Or link this merchant, of a legal entity that your product links."},"dba":{"type":["string","null"],"minLength":1,"maxLength":200},"statementDescriptor":{"type":"string","minLength":5,"maxLength":22,"pattern":"^[\\x20-\\x7E]+$","description":"Required to make a merchant: 5 to 22 characters."}},"required":["externalId"]},"MerchantUpdate":{"type":"object","properties":{"version":{"type":"integer","minimum":0,"description":"The version you read. Or send it as If-Match."},"dba":{"type":["string","null"],"minLength":1,"maxLength":200},"statementDescriptor":{"type":"string","minLength":5,"maxLength":22,"pattern":"^[\\x20-\\x7E]+$"}}},"MerchantDelete":{"type":"object","properties":{"version":{"type":"integer","minimum":0,"description":"The version you read. Or send it as If-Match."}}}},"parameters":{}},"paths":{"/legal-entities":{"get":{"operationId":"listLegalEntities","tags":["legal-entities"],"summary":"List legal entities","description":"Lists the legal entities that your product links, newest change first by default. Offset pagination: page and size.","security":[{"centralAuthStaging":["merchants:read"]},{"centralAuthUs":["merchants:read"]}],"parameters":[{"schema":{"type":"integer","minimum":1,"description":"The page number, from 1.","example":1},"required":false,"description":"The page number, from 1.","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"description":"Items per page: 25 by default, 100 at most. A larger size is clamped, and the echoed query says so.","example":25},"required":false,"description":"Items per page: 25 by default, 100 at most. A larger size is clamped, and the echoed query says so.","name":"size","in":"query"},{"schema":{"type":"string","maxLength":200,"description":"Fields to sort by, comma-separated. A leading - sorts that field descending, as in FHIR _sort.","example":"-updatedAt,name"},"required":false,"description":"Fields to sort by, comma-separated. A leading - sorts that field descending, as in FHIR _sort.","name":"sort","in":"query"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,99}$","description":"Find a legal entity by your product's own id.","example":"agency-1042"},"required":false,"description":"Find a legal entity by your product's own id.","name":"externalId","in":"query"}],"responses":{"200":{"description":"A page of legal entities.","headers":{"Trace-Id":{"$ref":"#/components/headers/TraceId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegalEntityList"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"406":{"$ref":"#/components/responses/NotAcceptable"},"422":{"$ref":"#/components/responses/UnprocessableContent"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"operationId":"createLegalEntity","tags":["legal-entities"],"summary":"Make or link a legal entity","description":"Makes a legal entity, or links your product to the one that has this EIN: 201 with the whole legal entity, in both cases. Send an Idempotency-Key (a UUID): a retry with the same key gets the same answer. An externalId that your product already uses is 409 conflict, and data.id names the record that has it.","security":[{"centralAuthStaging":["merchants:write"]},{"centralAuthUs":["merchants:write"]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A UUID (v4 or v7) for this operation, reused on every retry of it."},"required":true,"description":"A UUID (v4 or v7) for this operation, reused on every retry of it.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegalEntityCreate"}}}},"responses":{"201":{"description":"The legal entity. Location names it.","headers":{"Trace-Id":{"$ref":"#/components/headers/TraceId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegalEntity"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"406":{"$ref":"#/components/responses/NotAcceptable"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/UnprocessableContent"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/legal-entities/{id}":{"get":{"operationId":"getLegalEntity","tags":["legal-entities"],"summary":"Read a legal entity","description":"Reads one legal entity that your product links. Any other one is not found.","security":[{"centralAuthStaging":["merchants:read"]},{"centralAuthUs":["merchants:read"]}],"parameters":[{"schema":{"type":"string","pattern":"^len-[a-z][a-z0-9]{23}$","example":"len-peg3c7w14pekpm7s46raslq4"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The legal entity.","headers":{"Trace-Id":{"$ref":"#/components/headers/TraceId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegalEntity"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"406":{"$ref":"#/components/responses/NotAcceptable"},"422":{"$ref":"#/components/responses/UnprocessableContent"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}},"put":{"operationId":"updateLegalEntity","tags":["legal-entities"],"summary":"Change a legal entity","description":"A partial PUT of the legal name: an absent field is unchanged. Send the version you read, in the body (a stale one gets 409 edit_conflict) or as If-Match (412). Every product that links the legal entity sees the change.","security":[{"centralAuthStaging":["merchants:write"]},{"centralAuthUs":["merchants:write"]}],"parameters":[{"schema":{"type":"string","pattern":"^len-[a-z][a-z0-9]{23}$","example":"len-peg3c7w14pekpm7s46raslq4"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid","description":"A UUID (v4 or v7) for this operation, reused on every retry of it."},"required":false,"description":"A UUID (v4 or v7) for this operation, reused on every retry of it.","name":"idempotency-key","in":"header"},{"schema":{"type":"string","maxLength":20,"description":"The ETag of your read, such as W/\"3\": the same as version in the body."},"required":false,"description":"The ETag of your read, such as W/\"3\": the same as version in the body.","name":"if-match","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegalEntityUpdate"}}}},"responses":{"200":{"description":"The changed legal entity, with its new version.","headers":{"Trace-Id":{"$ref":"#/components/headers/TraceId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegalEntity"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"406":{"$ref":"#/components/responses/NotAcceptable"},"409":{"$ref":"#/components/responses/Conflict"},"412":{"$ref":"#/components/responses/PreconditionFailed"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/UnprocessableContent"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/merchants":{"get":{"operationId":"listMerchants","tags":["merchants"],"summary":"List merchants","description":"Lists the merchants that your product links, newest change first by default. Offset pagination: page and size.","security":[{"centralAuthStaging":["merchants:read"]},{"centralAuthUs":["merchants:read"]}],"parameters":[{"schema":{"type":"integer","minimum":1,"description":"The page number, from 1.","example":1},"required":false,"description":"The page number, from 1.","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"description":"Items per page: 25 by default, 100 at most. A larger size is clamped, and the echoed query says so.","example":25},"required":false,"description":"Items per page: 25 by default, 100 at most. A larger size is clamped, and the echoed query says so.","name":"size","in":"query"},{"schema":{"type":"string","maxLength":200,"description":"Fields to sort by, comma-separated. A leading - sorts that field descending, as in FHIR _sort.","example":"-updatedAt,name"},"required":false,"description":"Fields to sort by, comma-separated. A leading - sorts that field descending, as in FHIR _sort.","name":"sort","in":"query"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,99}$","description":"Find a merchant by your product's own id.","example":"agency-1042"},"required":false,"description":"Find a merchant by your product's own id.","name":"externalId","in":"query"}],"responses":{"200":{"description":"A page of merchants.","headers":{"Trace-Id":{"$ref":"#/components/headers/TraceId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantList"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"406":{"$ref":"#/components/responses/NotAcceptable"},"422":{"$ref":"#/components/responses/UnprocessableContent"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"operationId":"createMerchant","tags":["merchants"],"summary":"Make or link a merchant","description":"Makes a merchant (send legalEntityId and statementDescriptor), or links one that exists (send merchantId). Either way, the legal entity is one that your product links, and the answer is 201 with the whole merchant. Send an Idempotency-Key (a UUID). An externalId that your product already uses is 409 conflict, and data.id names the record that has it.","security":[{"centralAuthStaging":["merchants:write"]},{"centralAuthUs":["merchants:write"]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"A UUID (v4 or v7) for this operation, reused on every retry of it."},"required":true,"description":"A UUID (v4 or v7) for this operation, reused on every retry of it.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantCreate"}}}},"responses":{"201":{"description":"The merchant. Location names it.","headers":{"Trace-Id":{"$ref":"#/components/headers/TraceId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Merchant"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"406":{"$ref":"#/components/responses/NotAcceptable"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/UnprocessableContent"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/legal-entities/{id}/merchants":{"get":{"operationId":"listLegalEntityMerchants","tags":["legal-entities"],"summary":"List a legal entity's merchants","description":"Lists every merchant of a legal entity that your product links, so that you can pick one to link. externalId is null for a merchant that your product does not link.","security":[{"centralAuthStaging":["merchants:read"]},{"centralAuthUs":["merchants:read"]}],"parameters":[{"schema":{"type":"string","pattern":"^len-[a-z][a-z0-9]{23}$","example":"len-peg3c7w14pekpm7s46raslq4"},"required":true,"name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"description":"The page number, from 1.","example":1},"required":false,"description":"The page number, from 1.","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"description":"Items per page: 25 by default, 100 at most. A larger size is clamped, and the echoed query says so.","example":25},"required":false,"description":"Items per page: 25 by default, 100 at most. A larger size is clamped, and the echoed query says so.","name":"size","in":"query"},{"schema":{"type":"string","maxLength":200,"description":"Fields to sort by, comma-separated. A leading - sorts that field descending, as in FHIR _sort.","example":"-updatedAt,name"},"required":false,"description":"Fields to sort by, comma-separated. A leading - sorts that field descending, as in FHIR _sort.","name":"sort","in":"query"}],"responses":{"200":{"description":"A page of merchants.","headers":{"Trace-Id":{"$ref":"#/components/headers/TraceId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantList"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"406":{"$ref":"#/components/responses/NotAcceptable"},"422":{"$ref":"#/components/responses/UnprocessableContent"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/merchants/{id}":{"get":{"operationId":"getMerchant","tags":["merchants"],"summary":"Read a merchant","description":"Reads a merchant that your product links, or a merchant of a legal entity that your product links. Any other one is not found.","security":[{"centralAuthStaging":["merchants:read"]},{"centralAuthUs":["merchants:read"]}],"parameters":[{"schema":{"type":"string","pattern":"^mer-[a-z][a-z0-9]{23}$","example":"mer-q2v8k7n4m1x9c3b5z6a0s8d7"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The merchant.","headers":{"Trace-Id":{"$ref":"#/components/headers/TraceId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Merchant"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"406":{"$ref":"#/components/responses/NotAcceptable"},"422":{"$ref":"#/components/responses/UnprocessableContent"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}},"put":{"operationId":"updateMerchant","tags":["merchants"],"summary":"Change a merchant","description":"A partial PUT of a merchant that your product links: an absent field is unchanged, null clears it. Send the version you read, in the body (a stale one gets 409 edit_conflict) or as If-Match (412).","security":[{"centralAuthStaging":["merchants:write"]},{"centralAuthUs":["merchants:write"]}],"parameters":[{"schema":{"type":"string","pattern":"^mer-[a-z][a-z0-9]{23}$","example":"mer-q2v8k7n4m1x9c3b5z6a0s8d7"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid","description":"A UUID (v4 or v7) for this operation, reused on every retry of it."},"required":false,"description":"A UUID (v4 or v7) for this operation, reused on every retry of it.","name":"idempotency-key","in":"header"},{"schema":{"type":"string","maxLength":20,"description":"The ETag of your read, such as W/\"3\": the same as version in the body."},"required":false,"description":"The ETag of your read, such as W/\"3\": the same as version in the body.","name":"if-match","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantUpdate"}}}},"responses":{"200":{"description":"The changed merchant, with its new version.","headers":{"Trace-Id":{"$ref":"#/components/headers/TraceId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Merchant"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"406":{"$ref":"#/components/responses/NotAcceptable"},"409":{"$ref":"#/components/responses/Conflict"},"412":{"$ref":"#/components/responses/PreconditionFailed"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/UnprocessableContent"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}},"delete":{"operationId":"deleteMerchant","tags":["merchants"],"summary":"Remove your product's link to a merchant","description":"Removes your product's own link to the merchant. The merchant stays for the other products. Send the version you read, in the body or as If-Match. A second delete gets 404.","security":[{"centralAuthStaging":["merchants:write"]},{"centralAuthUs":["merchants:write"]}],"parameters":[{"schema":{"type":"string","pattern":"^mer-[a-z][a-z0-9]{23}$","example":"mer-q2v8k7n4m1x9c3b5z6a0s8d7"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","maxLength":20,"description":"The ETag of your read, such as W/\"3\": the same as version in the body."},"required":false,"description":"The ETag of your read, such as W/\"3\": the same as version in the body.","name":"if-match","in":"header"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantDelete"}}}},"responses":{"204":{"description":"The link is removed.","headers":{"Trace-Id":{"$ref":"#/components/headers/TraceId"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"406":{"$ref":"#/components/responses/NotAcceptable"},"409":{"$ref":"#/components/responses/Conflict"},"412":{"$ref":"#/components/responses/PreconditionFailed"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/UnprocessableContent"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"webhooks":{}}