Catalog connectors — ClearTax GSP, HubSpot, Shopify, Zendesk

Catalog connectors are the four ready-made partner connections — ClearTax GSP (e-Invoice & e-Way Bill), HubSpot CRM, Shopify Admin and Zendesk Support — that you pick from the connector list instead of hand-building HTTP calls. You configure one as a connection inside an integration app, test it, and then use it in a flow step that reads from or writes to the partner. The flow decides what to do with the data; the connector only knows how to talk to that one partner.

Overview

Each catalog connector is a reviewed description of one partner's API that ships with the platform: where its host is, how it authenticates, which address a read and a write go to, and where the records sit in the partner's answer. To an administrator it looks exactly like any other connector — the same New Connection dialog, a typed form generated from the connector's declaration, secret fields that hold a ${secret:…} reference, and the same retry and timeout handling. How the tier is built is described in Connector authoring; this page is the operator manual for the four connectors that ship.

What none of them do: OAuth sign-in flows, bulk writes, multi-page reads, updates or deletes. Every write sends one POST to the partner's collection address, which the partner treats as "create". If you need any of those, use the HTTP REST connector or one of the built-in families (Salesforce, Zoho, Tally).

When to use it

• You want orders from a Shopify store, tickets from Zendesk, or HubSpot contacts, companies or deals pulled into xMatix on a schedule.
• You want an xMatix event to create a ticket in Zendesk, a deal or contact in HubSpot, or an order in Shopify.
• You file GST e-invoices through ClearTax and need a transport for the e-invoice payload xMatix prepares.

Use the HTTP REST connector instead when you need paging, an update call, form-encoded bodies, or values from an earlier flow step in the request.

How xMatix handles it

• Connection and step settings merge. A flow step can override any connection setting for that step only — for example, one HubSpot connection with Object type Contacts, and one step that reads Deals.
• Secrets are fetched only when referenced. When a step runs, xMatix looks for ${secret:…} references in the connection and step settings and fetches each one. If any cannot be found, the step fails before anything is sent to the partner.
• Reads hand over the records, not the envelope. Each connector knows where the partner puts its records (results for HubSpot, orders for Shopify, tickets for Zendesk, data for ClearTax). When that is found, the next step receives just the list. When it is not — usually because the partner answered with an error — the next step receives { status, ok, body } so you can see what came back.
• One page per read. A read sends the configured page size and returns that first page. Paging links in the partner's answer are ignored.
• Writes return the partner's answer as { status, ok, body }, including when the partner refuses the request. A write is never retried automatically, so a timeout cannot create a duplicate.
• Test Connection only probes reachability. It calls one address with the connection's own settings and counts any HTTP status below 500 as a pass. A wrong token gives a green result with HTTP 401 or 403 in the message.

Prerequisites

• Access to Setup → Platform → Integrations, and the Connection Manager or Admin role on the integration app you will use (see Permissions).
• An integration app to hold the connection. Create one on the Integrations page if you have none.
• The partner credential, issued by the partner: a HubSpot private-app access token, a Shopify Admin API access token, a Zendesk API token plus the agent email it belongs to, or your ClearTax auth token, owner id and GSTIN.
• For writes, a flow whose transform step produces the record in the partner's own field names.

Procedure

Step 1 — Store the credential as a secret

Open Setup → Platform → Integrations, open the integration app and go to Secrets. Select Add Secret, enter a Reference (letters, digits and . _ - : only, for example hubspot-token) and paste the Value. Save. The list shows the reference, key id and dates, never the value. See Credentials and rotation.

For ClearTax GSP, the reference must be exactly cleartax_auth_token. That connector reads the secret by this fixed name, so a token stored under any other reference is never sent to ClearTax.

Step 2 — Create the connection

Go to the app's Connections tab and select New Connection. Enter a Name (for example "Shopify — main store"), leave Active on, and choose the Connector Type. The description of the connector and its Testable badge appear under the picker, and the Configuration box shows the connector's form. Fill in the fields listed for your connector under Fields. In each secret field, pick or type the reference, for example ${secret:hubspot-token}. Do not paste the token itself into the form.

Step 3 — Save and test

Select Create to save. Test Connection works only on a saved connection, so reopen it with Edit and select Test Connection (after later changes, the button that saves is Save). A pass reads "Connection OK" with "Reached address (HTTP status)"; a fail reads "Test failed" with "address returned HTTP status" or the network error.

Read the status, not just the colour. HTTP 200 means the partner accepted the credential. HTTP 401 or 403 is shown as Connection OK but means the token, its scopes or the account are wrong. HTTP 404 usually means the shop name, subdomain or host is wrong.

Step 4 — Read from the partner in a flow

Open Flows, add a connector-read step and choose the connection. To change a setting for this step only — a different HubSpot Object type, a different Shopify Order status filter — set the same key in the step's settings. Add a transform step to map the partner's fields to xMatix fields, then a sink step to write the records. Run the flow once and check the run on Overview (Recent Runs) or Errors. A flow preview does not call the partner, so only a real run proves the connection.

Step 5 — Write to the partner in a flow

Add a connector-write step after the step that builds the record. The connector wraps your record the way the partner expects — you supply only the record itself:

Check the write step's output: ok is true for a 2xx answer, and body carries the partner's reply (for example, the new record's id, or its validation errors).

Step 6 — Retire or rotate

To stop all traffic through a connection, edit it and switch Active off — every step that uses it then fails with a message that the connection is inactive. To change a credential, use Rotate on the Secrets tab; the connection and flows need no edit. To remove a connection for good, use Delete in the Connections list after you have moved its flows to another connection.

Fields

ClearTax GSP (e-Invoice & e-Way Bill)

A read needs the IRN in the step input as a field named irn; without it the status request goes out with no IRN. Although the name mentions e-way bills, this connector has no e-way-bill operation.

HubSpot CRM

Shopify Admin

Zendesk Support

Every connector also accepts the Raw JSON switch in the Configuration box. It shows the same settings as JSON; keep secrets out of it and use ${secret:…} references there too.

Business rules

• Required fields are checked by the form when you save. Nothing checks that the values are right until the partner answers.
• Empty query values are left out. If a page size or status filter is blank, the parameter is simply not sent and the partner's default applies.
• Records are not paged. Only the first page of a read arrives in each run.
• Retries: reads are retried on transient failures; writes (POST) are never retried. A partner that answers 429 (rate limited) does not trip the connection's circuit breaker.
• Step settings win over connection settings key by key, for that step only.
• An inactive connection fails every step that uses it. A missing secret fails the step before the call; Test Connection does not catch this, because it sends an empty value instead.

Example

An online store sells through Shopify and wants each day's orders in xMatix.

1. The administrator stores the store's Admin API token on Secrets with Reference shopify-main-token.
2. They create a connection "Shopify — main store" of type Shopify Admin: Shop example-store, API version 2024-01, Admin API access token ${secret:shopify-main-token}, Order status filter Open, Page size 50.
3. Test Connection reports "Reached https://example-store.myshopify.com/admin/api/2024-01/shop.json (HTTP 200)".
4. A scheduled flow runs every hour. Its connector-read step asks Shopify for open orders, 50 at a time, and receives the list of orders. A transform step maps the order number, customer email and line items to xMatix fields, and a sink step writes the sales orders.
5. On a busy day 80 orders arrive in one hour, but each run brings in only one page of 50. The administrator raises the page size and moves the schedule to every 15 minutes so every run's page covers the new orders.

Training

Practice exercise

In a sandbox integration app, create a Zendesk Support connection with your trainer's subdomain and agent email, and an API token that points at a secret holding a deliberately wrong token. Select Test Connection. Expected result: "Connection OK" with HTTP 401 — the address is reachable but the token is refused. Now rotate the secret to the real token and test again: HTTP 200. Finally, build a flow with one connector-read step on this connection and run it; the run output is a list of tickets, at most Page size long.

Quick reference

• Setup → Platform → Integrations → app → Connections → New Connection.
• Store tokens on Secrets; put ${secret:reference} in the form, never the token.
• ClearTax's secret reference must be exactly cleartax_auth_token.
• Test Connection works on a saved connection only and passes on anything below HTTP 500 — read the status.
• One read = one page; writes always create a new record.
• Step settings override the connection for that step.
• ClearTax reads need irn in the step input; there is no e-way-bill operation.
• Inactive connection or missing secret = the step fails before calling the partner.

Permissions

Integrations is opened from Setup → Platform → Integrations by users whose profile has the integration administration capability. Inside an app, what you can do depends on your role on that app's Members tab:

A user without a role on the app sees "You don't have access to this integration app". Nobody in an organization can add or change a catalog connector's definition; it ships with the platform.

Configuration

For ClearTax, plan one connection per GSTIN: each GSTIN files separately, with its own owner id and token.

Common problems

Test Connection is green, but every run fails with 401 or 403

The test counts any status below 500 as reachable. Check the status in the result. Rotate the secret to a valid token, or give the partner's app or token the scopes it needs for the records you read and write.

Test Connection shows HTTP 404

The address is wrong: the Shopify Shop name, the Zendesk Subdomain or the ClearTax GSP host. Enter only the name or host, without https:// or a trailing path. For Shopify, also check that the API version is still supported.

ClearTax rejects every call as unauthorised, though the token is right

The token is stored under a reference other than cleartax_auth_token, so it is never sent. Add the secret again under that exact reference and set ClearTax auth token to ${secret:cleartax_auth_token}.

The step fails with "references secret(s) that could not be resolved"

A reference in the connection or step has no stored value in this app, or the stored value can no longer be read. Re-enter it on Secrets under exactly the referenced name.

The step fails with "references connection … which is inactive"

Someone switched Active off. Turn it back on, or point the step at another connection.

The read gives { status, ok, body } instead of a list of records

The partner answered with something other than its usual list — usually an error. Read status and body: 401/403 is the credential, 404 the address, 429 the partner's rate limit.

Only some records arrive

Each read returns one page. Raise Page size within the partner's limit and run the flow more often, or use the HTTP REST connector with paging for a full pull. For a large one-off backfill, use a data import.

A write creates duplicates instead of updating

Catalog writes always create. To update existing partner records, use the HTTP REST connector with the partner's update address.

Common questions

How is a catalog connector different from HTTP REST?

HTTP REST is a blank connector: you type the address, headers and request shape on every connection or step, and in return you get paging, any HTTP method and values from earlier steps. A catalog connector packages one partner's host, sign-in, request shape and record location behind a short typed form, so you configure "Zendesk" rather than "an HTTP call". Both use the same secret handling, retries and circuit breaker. Pick the catalog connector when its read and create operations are enough; pick HTTP REST as soon as you need updates, paging or a request built from earlier steps.

Can a catalog connector drive a sync profile?

No. Sync profiles, with their change detection, conflict handling and record ledger, need a sync provider — Salesforce, Zoho Books, Zoho Payroll, Zoho People or Tally. Catalog connectors are used in flows you build yourself: scheduled pulls, event-driven pushes and staged imports. That means deciding what counts as new or changed is up to your flow, for example by filtering on order status or by keeping the partner's id on the xMatix record.

Is the ClearTax connector all we need for e-invoicing?

It is the transport. On an invoice, the E Invoice Generator action builds the e-invoice payload, stores it in Payload (eInvoice) and sets Status (eInvoice) to Pending. Sending that payload through this connector is a flow you configure, and writing ClearTax's answer — the Invoice Reference Number (eInvoice) and QR code — back onto the invoice is also a flow step; nothing does it automatically. Your ClearTax onboarding (owner id, GSTIN registration, token) comes first. See E-invoicing.

We use a partner that is not listed. What are our options?

If it is a JSON-over-HTTPS API with header-based sign-in, the HTTP REST connector reaches it today; you write the request shapes in your flow steps. Catalog connectors cannot be added or edited by an organization, because each one is reviewed and shipped with the platform. If you would like a partner packaged as a catalog connector, ask your xMatix contact.

Related topics

• Connector authoring — how catalog connectors are defined, every token and limit
• Connect an external system
• Outbound integration
• Credentials and rotation
• Sync health, conflicts and failed runs
• Troubleshooting integrations
• Integrations overview