Delete retail invoice

Permanently delete a retail invoice and its associated data.

DELETE /v1/invoices/retail/{invoice_id}

cURL

curl --request DELETE \
  --url https://api.paypulse.io/v1/invoices/retail/inv_abc123 \
  --header 'Authorization: Bearer <token>'

200

{
  "message": "Invoice deleted successfully",
  "code": 200,
  "data": {
    "deleted_invoice": {
      "invoice_id": "inv_abc123",
      "vendor_name": "Domino's Pizza",
      "sub_type": "food-delivery",
      "invoice_date": "2025-03-10",
      "total_amount": 149,
      "currency": "SEK"
    }
  }
}

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invoice not found or you don't have permission to delete it"
  }
}

{
  "error": {
    "code": "DEPENDENCY_FAILURE",
    "message": "Error deleting invoice file from S3"
  }
}

This action is irreversible. The invoice record, its parsed details, and the source HTML file in S3 are all permanently deleted.

Authentication

All requests to this endpoint must include a valid JWT in the Authorization header.

Authorization: Bearer <token>

Path parameters

invoice_id · string · required

The unique identifier of the retail invoice to delete.

What gets deleted

Deleting a retail invoice removes the following:

• The invoice record from the RetailInvoices DynamoDB table.
• The invoice’s parsed detail record from the corresponding category detail table (e.g., FoodDeliveryInvoices, ClothingInvoices, TechnologyInvoices, SubscriptionInvoices, GroceryInvoices, MiscUtilityInvoices, MiscInvoices, TravelInvoices).
• The raw HTML invoice file from S3.

Ownership is validated before deletion — you can only delete invoices that belong to the authenticated user.

Response

message · string

A human-readable confirmation message. Example: "Invoice deleted successfully"

code · number

HTTP status code. 200 on success.

data · object

Hide properties

deleted_invoice · object

Metadata of the deleted invoice.

Hide properties

invoice_id · string

The ID of the deleted invoice.

vendor_name · string

The name of the vendor associated with the invoice.

sub_type · string

The category of the retail invoice. One of: food-delivery, clothing, technology, subscriptions, grocery, utility, miscellaneous, travel.

invoice_date · string

The date of the invoice.

total_amount · number

The total amount of the invoice.

currency · string

The currency of the invoice amount. Defaults to "SEK" if not set.

Error responses

Status	Error code	Description
400	MISSING_FIELDS	The invoice_id path parameter is absent.
401	INVALID_CREDENTIALS	The Authorization header is missing or the token is invalid.
401	TOKEN_EXPIRED	The JWT has expired.
404	INVALID_REQUEST	No invoice found for the given invoice_id, or the invoice belongs to a different user.
502	DEPENDENCY_FAILURE	A downstream dependency (DynamoDB or S3) returned an error during deletion.
500	INTERNAL_SERVER_ERROR	An unexpected server-side error occurred.

Error responses follow this structure:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invoice not found or you don't have permission to delete it"
  }
}

cURL

curl --request DELETE \
  --url https://api.paypulse.io/v1/invoices/retail/inv_abc123 \
  --header 'Authorization: Bearer <token>'

200

{
  "message": "Invoice deleted successfully",
  "code": 200,
  "data": {
    "deleted_invoice": {
      "invoice_id": "inv_abc123",
      "vendor_name": "Domino's Pizza",
      "sub_type": "food-delivery",
      "invoice_date": "2025-03-10",
      "total_amount": 149,
      "currency": "SEK"
    }
  }
}

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invoice not found or you don't have permission to delete it"
  }
}

{
  "error": {
    "code": "DEPENDENCY_FAILURE",
    "message": "Error deleting invoice file from S3"
  }
}