Delete Order

This endpoint deletes an order. Only draft or cancelled orders can be deleted.

DELETE /v1/orders/:id

cURL

curl --location --request DELETE 'https://api.stateset.com/v1/orders/ord_123abc' \
--header 'Authorization: Token <token>'

curl --location --request DELETE 'https://api.stateset.com/v1/orders/ord_123abc?archive_instead=true' \
--header 'Authorization: Token <token>'

mutation orderDeleteMutation {
  orderDelete(id: "${orderId}", archiveInstead: false) {
    success
    order {
      id
      deleted
    }
    userErrors {
      field
      message
    }
  }
}

const deletedOrder = await stateset.orders.delete('ord_123abc');

// Or archive instead
const archivedOrder = await stateset.orders.delete('ord_123abc', {
  archive_instead: true
});

deleted_order = stateset.orders.delete('ord_123abc')

# Or archive instead
archived_order = stateset.orders.delete('ord_123abc', {
  'archive_instead': True
})

deleted_order = Stateset::Order.delete('ord_123abc')

# Or archive instead
archived_order = Stateset::Order.delete('ord_123abc', {
  archive_instead: true
})

deletedOrder, err := stateset.Orders.Delete("ord_123abc")

// Or archive instead
archivedOrder, err := stateset.Orders.Delete("ord_123abc", DeleteOptions{
  ArchiveInstead: true
})

Order deletedOrder = stateset.orders.delete("ord_123abc");

// Or archive instead
DeleteOptions options = new DeleteOptions();
options.setArchiveInstead(true);
Order archivedOrder = stateset.orders.delete("ord_123abc", options);

$deleted_order = $stateset->orders->delete('ord_123abc');

// Or archive instead
$archived_order = $stateset->orders->delete('ord_123abc', [
  'archive_instead' => true
]);

var deletedOrder = await stateset.Orders.Delete("ord_123abc");

// Or archive instead
var archivedOrder = await stateset.Orders.Delete("ord_123abc", new DeleteOptions {
  ArchiveInstead = true
});

Success Response

{
  "id": "ord_123abc",
  "deleted": true,
  "archived": false,
  "related_records": {
    "payments": 0,
    "shipments": 0,
    "returns": 0,
    "refunds": 0
  },
  "deleted_at": "2024-01-15T14:30:00Z",
  "deleted_by": "user_123"
}

{
  "id": "ord_123abc",
  "deleted": false,
  "archived": true,
  "status": "archived",
  "archived_at": "2024-01-15T14:30:00Z",
  "archived_by": "user_123",
  "archive_reason": "User requested archival instead of deletion"
}

{
  "error": {
    "code": "order_not_deletable",
    "message": "Cannot delete order that has been shipped. Only draft or cancelled orders can be deleted.",
    "details": {
      "order_id": "ord_123abc",
      "current_status": "shipped",
      "deletable_statuses": ["draft", "cancelled"],
      "suggestion": "Cancel the order first or archive it instead"
    }
  }
}

{
  "error": {
    "code": "active_returns",
    "message": "Cannot delete order with active returns. Please resolve all returns first.",
    "details": {
      "order_id": "ord_123abc",
      "active_returns": 2,
      "return_ids": ["ret_456def", "ret_789ghi"]
    }
  }
}

Path Parameters

id · string · required

The unique identifier of the order to delete

Query Parameters

force · boolean

Force deletion even if there are related records (requires admin permission)

archive_instead · boolean

Archive the order instead of deleting it (recommended for audit trail)

Response

id · string

The ID of the deleted order

deleted · boolean

Indicates whether the order was successfully deleted

archived · boolean

Indicates if the order was archived instead of deleted

related_records · object

Summary of related records affected

Show properties

payments · number

Number of related payment records

shipments · number

Number of related shipment records

returns · number

Number of related return records

refunds · number

Number of related refund records

deleted_at · string

Timestamp when the order was deleted

deleted_by · string

User who deleted the order

Error Responses

error · object

Error object containing details about what went wrong

Show properties

code · string

Error code (e.g., “order_not_deletable”, “order_shipped”, “active_refunds”)

message · string

Human-readable error message

details · object

Additional error details including order status and blockers

cURL

curl --location --request DELETE 'https://api.stateset.com/v1/orders/ord_123abc' \
--header 'Authorization: Token <token>'

curl --location --request DELETE 'https://api.stateset.com/v1/orders/ord_123abc?archive_instead=true' \
--header 'Authorization: Token <token>'

mutation orderDeleteMutation {
  orderDelete(id: "${orderId}", archiveInstead: false) {
    success
    order {
      id
      deleted
    }
    userErrors {
      field
      message
    }
  }
}

const deletedOrder = await stateset.orders.delete('ord_123abc');

// Or archive instead
const archivedOrder = await stateset.orders.delete('ord_123abc', {
  archive_instead: true
});

deleted_order = stateset.orders.delete('ord_123abc')

# Or archive instead
archived_order = stateset.orders.delete('ord_123abc', {
  'archive_instead': True
})

deleted_order = Stateset::Order.delete('ord_123abc')

# Or archive instead
archived_order = Stateset::Order.delete('ord_123abc', {
  archive_instead: true
})

deletedOrder, err := stateset.Orders.Delete("ord_123abc")

// Or archive instead
archivedOrder, err := stateset.Orders.Delete("ord_123abc", DeleteOptions{
  ArchiveInstead: true
})

Order deletedOrder = stateset.orders.delete("ord_123abc");

// Or archive instead
DeleteOptions options = new DeleteOptions();
options.setArchiveInstead(true);
Order archivedOrder = stateset.orders.delete("ord_123abc", options);

$deleted_order = $stateset->orders->delete('ord_123abc');

// Or archive instead
$archived_order = $stateset->orders->delete('ord_123abc', [
  'archive_instead' => true
]);

var deletedOrder = await stateset.Orders.Delete("ord_123abc");

// Or archive instead
var archivedOrder = await stateset.Orders.Delete("ord_123abc", new DeleteOptions {
  ArchiveInstead = true
});

Success Response

{
  "id": "ord_123abc",
  "deleted": true,
  "archived": false,
  "related_records": {
    "payments": 0,
    "shipments": 0,
    "returns": 0,
    "refunds": 0
  },
  "deleted_at": "2024-01-15T14:30:00Z",
  "deleted_by": "user_123"
}

{
  "id": "ord_123abc",
  "deleted": false,
  "archived": true,
  "status": "archived",
  "archived_at": "2024-01-15T14:30:00Z",
  "archived_by": "user_123",
  "archive_reason": "User requested archival instead of deletion"
}

{
  "error": {
    "code": "order_not_deletable",
    "message": "Cannot delete order that has been shipped. Only draft or cancelled orders can be deleted.",
    "details": {
      "order_id": "ord_123abc",
      "current_status": "shipped",
      "deletable_statuses": ["draft", "cancelled"],
      "suggestion": "Cancel the order first or archive it instead"
    }
  }
}

{
  "error": {
    "code": "active_returns",
    "message": "Cannot delete order with active returns. Please resolve all returns first.",
    "details": {
      "order_id": "ord_123abc",
      "active_returns": 2,
      "return_ids": ["ret_456def", "ret_789ghi"]
    }
  }
}