Merchants API

The Merchants API allows you to interact with Cohort programmatically.

It is organized around REST. Our API has predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

The base URL for the API is https://api.getcohort.com

Authentication

The Cohort API uses API keys to authenticate requests. You can view and manage your API keys in the Settings > Integrations section of the Cohort Admin.

At the moment, API keys are not scoped and have full permissions.

Every call to the API requires to be authenticated by passing your API key in the authorization header: Authorization: Bearer <your-api-key>

A 401 HTTP error will be returned if the API key is not provided or invalid.

Do not share your API keys with anyone. Anyone with this API Key can use the Cohort API on your behalf. If you have any reason to believe it has been compromised, please send us an email and it can be deactivated or changed.

Test and Live modes

Cohort does not provide a dedicated staging / sandbox environment. Instead, every organization is provided with a Test and a Live merchant whose data are completely separated.

In the Cohort Admin, you can create different API keys for each mode.

Test mode API keys have the prefix test_ and live mode API keys have the prefix live_.

Errors

Cohort uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success.

For all errors that are due to invalid or unexpected input (a missing parameter, an invalid state, ..) the API will return a 417 status code with a code and message providing context about the error.

{
    "code": "generic.invalid-request", // The type of the error
    "message": "Parameter email not provided" // More context about the error
}

Codes in the 5xx range indicate an error with Cohort’s servers (these should not happen, feel free to reach out at [email protected] if you are encountering them).

API Reference

The full API Reference is available at https://api.getcohort.com/docs/merchants-api

Webhooks

Cohort offers Webhooks that you can subscribe to in order to get notified when specific events happen in Cohort.

Go to your Cohort Admin > Settings > Integrations and use your Webhooks Portal to register new Webhooks.

At the moment, there is no way to register new Webhooks programmatically.

The detail of all the Webhooks Events that can be subscribed to can be found here:

https://www.svix.com/event-types/eu/org_2Osm3gZeJWuhjTsaGO0Sz5C1RzZ/