Transactions - Usage Examples
Last Updated: 2026-07-08
Authentication
# Step 1: Obtain token
curl -s -X POST https://api.djanity.com/auth/login/ \
-H "Content-Type: application/json" \
-d '{"username": "[email protected]", "password": "..."}'
# Returns: {"access": "<jwt>", "refresh": "<jwt>"}
# Step 2: All subsequent requests use:
# -H "Authorization: Bearer <token>"
Sale Transactions
List transactions
Supports status and store query parameters.
curl -s "https://api.djanity.com/transactions/?status=completed&store=store-sanity-id-xyz789" \
-H "Authorization: Bearer <token>"
Response:
[
{
"transactionId": "saleTransaction_abc123",
"status": "completed",
"totalAmount": "43.18",
"store": "store-uuid-001",
"created_at": "2026-02-27T14:30:00Z"
}
]
Retrieve a transaction with line items
curl -s https://api.djanity.com/transactions/saleTransaction_abc123/ \
-H "Authorization: Bearer <token>"
Response:
{
"transactionId": "saleTransaction_abc123",
"status": "completed",
"subtotal": "39.98",
"taxAmount": "3.20",
"totalAmount": "43.18",
"totalPaid": "50.00",
"changeDue": "6.82",
"store": {
"id": "store-uuid-001",
"name": "London Flagship"
},
"lineItems": [
{
"id": "line-item-uuid-001",
"productVariantId": "variant-uuid-001",
"sku": "SKU-CLASSIC-TEE-M-BLK",
"quantity": 2,
"unitPrice": "19.99",
"subtotal": "39.98"
}
],
"created_at": "2026-02-27T14:30:00Z",
"completedAt": "2026-02-27T14:31:00Z"
}
Create a transaction with staff notes
The notes field stores internal staff annotations. It is optional, never null, and writable on POST/PUT/PATCH.
curl -s -X POST https://api.djanity.com/transactions/ \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"storeId": "store-uuid-001",
"notes": "Customer requested gift wrapping, check with manager"
}'
Response (201 Created):
{
"transactionId": "TXN-20260227-A1B2C3D4",
"status": "pending",
"subtotal": "0.00",
"taxAmount": "0.00",
"totalAmount": "0.00",
"notes": "Customer requested gift wrapping, check with manager",
"created_at": "2026-02-27T14:32:00Z"
}
Notes are returned in all GET responses and can be updated via PATCH:
curl -s -X PATCH https://api.djanity.com/transactions/TXN-20260227-A1B2C3D4/ \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"notes": "Gift wrap completed, blue ribbon"}'
Void a transaction
POST /transactions/{transactionId}/void/ marks the transaction voided, returns committed inventory, and issues gateway refunds for all succeeded payments synchronously.
Note: Response time is longer than other write operations because RefundService.process_refund() is called inline for each succeeded payment.
curl -s -X POST https://api.djanity.com/transactions/saleTransaction_abc123/void/ \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"reason": "Customer changed mind before order shipped"}'
Response (200 OK):
{
"transactionId": "saleTransaction_abc123",
"status": "voided",
"voidedAt": "2026-02-27T15:10:00Z",
"voidReason": "Customer changed mind before order shipped",
"totalAmount": "43.18",
"payment_records": [
{
"id": "payment-uuid-001",
"amount": "43.18",
"status": "voided",
"refunds": [
{
"refund_id": "REF-20260227-A1B2C3D4",
"amount": "43.18",
"status": "succeeded",
"processor_refund_id": "re_stripe_abc123",
"processed_at": "2026-02-27T15:10:01Z"
}
]
}
]
}
If the gateway refund fails, payment.status is still set to 'voided' (the finally block guarantees it). The refund record will have status: "failed". Manual reconciliation with the payment processor may be required. A failed gateway refund does not cause a non-200 response.
Returns
Create a return
curl -s -X POST https://api.djanity.com/returns/ \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"transaction": "saleTransaction_abc123",
"return_reason": "defective",
"notes": "Seam split on first wear",
"line_items": [
{
"original_line_item": "line-item-uuid-001",
"quantity": 1,
"reason": "defective"
}
]
}'
Response (201 Created):
{
"id": "return-uuid-001",
"return_number": "RET-2026-001",
"transaction": "saleTransaction_abc123",
"status": "pending",
"return_reason": "defective",
"refund_amount": "19.99",
"created_at": "2026-02-27T15:00:00Z"
}
List returns
curl -s https://api.djanity.com/returns/ \
-H "Authorization: Bearer <token>"
Sale Line Items
List line items for a transaction
curl -s "https://api.djanity.com/line-items/?transaction=saleTransaction_abc123" \
-H "Authorization: Bearer <token>"
Response:
[
{
"id": "line-item-uuid-001",
"transactionId": "saleTransaction_abc123",
"productVariantId": "variant-uuid-001",
"sku": "SKU-CLASSIC-TEE-M-BLK",
"quantity": 2,
"unitPrice": "19.99",
"subtotal": "39.98"
}
]
Fulfillment Tracking
List fulfillment records
curl -s https://api.djanity.com/fulfillments/ \
-H "Authorization: Bearer <token>"
Response:
[
{
"id": "fulfillment-uuid-001",
"transaction": "saleTransaction_abc123",
"fulfillment_type": "pickup",
"status": "ready_for_pickup",
"scheduled_date": "2026-02-28",
"notes": "Customer requested morning slot"
}
]
Retrieve a fulfillment
curl -s https://api.djanity.com/fulfillments/fulfillment-uuid-001/ \
-H "Authorization: Bearer <token>"
Filtering Transactions by Date Range
curl -s "https://api.djanity.com/transactions/?ordering=-created_at&status=completed" \
-H "Authorization: Bearer <token>"