> ## Documentation Index > Fetch the complete documentation index at: https://docs.eximpe.com/llms.txt > Use this file to discover all available pages before exploring further. # Search HS Codes > Find the HS codes a goods sub-merchant can declare, by code or description. ## Overview A sub-merchant with a goods category must declare at least one HS code in `global_company.hs_codes`, and each code must be one EximPe recognises. This endpoint searches that list by code or by description. Send the `value` of each code you pick in `hs_codes` on [Create Merchant](https://docs.eximpe.com/api-reference/v3/merchant/create.md) or [Update Merchant](https://docs.eximpe.com/api-reference/v3/merchant/update.md). ## Query Parameters | Name | Type | Required | Description | | - | - | - | - | | search | string | No | Text to match against the code and its description, e.g. `8471` or `laptop`. Leave it out to page through every code. | | page | integer | No | Page number. Default `1`. | | page\_size | integer | No | Results per page. Default `250`, maximum `1000`. | ## Response `data` is a page, with the same paging fields as [List Merchants](https://docs.eximpe.com/api-reference/v3/merchant/list.md#response). Each result is one HS code: | Name | Type | Description | | - | - | - | | id | integer | EximPe's ID for the code. | | value | string | The HS code. Send this in `hs_codes`. | | description | string | What the code covers. | | policy | string | The import policy that applies to the code. Empty when none is recorded. | ```json 200 OK theme={null} { "success": true, "message": "HS codes retrieved successfully", "data": { "count": 2, "page": 1, "page_size": 250, "next": null, "previous": null, "results": [ { "id": 10421, "value": "84713010", "description": "Personal computer, portable, laptop", "policy": "Free" }, { "id": 10422, "value": "84713090", "description": "Other portable automatic data processing machines", "policy": "Free" } ] } } ``` ## Errors | Status | `error.code` | When | `details` | | - | - | - | - | | `401` | `ERR_AUTH_000`, `ERR_AUTH_001` | `X-Client-ID` or `X-Client-Secret` is missing or wrong | `{"authentication": "Missing credentials."}` or `{"authentication": "Invalid credentials."}` | | `403` | `ERR_AUTH_003` | Your account is not a PSP | `{}`. Only PSPs can manage sub-merchants | | `403` | `ERR_MERCHANT_017` | Your account is a PSP, but not set up for import collections | `{}`. Contact EximPe | ## OpenAPI ````yaml openapi/v3-partner-merchants.json GET /partners/merchants/hs-codes/ openapi: 3.0.0 info: title: EximPe Payment Gateway API — v3 Partner Merchants version: 3.0.0 description: Create and manage sub-merchants on the v3 partner API. servers: - url: https://api-pacb-uat.eximpe.com description: Payment Gateway Sandbox URL security: - clientAuth: [] clientSecretAuth: [] apiVersionHeader: [] tags: - name: Merchants paths: /partners/merchants/hs-codes/: get: tags: - Merchants summary: Search HS Codes description: >- Find the HS codes a goods sub-merchant can declare, by code or description. operationId: v3_searchHsCodes parameters: - name: search in: query required: false description: Text to match against the code and its description. schema: type: string - name: page in: query required: false description: Page number. Default `1`. schema: type: integer default: 1 - name: page_size in: query required: false description: Results per page. Default `250`, maximum `1000`. schema: type: integer default: 250 maximum: 1000 responses: '200': description: A page of HS codes. content: application/json: schema: $ref: '#/components/schemas/v3_HSCodeSearchResponse' example: success: true message: HS codes retrieved successfully data: count: 1 page: 1 page_size: 250 next: null previous: null results: - id: 10421 value: '84713010' description: Personal computer, portable, laptop policy: Free '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/v3_ErrorResponse' example: success: false error: code: ERR_AUTH_000 message: Missing credentials details: authentication: Missing credentials. '403': description: >- Your account is not a PSP (`ERR_AUTH_003`), or is a PSP not set up for import collections (`ERR_MERCHANT_017`). content: application/json: schema: $ref: '#/components/schemas/v3_ErrorResponse' example: success: false error: code: ERR_MERCHANT_017 message: >- Sub-Merchant endpoints are only available to IMPORT PSP accounts details: {} security: - clientAuth: [] clientSecretAuth: [] apiVersionHeader: [] components: schemas: v3_HSCodeSearchResponse: type: object required: - success - message - data properties: success: type: boolean message: type: string data: type: object properties: count: type: integer page: type: integer page_size: type: integer next: type: string nullable: true previous: type: string nullable: true results: type: array items: $ref: '#/components/schemas/v3_HSCode' v3_ErrorResponse: type: object required: - success - error properties: success: type: boolean enum: - false description: >- Indicates if the request was successful. Always false for error responses. error: $ref: '#/components/schemas/v3_ErrorDetails' v3_HSCode: type: object properties: id: type: integer value: type: string description: The HS code. Send this in `hs_codes`. description: type: string description: What the code covers. policy: type: string description: >- The import policy that applies to the code. Empty when none is recorded. v3_ErrorDetails: type: object required: - code - message properties: code: type: string description: Error code (e.g., ERR_ORDER_002) message: type: string description: Error message details: description: >- More about the error. An object keyed by field name when fields fail validation, with nested objects for nested fields; a string when the error is about the request as a whole; or an empty object when there is nothing to add. oneOf: - type: object additionalProperties: true - type: string securitySchemes: clientAuth: type: apiKey name: X-Client-ID in: header description: >- **Client Application ID** - Your unique application identifier used to authenticate API requests. You can find your Client ID in the Developer Settings section of the merchant dashboard. x-displayName: Client ID x-example: your-client-id clientSecretAuth: type: apiKey name: X-Client-Secret in: header description: >- **Client Secret Key** - Your secret key used alongside the Client ID for secure authentication. Keep this confidential and never expose it in client-side code. Available in the Developer Settings section of the merchant dashboard. x-displayName: Client Secret x-example: your-client-secret apiVersionHeader: type: apiKey name: X-API-Version in: header description: >- **API Version** - Specifies which version of the API to use (e.g., '1.X.X', '2.X.X', or '3.X.X'). This header allows you to control which API version your integration uses. Default version information is available in the Developer Settings. x-displayName: API Version x-example: 3.0.0 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.