> For the complete documentation index, see [llms.txt](https://docs.africanies.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.africanies.com/product-hs-code.md).

# Product HS Code

## Search products HS codes.

> This endpoint is the recommended way to find the correct HS code for what the customer is shipping.\
> \
> Recommended integration flow:\
> 1\. Add a searchable item input in your UI.\
> 2\. As the user types, call this endpoint with the typed value.\
> 3\. Use the response to populate a dropdown/autocomplete list.\
> 4\. Let the user select the best match and save the returned HS code.\
> 5\. Send that HS code in \`boxes.\*.items.\*.product\_hs\_code\` when creating/purchasing shipment.\
> \
> Important:\
> \- It is strongly advised to use HS codes returned by this API.\
> \- Submitting an HS code that is not recognized in our system will cause shipment validation to fail.\
> \- This is critical because global carriers (for example DHL) require valid HS codes for customs.

```json
{"openapi":"3.0.3","info":{"title":"AfricanIES - Sandbox API Documentation","version":"1.0.0"},"tags":[{"name":"Product HS Code","description":""}],"servers":[{"url":"https://api-sandbox.africaniestest.com"}],"security":[{"AfricaniesAuth":{}}],"components":{"securitySchemes":{"AfricaniesAuth":{"type":"apiKey","description":"Base64-encoded public_key:private_key value.","name":"Authorization","in":"header"}}},"paths":{"/api/v1/product/search/{value}":{"get":{"summary":"Search products HS codes.","operationId":"searchProductsHSCodes","description":"This endpoint is the recommended way to find the correct HS code for what the customer is shipping.\n\nRecommended integration flow:\n1. Add a searchable item input in your UI.\n2. As the user types, call this endpoint with the typed value.\n3. Use the response to populate a dropdown/autocomplete list.\n4. Let the user select the best match and save the returned HS code.\n5. Send that HS code in `boxes.*.items.*.product_hs_code` when creating/purchasing shipment.\n\nImportant:\n- It is strongly advised to use HS codes returned by this API.\n- Submitting an HS code that is not recognized in our system will cause shipment validation to fail.\n- This is critical because global carriers (for example DHL) require valid HS codes for customs.","parameters":[{"in":"header","name":"X-Shipment-Mode","description":"Required shipment mode. Use SFN for shipping from Nigeria or STN for shipping to Nigeria.","required":true,"schema":{"type":"string","enum":["SFN","STN"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"hs_code":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string","nullable":true}}}}}}}}},"500":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"array"}}}}}}},"tags":["Product HS Code"]}}}}
```

## Verify product.

> This endpoint verifies whether an HS code is valid and recognized in our system.\
> Use it when you need an explicit validation check before submitting shipment items.

```json
{"openapi":"3.0.3","info":{"title":"AfricanIES - Sandbox API Documentation","version":"1.0.0"},"tags":[{"name":"Product HS Code","description":""}],"servers":[{"url":"https://api-sandbox.africaniestest.com"}],"security":[{"AfricaniesAuth":{}}],"components":{"securitySchemes":{"AfricaniesAuth":{"type":"apiKey","description":"Base64-encoded public_key:private_key value.","name":"Authorization","in":"header"}},"schemas":{"ProductVerifyRequest":{"type":"object","properties":{"hs_code":{"type":"string","description":"The HS code of the product to verify."}},"required":["hs_code"]}}},"paths":{"/api/v1/product/verify":{"post":{"summary":"Verify product.","operationId":"verifyProduct","description":"This endpoint verifies whether an HS code is valid and recognized in our system.\nUse it when you need an explicit validation check before submitting shipment items.","parameters":[{"in":"header","name":"X-Shipment-Mode","description":"Required shipment mode. Use SFN for shipping from Nigeria or STN for shipping to Nigeria.","required":true,"schema":{"type":"string","enum":["SFN","STN"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","properties":{"hs_code":{"type":"string"},"valid":{"type":"boolean"},"description":{"type":"string"},"category":{"type":"string"}}}}}}}},"404":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"array"}}}}}},"500":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"array"}}}}}}},"tags":["Product HS Code"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductVerifyRequest"}}}}}}}}
```

## Get products and HS codes.

> This endpoint retrieves products and their HS code metadata used during shipment creation.\
> HS code selection is required for international shipping and customs processing.

```json
{"openapi":"3.0.3","info":{"title":"AfricanIES - Sandbox API Documentation","version":"1.0.0"},"tags":[{"name":"Product HS Code","description":""}],"servers":[{"url":"https://api-sandbox.africaniestest.com"}],"security":[{"AfricaniesAuth":{}}],"components":{"securitySchemes":{"AfricaniesAuth":{"type":"apiKey","description":"Base64-encoded public_key:private_key value.","name":"Authorization","in":"header"}}},"paths":{"/api/v1/product/{id}":{"get":{"summary":"Get products and HS codes.","operationId":"getProductsAndHSCodes","description":"This endpoint retrieves products and their HS code metadata used during shipment creation.\nHS code selection is required for international shipping and customs processing.","parameters":[{"in":"header","name":"X-Shipment-Mode","description":"Required shipment mode. Use SFN for shipping from Nigeria or STN for shipping to Nigeria.","required":true,"schema":{"type":"string","enum":["SFN","STN"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"hs_code":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string","nullable":true}}}}}}}}},"500":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"array"}}}}}}},"tags":["Product HS Code"]}}}}
```