> For the complete documentation index, see [llms.txt](https://developer.celigo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.celigo.com/api/api-reference/b2b-manager/bar-tender-templates.md).

# Bar Tender Templates

Celigo-published BarTender (`.btw`) label templates synced daily from BarTender Cloud. List unique names, load selected template details and lookup-cache field mappings, or download a published `.btw`.

Requires a standard integrator.io JWT with manage or monitor role, plus EDI and EDI label-printing entitlements on the account.

### BarTender template schemas

## The BarTenderTemplateCatalog object

```json
{"openapi":"3.2.0","info":{"title":"BarTender Templates","version":"1.0.0"},"components":{"schemas":{"BarTenderTemplateCatalog":{"type":"object","description":"Response from `GET /v1/bartenderTemplates`. When `name` is omitted the\nbody is `{ names }`. When `name` is provided the body is\n`{ syncedAt, templates, fieldMappings }` for the matching entries.","properties":{"names":{"type":"array","description":"Unique published template names, sorted. Present when `name` is\nomitted. An empty catalog returns `[]`.","items":{"type":"string"}},"syncedAt":{"type":"string","format":"date-time","description":"UTC timestamp of the last successful catalog sync. Present when\n`name` is provided."},"templates":{"type":"array","description":"Published templates whose `name` matches any requested `name` value.\nPresent when `name` is provided. Unknown names yield an empty array,\nnot a 404.","items":{"$ref":"#/components/schemas/BarTenderTemplate"}},"fieldMappings":{"type":"array","description":"Published lookup-cache mappings whose `key` matches any requested\n`name` value. Present when `name` is provided. A catalog that predates\nfield-mapping sync returns `[]`.","items":{"$ref":"#/components/schemas/BarTenderFieldMapping"}}},"if":{"required":["names"]},"then":{"required":["names"]},"else":{"required":["syncedAt","templates","fieldMappings"]}},"BarTenderTemplate":{"type":"object","description":"One published BarTender label template. Internal catalog fields (`id`,\n`btChecksum`, `modifiedDateTime`, `version`) are not exposed — only `name`\nand `s3Key` are returned.","required":["name","s3Key"],"properties":{"name":{"type":"string","description":"Published display name, derived from the `.btw` file stem\n(`amazon.btw` → `\"amazon\"`). Use this value in the `name` query\nparameter and in `GET /v1/bartenderTemplates/{name}/download`."},"s3Key":{"type":"string","description":"Object key for the `.btw` binary in the UI-resources bucket. Pass this\nto the downstream S3 export step that pushes the template to the\ncustomer's BarTender environment."}}},"BarTenderFieldMapping":{"type":"object","description":"One lookup-cache field mapping from the published catalog. Keys often\nname a template (or a pipe-separated alias such as `amazon | 133`);\nvalues keep whatever JSON shape the master cache stored.","required":["key","value"],"properties":{"key":{"type":"string","description":"Mapping key. Filtered with the same case-sensitive exact / pipe-token\nmatch as template `name` when `name` is supplied on the list route."},"value":{"description":"Mapping value from the master lookup cache. May be a string or an\nobject; consumers should check the runtime type before use.","oneOf":[{"title":"String value","type":"string"},{"title":"Object value","type":"object","additionalProperties":true}]}}}}}}
```

## The BarTenderTemplate object

```json
{"openapi":"3.2.0","info":{"title":"BarTender Templates","version":"1.0.0"},"components":{"schemas":{"BarTenderTemplate":{"type":"object","description":"One published BarTender label template. Internal catalog fields (`id`,\n`btChecksum`, `modifiedDateTime`, `version`) are not exposed — only `name`\nand `s3Key` are returned.","required":["name","s3Key"],"properties":{"name":{"type":"string","description":"Published display name, derived from the `.btw` file stem\n(`amazon.btw` → `\"amazon\"`). Use this value in the `name` query\nparameter and in `GET /v1/bartenderTemplates/{name}/download`."},"s3Key":{"type":"string","description":"Object key for the `.btw` binary in the UI-resources bucket. Pass this\nto the downstream S3 export step that pushes the template to the\ncustomer's BarTender environment."}}}}}}
```

## The BarTenderFieldMapping object

```json
{"openapi":"3.2.0","info":{"title":"BarTender Templates","version":"1.0.0"},"components":{"schemas":{"BarTenderFieldMapping":{"type":"object","description":"One lookup-cache field mapping from the published catalog. Keys often\nname a template (or a pipe-separated alias such as `amazon | 133`);\nvalues keep whatever JSON shape the master cache stored.","required":["key","value"],"properties":{"key":{"type":"string","description":"Mapping key. Filtered with the same case-sensitive exact / pipe-token\nmatch as template `name` when `name` is supplied on the list route."},"value":{"description":"Mapping value from the master lookup cache. May be a string or an\nobject; consumers should check the runtime type before use.","oneOf":[{"title":"String value","type":"string"},{"title":"Object value","type":"object","additionalProperties":true}]}}}}}}
```

## List BarTender label templates

> Returns Celigo-published BarTender catalog data. The catalog is read from\
> S3 (\`catalog.json\`, written by the daily sync cron) and cached in-process.\
> \
> Omit \`name\` to get unique published template names (sorted). Pass one or\
> more \`name\` values to get matching templates and lookup-cache field\
> mappings plus the catalog \`syncedAt\`.\
> \
> \`name\` accepts a comma-separated list or repeated query parameters.\
> Matching is case-sensitive and also treats pipe-separated tokens as\
> aliases (\`amazon | 133\` matches \`amazon\` or \`133\`). Unknown names return\
> empty \`templates\` and \`fieldMappings\` — not 404. \`limit\`, \`page\`, and\
> \`search\` are ignored.

```json
{"openapi":"3.2.0","info":{"title":"BarTender Templates","version":"1.0.0"},"tags":[{"name":"BarTender Templates","description":"Celigo-published BarTender (`.btw`) label templates synced daily from\nBarTender Cloud. List unique names, load selected template details and\nlookup-cache field mappings, or download a published `.btw`.\n\nRequires a standard integrator.io JWT with manage or monitor role, plus\nEDI and EDI label-printing entitlements on the account.\n\n## BarTender template schemas\n\n{% openapi-schemas spec=\"bartendertemplate\" schemas=\"BarTenderTemplateCatalog,BarTenderTemplate,BarTenderFieldMapping\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"BarTenderTemplateCatalog":{"type":"object","description":"Response from `GET /v1/bartenderTemplates`. When `name` is omitted the\nbody is `{ names }`. When `name` is provided the body is\n`{ syncedAt, templates, fieldMappings }` for the matching entries.","properties":{"names":{"type":"array","description":"Unique published template names, sorted. Present when `name` is\nomitted. An empty catalog returns `[]`.","items":{"type":"string"}},"syncedAt":{"type":"string","format":"date-time","description":"UTC timestamp of the last successful catalog sync. Present when\n`name` is provided."},"templates":{"type":"array","description":"Published templates whose `name` matches any requested `name` value.\nPresent when `name` is provided. Unknown names yield an empty array,\nnot a 404.","items":{"$ref":"#/components/schemas/BarTenderTemplate"}},"fieldMappings":{"type":"array","description":"Published lookup-cache mappings whose `key` matches any requested\n`name` value. Present when `name` is provided. A catalog that predates\nfield-mapping sync returns `[]`.","items":{"$ref":"#/components/schemas/BarTenderFieldMapping"}}},"if":{"required":["names"]},"then":{"required":["names"]},"else":{"required":["syncedAt","templates","fieldMappings"]}},"BarTenderTemplate":{"type":"object","description":"One published BarTender label template. Internal catalog fields (`id`,\n`btChecksum`, `modifiedDateTime`, `version`) are not exposed — only `name`\nand `s3Key` are returned.","required":["name","s3Key"],"properties":{"name":{"type":"string","description":"Published display name, derived from the `.btw` file stem\n(`amazon.btw` → `\"amazon\"`). Use this value in the `name` query\nparameter and in `GET /v1/bartenderTemplates/{name}/download`."},"s3Key":{"type":"string","description":"Object key for the `.btw` binary in the UI-resources bucket. Pass this\nto the downstream S3 export step that pushes the template to the\ncustomer's BarTender environment."}}},"BarTenderFieldMapping":{"type":"object","description":"One lookup-cache field mapping from the published catalog. Keys often\nname a template (or a pipe-separated alias such as `amazon | 133`);\nvalues keep whatever JSON shape the master cache stored.","required":["key","value"],"properties":{"key":{"type":"string","description":"Mapping key. Filtered with the same case-sensitive exact / pipe-token\nmatch as template `name` when `name` is supplied on the list route."},"value":{"description":"Mapping value from the master lookup cache. May be a string or an\nobject; consumers should check the runtime type before use.","oneOf":[{"title":"String value","type":"string"},{"title":"Object value","type":"object","additionalProperties":true}]}}},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/bartenderTemplates":{"get":{"operationId":"listBarTenderTemplates","tags":["BarTender Templates"],"summary":"List BarTender label templates","description":"Returns Celigo-published BarTender catalog data. The catalog is read from\nS3 (`catalog.json`, written by the daily sync cron) and cached in-process.\n\nOmit `name` to get unique published template names (sorted). Pass one or\nmore `name` values to get matching templates and lookup-cache field\nmappings plus the catalog `syncedAt`.\n\n`name` accepts a comma-separated list or repeated query parameters.\nMatching is case-sensitive and also treats pipe-separated tokens as\naliases (`amazon | 133` matches `amazon` or `133`). Unknown names return\nempty `templates` and `fieldMappings` — not 404. `limit`, `page`, and\n`search` are ignored.","parameters":[{"name":"name","in":"query","required":false,"description":"Filter to these published template names. Comma-separated or\nrepeated (`?name=amazon&name=walmart`). When omitted or empty, the\nresponse is `{ names }` only.","schema":{"type":"string"}}],"responses":{"200":{"description":"Unique names when `name` is omitted; filtered catalog details when\n`name` is provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BarTenderTemplateCatalog"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"description":"The global BarTender label-printing kill switch\n(`BARTENDER_LABEL_PRINTING_DISABLED`) is active. The route responds\nwith a bare `404` and an empty body so the feature appears unavailable."},"422":{"description":"The account lacks a required EDI entitlement. Missing `edi.enabled` or\n`edi.labelPrinting.enabled` both return the same\n`edi_subscription_required` error — the route reuses the standard EDI\nlicense gate used by other B2B Manager endpoints.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The catalog could not be read from S3 or the stored `catalog.json` is\nmalformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The catalog has never been published for this environment, or the\nEDI license check could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Download a BarTender label template

> Returns the published \`.btw\` binary for the named template.\
> \
> \`name\` must match a published catalog entry exactly — pipe-token alias\
> matching from the list route is not applied here. The file is streamed\
> as \`application/octet-stream\` with \`Content-Disposition: attachment\`.

```json
{"openapi":"3.2.0","info":{"title":"BarTender Templates","version":"1.0.0"},"tags":[{"name":"BarTender Templates","description":"Celigo-published BarTender (`.btw`) label templates synced daily from\nBarTender Cloud. List unique names, load selected template details and\nlookup-cache field mappings, or download a published `.btw`.\n\nRequires a standard integrator.io JWT with manage or monitor role, plus\nEDI and EDI label-printing entitlements on the account.\n\n## BarTender template schemas\n\n{% openapi-schemas spec=\"bartendertemplate\" schemas=\"BarTenderTemplateCatalog,BarTenderTemplate,BarTenderFieldMapping\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/bartenderTemplates/{name}/download":{"get":{"operationId":"downloadBarTenderTemplate","tags":["BarTender Templates"],"summary":"Download a BarTender label template","description":"Returns the published `.btw` binary for the named template.\n\n`name` must match a published catalog entry exactly — pipe-token alias\nmatching from the list route is not applied here. The file is streamed\nas `application/octet-stream` with `Content-Disposition: attachment`.","parameters":[{"name":"name","in":"path","required":true,"description":"Published template name from `GET /v1/bartenderTemplates`. Allowed\ncharacters are letters, digits, period, underscore, space, and\nhyphen; `..` is rejected.","schema":{"type":"string","pattern":"^[A-Za-z0-9._ -]+$"}}],"responses":{"200":{"description":"Published `.btw` binary.","headers":{"Content-Disposition":{"description":"Attachment filename taken from the template object's basename\n(the `.btw` file name).","schema":{"type":"string"}}},"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"`name` is empty or contains characters outside\n`[A-Za-z0-9._ -]`, or includes `..`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"description":"The template is not in the published catalog, or the global\nlabel-printing kill switch is active (bare `404`, empty body).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The account lacks a required EDI entitlement. Missing `edi.enabled` or\n`edi.labelPrinting.enabled` both return `edi_subscription_required`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The catalog could not be read, or the `.btw` object could not be\nfetched from S3.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The catalog has never been published for this environment, or the\nEDI license check could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```