Merchant Items API
Manage Items
Create standalone merchant items or add existing items to an invoice. Manage your product catalog with ease.
API Endpoints
POST
https://sofizpay.com/merchant/items/Create standalone items or add existing items to an invoice
PATCH
https://sofizpay.com/merchant/items/Update an existing item details, pricing, or availability
GET
https://sofizpay.com/merchant/items/Get merchant items with optional filtering and pagination
Select Method
All endpoints require Sofizpay authentication using encrypted_sk parameter
Request Parameters (POST)
| Parameter | Type | Required | Description |
|---|---|---|---|
encrypted_sk | string | Yes | Base64 encrypted Sofizpay secret key |
items | array | Yes | Array of items to create |
invoice_id | string | No | Invoice ID to add items to (optional) |
Example Request
cURL
bash
1curl -X POST "https://sofizpay.com/merchant/items/" \
2 -H "Content-Type: application/json" \
3 -d '{
4 "encrypted_sk": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0K...",
5 "items": [
6 {
7 "name": "Samsung Galaxy S24",
8 "description": "Latest Samsung smartphone with 128GB storage",
9 "unit_price": 850.00,
10 "category": "Electronics",
11 "sku": "SAM-S24-128"
12 },
13 {
14 "name": "Wireless Earbuds",
15 "description": "Premium noise-cancelling wireless earbuds",
16 "unit_price": 120.00,
17 "category": "Accessories",
18 "sku": "WE-PREM-001"
19 }
20 ]
21 }'Python
python
1import requests
2import json
3
4url = "https://sofizpay.com/merchant/items/"
5headers = {
6 "Content-Type": "application/json"
7}
8
9data = {
10 "encrypted_sk": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0K...",
11 "items": [
12 {
13 "name": "Samsung Galaxy S24",
14 "description": "Latest Samsung smartphone with 128GB storage",
15 "unit_price": 850.00,
16 "category": "Electronics",
17 "sku": "SAM-S24-128"
18 },
19 {
20 "name": "Wireless Earbuds",
21 "description": "Premium noise-cancelling wireless earbuds",
22 "unit_price": 120.00,
23 "category": "Accessories",
24 "sku": "WE-PREM-001"
25 }
26 ]
27}
28
29response = requests.post(url, headers=headers, json=data)
30result = response.json()
31print(result)JavaScript
javascript
1const url = "https://sofizpay.com/merchant/items/";
2const data = {
3 encrypted_sk: "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0K...",
4 items: [
5 {
6 name: "Samsung Galaxy S24",
7 description: "Latest Samsung smartphone with 128GB storage",
8 unit_price: 850.00,
9 category: "Electronics",
10 sku: "SAM-S24-128"
11 },
12 {
13 name: "Wireless Earbuds",
14 description: "Premium noise-cancelling wireless earbuds",
15 unit_price: 120.00,
16 category: "Accessories",
17 sku: "WE-PREM-001"
18 }
19 ]
20};
21
22fetch(url, {
23 method: 'POST',
24 headers: {
25 'Content-Type': 'application/json'
26 },
27 body: JSON.stringify(data)
28})
29.then(response => response.json())
30.then(result => console.log(result));Success Response (200)
Items created successfully with all details
json
1{
2 "success": true,
3 "message": "Items created successfully",
4 "items": [
5 {
6 "id": "item_001",
7 "name": "Samsung Galaxy S24",
8 "description": "Latest Samsung smartphone with 128GB storage",
9 "unit_price": 850.00,
10 "category": "Electronics",
11 "sku": "SAM-S24-128",
12 "active": true,
13 "created_at": "2025-08-03T10:00:00Z",
14 "updated_at": "2025-08-03T10:00:00Z"
15 },
16 {
17 "id": "item_002",
18 "name": "Wireless Earbuds",
19 "description": "Premium noise-cancelling wireless earbuds",
20 "unit_price": 120.00,
21 "category": "Accessories",
22 "sku": "WE-PREM-001",
23 "active": true,
24 "created_at": "2025-08-03T10:00:00Z",
25 "updated_at": "2025-08-03T10:00:00Z"
26 }
27 ]
28}Error Response (400/404)
Common error responses for authentication or validation failures
json
{
"error": "Invalid secret key"
}
// Or for validation errors:
{
"error": "Item with this SKU already exists for this merchant"
}
// Or for missing fields:
{
"error": "Missing encrypted_sk"
}Update Item Example (PATCH)
Update an existing item by changing its details, pricing, or availability status
json
1{
2 "encrypted_sk": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0K...",
3 "item_id": "item_001",
4 "name": "Samsung Galaxy S24 Ultra",
5 "description": "Latest Samsung smartphone with 256GB storage and S-Pen",
6 "unit_price": 950.00,
7 "category": "Electronics",
8 "active": true
9}
10
11// Response:
12{
13 "success": true,
14 "message": "Item updated successfully",
15 "item": {
16 "id": "item_001",
17 "name": "Samsung Galaxy S24 Ultra",
18 "description": "Latest Samsung smartphone with 256GB storage and S-Pen",
19 "unit_price": 950.00,
20 "category": "Electronics",
21 "sku": "SAM-S24-128",
22 "active": true,
23 "created_at": "2025-08-03T10:00:00Z",
24 "updated_at": "2025-08-03T11:15:00Z"
25 }
26}Security Note
Always keep your encrypted secret key secure. Use HTTPS for all API calls and validate all responses on your server.