# Merchants

## Get merchants

> Retrieves a list of merchants available for your partner account. Merchants can also be filtered based on metadata information, using query string keys \`meta.{key}={value}\`, such as \`?meta.iso\_id=2\`

```json
{"openapi":"3.0.3","info":{"title":"Partner Merchant API","version":"1.0"},"servers":[{"url":"https://partners.clym.io/api"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key generated in Clym Partner Portal."}},"schemas":{"Pagination":{"type":"object","description":"Pagination metadata","properties":{"current_page":{"type":"number"},"next_page":{"type":"number"},"prev_page":{"type":"number"}}},"Merchant":{"description":"A merchant object","type":"object","properties":{"id":{"type":"string","description":"The Clym internal ID of the resource"},"merchant_id":{"type":"string","description":"The external merchant ID"},"company_name":{"type":"string","description":"An optional company name attached to this merchant"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code"},"state":{"type":"string","description":"Country state/province/region"},"city":{"type":"string","description":"City"},"address":{"type":"string","description":"Address"},"postal_code":{"type":"string","description":"Postal code"},"iso_id":{"type":"string","description":"An ISO identifier"},"description":{"type":"string","description":"An optional description of the merchant"},"created_at":{"type":"string","format":"date-time"},"registered_at":{"type":"string","format":"date-time"},"partner_id":{"type":"string"},"product":{"type":"object","description":"The default product associated to this merchant","properties":{"id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}}},"price_list":{"type":"object","description":"The default price list associated to this merchant","properties":{"id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"}}},"addons":{"type":"array","description":"An optional array of add-on products associated with this merchant","items":{"type":"object","properties":{"id":{"type":"string"},"start_date":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"product":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"support_url":{"type":"string"}}}}}},"domain":{"type":"object","description":"Once registered, the domain information that has been tied to the merchant entity","properties":{"id":{"type":"string"},"hostname":{"type":"string"},"status":{"type":"string"},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"activated_at":{"type":"string","format":"date-time"},"email":{"type":"string","format":"email"},"source":{"type":"string"}}},"meta":{"type":"object","description":"An optional object containing previously-set metadata for a merchant."}}}}},"paths":{"/portal/merchants":{"get":{"summary":"Get merchants","description":"Retrieves a list of merchants available for your partner account. Merchants can also be filtered based on metadata information, using query string keys `meta.{key}={value}`, such as `?meta.iso_id=2`","parameters":[{"in":"query","name":"id","schema":{"type":"string"},"description":"Retrieve a specific merchant by ID or merchant_id"},{"in":"query","name":"ids","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true,"description":"Retrieve multiple merchants by their IDs"},{"in":"query","name":"merchant_id","schema":{"type":"string"},"description":"Filter by merchant ID (exact match)"},{"in":"query","name":"search","schema":{"type":"string"},"description":"Search by merchant_id or associated domain hostname"},{"in":"query","name":"is_registered","schema":{"type":"boolean"},"description":"Filter by whether a domain is linked to the merchant"},{"in":"query","name":"created_at_start","schema":{"type":"string","format":"date-time"},"description":"Filter merchants created after this date"},{"in":"query","name":"created_at_end","schema":{"type":"string","format":"date-time"},"description":"Filter merchants created before this date"},{"in":"query","name":"registered_at_start","schema":{"type":"string","format":"date-time"},"description":"Filter merchants registered after this date"},{"in":"query","name":"registered_at_end","schema":{"type":"string","format":"date-time"},"description":"Filter merchants registered before this date"},{"in":"query","name":"activated_at_start","schema":{"type":"string","format":"date-time"},"description":"Filter by domain activation date (after)"},{"in":"query","name":"activated_at_end","schema":{"type":"string","format":"date-time"},"description":"Filter by domain activation date (before)"},{"in":"query","name":"domain_status","schema":{"type":"string","enum":["NEW","SCANNED","INVITED","ACTIVE","INACTIVE"]},"description":"Filter by associated domain status"},{"in":"query","name":"domain_id","schema":{"type":"string"},"description":"Filter by domain ID"},{"in":"query","name":"domain_partner_id","schema":{"type":"string"},"description":"Filter by domain partner ID"},{"in":"query","name":"page","schema":{"type":"integer","minimum":1,"default":1},"description":"Page number"},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":10},"description":"Results per page"}],"responses":{"200":{"description":"An array with all partner merchants","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Pagination"},"result":{"type":"array","items":{"$ref":"#/components/schemas/Merchant"}}}}}}}}}}}}
```

## Create merchant

> Create a new merchant in your partner account

```json
{"openapi":"3.0.3","info":{"title":"Partner Merchant API","version":"1.0"},"servers":[{"url":"https://partners.clym.io/api"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key generated in Clym Partner Portal."}}},"paths":{"/portal/merchants":{"post":{"summary":"Create merchant","description":"Create a new merchant in your partner account","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"merchant_id":{"type":"string","maxLength":204,"description":"Your merchant id"},"company_name":{"type":"string","description":"The company name"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code"},"state":{"type":"string","description":"Country state/province/region"},"city":{"type":"string","description":"City"},"address":{"type":"string","description":"Address"},"postal_code":{"type":"string","description":"Postal code"},"description":{"type":"string","description":"An optional description for this merchant"},"iso_id":{"type":"string","description":"Optional ISO identifier"},"product":{"type":"string","description":"The default billing product code for this merchant. This will act as the default product for the domain associated with this merchant"},"price_list":{"type":"string","description":"The default billing price list code for this merchant. This will act as the default price list for the domain associated with this merchant"},"addons":{"type":"array","description":"An array of add-on products to be assigned to this merchant and the future domain associated with this merchant","items":{"type":"object","properties":{"addon":{"type":"string"},"start_date":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","description":"Optional key-value object containing merchant metadata"}},"required":["merchant_id"]}}}},"responses":{"200":{"description":"Merchant added to the partner account","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"object","properties":{"id":{"type":"string"},"merchant_id":{"type":"string"},"company_name":{"type":"string"},"meta":{"type":"object"},"created_at":{"type":"string","format":"date-time"}}}}}}}}}}}}}
```

## Get merchant

> Retrieve information about a single merchant

```json
{"openapi":"3.0.3","info":{"title":"Partner Merchant API","version":"1.0"},"servers":[{"url":"https://partners.clym.io/api"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key generated in Clym Partner Portal."}},"schemas":{"Merchant":{"description":"A merchant object","type":"object","properties":{"id":{"type":"string","description":"The Clym internal ID of the resource"},"merchant_id":{"type":"string","description":"The external merchant ID"},"company_name":{"type":"string","description":"An optional company name attached to this merchant"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code"},"state":{"type":"string","description":"Country state/province/region"},"city":{"type":"string","description":"City"},"address":{"type":"string","description":"Address"},"postal_code":{"type":"string","description":"Postal code"},"iso_id":{"type":"string","description":"An ISO identifier"},"description":{"type":"string","description":"An optional description of the merchant"},"created_at":{"type":"string","format":"date-time"},"registered_at":{"type":"string","format":"date-time"},"partner_id":{"type":"string"},"product":{"type":"object","description":"The default product associated to this merchant","properties":{"id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}}},"price_list":{"type":"object","description":"The default price list associated to this merchant","properties":{"id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"}}},"addons":{"type":"array","description":"An optional array of add-on products associated with this merchant","items":{"type":"object","properties":{"id":{"type":"string"},"start_date":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"product":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"support_url":{"type":"string"}}}}}},"domain":{"type":"object","description":"Once registered, the domain information that has been tied to the merchant entity","properties":{"id":{"type":"string"},"hostname":{"type":"string"},"status":{"type":"string"},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"activated_at":{"type":"string","format":"date-time"},"email":{"type":"string","format":"email"},"source":{"type":"string"}}},"meta":{"type":"object","description":"An optional object containing previously-set metadata for a merchant."}}}}},"paths":{"/portal/merchants/{merchantId}":{"get":{"summary":"Get merchant","description":"Retrieve information about a single merchant","parameters":[{"name":"merchantId","in":"path","description":"Merchant id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The partner domain information","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"$ref":"#/components/schemas/Merchant"}}}}}}}}}}}
```

## Update merchant

> Update information about a merchant

```json
{"openapi":"3.0.3","info":{"title":"Partner Merchant API","version":"1.0"},"servers":[{"url":"https://partners.clym.io/api"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key generated in Clym Partner Portal."}},"schemas":{"Merchant":{"description":"A merchant object","type":"object","properties":{"id":{"type":"string","description":"The Clym internal ID of the resource"},"merchant_id":{"type":"string","description":"The external merchant ID"},"company_name":{"type":"string","description":"An optional company name attached to this merchant"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code"},"state":{"type":"string","description":"Country state/province/region"},"city":{"type":"string","description":"City"},"address":{"type":"string","description":"Address"},"postal_code":{"type":"string","description":"Postal code"},"iso_id":{"type":"string","description":"An ISO identifier"},"description":{"type":"string","description":"An optional description of the merchant"},"created_at":{"type":"string","format":"date-time"},"registered_at":{"type":"string","format":"date-time"},"partner_id":{"type":"string"},"product":{"type":"object","description":"The default product associated to this merchant","properties":{"id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}}},"price_list":{"type":"object","description":"The default price list associated to this merchant","properties":{"id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"}}},"addons":{"type":"array","description":"An optional array of add-on products associated with this merchant","items":{"type":"object","properties":{"id":{"type":"string"},"start_date":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"product":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"support_url":{"type":"string"}}}}}},"domain":{"type":"object","description":"Once registered, the domain information that has been tied to the merchant entity","properties":{"id":{"type":"string"},"hostname":{"type":"string"},"status":{"type":"string"},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"activated_at":{"type":"string","format":"date-time"},"email":{"type":"string","format":"email"},"source":{"type":"string"}}},"meta":{"type":"object","description":"An optional object containing previously-set metadata for a merchant."}}}}},"paths":{"/portal/merchants/{merchantId}":{"put":{"summary":"Update merchant","description":"Update information about a merchant","parameters":[{"name":"merchantId","in":"path","description":"Merchant id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"merchant_id":{"type":"string","description":"The new merchant id to use"},"company_name":{"type":"string","description":"The company legal name to use"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code"},"state":{"type":"string","description":"Country state/province/region"},"city":{"type":"string","description":"City"},"address":{"type":"string","description":"Address"},"postal_code":{"type":"string","description":"Postal code"},"description":{"type":"string","description":"Optional merchant description"},"meta":{"type":"object","description":"Optional key-value object containing merchant metadata"},"domain_id":{"type":"string","nullable":true,"description":"The domain id to attach to this merchant. If set to null, it will unassign the domain from the merchant."},"domain_partner_id":{"type":"string","nullable":true,"description":"If set, it will assign the specified domain partner to the merchant"},"iso_id":{"type":"string","nullable":true,"description":"Optional ISO identifier"},"product":{"type":"string","description":"The default billing product code for this merchant. This will act as the default product for the domain associated with this merchant"},"price_list":{"type":"string","description":"The default billing price list code for this merchant. This will act as the default price list for the domain associated with this merchant"},"addons":{"type":"array","description":"An array of add-on products to be assigned to this merchant and the future domain associated with this merchant","items":{"type":"object","properties":{"addon":{"type":"string"},"start_date":{"type":"string","format":"date-time"}}}}}}}}},"responses":{"200":{"description":"Acknowledgement that request was successful.","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"$ref":"#/components/schemas/Merchant"}}}}}}}}}}}
```

## Delete merchant

> Completely delete the merchant and associated domain (if any) from your partner account

```json
{"openapi":"3.0.3","info":{"title":"Partner Merchant API","version":"1.0"},"servers":[{"url":"https://partners.clym.io/api"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key generated in Clym Partner Portal."}}},"paths":{"/portal/merchants/{merchantId}":{"delete":{"summary":"Delete merchant","description":"Completely delete the merchant and associated domain (if any) from your partner account","parameters":[{"name":"merchantId","in":"path","description":"Merchant id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Merchant deletion confirmation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"object","properties":{"deleted":{"type":"boolean"}}}}}}}}}}}}}
```

## Bulk create merchants

> Create up to 200 merchants in bulk with a single API call. If product, price list and addons is specified in the root body (outside merchants), they will act as default data for all items in the merchants\[] array

```json
{"openapi":"3.0.3","info":{"title":"Partner Merchant API","version":"1.0"},"servers":[{"url":"https://partners.clym.io/api"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key generated in Clym Partner Portal."}},"schemas":{"Error":{"description":"An error object","type":"object","properties":{"code":{"type":"string","description":"An error code"},"ns":{"type":"string","description":"An error namespace"},"message":{"type":"string","description":"Additional error message information"},"status":{"type":"number"},"data":{"type":"object"}}}}},"paths":{"/portal/merchants/bulk/create":{"post":{"summary":"Bulk create merchants","description":"Create up to 200 merchants in bulk with a single API call. If product, price list and addons is specified in the root body (outside merchants), they will act as default data for all items in the merchants[] array","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"merchants":{"type":"array","items":{"anyOf":[{"type":"string","description":"Merchant id"},{"type":"object","properties":{"merchant_id":{"type":"string","description":"Merchant id"},"company_name":{"type":"string","description":"Company name"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code"},"state":{"type":"string","description":"Country state/province/region"},"city":{"type":"string","description":"City"},"address":{"type":"string","description":"Address"},"postal_code":{"type":"string","description":"Postal code"},"iso_id":{"type":"string","description":"An ISO identifier"},"description":{"type":"string","description":"Additional merchant description"},"product":{"type":"string","description":"The default billing product code for this merchant. This will act as the default product for the domain associated with this merchant"},"price_list":{"type":"string","description":"The default billing price list code for this merchant. This will act as the default price list for the domain associated with this merchant"},"addons":{"type":"array","description":"An array of add-on products to be assigned to this merchant and the future domain associated with this merchant","items":{"type":"object","properties":{"addon":{"type":"string"},"start_date":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","description":"Optional key-value object containing merchant metadata"}},"required":["merchant_id"]}]}},"product":{"type":"string","description":"The default billing product code for this merchant. This will act as the default product for the domain associated with this merchant"},"price_list":{"type":"string","description":"The default billing price list code for this merchant. This will act as the default price list for the domain associated with this merchant"},"addons":{"type":"array","description":"An array of add-on products to be assigned to this merchant and the future domain associated with this merchant","items":{"type":"object","properties":{"addon":{"type":"string"},"start_date":{"type":"string","format":"date-time"}}}}},"required":["merchants"]}}}},"responses":{"200":{"description":"Acknowledgement that request was successful.","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"object","properties":{"created":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"merchant_id":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}},"failed":{"type":"array","items":{"type":"object","properties":{"merchant_id":{"type":"string"},"error":{"$ref":"#/components/schemas/Error"}}}}}}}}}}}}}}}}
```

## Bulk delete merchants

> Delete up to 200 merchants in bulk with a single API call

```json
{"openapi":"3.0.3","info":{"title":"Partner Merchant API","version":"1.0"},"servers":[{"url":"https://partners.clym.io/api"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key generated in Clym Partner Portal."}},"schemas":{"Error":{"description":"An error object","type":"object","properties":{"code":{"type":"string","description":"An error code"},"ns":{"type":"string","description":"An error namespace"},"message":{"type":"string","description":"Additional error message information"},"status":{"type":"number"},"data":{"type":"object"}}}}},"paths":{"/portal/merchants/bulk/delete":{"post":{"summary":"Bulk delete merchants","description":"Delete up to 200 merchants in bulk with a single API call","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"merchants":{"type":"array","items":{"type":"string","description":"Merchant id"}}},"required":["merchants"]}}}},"responses":{"200":{"description":"Acknowledgement that request was successful.","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"object","properties":{"deleted":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"merchant_id":{"type":"string"}}}},"failed":{"type":"array","items":{"type":"object","properties":{"merchant_id":{"type":"string"},"error":{"$ref":"#/components/schemas/Error"}}}}}}}}}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clym.io/api-reference/merchants.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.