> For the complete documentation index, see [llms.txt](https://docs.thewalletcrew.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thewalletcrew.io/api-reference/extensions/comarch.md).
# Comarch
## Get the Comarch configuration
> Returns the Comarch configuration of the tenant. Secrets are never returned; \`hasClientSecret\` and\
> \`kafkaConnection.hasPassword\` tell whether they are stored.
```json
{"openapi":"3.1.1","info":{"title":"Neostore internal API","version":"v1"},"tags":[{"name":"Comarch"}],"servers":[{"url":"https://app.neostore.cloud","description":"Production Server"},{"url":"https://app-qa.neostore.cloud","description":"Staging Server"}],"security":[{"admin-bearer":["tenant.comarch.settings:read"]},{"apiKey":[]}],"components":{"securitySchemes":{"admin-bearer":{"type":"oauth2","flows":{"implicit":{"authorizationUrl":"https://auth.neostore.cloud/authorize?audience=https://app.neostore.cloud/api/","scopes":{}}}},"apiKey":{"type":"apiKey","name":"X-API-KEY","in":"header"}},"schemas":{"ComarchConfigurationResponse":{"required":["connection","providers","rateLimit"],"type":"object","properties":{"connection":{"description":"How the tenant reaches the Comarch API.","$ref":"#/components/schemas/ComarchConnectionResponse"},"providers":{"description":"How the built-in customer and coupon providers behave. `coupon` is always present.","$ref":"#/components/schemas/ComarchProvidersConfiguration"},"kafkaConnection":{"description":"The Kafka topic the tenant listens to; null when Kafka is not configured.","$ref":"#/components/schemas/ComarchKafkaConnectionResponse"},"rateLimit":{"description":"Cap on the calls sent to Comarch.","$ref":"#/components/schemas/ComarchRateLimitSettings"}},"additionalProperties":false,"description":"The stored Comarch configuration of the tenant, without its secrets."},"ComarchConnectionResponse":{"required":["baseUrl","clientId","hasClientSecret","partnerCode","programCode"],"type":"object","properties":{"baseUrl":{"type":"string","description":"Root URL of the Comarch CLM B2B Gateway API, always ending with a slash.","format":"uri"},"clientId":{"minLength":1,"type":"string","description":"OAuth2 client id issued by Comarch for the B2B Gateway API."},"programCode":{"minLength":1,"type":"string","description":"Comarch CLM code of the loyalty programme (Comarch `program_code`)."},"partnerCode":{"minLength":1,"type":"string","description":"Comarch code of the tenant's partner; only this partner's stores are looked up."},"hasClientSecret":{"type":"boolean","description":"Whether a client secret is stored. When true, a save may omit `connection.clientSecret` to keep it."}},"additionalProperties":false,"description":"How the tenant reaches the Comarch CLM B2B Gateway API, as stored, without the client secret."},"ComarchProvidersConfiguration":{"required":["customer"],"type":"object","properties":{"customer":{"description":"How the holder's Comarch customer record is read and updated.","$ref":"#/components/schemas/ComarchCustomerConfiguration"},"coupon":{"description":"Coupon sync settings. Always returned; on a save, omit it to keep the current settings.","$ref":"#/components/schemas/ComarchCouponConfiguration"}},"additionalProperties":false,"description":"How the built-in Comarch customer and coupon providers behave."},"ComarchCustomerConfiguration":{"type":"object","properties":{"retrieveCustomerTransactionBalance":{"type":"boolean","description":"When true, the account also carries `comarch.customer.waitingToBookPoints` (points not yet booked),\nat the cost of one more Comarch call per customer lookup. Default false.","default":false},"updateOnPassInstallationChange":{"type":"boolean","description":"When true, every pass install or removal on a device calls the\n`extensions.comarch.walletInstallationCustomerUpdater` script, and the update it returns is sent to\nthe Comarch customer named by the pass's Comarch customer id. Default false.","default":false}},"additionalProperties":false,"description":"How the holder's Comarch customer record is read and updated."},"ComarchCouponConfiguration":{"type":"object","properties":{"enabled":{"type":"boolean","description":"When true, the Comarch coupons of the pass's customer are reconciled with the pass's benefits on every\npass creation and every pass update that recomputes metadata. Default false.","default":false},"passType":{"type":["null","string"],"description":"Pass template of a separate pass issued for each synced coupon. Null or blank issues none."},"usedRetentionDays":{"maximum":3650,"minimum":0,"type":"integer","description":"Days a used coupon stays on the pass after the sync first sees it used, 0 to 3650 (else 400). 0 removes it at once. Default 0.","format":"int32","default":0},"expiredRetentionDays":{"maximum":3650,"minimum":0,"type":"integer","description":"Days an expired coupon stays on the pass, counted from its expiry date, 0 to 3650 (else 400). Default 30.","format":"int32","default":30}},"additionalProperties":false,"description":"How the holder's Comarch coupons become benefits on their passes."},"ComarchKafkaConnectionResponse":{"required":["bootstrapServers","hasPassword","topic","username"],"type":"object","properties":{"bootstrapServers":{"minLength":1,"type":"string","description":"Comma-separated list of Kafka bootstrap servers, as `host:port`."},"username":{"minLength":1,"type":"string","description":"Kafka user; must support SASL SCRAM-SHA-512."},"topic":{"minLength":1,"type":"string","description":"Kafka topic Comarch publishes its events to."},"hasPassword":{"type":"boolean","description":"Whether a Kafka password is stored. When false, no Comarch event is received."}},"additionalProperties":false,"description":"The Comarch Kafka topic the tenant listens to, as stored, without the password."},"ComarchRateLimitSettings":{"type":"object","properties":{"throttlingLimit":{"maximum":10000,"minimum":1,"type":"integer","description":"Maximum calls per second sent to Comarch, 1 to 10000 (else 400). Default 80.","format":"int32","default":80}},"additionalProperties":false,"description":"Cap on the calls this tenant sends to Comarch."},"ProblemDetails":{"type":"object","properties":{"type":{"type":["null","string"]},"title":{"type":["null","string"]},"status":{"type":["null","integer"],"format":"int32"},"detail":{"type":["null","string"]},"instance":{"type":["null","string"]}},"additionalProperties":{}},"HttpValidationProblemDetails":{"type":"object","allOf":[{"$ref":"#/components/schemas/ProblemDetails"}],"properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"additionalProperties":{}}}},"paths":{"/api/{tenantId}/admin/extensions/comarch":{"get":{"tags":["Comarch"],"summary":"Get the Comarch configuration","description":"Returns the Comarch configuration of the tenant. Secrets are never returned; `hasClientSecret` and\n`kafkaConnection.hasPassword` tell whether they are stored.","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Configuration returned.","content":{"text/plain":{"schema":{"description":"The stored Comarch configuration of the tenant, without its secrets.","$ref":"#/components/schemas/ComarchConfigurationResponse"}},"application/json":{"schema":{"description":"The stored Comarch configuration of the tenant, without its secrets.","$ref":"#/components/schemas/ComarchConfigurationResponse"}},"text/json":{"schema":{"description":"The stored Comarch configuration of the tenant, without its secrets.","$ref":"#/components/schemas/ComarchConfigurationResponse"}}}},"401":{"description":"The caller is not authenticated.","content":{"application/problem+json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"403":{"description":"The caller lacks the tenant.comarch.settings:read scope.","content":{"application/problem+json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"404":{"description":"Comarch is not configured for this tenant.","content":{"text/plain":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"429":{"description":"Over 1200 requests per minute to this endpoint for the tenant (default limit); retry after Retry-After.","headers":{"Retry-After":{"description":"Seconds to wait before retrying. Sent when the limiter knows it.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}}}}}}}
```
## Set Comarch configuration
> Creates or updates the Comarch configuration.\
> Omit \`connection.clientSecret\` to keep the stored client secret, and, when \`kafkaConnection\` is\
> sent, \`kafkaConnection.password\` to keep the stored Kafka password. Omitting \`kafkaConnection\`\
> removes the Kafka settings and keeps the stored password. Omitting \`rateLimit\` or\
> \`providers.coupon\` keeps the current settings.\
> Saving \`providers.customer.updateOnPassInstallationChange\` off deletes the\
> \`extensions.comarch.walletInstallationCustomerUpdater\` script.
```json
{"openapi":"3.1.1","info":{"title":"Neostore internal API","version":"v1"},"tags":[{"name":"Comarch"}],"servers":[{"url":"https://app.neostore.cloud","description":"Production Server"},{"url":"https://app-qa.neostore.cloud","description":"Staging Server"}],"security":[{"admin-bearer":["tenant.comarch.settings:write"]},{"apiKey":[]}],"components":{"securitySchemes":{"admin-bearer":{"type":"oauth2","flows":{"implicit":{"authorizationUrl":"https://auth.neostore.cloud/authorize?audience=https://app.neostore.cloud/api/","scopes":{}}}},"apiKey":{"type":"apiKey","name":"X-API-KEY","in":"header"}},"schemas":{"SetComarchRequest":{"required":["connection","providers"],"type":"object","properties":{"connection":{"description":"How the tenant reaches the Comarch API.","$ref":"#/components/schemas/ComarchConnectionRequest"},"providers":{"description":"How the built-in customer and coupon providers behave.","$ref":"#/components/schemas/ComarchProvidersConfiguration"},"kafkaConnection":{"description":"The Kafka topic to listen to. When omitted, the Kafka settings are removed and Comarch events stop being\nreceived; the stored Kafka password is kept, so switching Kafka back on does not ask for it again.","$ref":"#/components/schemas/ComarchKafkaConnectionRequest"},"rateLimit":{"description":"Cap on the calls sent to Comarch. When omitted, the current settings are kept (80 per second when none).","$ref":"#/components/schemas/ComarchRateLimitSettings"}},"additionalProperties":false,"description":"The Comarch configuration of the tenant, as sent on a save."},"ComarchConnectionRequest":{"required":["baseUrl","clientId","partnerCode","programCode"],"type":"object","properties":{"baseUrl":{"type":"string","description":"Root URL of the Comarch CLM B2B Gateway API. A trailing slash is added when missing.","format":"uri"},"clientId":{"minLength":1,"type":"string","description":"OAuth2 client id issued by Comarch for the B2B Gateway API."},"programCode":{"minLength":1,"type":"string","description":"Comarch CLM code of the loyalty programme (Comarch `program_code`)."},"partnerCode":{"minLength":1,"type":"string","description":"Comarch code of the tenant's partner; only this partner's stores are looked up."},"clientSecret":{"type":["null","string"],"description":"OAuth2 client secret. Never returned.\nOmitted, null or blank keeps the stored secret; refused with a 400 when none is stored yet."}},"additionalProperties":false,"description":"How the tenant reaches the Comarch CLM B2B Gateway API, as sent on a save."},"ComarchProvidersConfiguration":{"required":["customer"],"type":"object","properties":{"customer":{"description":"How the holder's Comarch customer record is read and updated.","$ref":"#/components/schemas/ComarchCustomerConfiguration"},"coupon":{"description":"Coupon sync settings. Always returned; on a save, omit it to keep the current settings.","$ref":"#/components/schemas/ComarchCouponConfiguration"}},"additionalProperties":false,"description":"How the built-in Comarch customer and coupon providers behave."},"ComarchCustomerConfiguration":{"type":"object","properties":{"retrieveCustomerTransactionBalance":{"type":"boolean","description":"When true, the account also carries `comarch.customer.waitingToBookPoints` (points not yet booked),\nat the cost of one more Comarch call per customer lookup. Default false.","default":false},"updateOnPassInstallationChange":{"type":"boolean","description":"When true, every pass install or removal on a device calls the\n`extensions.comarch.walletInstallationCustomerUpdater` script, and the update it returns is sent to\nthe Comarch customer named by the pass's Comarch customer id. Default false.","default":false}},"additionalProperties":false,"description":"How the holder's Comarch customer record is read and updated."},"ComarchCouponConfiguration":{"type":"object","properties":{"enabled":{"type":"boolean","description":"When true, the Comarch coupons of the pass's customer are reconciled with the pass's benefits on every\npass creation and every pass update that recomputes metadata. Default false.","default":false},"passType":{"type":["null","string"],"description":"Pass template of a separate pass issued for each synced coupon. Null or blank issues none."},"usedRetentionDays":{"maximum":3650,"minimum":0,"type":"integer","description":"Days a used coupon stays on the pass after the sync first sees it used, 0 to 3650 (else 400). 0 removes it at once. Default 0.","format":"int32","default":0},"expiredRetentionDays":{"maximum":3650,"minimum":0,"type":"integer","description":"Days an expired coupon stays on the pass, counted from its expiry date, 0 to 3650 (else 400). Default 30.","format":"int32","default":30}},"additionalProperties":false,"description":"How the holder's Comarch coupons become benefits on their passes."},"ComarchKafkaConnectionRequest":{"required":["bootstrapServers","topic","username"],"type":"object","properties":{"bootstrapServers":{"minLength":1,"type":"string","description":"Comma-separated list of Kafka bootstrap servers, as `host:port`."},"username":{"minLength":1,"type":"string","description":"Kafka user; must support SASL SCRAM-SHA-512."},"topic":{"minLength":1,"type":"string","description":"Kafka topic Comarch publishes its events to."},"password":{"type":["null","string"],"description":"Kafka password. Never returned.\nOmitted, null or blank keeps the stored password; refused with a 400 when none is stored yet."}},"additionalProperties":false,"description":"The Comarch Kafka topic the tenant listens to, as sent on a save. Comarch events read from it (customer,\npoint balance, coupon) refresh the passes of the customers they name."},"ComarchRateLimitSettings":{"type":"object","properties":{"throttlingLimit":{"maximum":10000,"minimum":1,"type":"integer","description":"Maximum calls per second sent to Comarch, 1 to 10000 (else 400). Default 80.","format":"int32","default":80}},"additionalProperties":false,"description":"Cap on the calls this tenant sends to Comarch."},"ProblemDetails":{"type":"object","properties":{"type":{"type":["null","string"]},"title":{"type":["null","string"]},"status":{"type":["null","integer"],"format":"int32"},"detail":{"type":["null","string"]},"instance":{"type":["null","string"]}},"additionalProperties":{}},"HttpValidationProblemDetails":{"type":"object","allOf":[{"$ref":"#/components/schemas/ProblemDetails"}],"properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"additionalProperties":{}}}},"paths":{"/api/{tenantId}/admin/extensions/comarch":{"put":{"tags":["Comarch"],"summary":"Set Comarch configuration","description":"Creates or updates the Comarch configuration.\nOmit `connection.clientSecret` to keep the stored client secret, and, when `kafkaConnection` is\nsent, `kafkaConnection.password` to keep the stored Kafka password. Omitting `kafkaConnection`\nremoves the Kafka settings and keeps the stored password. Omitting `rateLimit` or\n`providers.coupon` keeps the current settings.\nSaving `providers.customer.updateOnPassInstallationChange` off deletes the\n`extensions.comarch.walletInstallationCustomerUpdater` script.","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"The configuration to store.","content":{"application/json":{"schema":{"description":"The Comarch configuration of the tenant, as sent on a save.","$ref":"#/components/schemas/SetComarchRequest"}},"text/json":{"schema":{"description":"The Comarch configuration of the tenant, as sent on a save.","$ref":"#/components/schemas/SetComarchRequest"}},"application/*+json":{"schema":{"description":"The Comarch configuration of the tenant, as sent on a save.","$ref":"#/components/schemas/SetComarchRequest"}}},"required":true},"responses":{"204":{"description":"Configuration saved."},"400":{"description":"The body is invalid (missing required field, value out of range), or a client secret or Kafka password is omitted while none is stored yet.","content":{"text/plain":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"401":{"description":"The caller is not authenticated.","content":{"application/problem+json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"403":{"description":"The caller lacks the tenant.comarch.settings:write scope.","content":{"application/problem+json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"429":{"description":"Over 1200 requests per minute to this endpoint for the tenant (default limit); retry after Retry-After.","headers":{"Retry-After":{"description":"Seconds to wait before retrying. Sent when the limiter knows it.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}}}}}}}
```
## Delete Comarch configuration
> Removes the Comarch configuration with its client secret and Kafka password. The Comarch scripts are kept.\
> Succeeds even when nothing is configured.
```json
{"openapi":"3.1.1","info":{"title":"Neostore internal API","version":"v1"},"tags":[{"name":"Comarch"}],"servers":[{"url":"https://app.neostore.cloud","description":"Production Server"},{"url":"https://app-qa.neostore.cloud","description":"Staging Server"}],"security":[{"admin-bearer":["tenant.comarch.settings:write"]},{"apiKey":[]}],"components":{"securitySchemes":{"admin-bearer":{"type":"oauth2","flows":{"implicit":{"authorizationUrl":"https://auth.neostore.cloud/authorize?audience=https://app.neostore.cloud/api/","scopes":{}}}},"apiKey":{"type":"apiKey","name":"X-API-KEY","in":"header"}},"schemas":{"ProblemDetails":{"type":"object","properties":{"type":{"type":["null","string"]},"title":{"type":["null","string"]},"status":{"type":["null","integer"],"format":"int32"},"detail":{"type":["null","string"]},"instance":{"type":["null","string"]}},"additionalProperties":{}},"HttpValidationProblemDetails":{"type":"object","allOf":[{"$ref":"#/components/schemas/ProblemDetails"}],"properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"additionalProperties":{}}}},"paths":{"/api/{tenantId}/admin/extensions/comarch":{"delete":{"tags":["Comarch"],"summary":"Delete Comarch configuration","description":"Removes the Comarch configuration with its client secret and Kafka password. The Comarch scripts are kept.\nSucceeds even when nothing is configured.","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Configuration deleted."},"401":{"description":"The caller is not authenticated.","content":{"application/problem+json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"403":{"description":"The caller lacks the tenant.comarch.settings:write scope.","content":{"application/problem+json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"429":{"description":"Over 1200 requests per minute to this endpoint for the tenant (default limit); retry after Retry-After.","headers":{"Retry-After":{"description":"Seconds to wait before retrying. Sent when the limiter knows it.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.thewalletcrew.io/api-reference/extensions/comarch.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.