Skip to content
/
Soft Deletes
Last updated

Soft Deletes

MVMNT uses soft deletes for all resources. A DELETE doesn’t remove a record from the database—it sets deletedAt (and updates updatedAt). Most list endpoints hide soft-deleted records by default, so your integration should treat de letedAt as the source of truth.

What Are Soft Deletes?

A soft delete marks a record as deleted without physically deleting it. The record still exists and can be returned by the API, but it’s excluded from list results unless you explicitly request deleted records.

The deletedAt Field

Every entity in the MVMNT API includes a deletedAt field:

FieldTypeDescription
deletedAtISO 8601 datetime | nullTimestamp when entity was soft-deleted, or null if active

Active Entity

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "friendlyId": "ORD-12345",
  "key": "ERP-ORDER-789",
  "status": "delivered",
  "deletedAt": null,
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-20T14:00:00Z"
}

Soft-Deleted Entity

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "friendlyId": "ORD-12345",
  "key": "ERP-ORDER-789",
  "status": "delivered",
  "deletedAt": "2025-01-20T15:30:00Z",
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-20T15:30:00Z"
}

How Soft Deletes Work

Deleting an Entity

Use the standard DELETE request:

curl -X DELETE https://api.mvmnt.io/v1/orders/ORD-12345 \
  -H "Authorization: Bearer $TOKEN"

Response: 200 OK

What happens:

  1. deletedAt is set to the current timestamp
  2. updatedAt is also updated to the current timestamp
  3. Entity remains in database
  4. Entity is filtered out from list queries by default

List Queries (Filtering Behavior)

Default behavior - soft-deleted entities are excluded:

curl https://api.mvmnt.io/v1/orders \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "data": [
    {
      "id": "...",
      "friendlyId": "ORD-12346",
      "deletedAt": null
    },
    {
      "id": "...",
      "friendlyId": "ORD-12347",
      "deletedAt": null
    }
  ]
}

ORD-12345 is not included because it’s soft-deleted.

Include deleted entities - use ?includeDeleted=true:

curl "https://api.mvmnt.io/v1/orders?includeDeleted=true" \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "data": [
    {
      "id": "...",
      "friendlyId": "ORD-12345",
      "deletedAt": "2025-01-20T15:30:00Z"
    },
    {
      "id": "...",
      "friendlyId": "ORD-12346",
      "deletedAt": null
    },
    {
      "id": "...",
      "friendlyId": "ORD-12347",
      "deletedAt": null
    }
  ]
}

Get by ID (Still Accessible)

Soft-deleted entities are still accessible via GET by ID:

curl https://api.mvmnt.io/v1/orders/ORD-12345 \
  -H "Authorization: Bearer $TOKEN"

Response: 200 OK

{
  "id": "550e8400-...",
  "friendlyId": "ORD-12345",
  "deletedAt": "2025-01-20T15:30:00Z",
  ...
}

Your code must check deletedAt to determine if entity is deleted.

Query by Client Key

Deleted entities are also filtered out by default when querying by key:

curl "https://api.mvmnt.io/v1/orders?key=ERP-ORDER-789" \
  -H "Authorization: Bearer $TOKEN"

If the entity is deleted, this returns empty results unless you add ?includeDeleted=true.

Webhooks and Soft Deletes

DELETE Event

When an entity is deleted, a webhook event is triggered:

{
  "event": "order.deleted",
  "timestamp": "2025-01-20T15:30:00Z",
  "data": {
    "id": "550e8400-...",
    "friendlyId": "ORD-12345",
    "key": "ERP-ORDER-789",
    "deletedAt": "2025-01-20T15:30:00Z",
    "status": "delivered"
  }
}

Note: The data object includes deletedAt - your webhook handler must handle this field.

Other Events May Include Deleted Entities

Some webhook events may reference deleted entities (e.g., if a shipment references a deleted carrier). Always check deletedAt on related entities.

Why Soft Deletes?

Benefits

  1. Recovery: Records can be restored if something is deleted by mistake
  2. Auditability: Historical data remains available for reporting and troubleshooting
  3. Referential Integrity: Related records don’t break when they reference a deleted entity
  4. Retention: Some workflows require keeping deleted records for compliance and reporting
  5. Undo-Friendly UX: Products can support restore/undo without rebuilding data

Considerations

  1. Check deletedAt: Treat deletedAt != null as deleted, even if the API returns the record
  2. Webhook Handling: Deletion shows up as events, and other events can reference deleted entities
  3. Storage: Deleted records still consume database space
  4. Queries: Use ?includeDeleted=true when you need deleted records in list results
Previous page
Next page